----
-
-## What is ngcompass?
+## Overview
-ngcompass is a **command-line static analysis tool** built specifically for Angular projects. It scans your codebase without running it — reading your TypeScript, templates, and configuration files — and reports issues across four key areas:
+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.
-| Category | What it checks |
-|---|---|
-| **Architecture** | Module boundaries, circular dependencies, improper component relationships |
-| **Performance** | Missing `OnPush`, untracked subscriptions, heavy template expressions |
-| **SSR Compatibility** | Browser-only APIs used in universal code, hydration pitfalls |
-| **Code Quality** | Deprecated APIs, naming conventions, dead code, missing best practices |
+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.
-Think of it as **ESLint — but Angular-aware**. It understands the relationship between components, services, templates, and modules at a deeper level than generic TypeScript linters.
+## 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:
+
```bash
-# npm
npm install -g ngcompass@beta
+```
-# pnpm
-pnpm add -g ngcompass@beta
+Or add it to a project:
+
+```bash
+npm install --save-dev ngcompass@beta
```
-> This is a **beta release**. Install with `@beta` to opt in.
+Using pnpm:
+
+```bash
+pnpm add -D ngcompass@beta
+```
----
+> ngcompass is currently in beta. Install with `@beta` to opt in to the prerelease channel.
## Quick Start
```bash
-# 1. Go to your Angular project
cd my-angular-app
-
-# 2. Initialize configuration
ngcompass init
-
-# 3. Run analysis
ngcompass analyze
```
-That's it. ngcompass will scan your project and print a report to the terminal.
-
-For a visual report with search, filters, and per-file details, run:
+Generate a self-contained visual report:
```bash
ngcompass analyze --format ui
```
----
-
-## Output Formats
-
-ngcompass can output results in multiple formats depending on your workflow:
+Run through a project-local install:
```bash
-# Terminal output (default)
-ngcompass analyze
+npx ngcompass analyze
+pnpm exec ngcompass analyze
+```
-# Compact ESLint-style output (great for CI logs)
-ngcompass analyze --format console --compact
+## Output Formats
-# HTML report written to a file (default: ngcompass-report.html)
-ngcompass analyze --format html
-ngcompass analyze --format html --output my-report.html
+| 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 |
-# Interactive UI report (alias for html — same output)
-ngcompass analyze --format ui
+## Configuration
-# Machine-readable JSON
-ngcompass analyze --format json > results.json
+Create a configuration file:
-# SARIF for GitHub Code Scanning
-ngcompass analyze --format sarif > results.sarif
+```bash
+ngcompass init
```
-The HTML/UI report gives you a full visual breakdown — severity charts, per-file drill-down, search and filter — all in a single self-contained file.
-
----
-
-## Configuration
-
-Run `ngcompass init` to generate `ngcompass.config.ts` in your project root:
+This generates `ngcompass.config.ts`:
```ts
import { defineConfig } from '@ngcompass/config';
export default defineConfig({
- // Start from a preset: 'ngcompass:recommended' | 'ngcompass:strict' | 'ngcompass:performance' | 'ngcompass:reactivity' | 'ngcompass:all'
extends: 'ngcompass:recommended',
- // Files to scan
- include: [
- 'src/**/*.ts',
- 'src/**/*.html',
- ],
+ include: ['src/**/*.ts', 'src/**/*.html'],
exclude: [
'node_modules/**',
@@ -121,179 +108,137 @@ export default defineConfig({
'**/*.test.ts',
],
- // Override individual rules
- rules: {
- 'prefer-on-push-component-change-detection': 'error',
- 'no-document-access': 'warn',
+ profiles: {
+ ci: {
+ outputFormat: 'json',
+ maxWarnings: 0,
+ },
},
});
```
### Presets
-| Preset | Description |
+| Preset | Purpose |
|---|---|
-| `ngcompass:recommended` | Balanced set of rules for most Angular projects |
-| `ngcompass:strict` | Stricter checks including all recommended rules |
-| `ngcompass:performance` | Focus on rendering performance and change detection |
-| `ngcompass:reactivity` | Signals correctness and RxJS-to-Signals migration rules |
-| `ngcompass:all` | Every built-in rule enabled at its default severity |
-
-### Supported Rules
+| `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 |
-Run `ngcompass rules` to inspect the same list from the CLI.
-
-| Category | Rules |
-|---|---|
-| Correctness | `component-no-manual-detect-changes`, `signal-no-side-effects-in-computed`, `signal-effect-must-be-destroy-scoped`, `rxjs-no-nested-subscribe` |
-| Performance | `prefer-on-push-component-change-detection`, `template-no-call-expression`, `template-trackby-required`, `template-no-object-literal-binding`, `template-no-array-literal-binding` |
-| Security | `no-bypass-sanitization`, `template-no-unsafe-bindings` |
-| SSR | `no-document-access`, `prefer-after-render-over-after-view-init` |
-| Reactivity | `rxjs-no-subscribe-in-component`, `rxjs-require-takeUntilDestroyed`, `rxjs-avoid-subject-as-event-bus`, `rxjs-prefer-toSignal-for-template-state`, `toSignal-require-initialValue`, `signal-prefer-computed-over-sync-effect`, `signal-avoid-untracked-overuse` |
-| Modern API | `prefer-inject-over-constructor-di`, `signal-prefer-input-signal`, `signal-prefer-output-function`, `signal-prefer-model` |
-| Template | `template-prefer-control-flow`, `template-no-async-pipe-duplication` |
-| Testing | `spec-no-focused-test` |
+Override individual rules in the same config:
----
+```ts
+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` | Generate a `ngcompass.config.ts` in the current directory |
-| `ngcompass analyze` | Run analysis on the project |
-| `ngcompass config health` | Validate the current configuration |
-| `ngcompass rules` | List all available rules |
-| `ngcompass rules 
