compodoc / ngd

View the dependencies tree of you Angular application

CLI
Core
Compiler
Transformer

NGD: Angular Dependencies Graph

A tool that allows you to view your Angular application dependencies.

Generated Graphs (sample)

Sample Application

Angular Material 2

ng-bootstrap

soundcloud-ngrx

Install

Install from npm:

npm install -g @compodoc/ngd-cli

Install from Yarn:

yarn global add @compodoc/ngd-cli

Usage the CLI

$ ngd --help

Usage: ngd [options]

Options:

  -h, --help                    Output usage information
  -V, --version                 Output the version number
  -f, --file [file]             Entry *.ts file
  -p, --tsconfig [config]       A tsconfig.json
  -o, --open                    Open the generated HTML diagram file
  -g, --display-legend          Display the legend in the generated graph (default: true)
  -s, --silent                  In silent mode, log messages aren't logged in the console
  -t, --output-formats [formats] Output formats (default: html,svg,dot,json)
  -d, --output [folder]         Where to store the generated files

1) use a tsconfig.json:

Run inside your project (where your tsconfig.json is located):

$ cd my-awesome-cli-angular-app/
$ ngd
$ # or
$ ngd -p ./tsconfig.json

Note: This will read the files entry point in your tsconfig.json and crawl your app. If the entry point is not found, all *.ts files will be crawled, but not those mentioned in the exclude property (more details).

2) provide an entry file:

$ cd my-awesome-cli-angular-app/
$ ngd -f src/main.ts

NOTE: The file you provide should contain your root component.

Usage the API

1. Import the DotEngine and Compiler from @compodoc/ngd-transformer and @compodoc/ngd-compiler:

import { DotEngine } from '@compodoc/ngd-transformer';
import { Compiler } from '@compodoc/ngd-compiler';

2. Create an instance of a compiler:

const compiler = new Compiler(files, {
    tsconfigDirectory: cwd,
});

3. Get the found dependencies:

const deps = compiler.getDependencies();

4. Pass those dependencies to the transformer:

const engine = new DotEngine({
    output: program.output,
    displayLegend: program.displayLegend,
    outputFormats: program.outputFormats.split(','),
});

5. Generate the graph:

engine.generateGraph(deps).then(file => { ... });

Have a PR?

All contributions are welcome ;)

License

The MIT License (MIT) Copyright (c) 2016 - Wassim CHEGHAM

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ngd's Issues

Not retrieving all modules

Using this open-source Angular 2 application : https://github.com/r-park/soundcloud-ngrx

I didn't get in the outputed json modules like : HomeModule, BrowserModule, CoreModule for examples.

The graph is below.

Is it because they don't have "imports" ?

not working for me - no deps

I can provide you with what you need to help you debug, I just don't have a plunkr.

parameter for layouting

Is your feature request related to a problem? Please describe.
Layout of huge project is not optimal. It is now one "huge line".

Describe the solution you'd like
Add parameter --layout= for different types of layouting (horizontal, vertical, combine, ultramagic, and so on..)

(feat): add a changelog

Now that the project is starting to grow. It'd nice to have a changelog. See https://www.npmjs.com/package/conventional-changelog

(feat): add a client version of this tool

Currently, this tool runs on the server (Node). We need to add a client version so a developer can generate a live view of the application's deps.

We may look at D3.js for the visual part. This step should be straightforward. However, we need to write a client version of the crawler.

Of course, we also need to clean up all the references to the Node environment.

NGD does not recognise -l or --files option

Describe the bug
ngd does not recognise -l option (neither --files option), which is documented in README.md.

To Reproduce
Steps to reproduce the behavior:

1. npm i -g @compodoc/cli
2. e.g. ngd -l .\app.module.ts .\components\core\core.module.ts
3. NGD does not recognise this option and tries to use tsconfig.json instead (which does not contain entry files, hence the consequent SyntaxError).

Expected behavior
NGD should resolve all files listed (I guess, not documented).

Screenshots

Desktop (please complete the following information):

• OS: Windows 10
• CLI: Windows Terminal (PowerShell)

Additional context
None

is there an option to exclude all css, html files from output

Creates a lot of folders on mac

Running ng2-dg --file bootstrap.ts with any project (tried it e.g. with AngularShowcase/angular2-sample-app) creates empty folders named a,b,c and so on.

I'm using it with osx version 10.11.3 and node version v5.6.0

Plugin does not support tsconfig.json file with multi-line comments

Describe the bug
When using "ngd" command inside the root folder of an Angular 10 project an exception is thrown:

[20:30:05] using tsconfig: C:\Users\_\tsconfig.json
internal/modules/cjs/loader.js:1238
    throw err;
    ^

SyntaxError: C:\Users\_\tsconfig.json: Unexpected token / in JSON at position 0
    at parse (<anonymous>)
    at Object.Module._extensions..json (internal/modules/cjs/loader.js:1235:22)
    at Module.load (internal/modules/cjs/loader.js:1050:32)
    at Function.Module._load (internal/modules/cjs/loader.js:938:14)
    at Module.require (internal/modules/cjs/loader.js:1090:19)
    at require (internal/modules/cjs/helpers.js:75:18)
    at Object.Application.run (C:\Users\_\AppData\Roaming\npm\node_modules\@compodoc\ngd-cli\dist\cli.js:54:25)    
    at Object.<anonymous> (C:\Users\_\AppData\Roaming\npm\node_modules\@compodoc\ngd-cli\dist\index.js:4:19)       
    at Module._compile (internal/modules/cjs/loader.js:1201:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1221:10)

To Reproduce
Steps to reproduce the behavior:

1. Create an Angular 10 project
2. Run "ngd" in the same folder as the tsconfig.json

Expected behavior
It should understand that the text included in /* */ is a comment and parse the file correctly.

Screenshots
If needed, ask me.

Desktop:

• OS: Windows 10
• Version 2.1.0

Additional context
Here is my tsconfig.json, generated by Angular CLI:

/*
  This is a "Solution Style" tsconfig.json file, and is used by editors and TypeScript’s language server to improve development experience.
  It is not intended to be used to perform a compilation.

  To learn more about this file see: https://angular.io/config/solution-tsconfig.
*/
{
  "files": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    },
    {
      "path": "./tsconfig.spec.json"
    }
]
}

(feat): Add an option for filtering components

Option for excluding components with Regex or prefixes

Add a VSCode extension

We could have a Visual Studio Code extension version of this tool.
Some examples : https://code.visualstudio.com/Docs/extensions/example-hello-world

NGD unable to differentiate same component name in different moudles

If I have the same component name in different modules then ngd is not able to differentiate it and provides me duplicate entries. Does it look the components in the module through imports or just by name?

Can you please help me out here?

Thanks,
Abhay

Missing gulp-util

Works great!
The only thing is I had to install gulp-util before.

(bug): TypeError: Viz is not a function

Calling ngd-transformer directly for a simple module of an angular application breaks with :
Viz is not a function at DotEngine.generateSVG (/home/vogloblinsky/Documents/www/TMP/compodoc/compodoc/node_modules/@compodoc/ngd-transformer/dist/engines/dot/dot.js:179:22)

Reproduced with a simple Node.js script, using twice new ngdT.DotEngine().

Moving viz.js require from this line https://github.com/compodoc/ngd/blob/master/src/modules/transformer/src/engines/dot/dot.ts#L227 to the top https://github.com/compodoc/ngd/blob/master/src/modules/transformer/src/engines/dot/dot.ts#L4 solve the issue.

fix(): remove dependency on gulp-util from ngd-core pacakge

gulp-util is deprecated - replace it, following the guidelines at https://medium.com/gulpjs/gulp-util-ca3b1f9f9ac5

refactor this module

1st pass:

• rename "angular2-dependencies-graph" the "ngd"
• update package.json && redeploy to @compodoc/

2nd pass:

• move core features to @compodoc/ngd-core
• move compiler to @compodoc/ngd-compiler
• move codegen features (json, html, svg) to @compodoc/ngd-generator

Design doc here: https://docs.google.com/document/d/1BdlLdAvQkedI_14ZB7HeMMAQc1WWqOQ4ZLHqSpeKG7A/edit?ts=5846b3ef

Cannot install it

When I issue "npm i -g angular2-dependency-graph" I get

404
'angular2-dependency-graph' is not in the npm registry.

bug: node 7?

Why node versions > 7.0.0 not compatible ?

Support apps without "files" attribute / with "exclude" attribute

If there is no "files" Attribute, the typescript Compiler simply includes all typescript files. If there is a "exclude" attribute the typescript compiler includes all typescript files except the ones which are specified in the exclude array http://www.typescriptlang.org/docs/handbook/tsconfig.json.htm. I think it would make sense if this tool would do the same.

I quickly put some code together to make it possible for my application to use the tool. Not sure if it is super clean, but it works for me.

In application.ts, instead of:

if(!files) {
  logger.fatal('"tsconfig.json" file does not export a "files" attriute');
  process.exit(1);
}

I do:

if(!files) {

  let exclude = [];
  exclude = require(program.tsconfig).exclude;

  var walk = function(dir) {
    var results = [];
    var list = fs.readdirSync(dir);
    list.forEach(function(file) {
      if (exclude.indexOf(file) < 0) {
        file = dir + '/' + file;
        var stat = fs.statSync(file);
        if (stat && stat.isDirectory()) results = results.concat(walk(file));
        else if (path.extname(file) === '.ts') results.push(file)
      }
    });
    return results
  };

  files = walk('.');

}

Node v6.7.0

Hi,

Is it possible to increase node version ?

Currently we have this error when trying to install :

$ yarn global add angular2-dependencies-graph
yarn global v0.16.0
warning No license field
[1/4] 🔍  Resolving packages...
warning angular2-dependencies-graph > [email protected]: Viz.js is deprecated.
warning angular2-dependencies-graph > svg-to-png > imagemin > vinyl-fs > glob-watcher > gaze > globule > glob > [email protected]: graceful-fs v3.0.0 and before will fail on node releases >= v7.0. Please update to graceful-fs@^4.0.0 as soon as possible. Use 'npm ls graceful-fs' to find it in the tree.
warning angular2-dependencies-graph > svg-to-png > imagemin > vinyl-fs > glob-watcher > gaze > globule > [email protected]: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue
[2/4] 🚚  Fetching packages...
error [email protected]: The engine "node" is incompatible with this module. Expected version ">= 5.4.1 < 6".
error Found incompatible module
info Visit https://yarnpkg.com/en/docs/cli/global for documentation about this command.

$ node --version
v6.7.0

Thanks for your help !

Support ability to specify version of TypeScript

Once I got the app running, it did a fantastic job on the simpler test cases I threw at it. Unfortunately, it fails when running on our larger, more complex application due to the fact that our module resolution method utilizes a feature only available in newer versions of TypeScript (1.9.x nightlies) called Path Mapping. It greatly simplifies the module declarations throughout the system (important in larger applications), but with TypeScript 1.7.3, the app fails to recognize pretty much the entirety of our component tree after the parent app component.

Add a legend with graph

• by default ?
• option ?
• just colors : type of element ?

An example :

Add an option for supporting one entry component

Useful feature to analyse all related components about one single entry.

Arbitrary Code Injection Vulnerability for dependency

During npm audit through Veracode, it is detected Arbitrary Code Injection for dot library for compodoc/ngd-transformer package.

Vulnerability detail : dot is vulnerable to arbitrary code injection. The template function does not sanitize input set on Object.prototype, allowing an attacker who is able to compile templates to inject and execute arbitrary code.

Currently compodoc/ngd-transformer using 1.1.3 versiof dot library. Above Vulnerability is fixed in 2.​x.x (2.0.​0-beta.1) version of dot.

Can someone please help to upgrade dot library to latest version to solve above Vulnerability?

Since 2.1, `@compodoc/ngd-transformer` now requires Node >= 12.17.0

Describe the bug

The latest release of @compodoc/ngd-transformer includes 60dbb2a.
In this commit, viz.js has been replaced by @aduh95/viz.js (here).

Functionality speaking it looks ok however node requirement of @aduh95/viz.js is stricter than viz.js as it needs ^12.17.0 || >=13.2.0, see: https://github.com/aduh95/viz.js/blob/master/package.json#L24.

It can look irrelevant but as this was published in a minor release and as @compodoc/compodoc has a dependency on "@compodoc/ngd-transformer": "^2.0.0" (^2.1.0 for a few hours) it causes the following error when running yarn install with Node <12.17.0 :

error @aduh95/[email protected]: The engine "node" is incompatible with this module. Expected version "^12.17.0 || >=13.2.0". Got "12.16.2"
error Found incompatible module.

And it's breaking some of the CI steps of Storybook for instance.

Expected behavior

Builds of @compodoc/compodoc users should not be broken because one of its dependency had a minor release.

Additional context

Options I have in mind:

• Check with the maintainer of @aduh95/viz.js if current node requirement ("^12.17.0 || >=13.2.0") is correct. It has been bumped here but there is no info about the reason in the commit message.
• Update Node compatibility and make major releases of @compodoc/ngd-transformer and @compodoc/compodoc and so on Storybook side we will safely use an old/fixed version of Compodoc for now.

(feat): add a library mode

const ngd = require('angular2-dependencies-graph')

which APIs opened ?

• getDependencies : return json file as javascript object
• renderGraph

(feat): filter graph generation

Watching demo graph, we can have very long graph, unreadable quickly.

An option for filtering could be fine :

ngd -f tsconfig.json -i module,component

rename this shit

AngularJS Dependency graph

Does this tool generate dependencies for an AngularJS application?

error on running the tool

I just installed the tool and try to generate the dependency graph.

I get the following error:

Cannot read property 'indexOf' of undefined.

dot npm package vulnerability (npm audit failing)

Overview of the issue

Current Compodoc/ngd version (in master) depends on [email protected], which contains the vulnerability identified here:

https://www.npmjs.com/advisories/798

This is causing npm audit checks to break.

Operating System, Node.js, npm, compodoc version(s)

Looks like this dependency was added 2 years ago. And all versions of dot are affected.

bb3c75c

Suggest a Fix

Doesn't look like dot is actively developed any more because the last release was 2 years ago. So I think you'd need to replace it with a different npm package.

highlight the element or relationship on click

Is your feature request related to a problem? Please describe.
In huge project with lot of elements is very difficult to find the relationship between two elements because there is lot of long lines super-near to each other.

Describe the solution you'd like
Make relationship line clickable and highlight it and elements it's connected

(feat): material design color schema

https://www.materialui.co/colors

fix(providers): find a better label for configurable providers

currently the generated graph that is related to configurable providers looks like this :

• { provide: CURRENCY_PAIRS, useValue: "currencyPairs" }
• { provide: CURRENCY_PAIRS, useClass: currencyPairs }
• { provide: CURRENCY_PAIRS, useExisting: currencyPairs }
• { provide: CURRENCY_PAIRS, useFactory: () => { ... } }

We can prolly find a better label ?!

Proposals

1. CURRENCY_PAIRS:useValue("currencyPairs")
2. CURRENCY_PAIRS => "currencyPairs"
3. ???

Is it possible to use it for not angular projects also usage typescript code?

Is it possible to use it for not angular projects also usage typescript code?

(feat): Include all classes (not just components)

This is a great start. But could it be modified to include all classes? It looks like the tool does parse non-component classes (like services, models, etc.), but doesn't appear to include them in the graph output. I think being able to see all the dependencies would also be quite useful.

Max call stack size exceeded

Describe the bug
Running on a large angular app causes the error RangeError: Maximum call stack size exceeded during file generation.

To Reproduce
Steps to reproduce the behavior:
Sorry. Hard to provide any steps without just having a large app to test on, which I unfortunately cannot provide. Simply running ngd with no args threw the error after several files initially parsed successfully.

Expected behavior
Don't throw the error.

Screenshots

Desktop (please complete the following information):

• OS: Mac OS
• Browser: N/A
• Version: 2.1.0

yarn installation failed with phantomjs path

node : 6.5.0
npm : 3.10.9
yarn : 0.17.10

yarn add angular2-dependencies-graph

error /home/osboxes/Documents/www/compodoc-demo-todomvc-angular2/node_modules/phantomjs: Command failed.
Exit code: 1
Command: sh
Arguments: -c node install.js
Directory: /home/osboxes/Documents/www/compodoc-demo-todomvc-angular2/node_modules/phantomjs
Output:
PhantomJS not found on PATH
Phantom installation failed TypeError: Path must be a string. Received undefined
    at assertPath (path.js:7:11)
    at Object.join (path.js:1213:7)
    at findSuitableTempDirectory (/home/osboxes/Documents/www/compodoc-demo-todomvc-angular2/node_modules/phantomjs/install.js:127:30)
    at /home/osboxes/Documents/www/compodoc-demo-todomvc-angular2/node_modules/phantomjs/install.js:476:19
    at nextTickCallback (/home/osboxes/Documents/www/compodoc-demo-todomvc-angular2/node_modules/kew/kew.js:47:28)
    at _combinedTickCallback (internal/process/next_tick.js:67:7)
    at process._tickCallback (internal/process/next_tick.js:98:9) TypeError: Path must be a string. Received undefined
    at assertPath (path.js:7:11)
    at Object.join (path.js:1213:7)
    at findSuitableTempDirectory (/home/osboxes/Documents/www/compodoc-demo-todomvc-angular2/node_modules/phantomjs/install.js:127:30)
    at /home/osboxes/Documents/www/compodoc-demo-todomvc-angular2/node_modules/phantomjs/install.js:476:19
    at nextTickCallback (/home/osboxes/Documents/www/compodoc-demo-todomvc-angular2/node_modules/kew/kew.js:47:28)
    at _combinedTickCallback (internal/process/next_tick.js:67:7)
    at process._tickCallback (internal/process/next_tick.js:98:9)
info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command.

add minimum distance between lines

Maybe it would be a good idea to add a minimum distance between lines when the graph is generated, to be able to see clearly the dependence. Now you need to point the line to see the description, which is quite hard when there are a lot o dependencies. Also It will look nice.

Off topic: great job :)

Error parsing Dependencies

Problem
When the dependency graph builder parses a file and has a problem, it throws the error and stops parsing

Expected Behaviour?
If an unexpected error occurs a warning message is logged but the tool keeps parsing and still creates the graph.
Another option might be to allow a list of files to ignore completely as parameter.

---

Error
[07:57:54] parsing : E:/messenger-web/src/app/shared/version.service.ts
[07:57:54] parsing : E:/messenger-web/src/app/shared/layout/layout.component.ts
C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\built\platform\node\crawlers\dependencies.js:106
return node.initializer.elements.map(function (o) {
^

TypeError: Cannot read property 'map' of undefined
at C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\built\platform\node\crawlers\dependencies.
js:106:49
at Array.map (native)
at Dependencies.getComponentDeps (C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\built\platf
orm\node\crawlers\dependencies.js:98:16)
at Dependencies.getComponentSelector (C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\built\p
latform\node\crawlers\dependencies.js:67:25)
at visitNode (C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\built\platform\node\crawlers\de
pendencies.js:41:45)
at Array.forEach (native)
at C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\built\platform\node\crawlers\dependencies.
js:57:26
at visitEachNode (C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\node_modules\typescript\lib
\typescript.js:7421:30)
at Object.forEachChild (C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\node_modules\typescri
pt\lib\typescript.js:7578:24)
at Dependencies.getSourceFileDecorators (C:\Users\angelak\AppData\Roaming\npm\node_modules\angular2-dependencies-graph\buil
t\platform\node\crawlers\dependencies.js:33:16)

Typings install fails.

The npm typings script has a typo.

Currently, it read typings install --ambiant

It should read typings install --ambient

CLI Silent Option Doesn't Work

The CLI option --silent and -s doesn't do anything.
(Version: 2.0.0-alpha.5)

(feat): add tests

• basic regression tests (add in fa176aa)
• UI tests

feat: move the build system to Bazel

👉https://github.com/bazelbuild/rules_typescript

(feat): Add an ATOM extension

We could have an Atom Editor package version of this tool.
Read this for more details: https://www.sitepoint.com/how-to-write-a-syntax-highlighting-package-for-atom/

Cannot enlarge memory arrays.

after npm install , I'm running /root/node-v6.9.0-linux-x64/bin/ngd , then get errors as follow:

then i use /root/node-v6.9.0-linux-x64/bin/ngd -s TOTAL_MEMORY=60000000 ,still get errors.

how to solve this problem?

THANKS VERY MUCH!

Problem during installation

Hi,

this package cannot be installed. I have attached the log file from npm
npm-debug.txt

parametr for filtering what element to render

Is your feature request related to a problem? Please describe.
In huge project is problem to find the "right dependency" because there is lot of elements rendered and the situation is unclear.

Describe the solution you'd like
Add a parameter for filter what elements to render. For example want to render only Modules (not services nor exports...)

feat: move this repo to compodoc organization

ping @vogloblinsky

(feat) forRoot

Hi,

The ngd doesn't see anything inside forRoot().

Thanks.

export class SharedModule {
   static forRoot(): ModuleWithProviders {
    return {
      ngModule: SharedModule,
      providers: [ MyService, ExampleService]
    };
  }
}