angular-compat-matrix 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nizamudeen S
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# angular-compat-matrix
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Which Angular versions does your published library really work with?
+
+Run it with `npx angular-compat-matrix`, or install the package and run `ng-matrix`: both names start the same command.
+
+ng-matrix builds and packs your Angular library, installs the tarball the way a user would into a fresh app for each Angular major (made with that major's own CLI), builds it, and reports a matrix. It tests the package your users get, not the source you see.
+
+```
+$ npx angular-compat-matrix
+
+my-dropdown@3.0.0 (compiled with Angular 21.2.0; highest minVersion 20.0.0)
+
+            peer range  install  partial  AOT build  strict types
+Angular 19      ✓          ✓        ✗         —           —
+Angular 20      ✓          ✓        ✓         ✓           ✗
+Angular 21      ✓          ✓        ✓         ✓           ✓
+Angular 22      ✗          ✓        ✓         ✓           ✓
+
+✗ 19: partial: Needs Angular 20.0.0 or later: highest minVersion 20.0.0, in
+  MyDropdownComponent. Build the library with the oldest Angular you support, or take
+  this version out of the peer range.
+✗ 20: strict types: A template using the package type-checks only loosely…
+! 22: works, but peerDependencies doesn't allow it (@angular/core "^19.0.0 || ^20.0.0 ||
+  ^21.0.0"). Widen the range to include it.
+```
+
+## Usage
+
+Run it in your library's workspace: an Angular CLI workspace with a library project, or a folder with `ng-package.json`.
+
+```sh
+npx angular-compat-matrix                        # supported majors plus every major your peer range claims
+npx angular-compat-matrix --versions 18-22       # an explicit range (or 22, or 20,22)
+npx angular-compat-matrix --project my-lib       # one library in a workspace with several
+npx angular-compat-matrix --consumer ./example   # build your own example app instead of a generated one
+npx angular-compat-matrix --tests                # also run your library's tests on each version
+npx angular-compat-matrix --pm pnpm              # npm (default) or pnpm
+npx angular-compat-matrix --format markdown      # a table for your README; also json
+npx angular-compat-matrix --package some-lib@3   # check a published package instead of building
+```
+
+`npx angular-compat-matrix --help` lists every option.
+
+**Exit code:** 1 when a version inside your peer range fails, so CI goes red only for broken promises. A version outside the range that fails is a note. 2 means ng-matrix couldn't check a version at all.
+
+**Node:** ng-matrix runs every Angular version on the Node it runs on, and stops early if that Node is too old for one of them. Node 24.15 or later covers Angular 17 to 22. Angular's `engines` ranges only set minimums; [Angular's own support table](https://angular.dev/reference/versions) is narrower.
+
+## What it checks
+
+For each Angular major, in order. A failure marks the later checks `—`, so the first real failure is the one reported. The peer range is reported but never stops the other checks.
+
+| Check | Question | How |
+| --- | --- | --- |
+| Peer range | Does the package claim this version? | Every `@angular/*` peer is compared, not just `core`: a CDK range can leave a version out too |
+| Install | Does it install in a fresh app without peer conflicts? | npm: `--legacy-peer-deps` with the peers added explicitly, then `npm ls` reports every invalid peer. pnpm: `strict-peer-dependencies`. For a version the range doesn't claim, only that expected conflict is ignored |
+| Partial | Can this version's linker load the compiled code? | The highest `minVersion` in the package's `ɵɵngDeclare…` calls. ✗ is proof; ✓ is only advisory (`✓?`) when the package was compiled with a newer major, because `minVersion` has been too low before |
+| AOT build | Does a production build of an app using it succeed? | `ng build` of a smoke app that uses every public export, with `strictTemplates: false` and no size budgets |
+| Strict types | Do templates using it type-check? | The same build with `strictTemplates: true` and `skipLibCheck: false`, which also catches typings that use types an older `@angular/core` lacks |
+| Tests | Do your own tests pass on this version? | With `--tests`: your test command in a copy of your workspace, with Angular swapped to this version |
+
+### Why build, when there's minVersion?
+
+The Angular compiler writes a `minVersion` into each compiled declaration: the oldest Angular whose linker can handle the features it uses. It's set per feature, not from the Angular that compiled the code, and it has been too low more than once. Angular 16.1's input transforms broke 16.0 apps ([angular/angular#51413](https://github.com/angular/angular/pull/51413)). In Angular 22, factory declarations claim `minVersion: "12.0.0"` while using `ɵɵFactoryTarget.Service`, which only 22 has; an Angular 21 linker crashes on them with `Unsupported enum value`. So `minVersion` can prove a version fails, never that it works.
+
+### The smoke app
+
+ng-matrix reads your package's typings, where Angular records each declaration's selector, inputs and standalone flag. It writes a small app that:
+
+- imports every entry point in your `exports` map, and installs your optional peers too, since some entry point may need them
+- uses each component, directive and pipe once, each in a component of its own (as an app would), with a correctly typed value for every required input
+- writes attribute selectors that take a boolean or string bare (`<div myFlag>`), the way users do, and binds the rest
+- imports each NgModule and uses what it exports, and injects your services
+
+If your library needs more setup than that (providers, content, a parent component), give ng-matrix an example app with `--consumer`. It's copied, its Angular dependencies are moved to each version, and your package is installed from the tarball.
+
+## In CI
+
+A GitHub Actions job that checks the supported majors on every push:
+
+```yaml
+jobs:
+  angular-matrix:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - run: npm ci
+      - run: npx angular-compat-matrix --format markdown >> "$GITHUB_STEP_SUMMARY"
+```
+
+(`ng-matrix ci github`, which writes a workflow with one job per Angular version, is coming in v0.2.)
+
+## Where version data comes from
+
+Nothing about Angular's versions is hard-coded. It all comes from the npm registry when ng-matrix runs, and is cached for a day (`--offline` reuses the cache):
+
+- **Majors:** the published `@angular/core` versions, latest patch of each. A major counts as supported for 18 months after its x.0.0 release. `--next` adds whatever the `next` tag points to, which may be a minor pre-release.
+- **Node:** the `engines` of that version's `@angular/core` and `@angular/cli`.
+- **TypeScript** (for `--tests`): `@angular/compiler-cli`'s peer range. **RxJS and zone.js:** `@angular/core`'s.
+- **Your other peers** (Material, CDK…): the newest version whose own peer ranges accept that Angular.
+
+## Scope of v0.1
+
+In: Angular CLI workspaces and standalone ng-packagr libraries; npm 11 and a pinned pnpm (12.15.0); the six checks; terminal, Markdown and JSON output.
+
+Coming in v0.2: Nx workspaces (for now, run ng-matrix in the library folder with `--build "npx nx build my-lib"`), `ng-matrix ci github`, and SSR and with-zone.js columns.
+
+Not planned: Yarn and Bun (the JSON output makes them easy to add), checking apps for upgrade readiness, and anything that only shows up at runtime in a browser.
+
+## Development
+
+```sh
+npm install
+npm test                       # unit tests, against recorded registry answers
+npm run build
+npm ci --prefix fixtures       # the Angular 22 toolchain the fixture libraries build with
+node test/fixtures/run.ts      # every fixture case (or name one, e.g. healthy-npm)
+```
+
+`fixtures/libs` holds small libraries that each fail exactly one check: a feature newer than an older claimed major, a `minVersion` that's too low, peer ranges narrower and wider than reality, a CDK peer that leaves a version out, a type error only strict templates catch, typings only `skipLibCheck: false` catches, a kit over the default size budget, full compilation output, and tests that use a newer API. `fixtures/workspaces/cli-workspace` is an Angular CLI workspace, and `fixtures/consumers/healthy-example` an example app for `--consumer`. The suite also checks published packages: Angular Material 22, angular2-multiselect-dropdown 10, ngx-toastr and angular-calendar. [docs/real-world-round.md](docs/real-world-round.md) has the results of a run against 15 popular libraries.
+
+## License
+
+MIT © 2026 Nizamudeen S

package/dist/app.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { errorLines, exec, quietEnv } from "./exec.js";
+import { binOf, ensureTool } from "./tools.js";
+/** One flag set that works, without prompts, for every CLI from 17 to 22. */
+export function newAppArgs(pm) {
+    return [
+        'new',
+        'smoke',
+        '--minimal',
+        '--skip-git',
+        '--skip-install',
+        '--defaults',
+        '--interactive=false',
+        '--ssr=false',
+        `--package-manager=${pm}`,
+    ];
+}
+export async function generateApp(angular, pm, parentDir, cacheDir, offline) {
+    const cli = await ensureTool(cacheDir, '@angular/cli', angular.cliVersion, offline);
+    const result = await exec(process.execPath, [binOf(cli, 'ng'), ...newAppArgs(pm)], {
+        cwd: parentDir,
+        env: quietEnv({ CI: '1' }),
+        timeoutMs: 10 * 60_000,
+    });
+    const appDir = join(parentDir, 'smoke');
+    if (result.code !== 0 || !existsSync(join(appDir, 'angular.json'))) {
+        throw new Error(`ng new (Angular CLI ${angular.cliVersion}) failed:\n${errorLines(result.output).join('\n')}`);
+    }
+    return appDir;
+}
+export function readJson(path) {
+    // Generated tsconfig files start with /* comments */; JSON.parse can't take them.
+    const text = readFileSync(path, 'utf8').replace(/^\s*\/\*[\s\S]*?\*\/\s*/gm, '').replace(/^\s*\/\/.*$/gm, '');
+    return JSON.parse(text);
+}
+export function writeJson(path, value) {
+    writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+}
+/** The app project in angular.json: the generated one, or the first application of a --consumer app. */
+export function appProject(appDir) {
+    const workspace = readJson(join(appDir, 'angular.json'));
+    const entry = Object.entries(workspace.projects).find(([, p]) => (p.projectType ?? 'application') === 'application');
+    if (!entry)
+        throw new Error(`${appDir}/angular.json has no application project.`);
+    const [name, project] = entry;
+    const tsConfig = String(project.architect?.build?.options?.tsConfig ?? 'tsconfig.app.json');
+    return { name, tsConfig };
+}
+/**
+ * Points the build at ng-matrix's own tsconfig (and, for a generated app, its own main file),
+ * and removes the production budgets so a large component kit doesn't fail the build on size.
+ */
+export function configureBuild(appDir, mainFile) {
+    const path = join(appDir, 'angular.json');
+    const workspace = readJson(path);
+    const project = appProject(appDir);
+    const build = workspace.projects[project.name].architect.build;
+    build.options ??= {};
+    if (mainFile) {
+        // `browser` for the application builder (17+), `main` for the older webpack one.
+        if ('main' in build.options && !('browser' in build.options))
+            build.options.main = mainFile;
+        else
+            build.options.browser = mainFile;
+    }
+    build.options.tsConfig = 'tsconfig.ngm.json';
+    for (const configuration of Object.values(build.configurations ?? {})) {
+        if ('budgets' in configuration)
+            configuration.budgets = [];
+    }
+    writeJson(path, workspace);
+    return project;
+}
+/**
+ * Writes tsconfig.ngm.json extending the app's own tsconfig, with the template strictness set
+ * explicitly: Angular 17 to 21 apps write strictTemplates: true, and 22 makes it the default.
+ */
+export function writeTsconfig(appDir, baseTsConfig, mode, files) {
+    const config = {
+        extends: `./${baseTsConfig.replace(/^\.\//, '')}`,
+        compilerOptions: { skipLibCheck: mode.skipLibCheck },
+        angularCompilerOptions: { strictTemplates: mode.strictTemplates },
+    };
+    if (files) {
+        config.files = files;
+        config.include = [];
+    }
+    writeJson(join(appDir, 'tsconfig.ngm.json'), config);
+}

package/dist/build.js

@@ -0,0 +1,46 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { writeTsconfig } from "./app.js";
+import { errorLines, exec, quietEnv } from "./exec.js";
+export async function ngBuild(appDir, baseTsConfig, mode, files) {
+    writeTsconfig(appDir, baseTsConfig, mode, files);
+    const require = createRequire(join(appDir, 'package.json'));
+    const cliManifest = require.resolve('@angular/cli/package.json');
+    const ng = join(dirname(cliManifest), 'bin', 'ng.js');
+    const result = await exec(process.execPath, [ng, 'build', '--configuration', 'production'], {
+        cwd: appDir,
+        env: quietEnv({ CI: '1' }),
+        timeoutMs: 20 * 60_000,
+    });
+    if (result.code === 0)
+        return { pass: true, errorLines: [], durationMs: result.durationMs };
+    const lines = result.timedOut ? ['The build timed out after 20 minutes.'] : errorLines(result.output);
+    return { pass: false, errorLines: lines, hint: hintFor(result.output), durationMs: result.durationMs };
+}
+/** Plain-language explanations for build failures whose messages don't say what's wrong. */
+export function hintFor(output) {
+    if (/Unsupported enum value|Cannot create property 'message' on string/.test(output)) {
+        return 'The compiled code uses features newer than this Angular, though its minVersion says otherwise: the linker crashed on it. Build the library with the oldest Angular you support.';
+    }
+    const linker = /depends upon a library published using Angular version ([\d.]+), which requires Angular version ([\d.]+) or newer/.exec(output);
+    if (linker) {
+        return `The package was compiled with Angular ${linker[1]} and needs Angular ${linker[2]} or newer. Build it with the oldest Angular you support.`;
+    }
+    const missing = /No matching export in "[^"]*node_modules[\\/](@angular[\\/][\w-]+)[^"]*" for import "([\w$ɵ]+)"/.exec(output);
+    if (missing) {
+        return `The package imports ${missing[2]} from ${missing[1].replace('\\', '/')}, which this Angular version doesn't have.`;
+    }
+    // TS2305 inside a .d.ts: `Module '"@angular/core"' has no exported member 'X'`, with the file on the next line.
+    const member = /Module '"([^"]+)"' has no exported member(?: named)? '([\w$ɵ]+)'[\s\S]{0,300}?node_modules[\\/](?:\.pnpm[\\/]\S*?[\\/]node_modules[\\/])?((?:@[\w.-]+[\\/])?[\w.-]+)[\\/]\S*\.d\.ts/.exec(output);
+    if (member) {
+        const pkg = member[3].replace('\\', '/');
+        return `${pkg}'s typings use ${member[2]}, which this version's ${member[1]} doesn't export. Apps with skipLibCheck: false, or that use the type, fail to compile.`;
+    }
+    if (/has no exported member(?: named)? '([\w$ɵ]+)'/.test(output) && /\.d\.ts/.test(output)) {
+        return "The package's typings use a type this Angular doesn't export. Apps with skipLibCheck: false fail to compile.";
+    }
+    if (/error NG8002|error NG8008|is not assignable to type|TS2322/.test(output)) {
+        return 'A template using the package type-checks only loosely: with strict templates, Angular reports the error above. If it comes from a bare attribute like <div myDirective>, give that boolean input a booleanAttribute transform.';
+    }
+    return undefined;
+}

package/dist/cli.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import semver from 'semver';
+import { LibraryError, prepareLibrary } from "./library.js";
+import { angularImports, scanPackage, summarize } from "./partial.js";
+import { Registry } from "./registry.js";
+import { exitCode, findings, renderJson, renderMarkdown, renderTerminal } from "./report.js";
+import { defaultConcurrency, runAll } from "./run.js";
+import { defaultCacheDir } from "./tools.js";
+import { defaultMajors, describeMajor, loadVersionSources, majorsOf, nextVersion, nodeSatisfies, parseVersionList, } from "./versions.js";
+const HELP = `ng-matrix: which Angular versions does your published library really work with?
+
+It builds and packs your library, installs the tarball into a fresh app for each Angular
+major (made with that major's own CLI), builds it, and reports a matrix.
+
+Usage
+  npx angular-compat-matrix [options]
+  ng-matrix [options]                  (once installed)
+
+Options
+  --versions <list>      Angular majors to check: 22, 18-22, 20,22. Default: the supported
+                         majors, every major the peer range claims (from 17), and the newest
+  --next                 Also check whatever the \`next\` tag points to
+  --project <name>       The library project, in a workspace with several
+  --consumer <dir>       Build your own example app instead of a generated smoke app
+  --tests                Also run the library's tests on each version (slow)
+  --test-command <cmd>   The test command for --tests (default: <pm> test)
+  --format <format>      terminal (default), markdown or json
+  --pm <npm|pnpm>        Package manager for the apps (default: pnpm if there's a
+                         pnpm-lock.yaml, else npm)
+  --build <cmd>          Build the library with this command instead of the detected one
+  --skip-build           Pack the existing build output as is
+  --tarball <file>       Check this packed .tgz instead of building
+  --package <spec>       Check a published package, e.g. some-lib@3.1.0
+  --concurrency <n>      Versions checked at once (default: as many as free memory allows)
+  --keep                 Keep the temporary apps, for debugging
+  --offline              Use only cached registry answers and packages
+  --cwd <dir>            The library's workspace (default: the current folder)
+  --verbose              Show every error line, not just the first few
+  -h, --help             This help
+  -v, --version          ng-matrix's version
+
+Exit code: 1 when a version inside the peer range fails, 2 when a version couldn't be
+checked at all, 0 otherwise. A version outside the range that fails is a note, not an error.
+`;
+function toolVersion() {
+    const manifest = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(readFileSync(manifest, 'utf8')).version;
+}
+/** A problem ng-matrix explains and stops on, with exit code 2. */
+class Stop extends Error {
+    lines;
+    constructor(message, lines = []) {
+        super(message);
+        this.lines = lines;
+    }
+}
+function fail(message, lines = []) {
+    throw new Stop(message, lines);
+}
+function explain(error) {
+    if (error instanceof Stop || error instanceof LibraryError) {
+        process.stderr.write(`ng-matrix: ${error.message}\n${error.lines.map((l) => `  ${l}\n`).join('')}`);
+    }
+    else if (String(error.code).startsWith('ERR_PARSE_ARGS')) {
+        process.stderr.write(`ng-matrix: ${error.message}. See --help.\n`);
+    }
+    else {
+        process.stderr.write(`ng-matrix: unexpected error\n${error.stack ?? String(error)}\n`);
+    }
+    return 2;
+}
+export async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            versions: { type: 'string' },
+            next: { type: 'boolean', default: false },
+            project: { type: 'string' },
+            consumer: { type: 'string' },
+            tests: { type: 'boolean', default: false },
+            'test-command': { type: 'string' },
+            format: { type: 'string', default: 'terminal' },
+            pm: { type: 'string' },
+            build: { type: 'string' },
+            'skip-build': { type: 'boolean', default: false },
+            tarball: { type: 'string' },
+            package: { type: 'string' },
+            concurrency: { type: 'string' },
+            keep: { type: 'boolean', default: false },
+            offline: { type: 'boolean', default: false },
+            cwd: { type: 'string' },
+            verbose: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+        },
+    });
+    if (values.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (values.version) {
+        process.stdout.write(`${toolVersion()}\n`);
+        return 0;
+    }
+    if (positionals[0] === 'ci')
+        fail('`ng-matrix ci github` is planned for v0.2.');
+    if (positionals.length)
+        fail(`Unknown argument "${positionals[0]}". See --help.`);
+    const format = values.format;
+    if (!['terminal', 'markdown', 'json'].includes(format))
+        fail(`--format must be terminal, markdown or json, not "${format}".`);
+    const cwd = resolve(values.cwd ?? process.cwd());
+    const pm = (values.pm ?? (existsSync(join(cwd, 'pnpm-lock.yaml')) ? 'pnpm' : 'npm'));
+    if (pm !== 'npm' && pm !== 'pnpm')
+        fail(`--pm must be npm or pnpm (yarn and bun come later), not "${pm}".`);
+    const consumer = values.consumer ? resolve(cwd, values.consumer) : undefined;
+    const log = (line) => process.stderr.write(`[ng-matrix] ${line}\n`);
+    const cacheDir = defaultCacheDir();
+    const registry = new Registry({
+        cacheDir,
+        offline: values.offline,
+        recordedDir: process.env.NG_MATRIX_RECORDED_REGISTRY,
+    });
+    const workDir = mkdtempSync(join(tmpdir(), 'ng-matrix-'));
+    if (values.keep)
+        log(`Working in ${workDir} (--keep)`);
+    try {
+        const library = await prepareLibrary({
+            cwd,
+            project: values.project,
+            build: values.build,
+            skipBuild: values['skip-build'],
+            tarball: values.tarball,
+            packageSpec: values.package,
+        }, workDir, log);
+        const summary = summarize(scanPackage(library.dir));
+        const now = new Date();
+        const sources = await loadVersionSources(registry);
+        const majors = values.versions
+            ? parseVersionList(values.versions)
+            : defaultMajors(sources.core, library.manifest.peerDependencies?.['@angular/core'], now);
+        const published = new Set(majorsOf(sources.core));
+        for (const major of majors)
+            if (!published.has(major))
+                fail(`Angular ${major} isn't published on npm.`);
+        const angular = majors.map((major) => describeMajor(sources, major, now));
+        const next = values.next ? nextVersion(sources.core) : undefined;
+        if (values.next && !next)
+            log('The `next` tag is not ahead of `latest` right now; nothing extra to check.');
+        if (next)
+            angular.push(describeMajor(sources, semver.major(next), now, next));
+        // One Node for every version: Angular's engines ranges only set minimums.
+        const tooOld = angular.filter((a) => !nodeSatisfies(process.version, a.nodeRanges));
+        if (tooOld.length) {
+            fail(`This Node (${process.version}) can't run ${tooOld.map((a) => `Angular ${a.major}`).join(', ')}.`, tooOld.map((a) => `Angular ${a.major} needs Node ${a.nodeRanges.join(' and ')}`).concat('Use a Node that satisfies every version you check (24.15 or later covers 17 to 22), or check fewer versions.'));
+        }
+        const concurrency = values.concurrency ? Math.max(1, Number(values.concurrency)) : defaultConcurrency(angular.length);
+        log(`Checking ${library.manifest.name}@${library.manifest.version} on ${angular.map((a) => a.version).join(', ')} with ${pm}, ${concurrency} at a time`);
+        const versions = await runAll({
+            library,
+            summary,
+            pm,
+            registry,
+            cacheDir,
+            offline: values.offline,
+            workDir,
+            workspace: values.tarball || values.package ? undefined : cwd,
+            tests: values.tests,
+            testCommand: values['test-command'],
+            consumer,
+            keep: values.keep,
+            log,
+        }, angular, concurrency);
+        const report = {
+            tool: { name: 'angular-compat-matrix', version: toolVersion() },
+            checkedAt: now.toISOString(),
+            library: {
+                name: library.manifest.name,
+                version: library.manifest.version,
+                source: library.source,
+                compiledWith: summary.compiledWith,
+                highestMinVersion: summary.highest?.minVersion,
+                highestMinVersionIn: summary.highest ? `${summary.highest.type} (${summary.highest.file})` : undefined,
+                declarations: summary.declarations,
+            },
+            packageManager: pm,
+            node: process.version,
+            versions,
+            findings: findings(versions, library.manifest, angularImports(library.dir)),
+            exitCode: exitCode(versions),
+        };
+        const render = format === 'json' ? renderJson : format === 'markdown' ? renderMarkdown : (r) => renderTerminal(r, values.verbose);
+        process.stdout.write((format === 'terminal' ? '\n' : '') + render(report));
+        return report.exitCode;
+    }
+    catch (error) {
+        return explain(error);
+    }
+    finally {
+        if (!values.keep)
+            rmSync(workDir, { recursive: true, force: true, maxRetries: 3 });
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (error) => process.exit(explain(error)));

package/dist/exec.js

@@ -0,0 +1,110 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const ANSI = /\u001b\[[0-9;?]*[A-Za-z]|\u001b\][^\u0007]*\u0007/g;
+export function stripAnsi(text) {
+    return text.replace(ANSI, '');
+}
+/** Environment every child gets: no prompts, no analytics, no colour codes to strip later. */
+export function quietEnv(extra = {}) {
+    return {
+        ...process.env,
+        NG_CLI_ANALYTICS: 'false',
+        NG_DISABLE_VERSION_CHECK: '1',
+        NO_UPDATE_NOTIFIER: '1',
+        NPM_CONFIG_UPDATE_NOTIFIER: 'false',
+        NPM_CONFIG_FUND: 'false',
+        NPM_CONFIG_AUDIT: 'false',
+        FORCE_COLOR: '0',
+        ...extra,
+    };
+}
+export function exec(command, args, options) {
+    const started = Date.now();
+    return new Promise((resolve) => {
+        const child = options.shell
+            ? spawn([command, ...args].join(' '), { cwd: options.cwd, env: options.env ?? quietEnv(), shell: true })
+            : spawn(command, args, { cwd: options.cwd, env: options.env ?? quietEnv() });
+        let output = '';
+        let timedOut = false;
+        const append = (chunk) => (output += chunk.toString('utf8'));
+        child.stdout?.on('data', append);
+        child.stderr?.on('data', append);
+        const timer = options.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                killTree(child.pid);
+            }, options.timeoutMs)
+            : undefined;
+        const finish = (code) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code, output: stripAnsi(output), durationMs: Date.now() - started, timedOut });
+        };
+        child.on('error', (error) => {
+            output += `\n${error.message}`;
+            finish(127);
+        });
+        child.on('close', (code) => finish(code ?? 1));
+    });
+}
+function killTree(pid) {
+    if (!pid)
+        return;
+    if (process.platform === 'win32') {
+        spawnSync('taskkill', ['/pid', String(pid), '/T', '/F']);
+    }
+    else {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+/**
+ * npm's own CLI script, so npm runs as `node npm-cli.js` without a shell
+ * (spawning `npm.cmd` on Windows needs one, and then every argument needs quoting).
+ */
+export function npmCli() {
+    const candidates = [
+        process.env.npm_execpath,
+        join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        join(dirname(process.execPath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ];
+    for (const candidate of candidates) {
+        if (candidate && /npm-cli\.js$/.test(candidate) && existsSync(candidate))
+            return [process.execPath, candidate];
+    }
+    throw new Error("Couldn't find npm next to this Node. ng-matrix needs the npm that ships with Node.");
+}
+export function npm(args, options) {
+    const [node, cli] = npmCli();
+    return exec(node, [cli, ...args], options);
+}
+/** The first lines that look like errors, with a little context, for reports. */
+export function errorLines(output, max = 12) {
+    const lines = output.split(/\r?\n/).map((line) => line.trimEnd());
+    // Errors first; warnings (Angular prints NG8113 "not used" ones, say) only when there's nothing else.
+    const errors = /(\[ERROR\]|\berror TS\d+|\bERR_PNPM_|npm error|^\s*Error:|✘|✕|^\s*X |\berror NG\d{4}\b|ERESOLVE|unmet peer|invalid: )/i;
+    const anything = /(\[WARNING\]|\bNG\d{4}\b|\bwarn)/i;
+    for (const marker of [errors, anything]) {
+        const picked = [];
+        for (let i = 0; i < lines.length && picked.length < max; i++) {
+            if (!marker.test(lines[i]))
+                continue;
+            for (let j = i; j < Math.min(lines.length, i + 6) && picked.length < max; j++) {
+                const line = lines[j];
+                if (j > i && (errors.test(line) || anything.test(line)) && !marker.test(line))
+                    break;
+                if (line.trim() && !picked.includes(line))
+                    picked.push(line);
+            }
+            i += 5;
+        }
+        if (picked.length)
+            return picked;
+    }
+    return lines.filter((line) => line.trim()).slice(-max);
+}