ngcompass

Reference

CLI commands.

ngcompass exposes a set of subcommands. Run any of them with --help to see the latest flag list for your installed version. To see what analyze reports without installing anything, try the playground — it runs the same rule engine in your browser.

ngcompass analyze

Runs static analysis on your Angular project and reports violations grouped by file. The exit code is non-zero when violations at or above failOnSeverity are found.

bash
01npx ngcompass analyze

Common examples:

bash
01# Default console output
02npx ngcompass analyze
03

04# JSON output to a file
05npx ngcompass analyze --format json --output results.json
06

07# Stricter CI run
08npx ngcompass analyze --profile ci
  • --format <fmt>

    Output format: console (default) | json | sarif | html. Overrides outputFormat from config.

  • --output <path>

    File path for HTML or JSON output. Overrides outputPath from config.

  • --profile <name>

    Activate a named profile defined in ngcompass.config.ts. Useful for stricter CI rules.

  • --rule <id>

    Run only a single rule by ID. Useful for debugging one specific pattern.

  • --compact

    ESLint-style single-line output (console format only).

  • -q, --quiet

    Show summary counts only — suppress individual violation details.

  • --no-recommendation

    Suppress inline fix hints from output.

  • --force

    Ignore cached results and re-run all checks from scratch.

  • --skip-type-check

    Skip type-aware rules. Fastest mode with lowest memory — syntax-only rules still run.

  • --baseline [path]

    Hide violations recorded in a baseline file and report only new ones. Uses baseline.path from config when no path is given.

  • --no-baseline

    Ignore the baseline for this run, even when config enables it. Reports every violation, including recorded ones.

  • --max-workers <n>number

    Cap the number of worker threads. Lower values use less memory. Overrides maxWorkers from config.

ngcompass baseline

Records the violations a project already has, so analyze reports only newly introduced ones. Use it to adopt ngcompass on an existing codebase without fixing the backlog first.

bash
01# Record today's violations and commit the file
02npx ngcompass baseline create
03

04# Analyze, reporting only what is new
05npx ngcompass analyze --baseline
06

07# See what is being hidden
08npx ngcompass baseline show
09

10# Shrink the baseline after a cleanup
11npx ngcompass baseline prune
  • baseline create

    Runs a full uncached analysis and records every violation it finds. Fails if a baseline already exists, unless --force is passed.

  • baseline update

    Re-counts every file and rule scanned in this run and writes those counts. Entries for files the run did not scan are kept.

  • baseline prune

    Same re-count as update, and additionally follows renamed files and drops entries whose files no longer exist.

  • baseline show

    Prints what the baseline currently hides, grouped by rule. Reads the file only — no analysis runs.

Flags accepted by the baseline subcommands:

  • --path <path>

    Baseline file to read or write. Defaults to baseline.path from config (.ngcompass/baseline.json).

  • -p, --profile <name>

    Record under a named profile, so the baseline matches the rules CI enforces.

  • --rule <id>create, update

    Record or refresh one rule, leaving other entries untouched.

  • --forcecreate

    Overwrite an existing baseline file.

  • --top <n>show

    Files listed under each rule. Default 3.

  • --skip-type-check

    Skip type-aware rules while recording. The baseline then covers only the rules that ran.

  • --max-workers <n>

    Cap worker threads during the recording run.

ngcompass graph

Generates a full import dependency graph of your Angular project and writes it as a JSON file. Load the output into the interactive Dependency graph viewer to explore every import relationship, see what each file depends on and what depends on it, and identify the heaviest modules.

bash
01npx ngcompass graph --output graph.json

More examples:

bash
01# Write to the default location (ngcompass-graph.json)
02npx ngcompass graph
03

04# Write to a custom path
05npx ngcompass graph --output reports/graph.json
06

07# Scope to one file and its 2-hop neighborhood
08npx ngcompass graph --focus src/app/app.component.ts
09

10# Print JSON to stdout
11npx ngcompass graph --stdout
  • --output <path>default ngcompass-graph.json

    File path for the generated JSON. Pass this file to the /graph viewer on ngcompass.dev.

  • --stdout

    Write JSON to stdout instead of a file.

  • --focus <file>

    Scope the graph to a single file and its import neighborhood. Accepts a relative path or a partial filename.

  • --depth <n>numberdefault 2

    Neighborhood radius in import hops when using --focus. 1 = direct imports only, 2 = imports of imports, etc.

  • --force

    Ignore cached results and re-run from scratch.

ngcompass circular

Scans your project for circular import chains and reports every cycle — the exact files and the import order that closes the loop. Use --format json to produce a file you can load in the interactive Circular dependencies viewer.

bash
01npx ngcompass circular --format json --output cycles.json

More examples:

bash
01# Print cycles to the terminal
02npx ngcompass circular
03

04# Generate a JSON file for the /cycles viewer
05npx ngcompass circular --format json --output cycles.json
06

07# Open an interactive HTML report
08npx ngcompass circular --format ui
09

10# Scope to one file and its direct imports
11npx ngcompass circular --focus src/app/app.module.ts
  • --format <fmt>default console

    Output format: console | json. Use json to produce a file for the /cycles viewer; ui opens a self-contained HTML report.

  • --output <path>

    Write the report or JSON export to a file instead of stdout.

  • --focus <file>

    Scope cycle detection to a single file and its import neighborhood. Accepts a relative path or a partial filename.

  • --depth <n>numberdefault 1

    Neighborhood radius in import hops when using --focus.

  • --force

    Ignore cached results and re-run from scratch.

ngcompass complexity

Scores every function in the project for cyclomatic and cognitive complexity, groups the results by file, and writes them as JSON. Load the output into the interactive Complexity viewer to see each file as a heat tile sized by its total score, drill into a file to rank its functions, and jump straight to the worst offenders in the codebase.

bash
01npx ngcompass complexity --output complexity.json

More examples:

bash
01# Write to the default location (ngcompass-complexity.json)
02npx ngcompass complexity
03

04# Write to a custom path for the /complexity viewer
05npx ngcompass complexity --output complexity.json
06

07# Only functions that are already hard to read, ranked by branch count
08npx ngcompass complexity --min 10 --sort cyclomatic
09

10# Print JSON to stdout (pipe it into jq, a CI step, etc.)
11npx ngcompass complexity --stdout
  • --output <path>default ngcompass-complexity.json

    File path for the generated JSON. Pass this file to the /complexity viewer on ngcompass.dev.

  • --stdout

    Write JSON to stdout instead of a file. Skips the console summary.

  • --sort <metric>default cognitive

    Ranking metric: cyclomatic | cognitive. Decides the order of files and of functions inside each file.

  • --min <n>numberdefault 0

    Only include functions whose worst metric (the higher of cyclomatic and cognitive) is at least n. Files left with no function are dropped.

  • --profile <name>

    Activate a named profile from ngcompass.config.ts — useful when a profile narrows the analysed file set.

  • --force

    Ignore cached results and re-run from scratch.

The two metrics:

  • cyclomatic

    Number of independent paths through a function: 1 plus every if, loop, case with a test, catch, ternary, and && / || / ?? operator. It tracks how many tests you need to cover the function.

  • cognitive

    How hard the function is to follow. Each branch adds a point, and nesting adds more — a condition three levels deep costs more than the same condition at the top level. Better than cyclomatic at pointing to code that is painful to read.

Without --stdout, the command also prints a summary — the 15 hottest files with their 5 worst functions each — before writing the file:

bash
01Complexity summary — 24746 functions in 2865 files (sorted by cognitive)
02  max cyclomatic 38, max cognitive 26, avg cyclomatic 1.43, avg cognitive 0.48
03

04tools/config/manage-dependencies.ts (cyclomatic 201, cognitive 195)
05  959:36 <anonymous> [arrow] — cyclomatic 11, cognitive 26
06  1113:52 <anonymous> [arrow] — cyclomatic 14, cognitive 25
07  …and 72 more
08

09✔ Complexity report written to complexity.json

The JSON is a summary block plus one entry per file, each already sorted worst-first by sortedBy:

json
01{
02  "rootDir": "/repos/storefront",
03  "generatedAt": "2026-07-26T18:23:29.564Z",
04  "sortedBy": "cognitive",
05  "thresholds": { "min": 0 },
06  "summary": {
07    "fileCount": 2865,
08    "functionCount": 24746,
09    "maxCyclomatic": 38,
10    "maxCognitive": 26,
11    "avgCyclomatic": 1.43,
12    "avgCognitive": 0.48
13  },
14  "files": [
15    {
16      "filePath": "tools/config/manage-dependencies.ts",
17      "fileCyclomatic": 201,
18      "fileCognitive": 195,
19      "maxCyclomatic": 14,
20      "maxCognitive": 26,
21      "functionCount": 74,
22      "functions": [
23        {
24          "name": "addMissingDependenciesToPackageJson",
25          "kind": "function",
26          "line": 734,
27          "column": 1,
28          "endLine": 822,
29          "lineCount": 89,
30          "cyclomatic": 5,
31          "cognitive": 7
32        }
33      ]
34    }
35  ]
36}

ngcompass visualize

Treats a single file as a unit: the TypeScript file it anchors on, the template, stylesheets and spec that belong to it, and one lane per injected dependency. Pointing it at the template or the spec resolves back to the same unit. Load the JSON into the interactive Visualize viewer to trace every binding, event, test and dependency call — and to see the members that nothing references at all. Unlike graph, which works at the file level across the project, this command zooms in on one component.

bash
01npx ngcompass visualize src/app/user/user.component.ts

More examples:

bash
01# Write the standalone HTML diagram (default)
02npx ngcompass visualize src/app/user/user.component.ts
03

04# Write JSON for the /visualize viewer
05npx ngcompass visualize src/app/user/user.component.ts --format json
06

07# Any file of the unit resolves back to the .ts anchor
08npx ngcompass visualize src/app/user/user.component.html
09

10# Print JSON to stdout (pipe it into jq, a CI step, etc.)
11npx ngcompass visualize src/app/user/user.component.ts --stdout
  • --format <fmt>default html

    `html` writes a self-contained lane diagram, `json` writes the graph, `console` prints the summary only.

  • --output <path>default ngcompass-visualize.html / .json

    File path for the generated report. Pass the JSON to the /visualize viewer on ngcompass.dev.

  • --stdout

    Write JSON to stdout instead of a file. Skips the console summary.

What the export contains:

  • lanes

    One per file of the unit — the TypeScript anchor, its template, each stylesheet, the spec, and one lane per injected dependency. Each carries a `status`: `parsed`, `inline` for decorator-embedded template or styles, `declared-missing` when the decorator points at a file that is not on disk, or `unparseable`.

  • boxes

    The symbols inside a lane: class members in the TypeScript lane, the members a template references, stylesheet selectors, `it()` tests, and the dependency members the class actually calls.

  • edges

    Arrows follow dataflow, not mention order. `direction` is `data-down` for bindings and interpolations, `control-up` for event handlers, `both` for two-way bindings, and `calls` for member, spec and dependency calls. `weight` counts how many source sites the single arrow stands for.

With --format console, the command prints the unit lane by lane instead of writing a file:

bash
01Unit UserComponent — 5 lanes, 20 symbols, 10 edges
02

03ts user.component.ts
04  title 10:3
05  draft 11:3
06  load 20:3
07  onSave 26:3
08  neverUsedAnywhere 35:3
09

10template user.component.html
11  title 1:7
12  draft 2:20
13  onSave 3:9
14

15spec user.component.spec.ts
16  loads users on init 4:3
17  saves the draft 8:3
18

19dependency UserService
20  fetchAll
21  save

The JSON pairs a summary block with the lanes and the edges between their symbols:

json
01{
02  "rootDir": "/repos/storefront",
03  "generatedAt": "2026-07-30T15:26:10.193Z",
04  "entryFile": "src/app/user/user.component.ts",
05  "className": "UserComponent",
06  "summary": {
07    "laneCount": 5,
08    "boxCount": 20,
09    "edgeCount": 10
10  },
11  "lanes": [
12    {
13      "id": "ts",
14      "kind": "ts",
15      "status": "parsed",
16      "label": "user.component.ts",
17      "filePath": "src/app/user/user.component.ts",
18      "boxes": [
19        {
20          "id": "ts#onSave@26",
21          "name": "onSave",
22          "kind": "method",
23          "line": 26,
24          "column": 3
25        }
26      ]
27    }
28  ],
29  "edges": [
30    {
31      "from": "template#onSave@0",
32      "to": "ts#onSave@26",
33      "kind": "template-event",
34      "direction": "control-up",
35      "weight": 1
36    }
37  ]
38}

ngcompass init

Creates an ngcompass.config.ts file in the project root with the ngcompass:recommended preset. Prefer ng add ngcompass for Angular CLI projects — it runs init automatically as part of the schematic.

bash
01npx ngcompass init
  • --force

    Overwrite an existing ngcompass.config.ts. Without this flag, init aborts if the file already exists.

ngcompass config health

Validates the active config file. Reports unknown rule IDs, invalid severity values, unrecognised keys, and schema errors. Useful to run after editing ngcompass.config.ts manually.

bash
01npx ngcompass config health

Related

Configuration →

All config file options and CLI flag overrides.

Baseline →

Adopt ngcompass on an existing codebase and gate only new violations.

Dependency graph viewer →

Load a graph.json and explore your imports visually.

Cycles viewer →

Load a cycles.json and inspect every circular import.

Complexity viewer →

Load a complexity.json and rank your hardest functions.

Visualize viewer →

Load a visualize.json and see one file's class, template, styles and spec together.