ngcompass

ngcompass

Angular-aware static analysis for architecture, performance, SSR, security, and code quality.

Overview

ngcompass is a command-line static analysis tool built for Angular projects. It reads TypeScript, Angular templates, styles, and project configuration without running the application, then reports issues that generic TypeScript linters often miss.

It is designed for teams that want a clearer view of Angular-specific risks: component architecture, rendering performance, SSR compatibility, Signals and RxJS patterns, template safety, and modern Angular API adoption.

Highlights

Area	What ngcompass helps find
Architecture	Circular dependencies, boundary violations, and fragile component relationships
Performance	Missing OnPush, expensive template expressions, missing trackBy, and inefficient bindings
SSR	Browser-only APIs in universal code, hydration risks, and render lifecycle pitfalls
Security	Unsafe template bindings and sanitizer bypasses
Reactivity	RxJS subscription issues, Signals misuse, and migration opportunities
Code quality	Deprecated patterns, focused tests, and modern Angular API improvements

Installation

Install the beta CLI globally:

npm install -g ngcompass@beta

Or add it to a project:

npm install --save-dev ngcompass@beta

Using pnpm:

pnpm add -D ngcompass@beta

ngcompass is currently in beta. Install with @beta to opt in to the prerelease channel.

Quick Start

cd my-angular-app
ngcompass init
ngcompass analyze

Generate a self-contained visual report:

ngcompass analyze --format ui

Run through a project-local install:

npx ngcompass analyze
pnpm exec ngcompass analyze

Output Formats

Command	Output
ngcompass analyze	Default terminal report
ngcompass analyze --format console --compact	Compact one-line issue output
ngcompass analyze --format html --output report.html	Self-contained HTML report
ngcompass analyze --format ui	Interactive HTML report alias
ngcompass analyze --format json > results.json	Machine-readable JSON
ngcompass analyze --format sarif > results.sarif	SARIF for GitHub Code Scanning

Configuration

Create a configuration file:

ngcompass init

This generates ngcompass.config.ts:

import { defineConfig } from '@ngcompass/config';

export default defineConfig({
  extends: 'ngcompass:recommended',

  include: ['src/**/*.ts', 'src/**/*.html'],

  exclude: [
    'node_modules/**',
    'dist/**',
    'build/**',
    'coverage/**',
    '**/*.d.ts',
    '**/*.spec.ts',
    '**/*.test.ts',
  ],

  profiles: {
    ci: {
      outputFormat: 'json',
      maxWarnings: 0,
    },
  },
});

Presets

Preset	Purpose
ngcompass:recommended	Balanced default for most Angular projects
ngcompass:strict	Stronger enforcement for mature codebases
ngcompass:performance	Rendering and change-detection checks
ngcompass:reactivity	Signals and RxJS correctness
ngcompass:security	Security-focused Angular checks
ngcompass:ssr	Server rendering and hydration safety
ngcompass:all	Every built-in rule at its default severity

Override individual rules in the same config:

export default defineConfig({
  extends: ['ngcompass:recommended', 'ngcompass:performance'],
  rules: {
    'prefer-on-push-component-change-detection': 'error',
    'no-document-access': 'warn',
  },
});

Commands

Command	Description
ngcompass init	Create ngcompass.config.ts
ngcompass analyze	Run analysis
ngcompass rules	List available rules
ngcompass rules <name>	Inspect one rule
ngcompass config health	Validate configuration
ngcompass cache info	Show cache status
ngcompass cache clear	Clear cached analysis data
ngcompass cache path	Print the cache directory
ngcompass baseline create	Record existing violations as the baseline
ngcompass baseline update	Refresh counts for the rules and files scanned
ngcompass baseline prune	Lower counts to reality and drop stale entries
ngcompass baseline show	List what the baseline is hiding

Analyze Options

Option	Description
--format <fmt>	console, json, sarif, html, or ui
--output <path>	Output path for HTML/UI reports
--compact	Use compact issue output
-q, --quiet	Show summary counts only
--no-recommendation	Hide fix recommendations
--rule <id>	Run one rule in isolation
--force	Ignore cached results
-p, --profile <name>	Run a named config profile
--max-workers <n>	Limit worker threads
--skip-type-check	Skip rules that require TypeScript type checking
--baseline [path]	Hide violations recorded in a baseline file
--no-baseline	Ignore the configured baseline for this run

Baseline (Gradual Adoption)

Adopting strict rules on an existing codebase usually means thousands of violations on day one. A baseline records what already exists so CI fails only on newly introduced violations.

ngcompass baseline create   # record today's violations
git add .ngcompass/baseline.json

export default {
  baseline: { enabled: true },
};

From then on ngcompass analyze reports only what is new. Existing debt stays silent until someone fixes it:

ngcompass baseline show    # what is currently hidden, worst files first
ngcompass baseline prune   # tighten the baseline after cleanup

The baseline records a count per file and rule, so it survives line shifts and reformatting. Adopt one rule at a time with ngcompass baseline update --rule <id> — entries for other rules are left untouched.

Option	Default	Description
baseline.enabled	false	Apply the baseline during analyze
baseline.path	.ngcompass/baseline.json	Where the baseline lives
baseline.onStale	warn	What to do when violations were fixed: ignore, warn, error

Note that maxWarnings counts warnings after the baseline is applied, so already-recorded warnings no longer consume the budget.

CI

ngcompass exits with code 0 when analysis passes and a non-zero code when configured violations are found.

- name: Run ngcompass
  run: ngcompass analyze --format sarif > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Caching

ngcompass caches file discovery, execution plans, AST work, rule results, and full analysis output. Warm runs can reuse unchanged work instead of parsing and analyzing the entire project again.

ngcompass cache info
ngcompass cache clear
ngcompass analyze --force

Monorepo

Package	Responsibility
ngcompass	CLI entry point
@ngcompass/config	Config loading, validation, profiles, and health checks
@ngcompass/scanner	File discovery and filtering
@ngcompass/rules	Built-in rules, presets, and rule registry
@ngcompass/planner	Incremental execution planning
@ngcompass/engine	Rule execution and analysis orchestration
@ngcompass/ast	TypeScript, template, and style parsing helpers
@ngcompass/cache	Memory and disk cache services
@ngcompass/reporters	Console, JSON, SARIF, and HTML reporters
@ngcompass/common	Shared types and utilities
@ngcompass/site	Documentation site

Development

pnpm install
pnpm build
pnpm test
pnpm typecheck

Additional workspace checks:

pnpm smoke
pnpm validate:packages
pnpm prerelease:check

Requirements

• Node.js ^20.19.0 or >=22.12.0
• Angular v15 or later
• pnpm for repository development

Beta Notes

• Rule names, messages, and report layout may change before 1.0.
• Template analysis is best-effort for highly dynamic templates.
• Validate ngcompass against your project before making it a required CI gate.