ng-checkup 0.3.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 **A one-minute modernization report for any Angular codebase.**
 
-Point it at a repository and it tells you how far the code is from current Angular, what will break on the next upgrade, and where the work is. Eight areas get a grade, every finding names the files, and the HTML report is one self-contained page you can hand to your team lead.
+Point it at a repository and it tells you how far the code is from current Angular, what will break on the next upgrade, and where the work is. Twelve areas get a grade, from the Angular version and third-party packages to security and bundle size, every finding names the files, and the HTML report is one self-contained page you can hand to your team lead.
 
 ```bash
 npx ng-checkup
@@ -22,6 +22,9 @@ npx ng-checkup
 - [Set it up in a project](#set-it-up-in-a-project)
 - [Configuration](#configuration)
 - [Baseline: adopt it on legacy code](#baseline-adopt-it-on-legacy-code)
+- [Watch mode](#watch-mode)
+- [Upgrade plan](#upgrade-plan)
+- [Monorepos](#monorepos)
 - [What it checks](#what-it-checks)
 - [Reports](#reports)
 - [In CI](#in-ci)
@@ -100,6 +103,7 @@ npx ng-checkup init --ci gitlab    # pick the CI instead of detecting it (github
 | `offline` | skip the npm lookup of the latest Angular version | `--offline` |
 | `ignore` | paths left out of the analysis; a path matches everything below it, `*` stays within a folder, `**` crosses folders | |
 | `baseline` | the baseline file, relative to the config file (default `ng-checkup.baseline.json` in the root) | |
+| `plan` | add the upgrade plan to every run | `--plan` |
 
 An unknown key or a wrong type stops the run with an error, so a typo cannot silently switch off a CI threshold. Use `--config path/to/file.json` for a file elsewhere.
 
@@ -118,25 +122,95 @@ Baseline  2 worse
   worse  Type safety: Non-null assertions (x!) 0 → 1
 ```
 
-- **It records counts, not grades:** explicit `any`, `x!`, files in import cycles, components without OnPush or a spec, NgModule-declared components, deprecated API uses and [18 more](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#measures). Lower is better for every one.
+- **It records counts, not grades:** explicit `any`, `x!`, files in import cycles, components without OnPush or a spec, NgModule-declared components, deprecated API uses, sanitizer bypasses, eager routes and [24 more](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#measures). Lower is better for every one.
 - **It only goes down.** When numbers drop, the run says so; `npx ng-checkup baseline` locks the new numbers in. If a number went up, `baseline` refuses and lists it, so a regression cannot be waved through by re-running the command. `--force` accepts it, which is the moment someone has to explain why in review.
 - **It is a plain, sorted JSON file**, so lowering a number is a one-line diff in a merge request.
 - **The gap to the latest Angular is not in it.** That grows when Angular ships, not when the code gets worse.
 
 `ng add ng-checkup` and `npx ng-checkup init` create the first baseline and set CI to `--fail-on regression` for you.
 
+## Watch mode
+
+```bash
+npx ng-checkup --watch
+```
+
+Re-runs on every save and prints, under the usual summary, how the score and every measure moved since the watch started:
+
+```text
+Score 72 -> 76 (+4 since the watch started)
+  down Explicit any: 41 -> 37
+  down Components without OnPush: 12 -> 11
+```
+
+Only the changed files are parsed again, and the registry is asked again only when `package.json` or a lockfile changes, so a run after a save takes a fraction of the first one. Keep it open next to the editor while working through a refactor; run `npx ng-checkup baseline` in another terminal to lock a drop in, and the next run compares against it.
+
+## Upgrade plan
+
+```bash
+npx ng-checkup --plan --report plan.md
+```
+
+`--plan` adds the way from your Angular version to the latest, one major at a time as `ng update` requires:
+
+```text
+Upgrade plan  12 → 22, 10 steps, one major at a time
+  Before you start
+    · Move from TSLint to ESLint  ng add @angular-eslint/schematics
+  → 13  ng update @angular/core@13 @angular/cli@13
+        Node.js ^12.20.0 || ^14.15.0 || >=16.10.0 · TypeScript >=4.4.2 <4.7 (now 4.3.5)
+  ...
+  → 16  ng update @angular/core@16 @angular/cli@16
+        Node.js ^16.14.0 || >=18.10.0 · TypeScript >=4.9.3 <5.2 · zone.js ~0.13.0 (now 0.11.8)
+        · Convert NgModule components to standalone (18)  ng generate @angular/core:standalone
+  → 17  ng update @angular/core@17 @angular/cli@17
+        · Move templates to built-in control flow (13)  ng generate @angular/core:control-flow
+  ...
+```
+
+- **The same for everyone:** each step's `ng update` command (with Material and NgRx when you use them) and the Node.js, TypeScript, RxJS and zone.js ranges that major requires, from the versions' published package metadata. A range your project is outside of today is flagged at the step that has to move it.
+- **Specific to your code:** the migrations your findings call for (standalone, built-in control flow, the esbuild builder, signal inputs, Vitest, zoneless), each scheduled at the first step where Angular ships it, with the number of places it touches. Migrations your code does not need are left out.
+- **No time estimate.** Counts are measured; days would be a guess.
+
+The plan is in every format, including the HTML report ([example](https://stefankuburovic.github.io/ng-checkup/example.html#plan-title)) and the JSON (`report.plan`).
+
+## Monorepos
+
+In an Angular CLI workspace with several projects or an Nx workspace, the report adds a table with one row per project, worst score first (here [nx-examples](https://github.com/nrwl/nx-examples), shortened):
+
+```text
+Projects  5, worst first, graded on their own code
+   65  products            apps/products            poor: Change detection & zoneless readiness, Components & templates, Type safety  fair: State management
+   80  products-home-page  libs/products/home-page  poor: Type safety  fair: Components & templates, State management
+   80  shared-cart-state   libs/shared/cart/state   poor: Type safety  fair: State management
+```
+
+Each project is graded on the files it owns (a nested library keeps its own) with its own tsconfig. The Angular version and the third-party packages are shared, so they are graded once, for the workspace. Projects that import nothing from Angular (React apps, Node services, Cypress e2e folders) get no row.
+
+`--project <name>` narrows the whole report to one project, which is how a team owning one app runs it in CI:
+
+```bash
+npx ng-checkup --project admin --report admin.html
+```
+
+The baseline always covers the whole workspace, so `--project` runs do not compare against it.
+
 ## What it checks
 
 | Area | It looks at | Poor when |
 | --- | --- | --- |
 | [**Angular version & tooling**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#version) | installed vs. latest Angular, mixed `@angular/*` majors, webpack builder, end-of-life packages | three or more majors behind, i.e. out of support |
 | [**Deprecated APIs**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#deprecated-apis) | every imported Angular/NgRx symbol your **installed** version tags `@deprecated`, plus `*ngIf` / `*ngFor` in templates | something deprecated two majors ago is still used |
+| [**Third-party compatibility**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#dependencies) | the `@angular/core` peer range of every installed package (PrimeNG, Kendo, ng-bootstrap, NGXS, ...), the release that supports the next majors, npm deprecations | a package does not accept the installed Angular, or no release supports the latest |
 | [**Change detection**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#change-detection) | zoneless or zone.js, OnPush coverage, `NgZone`, zone-only test helpers | zone.js with less than half the components on OnPush |
 | [**Components & templates**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#components) | standalone, signal inputs and outputs, built-in control flow, `@defer` | average adoption below 40% |
 | [**State management**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#state) | classic NgRx, NgRx signal store, signals, `BehaviorSubject` services | the removed `@Effect()` decorator |
+| [**Architecture**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#architecture) | eager vs. lazy routes (following `loadChildren` into lazy modules), files over 500 and 1 000 lines, constructor injection, class-based guards and interceptors | ten eager routes and none lazy, or three files over 1 000 lines |
 | [**Testing**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#testing) | Karma / Jest / Vitest, specs next to components and services, Protractor / Playwright / Cypress | Karma, Protractor or no specs |
 | [**Type safety**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#type-safety) | `strictNullChecks`, `strictTemplates`, `noImplicitAny`, `any`, `x!`, `@ts-ignore`, `$any()` | both `strictNullChecks` and `strictTemplates` off |
+| [**Security**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#security) | `bypassSecurityTrust*`, HTML written straight into the DOM (`innerHTML =`, `insertAdjacentHTML`, `Renderer2.setProperty`), `eval`, `[innerHTML]` bindings | HTML written into the DOM past the sanitizer, or `eval` |
 | [**Circular dependencies**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#circular-deps) | import cycles through relative paths, barrels and tsconfig `paths` | more than three groups or ten files in loops |
+| [**Bundle size**](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md#bundle) | the initial bundle from the last `ng build --stats-json` (esbuild or webpack) against the build's budget, its largest packages, lazy chunks | over the `initial` error budget (1 MB by default) |
 
 Each finding says why it matters and which `ng generate` migration fixes it. **[Every check, its grading and its fix →](https://github.com/stefankuburovic/ng-checkup/blob/main/docs/checks.md)**
 
@@ -153,6 +227,7 @@ Defaults that changed between versions are applied per version: a component with
 | `npx ng-checkup --report checkup.html` | self-contained page: light and dark mode, prints cleanly to PDF, loads nothing from the network |
 | `npx ng-checkup --report checkup.md` | Markdown for a pull request, an issue or a wiki |
 | `npx ng-checkup --report checkup.json` | everything, machine-readable |
+| `npx ng-checkup --report checkup.sarif` | SARIF 2.1.0 for [GitHub code scanning](#in-ci) and other SARIF viewers |
 | `npx ng-checkup --json` | the JSON on stdout, for piping |
 
 `--report` is repeatable, so one run can write all three files.
@@ -170,9 +245,17 @@ Arguments:
 
 Options:
   -r, --report <file>    Write the full report; format from the extension:
-                         .html, .md or .json. Repeatable.
+                         .html, .md, .json or .sarif (GitHub code scanning).
+                         Repeatable.
       --json             Print the report as JSON to stdout instead of the summary
   -v, --verbose          Print every finding with its files
+      --plan             Add an upgrade plan to the latest Angular, one major
+                         at a time, with the migrations this code needs
+  -p, --project <name>   Analyse one project of an Angular CLI or Nx workspace.
+                         Without it, a multi-project workspace also gets a
+                         per-project table
+  -w, --watch            Re-run on every change and show how the score and the
+                         measures moved since the watch started
       --fail-on <grade>  Exit with code 1 if any area is graded <grade> or worse
                          (poor or fair), or with regression if a measure is
                          worse than the baseline (for CI)
@@ -228,6 +311,26 @@ ng-checkup:
     paths: [checkup.md, checkup.html]
 ```
 
+**GitHub code scanning**
+
+`--report ng-checkup.sarif` writes [SARIF](https://sarifweb.azurewebsites.net/), so findings show up as annotations on the changed lines of a pull request and in the Security tab:
+
+```yaml
+permissions:
+  security-events: write
+steps:
+  - uses: actions/checkout@v4
+  - run: npm ci
+  - run: npx ng-checkup --offline --max-examples 1000 --report ng-checkup.sarif
+  - uses: github/codeql-action/upload-sarif@v3
+    if: always()
+    with:
+      sarif_file: ng-checkup.sarif
+      category: ng-checkup
+```
+
+One rule per area, so alerts survive a rerun; a finding about the whole project (the Angular version, a package that blocks the upgrade) is placed on `package.json`. `--max-examples` decides how many locations each finding reports. Code scanning is free on public repositories and needs GitHub Advanced Security on private ones.
+
 On an existing codebase, start with a [baseline](#baseline-adopt-it-on-legacy-code) and `--fail-on regression`. `--fail-on poor` and `--fail-on fair` are for codebases that are already in good shape and want to stay there.
 
 ## Programmatic API
@@ -247,11 +350,11 @@ for (const check of report.checks) {
 await writeFile('checkup.md', renderMarkdown(report));
 ```
 
-`runCheckup` never writes anything. `renderHtml`, `renderMarkdown`, `overallScore`, `topPriorities`, `loadConfig`, `planInit` (what `init` would change, without writing it) and the baseline functions (`createBaseline`, `compareWithBaseline`, `readBaseline`, `serializeBaseline`) are exported too, along with the `Report`, `CheckResult`, `Finding` and `Grade` types. `Report` is also the schema of the JSON output.
+`runCheckup` never writes anything. Its options mirror the flags (`offline`, `plan`, `project`, `ignore`, `maxExamples`), plus `cache` from `createAnalysisCache()` to make repeated runs incremental. `renderHtml`, `renderMarkdown`, `renderSarif`, `overallScore`, `topPriorities`, `loadConfig`, `planInit` (what `init` would change, without writing it) and the baseline functions (`createBaseline`, `compareWithBaseline`, `readBaseline`, `serializeBaseline`) are exported too, along with the `Report`, `CheckResult`, `Finding` and `Grade` types. `Report` is also the schema of the JSON output.
 
 ## What leaves your machine
 
-One request: the latest `@angular/core` version from the npm registry, with a three-second timeout. `--offline` skips it and compares against the newest major this release knows, and the report says so. No source, no file names, no telemetry. The tool reads files and writes only the reports you ask for.
+Package names, and only to the public npm registry: the latest `@angular/core` version (three-second timeout), and for every installed third-party package that depends on Angular, its public metadata, to find the release that supports the next Angular and whether it is deprecated (eight at a time, four-second timeout each). `--offline` skips all of it: the report then compares against the newest major this release knows and says so. No source, no file names, no telemetry. The tool reads files and writes only the reports you ask for.
 
 ## How it works
 
@@ -269,16 +372,19 @@ One request: the latest `@angular/core` version from the npm registry, with a th
 
 **Is "with a spec" my test coverage?** No. It counts components and services with an `x.spec.ts` next to `x.ts`. It needs no test run, which is what keeps the tool fast and usable on a repository it has never seen.
 
-**Does it support Nx?** Yes: it reads `project.json` targets and tsconfig `paths`. A workspace with several apps is reported as one codebase for now.
+**Does it support Nx?** Yes: it reads `project.json` targets and tsconfig `paths`, and reports [each project separately](#monorepos) as well as the whole workspace.
+
+**Does it need RxJS or NgRx?** No. Checks report what they find: an app without RxJS has nothing for the RxJS deprecations to flag, and one without a state library is graded on signals and services. Other libraries (NGXS, Akita, PrimeNG, Kendo, Material) are covered where it matters for an upgrade, through their Angular peer ranges in the third-party check.
+
+**Why is bundle size "info"?** It reads the stats file of your last build instead of running one. `ng build --stats-json` writes it; run the checkup after that.
 
 **Which Angular versions?** Angular 2 and newer (not AngularJS). Checks whose rules changed between versions (standalone, OnPush, zoneless defaults) apply the rules of the version you run.
 
 ## Roadmap
 
-- Upgrade plan: the steps from your version to the latest, with the migrations each needs
-- Per-project reports for Nx and multi-project workspaces
-- Bundle size from the build's esbuild metafile
-- SARIF output for GitHub code scanning
+- Per-project baselines for monorepos
+- Change frequency from git history, to rank large files by how often they change
+- A VS Code extension showing findings inline
 
 Ideas and bug reports are welcome in [issues](https://github.com/stefankuburovic/ng-checkup/issues).
 

package/dist/angular-versions.d.ts

@@ -0,0 +1,14 @@
+/** What one Angular major requires, from the npm registry. A null field was not published for that major. */
+export interface AngularVersionInfo {
+    major: number;
+    /** The last released version of the major when the snapshot was taken. */
+    version: string;
+    /** Node.js range from @angular/core's `engines`. */
+    node: string | null;
+    /** TypeScript range from @angular/compiler-cli's peer dependency. */
+    typescript: string | null;
+    rxjs: string | null;
+    zoneJs: string | null;
+}
+/** Every Angular major from 4 to the newest, oldest first. */
+export declare const ANGULAR_VERSIONS: AngularVersionInfo[];

package/dist/angular-versions.js

@@ -0,0 +1,157 @@
+// Generated by scripts/update-angular-versions.mjs on 2026-10-20. Do not edit by hand.
+/** Every Angular major from 4 to the newest, oldest first. */
+export const ANGULAR_VERSIONS = [
+    {
+        "major": 4,
+        "version": "4.4.7",
+        "node": null,
+        "typescript": "^2.0.2",
+        "rxjs": "^5.0.1",
+        "zoneJs": "^0.8.4"
+    },
+    {
+        "major": 5,
+        "version": "5.2.11",
+        "node": null,
+        "typescript": ">=2.4.2 <2.7",
+        "rxjs": "^5.5.0",
+        "zoneJs": "^0.8.4"
+    },
+    {
+        "major": 6,
+        "version": "6.1.10",
+        "node": null,
+        "typescript": ">=2.7.2 <2.10",
+        "rxjs": "^6.0.0",
+        "zoneJs": "~0.8.26"
+    },
+    {
+        "major": 7,
+        "version": "7.2.15",
+        "node": null,
+        "typescript": ">=3.1.1 <3.3",
+        "rxjs": "^6.0.0",
+        "zoneJs": "~0.8.26"
+    },
+    {
+        "major": 8,
+        "version": "8.2.14",
+        "node": null,
+        "typescript": ">=3.4 <3.6",
+        "rxjs": "^6.4.0",
+        "zoneJs": "~0.9.1"
+    },
+    {
+        "major": 9,
+        "version": "9.1.13",
+        "node": null,
+        "typescript": ">=3.6 <3.9",
+        "rxjs": "^6.5.3",
+        "zoneJs": "~0.10.3"
+    },
+    {
+        "major": 10,
+        "version": "10.2.5",
+        "node": null,
+        "typescript": ">=3.9 <4.1",
+        "rxjs": "^6.5.3",
+        "zoneJs": "~0.10.3"
+    },
+    {
+        "major": 11,
+        "version": "11.2.14",
+        "node": null,
+        "typescript": ">=4.0 <4.2",
+        "rxjs": "^6.5.3",
+        "zoneJs": "^0.10.2 || ^0.11.3"
+    },
+    {
+        "major": 12,
+        "version": "12.2.17",
+        "node": "^12.14.1 || >=14.0.0",
+        "typescript": ">=4.2.3 <4.4",
+        "rxjs": "^6.5.3 || ^7.0.0",
+        "zoneJs": "~0.11.4"
+    },
+    {
+        "major": 13,
+        "version": "13.4.0",
+        "node": "^12.20.0 || ^14.15.0 || >=16.10.0",
+        "typescript": ">=4.4.2 <4.7",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.11.4"
+    },
+    {
+        "major": 14,
+        "version": "14.3.0",
+        "node": "^14.15.0 || >=16.10.0",
+        "typescript": ">=4.6.2 <4.9",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.11.4 || ~0.12.0"
+    },
+    {
+        "major": 15,
+        "version": "15.2.10",
+        "node": "^14.20.0 || ^16.13.0 || >=18.10.0",
+        "typescript": ">=4.8.2 <5.0",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.11.4 || ~0.12.0 || ~0.13.0"
+    },
+    {
+        "major": 16,
+        "version": "16.2.12",
+        "node": "^16.14.0 || >=18.10.0",
+        "typescript": ">=4.9.3 <5.2",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.13.0"
+    },
+    {
+        "major": 17,
+        "version": "17.3.12",
+        "node": "^18.13.0 || >=20.9.0",
+        "typescript": ">=5.2 <5.5",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.14.0"
+    },
+    {
+        "major": 18,
+        "version": "18.2.14",
+        "node": "^18.19.1 || ^20.11.1 || >=22.0.0",
+        "typescript": ">=5.4 <5.6",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.14.10"
+    },
+    {
+        "major": 19,
+        "version": "19.2.25",
+        "node": "^18.19.1 || ^20.11.1 || >=22.0.0",
+        "typescript": ">=5.5 <5.9",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.15.0"
+    },
+    {
+        "major": 20,
+        "version": "20.3.34",
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
+        "typescript": ">=5.8 <6.0",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.15.0"
+    },
+    {
+        "major": 21,
+        "version": "21.2.25",
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
+        "typescript": ">=5.9 <6.1",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.15.0 || ~0.16.0"
+    },
+    {
+        "major": 22,
+        "version": "22.2.3",
+        "node": "^22.22.3 || ^24.15.0 || >=26.0.0",
+        "typescript": ">=6.0 <6.1",
+        "rxjs": "^6.5.3 || ^7.4.0",
+        "zoneJs": "~0.15.0 || ~0.16.0"
+    }
+];
+//# sourceMappingURL=angular-versions.js.map

package/dist/angular-versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"angular-versions.js","sourceRoot":"","sources":["../src/angular-versions.ts"],"names":[],"mappings":"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"}

package/dist/bundle.d.ts

@@ -0,0 +1,58 @@
+import { type WorkspaceInfo } from './workspace.js';
+/** Default budgets of a new Angular application (`initial`), used when the build target declares none. */
+export declare const DEFAULT_BUDGET: {
+    warning: number;
+    error: number;
+};
+/** What one stats file says about one application's build. */
+export interface BundleStats {
+    /** Project name from the build target, or the folder name when the file was found by searching `dist`. */
+    project: string;
+    /** The stats file, relative to the analysed root. */
+    file: string;
+    format: 'esbuild' | 'webpack';
+    /** When the stats file was written: a stale file describes an old build. ISO 8601. */
+    builtAt: string;
+    /** Bytes the browser loads before the app starts: entry scripts, what they import statically, global styles. */
+    initialBytes: number;
+    lazyChunks: number;
+    lazyBytes: number;
+    /** The largest lazily loaded file. Undefined without lazy chunks. */
+    largestLazy?: {
+        file: string;
+        bytes: number;
+    };
+    /**
+     * Bytes of the initial bundle per npm package, largest first; code outside
+     * `node_modules` is grouped as `(your code)`. Empty when the stats file does
+     * not break outputs down by input (webpack stats without modules).
+     */
+    initialByPackage: Array<{
+        name: string;
+        bytes: number;
+    }>;
+    /** The `initial` budget of the build target's production configuration, else `DEFAULT_BUDGET`. Bytes. */
+    budget: {
+        warning?: number;
+        error?: number;
+    };
+}
+/**
+ * Finds and reads the stats file of every application build.
+ *
+ * `ng build --stats-json` writes `browser-stats.json` (Angular 18 and later)
+ * or `stats.json` (the esbuild builder in 17, and every webpack build) into
+ * the output folder. The folder comes from the build target's `outputPath`,
+ * or `dist/<project>` as the CLI defaults to; without targets, `dist` is
+ * searched two levels deep. Nothing is built: a project that was never built
+ * with `--stats-json` simply has no entry, and a stats file that does not
+ * parse is skipped rather than failing the run.
+ */
+export declare function readBundleStats(workspace: WorkspaceInfo): BundleStats[];
+/** The parts of a stats file that do not depend on where it was found. */
+type ParsedStats = Pick<BundleStats, 'format' | 'initialBytes' | 'lazyChunks' | 'lazyBytes' | 'largestLazy' | 'initialByPackage'>;
+/** Reads either format; undefined for JSON that is neither. Exported for tests. */
+export declare function parseStats(json: unknown): ParsedStats | undefined;
+/** `"500kB"` → 512000, `"1mb"` → 1048576, `"300"` → 300 bytes. Undefined for anything else. */
+export declare function parseSize(value: unknown): number | undefined;
+export {};

package/dist/bundle.js

@@ -0,0 +1,189 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { asRecord } from './workspace.js';
+/** Default budgets of a new Angular application (`initial`), used when the build target declares none. */
+export const DEFAULT_BUDGET = { warning: 500 * 1024, error: 1024 * 1024 };
+/** Builders whose output is a browser bundle with a stats file. */
+const APPLICATION_BUILDERS = /:(application|browser|browser-esbuild)$/;
+/**
+ * Finds and reads the stats file of every application build.
+ *
+ * `ng build --stats-json` writes `browser-stats.json` (Angular 18 and later)
+ * or `stats.json` (the esbuild builder in 17, and every webpack build) into
+ * the output folder. The folder comes from the build target's `outputPath`,
+ * or `dist/<project>` as the CLI defaults to; without targets, `dist` is
+ * searched two levels deep. Nothing is built: a project that was never built
+ * with `--stats-json` simply has no entry, and a stats file that does not
+ * parse is skipped rather than failing the run.
+ */
+export function readBundleStats(workspace) {
+    const builds = workspace.targets.filter((target) => target.target === 'build' && APPLICATION_BUILDERS.test(target.builder));
+    const candidates = builds.map((target) => ({ project: target.project, directory: outputDirectory(workspace.root, target), target }));
+    if (candidates.length === 0) {
+        for (const directory of subdirectories(join(workspace.root, 'dist'), 2))
+            candidates.push({ project: relative(join(workspace.root, 'dist'), directory).split(/[\\/]/).join('/'), directory });
+    }
+    const results = [];
+    const seen = new Set();
+    for (const { project, directory, target } of candidates) {
+        const path = ['browser-stats.json', 'stats.json'].map((name) => join(directory, name)).find((candidate) => existsSync(candidate));
+        if (!path || seen.has(path))
+            continue;
+        seen.add(path);
+        try {
+            const parsed = parseStats(JSON.parse(readFileSync(path, 'utf8')));
+            if (!parsed)
+                continue;
+            results.push({ project, file: relative(workspace.root, path).split(/[\\/]/).join('/'), builtAt: statSync(path).mtime.toISOString(), budget: target ? readInitialBudget(target) : DEFAULT_BUDGET, ...parsed });
+        }
+        catch {
+            // Unreadable or truncated (a build still writing it): no entry.
+        }
+    }
+    return results;
+}
+/** Reads either format; undefined for JSON that is neither. Exported for tests. */
+export function parseStats(json) {
+    const record = asRecord(json);
+    if (typeof record['outputs'] === 'object' && record['outputs'] !== null)
+        return parseEsbuildMetafile(asRecord(record['outputs']));
+    if (Array.isArray(record['assets']) && Array.isArray(record['chunks']))
+        return parseWebpackStats(record);
+    return undefined;
+}
+/**
+ * An esbuild metafile, as the Angular application builder writes it.
+ *
+ * The initial set is computed the way the CLI's "Initial total" is: every
+ * output with an entry point that no other output loads through a dynamic
+ * `import()`, plus everything those reach through static imports. Lazy
+ * routes are entry points too in this format, which is why "has an entry
+ * point" alone would count them as initial. Component CSS files without an
+ * entry point are inlined by Angular and not loaded as files, so they are
+ * left out like the CLI leaves them out.
+ */
+function parseEsbuildMetafile(outputs) {
+    const files = new Map();
+    for (const [name, value] of Object.entries(outputs)) {
+        if (name.endsWith('.map'))
+            continue;
+        const output = asRecord(value);
+        const imports = (Array.isArray(output['imports']) ? output['imports'] : []).map((entry) => asRecord(entry)).map((entry) => ({ path: String(entry['path']), kind: String(entry['kind']) }));
+        const inputs = Object.fromEntries(Object.entries(asRecord(output['inputs'])).map(([input, data]) => [input, Number(asRecord(data)['bytesInOutput']) || 0]));
+        files.set(name, { bytes: Number(output['bytes']) || 0, entryPoint: typeof output['entryPoint'] === 'string' ? output['entryPoint'] : undefined, imports, inputs });
+    }
+    const dynamicTargets = new Set([...files.values()].flatMap((file) => file.imports.filter((entry) => entry.kind === 'dynamic-import').map((entry) => entry.path)));
+    const initial = new Set();
+    const queue = [...files.entries()].filter(([name, file]) => file.entryPoint !== undefined && !dynamicTargets.has(name)).map(([name]) => name);
+    while (queue.length > 0) {
+        const name = queue.pop();
+        if (initial.has(name) || !files.has(name))
+            continue;
+        initial.add(name);
+        for (const entry of files.get(name).imports)
+            if (entry.kind === 'import-statement')
+                queue.push(entry.path);
+    }
+    const lazy = [...files.entries()].filter(([name]) => !initial.has(name) && name.endsWith('.js'));
+    const byPackage = new Map();
+    for (const name of initial) {
+        for (const [input, bytes] of Object.entries(files.get(name).inputs)) {
+            const owner = packageOf(input);
+            if (owner)
+                byPackage.set(owner, (byPackage.get(owner) ?? 0) + bytes);
+        }
+    }
+    return summarise('esbuild', [...initial].reduce((sum, name) => sum + files.get(name).bytes, 0), lazy.map(([file, data]) => ({ file, bytes: data.bytes })), byPackage);
+}
+/**
+ * Webpack stats (`--stats-json` with the browser builder, Angular 16 and
+ * earlier). Chunks marked `initial` hold the initial files; every other
+ * `.js` asset is lazy. Packages come from `modules` when the stats include
+ * them, which Angular's do.
+ */
+function parseWebpackStats(stats) {
+    const assets = new Map(stats['assets'].map((entry) => asRecord(entry)).map((asset) => [String(asset['name']), Number(asset['size']) || 0]));
+    const chunks = stats['chunks'].map((entry) => asRecord(entry));
+    const initialChunkIds = new Set(chunks.filter((chunk) => chunk['initial'] === true).map((chunk) => String(chunk['id'])));
+    const initialFiles = new Set(chunks.filter((chunk) => chunk['initial'] === true).flatMap((chunk) => (Array.isArray(chunk['files']) ? chunk['files'].map(String) : [])).filter((file) => /\.(js|css)$/.test(file)));
+    const lazy = [...assets.entries()].filter(([name]) => name.endsWith('.js') && !initialFiles.has(name)).map(([file, bytes]) => ({ file, bytes }));
+    const byPackage = new Map();
+    for (const module of Array.isArray(stats['modules']) ? stats['modules'].map((entry) => asRecord(entry)) : []) {
+        const inInitial = Array.isArray(module['chunks']) && module['chunks'].some((id) => initialChunkIds.has(String(id)));
+        const owner = inInitial ? packageOf(String(module['name'] ?? '')) : undefined;
+        if (owner)
+            byPackage.set(owner, (byPackage.get(owner) ?? 0) + (Number(module['size']) || 0));
+    }
+    return summarise('webpack', [...initialFiles].reduce((sum, file) => sum + (assets.get(file) ?? 0), 0), lazy, byPackage);
+}
+/** The shared tail of both parsers. */
+function summarise(format, initialBytes, lazy, byPackage) {
+    const largestLazy = [...lazy].sort((left, right) => right.bytes - left.bytes)[0];
+    return {
+        format,
+        initialBytes,
+        lazyChunks: lazy.length,
+        lazyBytes: lazy.reduce((sum, file) => sum + file.bytes, 0),
+        ...(largestLazy ? { largestLazy } : {}),
+        initialByPackage: [...byPackage.entries()].map(([name, bytes]) => ({ name, bytes })).filter((entry) => entry.bytes > 0).sort((left, right) => right.bytes - left.bytes),
+    };
+}
+/**
+ * The npm package an input path belongs to (`@angular/core`, `rxjs`), or
+ * `(your code)` for anything outside `node_modules`. Undefined for the
+ * builder's virtual inputs (`angular:…`, `<runtime>`), which no one can act on.
+ */
+function packageOf(input) {
+    const path = input.replace(/\\/g, '/').replace(/^\.\//, '');
+    const index = path.lastIndexOf('node_modules/');
+    if (index >= 0) {
+        const parts = path.slice(index + 'node_modules/'.length).split('/');
+        return parts[0]?.startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0];
+    }
+    if (path.startsWith('angular:') || path.startsWith('<') || path === '')
+        return undefined;
+    return '(your code)';
+}
+/** The build output folder: `outputPath` as a string or `{ base }`, else the CLI default `dist/<project>`. */
+function outputDirectory(root, target) {
+    const option = target.options['outputPath'];
+    const base = typeof option === 'string' ? option : typeof asRecord(option)['base'] === 'string' ? asRecord(option)['base'] : `dist/${target.project}`;
+    return resolve(target.baseDirectory || root, base);
+}
+/**
+ * The `initial` budget of the production configuration. Angular reads
+ * `kb` and `mb` as binary units (1 kB = 1024 bytes), so this does too.
+ * Absent when the target has no production configuration or no `initial`
+ * budget; `DEFAULT_BUDGET` then applies.
+ */
+function readInitialBudget(target) {
+    const budgets = asRecord(asRecord(target.configurations)['production'])['budgets'];
+    const initial = Array.isArray(budgets) ? budgets.map((entry) => asRecord(entry)).find((budget) => budget['type'] === 'initial') : undefined;
+    if (!initial)
+        return DEFAULT_BUDGET;
+    return { warning: parseSize(initial['maximumWarning']), error: parseSize(initial['maximumError']) };
+}
+/** `"500kB"` → 512000, `"1mb"` → 1048576, `"300"` → 300 bytes. Undefined for anything else. */
+export function parseSize(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?\s*$/i.exec(value);
+    if (!match)
+        return undefined;
+    const factor = { b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3 }[(match[2] ?? 'b').toLowerCase()];
+    return Math.round(Number(match[1]) * factor);
+}
+/** Directories under `directory` down to `depth` levels, deepest last. Empty when it does not exist. */
+function subdirectories(directory, depth) {
+    if (depth === 0 || !existsSync(directory))
+        return [];
+    const found = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const path = join(directory, entry.name);
+        found.push(path, ...subdirectories(path, depth - 1));
+    }
+    return found;
+}
+//# sourceMappingURL=bundle.js.map