ngcompass

Reference

Configuration.

ngcompass is configured via ngcompass.config.ts in your project root. Run ng add ngcompass to install locally and generate a starter config. Run npx ngcompass config health to validate it.

Full example

ngcompass.config.ts
01import { defineConfig } from '@ngcompass/config';
02

03export default defineConfig({
04  // Preset to extend (string or array of strings)
05  extends: 'ngcompass:recommended',
06

07  // Angular version override - auto-detected when omitted
08  angularVersion: '17.2',   // "17" or "17.2", no range prefixes
09

10  // Files to scan
11  include: [
12    'src/**/*.ts',
13    'src/**/*.html',
14  ],
15  exclude: [
16    'node_modules/**',
17    'dist/**',
18    'build/**',
19    'coverage/**',
20    '**/*.d.ts',
21    '**/*.spec.ts',
22    '**/*.test.ts',
23  ],
24

25  // Rule overrides - 'off' | 'warn' | 'error'
26  rules: {
27    'prefer-on-push-component-change-detection': 'error',
28    'no-document-access': 'warn',
29    'rxjs-no-subscribe-in-component': 'error',
30    'template-prefer-control-flow': 'warn',
31    'spec-no-focused-test': 'off',
32  },
33

34  // Severity threshold for non-zero exit
35  failOnSeverity: 'error',    // 'warn' | 'error'
36  maxWarnings: 10,            // fail if warnings exceed this
37

38  // Baseline - record existing violations, gate only new ones
39  baseline: {
40    enabled: false,
41    path: '.ngcompass/baseline.json',
42    onStale: 'warn',          // 'ignore' | 'warn' | 'error'
43  },
44

45  // Cache settings
46  cache: {
47    enabled: true,
48    strategy: 'local',        // 'memory' | 'local'
49    location: 'node_modules/.cache/ngcompass',
50    ttl: 86400000,            // 24 hours in ms
51  },
52

53  // Concurrency (default: CPU count - 1)
54  maxWorkers: 4,
55

56  // Output defaults (can be overridden on the CLI)
57  outputFormat: 'console',    // 'console' | 'json' | 'sarif' | 'html'
58  outputPath: 'ngcompass-report.html',
59

60  // Per-file-pattern overrides
61  overrides: [
62    {
63      files: ['src/app/legacy/**/*.ts'],
64      rules: {
65        'prefer-inject-over-constructor-di': 'off',
66      },
67    },
68  ],
69

70  // Named profiles - activate with --profile <name>
71  profiles: {
72    ci: {
73      failOnSeverity: 'warn',
74      rules: {
75        'spec-no-focused-test': 'error',
76      },
77    },
78  },
79

80  // TypeScript project reference
81  parserOptions: {
82    project: './tsconfig.json',
83    tsconfigRootDir: '.',
84  },
85});

Options reference

  • extendsstring | string[]

    Preset or array of presets to extend. See the Presets page for available values.

  • angularVersionstringdefault auto-detected

    Angular version used for version-aware rule selection. Accepts "17" or "17.2" — a plain major or major.minor number, without a range prefix such as ^ or >=. Auto-detected from your project when omitted.

  • includestring[]default "src/**/*.ts"

    Glob patterns for files to analyze.

  • excludestring[]default "**/*.spec.ts"

    Glob patterns to exclude. Spec and stories files are excluded by default.

  • rulesRecord<ruleId, severity>

    Per-rule severity overrides. Values: "off" | "warn" | "error". Can also accept an object with { severity, options }.

  • failOnSeverity"warn" | "error"default "error"

    Exit with a non-zero code when violations at this severity or above are found.

  • maxWarningsnumberdefault 10

    Maximum allowed warnings before the process exits with a non-zero code.

  • cacheboolean | CacheOptionsdefault true

    Enable or configure incremental caching. When true, uses local disk cache in node_modules/.cache/ngcompass with a 24h TTL.

  • baselineboolean | BaselineOptionsdefault false

    Hide violations recorded in a baseline file so only new ones are reported. Accepts { enabled, path, onStale }. See the Baseline page.

  • maxWorkersnumberdefault CPU count - 1

    Maximum worker threads for parallel analysis. Syntax-only rules run in workers; type-aware rules serialize on the main thread.

  • outputFormat"console" | "json" | "sarif" | "html"default "console"

    Default output format. Overridden by --format on the CLI.

  • outputPathstringdefault "ngcompass-report.html"

    Path for the UI/HTML report file.

  • overridesOverride[]

    File-pattern-scoped rule overrides. Each entry has a files glob array and a rules object.

  • profilesRecord<name, PartialConfig>

    Named partial configs. Activate with --profile <name> on the CLI.

  • ignorePatternsstring[]

    Additional glob patterns to ignore beyond exclude.

  • parserOptionsParserOptions

    TypeScript project options. Accepts project, tsconfigRootDir, sourceType, and ecmaVersion.

Angular version awareness

Some rules only make sense from a certain Angular version onwards — template-prefer-control-flow has nothing to suggest before @if existed in Angular 17, and signal-prefer-model needs model()from 17.2. Every rule declares the version it applies from, and ngcompass resolves your project's Angular version before selecting rules. The Rules page lists the floor for each rule.

The version is resolved in this order, first match wins:

  • angularVersionconfig

    The value you set in ngcompass.config.ts. Use this when detection cannot see your Angular packages — for example in a monorepo where the config sits outside the Angular workspace.

  • @angular/coreinstalled

    The version field of the installed node_modules/@angular/core/package.json, searched upwards from the config file. This is the most accurate source because it is the Angular you actually compile against.

  • package.jsondeclared

    The @angular/core specifier declared in dependencies, devDependencies, or peerDependencies. Range prefixes such as ^ and >= are stripped, so ^17.2.0 resolves to 17.2.

  • unknownfallback

    No installed Angular and no usable specifier. ngcompass reports this and runs every rule rather than guessing.

Once resolved, rule selection follows three rules:

  • Below the floor

    A rule whose minimum Angular version is newer than your project is skipped. The run reports how many rules were skipped; --debug lists them by name.

  • Explicitly configured

    A rule you name yourself in the rules block always runs, even below its floor. Your config wins over the version gate.

  • Version unknown

    When the Angular version cannot be resolved, no rule is gated — every rule runs, and the CLI suggests setting angularVersion.

ngcompass.config.ts
01export default defineConfig({
02  extends: 'ngcompass:recommended',
03

04  // Pin the version instead of relying on detection
05  angularVersion: '16.2',
06

07  rules: {
08    // Runs anyway, even though it is gated at Angular 17.2 -
09    // explicit configuration overrides the version gate
10    'signal-prefer-model': 'warn',
11  },
12});

File-pattern overrides

Use overrides to apply different rule severities to specific file patterns — useful for legacy code or generated files.

typescript
01overrides: [
02  {
03    files: ['src/app/legacy/**/*.ts'],
04    rules: {
05      'prefer-inject-over-constructor-di': 'off',
06      'prefer-on-push-component-change-detection': 'warn',
07    },
08  },
09],

Profiles

Profiles let you define partial config overrides that you activate with the --profile <name> flag. Useful for running stricter rules in CI than locally.

typescript
01profiles: {
02  ci: {
03    failOnSeverity: 'warn',
04    maxWarnings: 0,
05    rules: {
06      'spec-no-focused-test': 'error',
07    },
08  },
09  local: {
10    failOnSeverity: 'error',
11  },
12},

Activate a profile:

bash
01npx ngcompass analyze --profile ci

Validate your config

bash
01npx ngcompass config health

Validates the active config, reports unknown rule IDs, invalid severity values, and schema errors.

CLI flags reference

Flags passed on the command line override the equivalent config-file settings for that run only.

  • --profile <name>

    Activate a named profile defined in the profiles config key.

  • --format <fmt>

    Output format for this run: console | json | sarif | html | ui (ui is an alias for html). Overrides outputFormat from config.

  • --compact

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

  • -q, --quiet

    Show summary counts only — suppress individual violation details. Useful in CI when you only care about pass/fail.

  • --no-recommendation

    Suppress fix recommendations from output. Violations are still reported; only the fix hint line is hidden.

  • --output <path>

    Output path for HTML reports. Overrides outputPath from config.

  • --force

    Ignore cached results and re-run all checks. Results are not written back to cache.

  • --rule <id>

    Run only a single rule by ID. Useful for debugging or focused checks on one pattern.

  • --max-workers <n>number

    Cap the number of worker threads. Lower values use less memory (e.g. --max-workers 2). Overrides maxWorkers from config.

  • --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.

  • --skip-type-check

    Skip rules that require the TypeScript type checker. Fastest mode with lowest memory usage — syntax-only rules still run.