📂 tslint-folders-diagrams
Generate architecture diagrams from the folder configuration of tslint-folders.
status - stable
tslint-folders-diagrams is stable and in use every day in CI builds and on dev boxes (Linux, Mac, Windows) for at least one major product.
why?
Automatically create up-to-date architecture diagrams from the same config as used by tslint-folders to validate the source code.
features
- Provides a tool to generate architecture diagrams from the same model used by tslint-folders
- Output formats:
- plain text - suitable for a markdown file
- dot (graphviz)
- svg (via graphviz)
versioning
We use SemVer for versioning. For the versions available, see Releases.
usage
1 Install via yarn into your website
yarn add tslint-folders-diagrams
2 Generate a summary of the package configuration
Assuming that tslint.tslint-folders.json (from tslint-folders) has been correctly configured to model the expected package structure, then you can run this command to generate a summary:
node node_modules/tslint-folders-diagrams/dist/lib/tslint-folders-diagrams.js tslint.tslint-folders.json Text
example output:
package structure:
_____
shell - Application Shell
--> (any)
todo-area - TODO Area Package
--> grid-package, utils
folders:
components - components
--> (any)
viewmodels - view models
--> models, utils
models - models
--> utils
utils - utils
--> (none)
contact-area - Area that shows contact details
--> grid-package, utils
grid-package - Grid Package with no dependencies
--> (none)
utils - Utils package
--> (none)
_____
Allowed imports are shown for each package, after the --> arrow.
using graphviz to generate image diagrams of the architecture
A diagram can be automatically generated from the same config used to validated the code:
see generating diagrams for details.
command line arguments
tslint-folders-diagrams has many command line arguments, to allow you to customize the output.
To see the available arguments, you can run the command, with no arguments:
node node_modules/tslint-folders-diagrams/dist/lib/tslint-folders-diagrams.js
The general usage pattern is:
node node_modules/tslint-folders-diagrams/dist/lib/tslint-folders-diagrams.js <path to tslint.json> <format> [options]
- where format is one of: Text, Dot
The general options are:
| Option | Description | Example |
|---|---|---|
| disableTopCluster | Disable the automatically added top-level cluster (group). Helps if only the sub-folders are of interest. | -disableTopCluster |
| help | Shows the usage text. |
-help or -h
|
| importBlacklist | Exclude these top-level packages from the diagram. Helps to simplify the diagram. | -importBlacklist=package-1,package-2 |
| importWhitelist | Include only these top-level packages in the diagram. Helps to simplify the diagram. | -importWhitelist=package-1,package-2 |
| output | Write the output to the given filepath, instead of using standard output. | -outpath=/tmp/my-file.dot |
| skipSubFolders | Exclude sub-folders from the diagram. | -skipSubFolders |
The following options are specific to the Dot output format:
| Option | Description | Example |
|---|---|---|
| clusterFromTslintJson | Use diagramCluster from the tslint.tslint-folders.json config file, instead of automatically calculating a suitable cluster. |
-clusterFromTslintJson |
| colorScheme | Controls which graphviz color scheme to use. Defaults to pastel19
|
-colorScheme=piyg11 |
| disableGraphOptimizer | Disable the graph optimizer. The graph optimizer tries to automatically simplify the diagram, by avoiding duplicate edges, and by merging shared edge end points and clusters. For some configurations, it could be that the result is better with optimizations turned off. | -disableGraphOptimizer |
| maxColors | Control the maximum number of colors used from the graphviz theme. Defaults to 9 colors. | -maxColors=6 |
| packageShape | Control what kind of shapes are used to draw the packages. Defaults to oval. Allowed values are: box, oval, octagon, component, cyclinder, box3d, folder. | -packageShape=cylinder |
| showImportAnyAsNodeNotEdges | If a package can import any other package, then this can result in a large number of edges connected to this package. To avoid that, this option instead renders the 'any' specification as a single 'imports any' node, which helps to simplify the diagram. | -showImportAnyAsNodeNotEdges |
| subFolderShape | Control what kind of shapes are used to draw the sub-folders. Defaults to folder. Allowed values are: box, oval, octagon, component, cyclinder, box3d, folder. | -subFolderShape=octagon |
| subTitle | Set the sub-title of the diagram. | -subTitle="Top-level Packages" |
| title | Set the title of the diagram. | -title="Project Packages" |
examples
For working examples, see the following scripts:
| Script | Description |
|---|---|
./generate_graph_image_example.sh |
Basic example that generates an image from the example configuration (./tslint.tslint-folders.json). |
./generate_graph_image_example_shapes.sh |
Uses different kinds of shapes to draw the packages and sub-folders. |
./generate_graph_image_optimized_example_blacklist.sh |
Uses optimization options to simplify the diagram. |
./generate_graph_image_example_whitelist.sh |
Uses a whitelist, to only show some top-level packages. Generates a separate diagram of sub-folders. |
sites
| site | URL |
|---|---|
| source code (github) | https://github.com/mrseanryan/tslint-folders-diagrams |
| github page | https://mrseanryan.github.io/tslint-folders-diagrams/ |
| npm | https://www.npmjs.com/package/tslint-folders-diagrams |
building and testing this source code
To work on the source code for tslint-folders-diagrams, there are a few scripts:
| command | description |
|---|---|
| yarn build | Builds the tool to the 'dist' folder, where it can be executed. |
| yarn docs | Generates a summary of the package structure described in tslint.json. |
| yarn lint | Lints the source code of the rules. |
| yarn start | Builds, tests and lints the code. |
developing code in this repository
see the contributing readme.
origin
This project is based on the excellent seeder project typescript-library-starter.
The project was started to avoid having to repeatedly fix similar coding issues in large TypeScript code bases.
ORIGINAL readme (from the seeder project)
that's it
That's pretty much it. Let me know if this is useful or how it can be improved!
authors
Original work by Sean Ryan - mr.sean.ryan(at gmail.com)
licence = MIT
This project is licensed under the MIT License - see the LICENSE file for details.