IDs for class, etc. subgraphs should include the modules for cases like bytestring where two datatypes have the same name TODO for SourceGraph ==================== This is the list of planned improvements to the SourceGraph program. Please note that some of these improvements will actually take place in the [Graphalyze](http://hackage.haskell.org/package/Graphalyze) library. Parsing Improvements -------------------- SourceGraph uses [haskell-src-exts](http://hackage.haskell.org/package/haskell-src-exts) to parse Haskell code. As such, it is limited in terms of what it can parse first of all by what haskell-src-exts supports. * The following types of items are not yet recognised; either add support for them (e.g. using cpphs for CPP) or else log a message if there is no sane way of integrating them into the call graph: - Invalid code (these files will not even be readable by haskell-src-exts and as such a warning should be displayed). - Modules using the C Pre-Processor; adding support for this will depend on better Cabal file support and command line options. - [Haskell Regular Patterns](http://hackage.haskell.org/package/harp), [Haskell Source with XML](http://hackage.haskell.org/package/hsx) and the embedded XML syntax of [Haskell Server Pages](http://hackage.haskell.org/package/hsp) all utilise haskell-src-exts to extend Haskell syntax; as such, the parsing support is available but it is unknown how to convert them to entities in the call graph. - It is unknown how to add [Data Family](http://www.haskell.org/haskellwiki/GHC/Type_families) instances (both normal and GADT style) into the call graph. - It is probably not possible to integrate [Foreign Function Interface](http://www.haskell.org/haskellwiki/FFI) imports and exports into the call graph. - [Template Haskell](http://www.haskell.org/haskellwiki/Template_Haskell) is also not currently supported. * The following items have partial/incomplete/possibly wrong support for integration into the call graph: - Currently pragmas, LANGUAGE options, etc. are only supported if they are included in the top level of the module (as such, haskell-src-exts will use them for parsing purposes). - Entities explicitly imported from an external module are not always correctly categorised; to improve support for this, any class methods or datatype constructors/record functions should be explicitly imported [rather than using the `Foo(..)`] syntax; furthermore, a datatype import is only recognised as such if at least one constructor is imported (otherwise it is assumed to be a class). - When using record puns, it is not always possible to distinguish between the records and punned values. - When using record wildcards, not all records are completely listed/used as both record functions and variables (see the problem with record puns above). - Multi-param type classes may not be considered/formatted correctly. - Entities that are imported into a module and then re-exported (including re-exporting the entire imported module) may not be considered correctly. Analysis Improvements --------------------- * When considering levels, produce a plot of level size vs depth. - Similar plots may be useful for other analyses, such as the number of cycles of a given size. - Possibly also provide a characterisation of the "shape" of the plot. * Provide comparisons from other large-scale Haskell projects for analyses such as shape of the level graph, cyclomatic complexity. - To achieve this, possibly run a cut-down version of SourceGraph over all packages in [HackageDB](http://hackage.haskell.org/package/) to accumulate the comparison information. * Include more ways of analysing software from its Call Graph. Reporting Format ---------------- * Use CSS, etc. to improve the generated HTML files. * Produce multi-page HTML documents. * Improve formatting of entity listing (listing of cliques, etc.). * Report errors/warnings (from parsing, etc.). * Improve graph visualisation: - Having a lot of edges makes it difficult to "read" the visualisation (maybe when clustering have the edges go from cluster to cluster?). - Ensure node labels do not extend past the boundary of the node (note: for cluster labels, this seems to be a bug with Graphviz's SVG output). Project Integration ------------------- * Allow clearer differentiation between Cabal-based and source-based projects. - When basing it off files, allow the user to specify several files. * For Cabal: - When using Cabal, provide some way to choose which section is being analysed (i.e. library or an executable). + Probably also some way of reporting to the user which options are available. - Pass GHC, CPP, etc. flags through for when parsing the files. - Use the correct source directory and match modules to files. Program Usage ------------- * Provide command-line options to allow users to set the following: - Output directory. - Report format. - What output to generate, e.g.: + Brief analysis summary. + Only produce a call-graph (overall, imports and per-module). - What to analyse, that is one of the following: + Only one module (not when using Cabal mode). + Only files used in that project. + All files found (whether they are used in the project or not). * The ability to specify project flags (Cabal flags, CPP flags, etc.). * Write a README and supporting documentation. Future Plans ------------ * Write a proper website for SourceGraph. * Provide some way of making the analyses "interactive" (e.g. zooming, slicing, etc.). - Noam Lewis' proposed interactive graph editor may be a start towards providing this kind of functionality. * Integrate SourceGraph into [HackageDB](http://hackage.haskell.org/package/).