angular-compat-matrix 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@ 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.
+ng-matrix builds and packs your Angular library, installs the tarball into a fresh app for each Angular major (created with that major's own CLI), builds it, and reports a compatibility matrix. It tests the exact package your users get, not your local source.
 
 ```
 $ npx angular-compat-matrix
@@ -20,107 +20,387 @@ 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…
+✗ 20: strict types: Fails with strictTemplates: true and skipLibCheck: false.
 ! 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`.
+## Quick Start
+
+Run it in your library's workspace: an Angular CLI workspace with a library project, or any 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
+# Check supported majors plus every major your peer range claims
+npx angular-compat-matrix
+
+# Check a specific range or list of majors
+npx angular-compat-matrix --versions 18-22
+npx angular-compat-matrix --versions 20,22
+
+# Check one library in a workspace with several
+npx angular-compat-matrix --project my-lib
+
+# Check a published package from npm (no local build needed)
+npx angular-compat-matrix --package primeng@19.0.0
+
+# Generate Markdown for your README or GitHub Actions summary
+npx angular-compat-matrix --format markdown
+
+# Machine-readable JSON output for CI pipelines
+npx angular-compat-matrix --json
+
+# Verbose output (shows exact commands executed and full failure logs)
+npx angular-compat-matrix --verbose
 ```
 
-`npx angular-compat-matrix --help` lists every option.
+---
+
+## How to Read the Matrix
+
+The matrix tests each Angular major in order. A failure on any step marks subsequent checks `—`, ensuring the first true incompatibility is reported clearly.
 
-**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.
+### Symbols
 
-**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.
+| Terminal | Markdown | Meaning |
+| :---: | :---: | :--- |
+| `✓` | `✅` | **Passed:** The check succeeded. |
+| `✗` | `❌` | **Failed:** The check failed. |
+| `✓?` | `✅*` | **Advisory pass:** Passed on `minVersion` alone, but because the library was compiled with a newer Angular major, `minVersion` has been historically unreliable. The build check decides compatibility. |
+| `—` | `—` | **Not run:** Skipped because an earlier check failed. |
+| `·` | `n/a` | **None:** Nothing to check (e.g. no `@angular/*` peer declared). |
+| `!` | `⚠️` | **Setup error:** ng-matrix itself could not set up the app on this machine (e.g. disk full, network timeout). This is not a library failure. |
 
-## 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.
+## What It Checks
 
-| Check | Question | How |
+| Check | What it asks | How it verifies |
 | --- | --- | --- |
-| 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 |
+| **Peer range** | Does your package claim this version? | Compares every declared `@angular/*` peer (e.g. `@angular/core`, `@angular/cdk`, `@angular/material`). Never stops other checks. |
+| **Install** | Does it install cleanly without peer conflicts? | Installs the packed tarball into a fresh Angular app using your package manager (`npm` with `--legacy-peer-deps` + `npm ls`, or `pnpm` with `strictPeerDependencies: false`). For versions outside your peer range, expected peer conflicts are safely ignored. |
+| **Partial** | Can this version's Angular linker load the compiled code? | Scans every `ɵɵngDeclare…` call in the published code for `minVersion`. A failure is absolute proof of incompatibility. |
+| **AOT build** | Does a production app build with your library? | Runs `ng build --configuration production` (`strictTemplates: false`, `skipLibCheck: true`) on a smoke app using every public component, directive, pipe, service, and entry point. |
+| **Strict types** | Do consumer templates type-check under strict settings? | Re-runs the build with `strictTemplates: true` and `skipLibCheck: false`. Catches template type errors and invalid typings. (Errors strictly inside third-party `node_modules/**/*.d.ts` are reported as warnings and do not fail the check). |
+| **Tests** | Do your own unit tests pass on this version? | (Opt-in with `--tests`): Copies your workspace, swaps Angular dependencies to the target major, and executes your test command (`npm test` or `--test-command`). |
 
-### Why build, when there's minVersion?
+### The Generated Smoke App
 
-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.
+When not using `--consumer`, ng-matrix inspects your package typings and generates a standalone smoke app:
+- Imports all entry points exposed in your `package.json` `exports` map.
+- Instantiates each component, directive, and pipe in its own isolated component.
+- Supplies correctly-typed mock values for required `@Input()` fields.
+- Uses attribute selectors bare (`<div myFlag>`) when they accept booleans or strings, matching real user patterns.
+- Handles undeclared dependencies in secondary entry points: if a secondary entry point (e.g. `my-lib/chart`) fails because an undeclared extra (like `chart.js`) is missing, ng-matrix omits that entry point and warns you rather than failing the whole library. If the package's *main* entry point (`.`) imports an undeclared package, AOT fails immediately with a clear explanation.
 
-### The smoke app
+If your library requires specialized providers, wrappers, or mock services, supply your own example app with `--consumer ./path-to-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
+## Install-Script Safety Default & `--allow-scripts`
 
-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.
+By default, ng-matrix **blocks arbitrary install scripts** (`preinstall`, `install`, `postinstall`) during `npm` and `pnpm` installations.
+
+Only native build tools essential to the Angular toolchain are permitted to run:
+- `esbuild`
+- `@parcel/watcher`
+- `lmdb`
+- `@swc/core`
+
+If your library or one of its dependencies requires an install script to compile native bindings, opt in explicitly:
+```sh
+npx angular-compat-matrix --allow-scripts
+```
+
+If an installation or build fails while scripts were blocked, ng-matrix explicitly lists which packages were skipped in the output findings so you know whether `--allow-scripts` is needed.
+
+---
+
+## Cache Management
+
+ng-matrix caches npm registry metadata and downloaded tools (such as pinned pnpm binaries) to keep runs fast and enable `--offline` usage.
+
+```sh
+# View cache location, disk usage, and file count
+ng-matrix cache
+
+# Clear the cache entirely
+ng-matrix cache clean
+```
+
+### Cache Locations by OS
+
+- **Linux:** `$XDG_CACHE_HOME/ng-matrix` or `~/.cache/ng-matrix`
+- **macOS:** `~/.cache/ng-matrix` (or `$XDG_CACHE_HOME/ng-matrix`)
+- **Windows:** `%LOCALAPPDATA%\ng-matrix\Cache`
+- **Custom Location:** Set the `NG_MATRIX_CACHE` environment variable to override the default on any OS.
+
+---
+
+## Exit Codes
+
+ng-matrix returns standard POSIX exit codes suitable for CI pipelines:
+
+- **`0` (Success):** Every version claimed by the library's peer dependencies passed all checks. (If the library declares no `@angular/*` peer dependencies, 0 is returned if any checked version passes).
+- **`1` (Broken Promise):** At least one Angular major claimed by your `peerDependencies` failed a check (install, partial, AOT, strict types, or tests).
+- **`2` (Environment / Setup Error):** ng-matrix could not check a version due to machine or network failure (e.g. disk full ENOSPC, network down, step timeout, invalid CLI options).
+
+---
 
 ## In CI
 
-A GitHub Actions job that checks the supported majors on every push:
+### GitHub Actions
+
+Add a step to your workflow to verify compatibility and post the matrix directly to your workflow run summary:
 
 ```yaml
+name: Compatibility Matrix
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
 jobs:
-  angular-matrix:
+  compat:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-node@v7
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 24
       - run: npm ci
-      - run: npx angular-compat-matrix --format markdown >> "$GITHUB_STEP_SUMMARY"
+      - name: Run Angular Compatibility Matrix
+        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
+---
+
+## JSON Output & Stable Schema Contract
+
+When running with `--json` or `--format json`, ng-matrix outputs structured JSON with a fixed schema contract.
+
+The top-level field `schemaVersion` is guaranteed. Any future additions or modifications to the JSON shape will increment `schemaVersion`.
+
+### Schema Version 1 Specification
+
+```json
+{
+  "schemaVersion": 1,
+  "tool": {
+    "name": "angular-compat-matrix",
+    "version": "0.1.0"
+  },
+  "checkedAt": "2026-10-26T12:00:00.000Z",
+  "library": {
+    "name": "my-lib",
+    "version": "1.0.0",
+    "source": "package",
+    "compiledWith": "20.2.0",
+    "highestMinVersion": "20.0.0",
+    "highestMinVersionIn": "component (dist/my-lib.mjs)",
+    "declarations": 12
+  },
+  "packageManager": "npm",
+  "installScripts": "toolchain-only",
+  "node": "v24.19.0",
+  "versions": [
+    {
+      "major": 21,
+      "angularVersion": "21.2.0",
+      "supported": true,
+      "prerelease": false,
+      "claimed": true,
+      "peerMisses": [],
+      "checks": {
+        "peer": {
+          "status": "pass",
+          "message": "Claimed: @angular/core@^21.0.0.",
+          "errorLines": [],
+          "durationMs": 0
+        },
+        "install": {
+          "status": "pass",
+          "message": "Installed with npm.",
+          "errorLines": [],
+          "durationMs": 4200
+        },
+        "partial": {
+          "status": "pass",
+          "advisory": false,
+          "message": "minVersion is 20.0.0.",
+          "errorLines": [],
+          "durationMs": 12
+        },
+        "aot": {
+          "status": "pass",
+          "message": "Production build succeeded.",
+          "errorLines": [],
+          "durationMs": 6100
+        },
+        "strict": {
+          "status": "pass",
+          "message": "Builds with strictTemplates: true and skipLibCheck: false.",
+          "errorLines": [],
+          "durationMs": 5900
+        },
+        "tests": {
+          "status": "off",
+          "message": "Not requested (--tests).",
+          "errorLines": [],
+          "durationMs": 0
+        }
+      },
+      "skippedInstallScripts": [],
+      "omittedEntryPoints": [],
+      "dtsErrors": false,
+      "durationMs": 16212
+    }
+  ],
+  "findings": [
+    {
+      "level": "error",
+      "majors": [19],
+      "text": "AOT build: Production build failed."
+    }
+  ],
+  "exitCode": 0
+}
+```
 
-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):
+### JSON Fields Reference
+
+- **`schemaVersion`** (`number`): The JSON schema version (currently `1`).
+- **`tool`** (`{ name: string, version: string }`): CLI name and version.
+- **`checkedAt`** (`string`): ISO-8601 timestamp when the check was performed.
+- **`library`** (`object`):
+  - `name`: Package name.
+  - `version`: Package version.
+  - `source`: How the package was acquired (`workspace`, `tarball`, or `package`).
+  - `compiledWith` (`string?`): The Angular version that built this library.
+  - `highestMinVersion` (`string?`): Highest `minVersion` found across declarations.
+  - `highestMinVersionIn` (`string?`): Component or declaration file with the highest `minVersion`.
+  - `declarations` (`number`): Count of Angular declarables detected.
+- **`packageManager`** (`string`): `'npm'` or `'pnpm'`.
+- **`installScripts`** (`'toolchain-only' | 'all'`): Whether `--allow-scripts` was active.
+- **`node`** (`string`): Node.js runtime version.
+- **`versions`** (`VersionReport[]`): Results per Angular major:
+  - `major`: Angular major version number.
+  - `angularVersion`: Resolved patch version checked.
+  - `supported`: Whether this major is currently within Angular's official 18-month support window.
+  - `prerelease`: Whether this major came from a pre-release tag (`next`).
+  - `claimed`: `true` if peer dependencies include this version, `false` if excluded, `null` if no Angular peers declared.
+  - `peerMisses`: Array of declared peers whose ranges excluded this major (`{ name, range, version }`).
+  - `checks`: Object mapping check names (`peer`, `install`, `partial`, `aot`, `strict`, `tests`) to check results:
+    - `status`: `'pass' | 'fail' | 'not-run' | 'off' | 'none'`.
+    - `message`: Summary message.
+    - `errorLines`: First relevant error lines extracted from build or install logs.
+    - `fullOutput` (`string?`): Full command stdout and stderr on failure (optional; present only when `--verbose` is used).
+    - `hint` (`string?`): Plain-language diagnostic hint.
+    - `durationMs`: Execution duration in milliseconds.
+    - `advisory` (`boolean?`): `true` when partial check passed only on `minVersion` despite being built with newer Angular.
+  - `setupError` (`string?`): Description if the run failed due to machine/environment reasons.
+  - `skippedInstallScripts` (`string[]?`): Packages whose install scripts were blocked.
+  - `omittedEntryPoints` (`{ entry: string, missingPackage: string }[]?`): Secondary entry points skipped due to undeclared dependencies.
+  - `dtsErrors` (`boolean?`): `true` if strict build had errors confined to `node_modules/**/*.d.ts`.
+  - `durationMs`: Total duration for checking this major.
+- **`findings`** (`Finding[]`): Merged diagnostics across all checked versions:
+  - `level`: `'error' | 'warning' | 'note'`.
+  - `majors`: Array of major version numbers affected.
+  - `text`: Human-readable problem description and suggested resolution.
+  - `suggestedPeerDependencies` (`Record<string, string>?`): Recommended peer dependencies when none were declared.
+- **`exitCode`** (`number`): `0`, `1`, or `2`.
+
+---
+
+## Troubleshooting Real-World Issues
+
+Here are the most common real-world incompatibilities identified across popular Angular packages and how to solve them:
+
+### 1. Linker Crash on Older Angular (`Unsupported enum value` / `ɵɵFactoryTarget.Service`)
+- **Symptom:** The library claims support for Angular 20 and 21, but on Angular 20 the linker crashes with `Unsupported enum value` or `Cannot create property 'message' on string`.
+- **Cause:** The library was compiled with Angular 21 or 22. Newer Angular compilers emit bytecode constructs that older linkers do not recognize, even though `minVersion` was claimed as `12.0.0`.
+- **Fix:** Compile your library with the **oldest** Angular major you support, or narrow your `peerDependencies` range to exclude older majors.
+
+### 2. Secondary Entry Points with Undeclared Dependencies
+- **Symptom:** A component in a secondary entry point (e.g. `primeng/chart` or `ng-zorro-antd/graph`) fails because `chart.js` or `dagre-d3-es` is not found.
+- **Handling:** ng-matrix omits secondary entry points that fail exclusively because of undeclared packages and flags a warning finding. However, if your **main** entry point (`.`) imports an undeclared package, ng-matrix fails the AOT check because all consumers would experience build failures.
+- **Fix:** Move undeclared packages into `peerDependencies` (or `dependencies` if required).
+
+### 3. Library Typings Errors under `skipLibCheck: false`
+- **Symptom:** Strict build fails with errors inside declaration files under `node_modules/**/*.d.ts`.
+- **Handling:** When errors are confined strictly to third-party declaration files, ng-matrix marks the strict check as passed with an informational warning finding (`"library typings have errors with skipLibCheck: false"`). It does not fail the version or trigger an exit code 1.
+- **Fix:** Keep your third-party typing dependencies aligned with target TypeScript versions.
+
+### 4. Disk Full (ENOSPC)
+- **Symptom:** Exit code 2 with `ENOSPC: no space left on device`.
+- **Fix:** Clear temporary build folders and caches using `ng-matrix cache clean`, or point `NG_MATRIX_CACHE` and `TMPDIR`/`TEMP` to a drive with sufficient disk space.
+
+> **Tip for library authors:** If your library accepts bare attributes like `<comp myFlag>`, give boolean inputs `@Input({ transform: booleanAttribute })` so consumers can write bare attributes under strict template checking (ng-matrix does not check this).
+
+---
+
+## Options Reference
 
-- **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.
+```
+Usage
+  npx angular-compat-matrix [options]
+  ng-matrix [options]                  (once installed)
+  ng-matrix cache                      (show cache location and size)
+  ng-matrix cache clean                (delete the cache)
+
+Options
+  --versions <list>      Angular majors to check: 22, 18-22, 20,22. Default: supported
+                         majors, claimed majors (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
+  --json                 Shorthand for --format json
+  --pm <npm|pnpm>        Package manager for the apps (default: pnpm if lockfile present, 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: based on available memory)
+  --step-timeout <min>   Maximum minutes any single step may take (default: 20)
+  --keep                 Keep the temporary apps after completion for debugging
+  --allow-scripts        Permit all package install scripts to run (default: toolchain only)
+  --offline              Use only cached registry answers and packages
+  --cwd <dir>            The library's workspace (default: current directory)
+  --verbose              Show commands run and full build/install output for failures
+  -h, --help             Show help
+  -v, --version          Show version
+```
 
-## 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.
+## Known Limitations & Roadmap
 
-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.
+- **Supported Workspaces:** Angular CLI workspaces and standalone `ng-packagr` libraries.
+- **Node.js:** Node 24.15 or later is recommended to cover all Angular majors from 17 through 22.
+- **Planned:**
+  - `ng-matrix ci github`: Generates dedicated GitHub Actions workflows with matrix parallelism.
+  - First-class Nx workspace discovery and integration.
+  - Dedicated SSR (Server-Side Rendering) and `with-zone.js` validation columns.
+- **Out of Scope:** Yarn and Bun (npm and pnpm cover package testing; JSON output makes custom wrappers simple), app migration tooling, and runtime browser testing.
 
-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)
+npm test                       # run all unit tests
+npm run build                  # compile TypeScript
+npm ci --prefix fixtures       # install Angular fixture toolchain
+node test/fixtures/run.ts      # run fixture integration tests
 ```
 
-`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
 

package/dist/app.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { errorLines, exec, quietEnv } from "./exec.js";
+import { environmentProblem, errorLines, exec, quietEnv, stepTimeout } 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) {
@@ -21,11 +21,12 @@ export async function generateApp(angular, pm, parentDir, cacheDir, offline) {
     const result = await exec(process.execPath, [binOf(cli, 'ng'), ...newAppArgs(pm)], {
         cwd: parentDir,
         env: quietEnv({ CI: '1' }),
-        timeoutMs: 10 * 60_000,
+        timeoutMs: stepTimeout(),
     });
     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')}`);
+        const why = environmentProblem(result);
+        throw new Error(`ng new (Angular CLI ${angular.cliVersion}) failed${why ? `: ${why}` : ''}:\n${errorLines(result.output).join('\n')}`);
     }
     return appDir;
 }

package/dist/build.js

@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { writeTsconfig } from "./app.js";
-import { errorLines, exec, quietEnv } from "./exec.js";
+import { environmentProblem, errorLines, exec, quietEnv, stepTimeout } from "./exec.js";
 export async function ngBuild(appDir, baseTsConfig, mode, files) {
     writeTsconfig(appDir, baseTsConfig, mode, files);
     const require = createRequire(join(appDir, 'package.json'));
@@ -10,12 +10,19 @@ export async function ngBuild(appDir, baseTsConfig, mode, files) {
     const result = await exec(process.execPath, [ng, 'build', '--configuration', 'production'], {
         cwd: appDir,
         env: quietEnv({ CI: '1' }),
-        timeoutMs: 20 * 60_000,
+        timeoutMs: stepTimeout(),
     });
     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 };
+    const lines = errorLines(result.output);
+    return {
+        pass: false,
+        errorLines: lines,
+        fullOutput: result.output,
+        hint: hintFor(result.output) ?? lines[0],
+        durationMs: result.durationMs,
+        environment: environmentProblem(result),
+    };
 }
 /** Plain-language explanations for build failures whose messages don't say what's wrong. */
 export function hintFor(output) {
@@ -39,8 +46,122 @@ export function hintFor(output) {
     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 (isDtsOnlyFailure(errorLines(output))) {
+        return 'library typings have errors with skipLibCheck: false';
+    }
     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;
 }
+/**
+ * Whether the build failed only because of errors inside declaration files (.d.ts)
+ * of a library, with no errors in the smoke app's templates or components.
+ */
+export function isDtsOnlyFailure(lines) {
+    if (!lines.length)
+        return false;
+    let hasDtsError = false;
+    for (const line of lines) {
+        if (/error NG\d+/.test(line))
+            return false;
+        if (/(?:src[\\/]ngm-smoke|src[\\/]ngm-main)\.ts/i.test(line))
+            return false;
+        if (/\.d\.ts(?::|\s|$)/i.test(line))
+            hasDtsError = true;
+    }
+    return hasDtsError;
+}
+function packageNameFromSpecifier(specifier) {
+    if (specifier.startsWith('@')) {
+        const parts = specifier.split('/');
+        return parts.slice(0, 2).join('/');
+    }
+    return specifier.split('/')[0];
+}
+function isDeclared(pkg, manifest) {
+    if (pkg === manifest.name)
+        return true;
+    if (manifest.dependencies && pkg in manifest.dependencies)
+        return true;
+    if (manifest.peerDependencies && pkg in manifest.peerDependencies)
+        return true;
+    if (manifest.optionalDependencies && pkg in manifest.optionalDependencies)
+        return true;
+    return false;
+}
+function findEntryPointForFile(filePath, manifest, entries) {
+    if (entries.length <= 1)
+        return entries[0] ?? manifest.name;
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    const exportsMap = manifest.exports;
+    if (exportsMap && typeof exportsMap === 'object') {
+        for (const [key, value] of Object.entries(exportsMap)) {
+            const entryName = key === '.' ? manifest.name : `${manifest.name}/${key.slice(2)}`;
+            if (typeof value === 'string') {
+                const clean = value.replace(/^\.\//, '');
+                if (normalizedPath.endsWith(clean))
+                    return entryName;
+            }
+            else if (value && typeof value === 'object') {
+                for (const target of Object.values(value)) {
+                    if (typeof target === 'string') {
+                        const clean = target.replace(/^\.\//, '');
+                        if (normalizedPath.endsWith(clean))
+                            return entryName;
+                    }
+                }
+            }
+        }
+    }
+    for (const entry of entries) {
+        if (entry === manifest.name)
+            continue;
+        const sub = entry.slice(manifest.name.length + 1);
+        if (normalizedPath.includes(sub) || normalizedPath.includes(sub.replace(/\//g, '-'))) {
+            return entry;
+        }
+    }
+    return entries[0] ?? manifest.name;
+}
+/**
+ * Spots when a build fails ONLY because entry points import packages that aren't declared
+ * in dependencies, peerDependencies or optionalDependencies (e.g. chart.js, lodash, cron-parser).
+ */
+export function findUndeclaredImports(lines, manifest, entries) {
+    const undeclared = [];
+    const seen = new Set();
+    let hasOtherErrors = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const esbuildMatch = /Could not resolve ["']([^"']+)["']/.exec(line);
+        const webpackMatch = /Can't resolve '([^']+)'/.exec(line);
+        const specifier = esbuildMatch?.[1] ?? webpackMatch?.[1];
+        if (specifier) {
+            const pkg = packageNameFromSpecifier(specifier);
+            if (!isDeclared(pkg, manifest)) {
+                let filePath = '';
+                for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                    const locMatch = /(?:^|\s+)([A-Za-z]:[\\/][^\s:]+|node_modules[\\/][^\s:]+|[^\s:]+):\d+:\d+:/.exec(lines[j]);
+                    if (locMatch) {
+                        filePath = locMatch[1];
+                        break;
+                    }
+                }
+                const entry = findEntryPointForFile(filePath, manifest, entries);
+                const key = `${entry}\0${pkg}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    undeclared.push({ entry, missingPackage: pkg });
+                }
+            }
+            else {
+                hasOtherErrors = true;
+            }
+        }
+        else if (/^X \[ERROR\]/.test(line) && !line.includes('Could not resolve')) {
+            hasOtherErrors = true;
+        }
+    }
+    return hasOtherErrors ? [] : undeclared;
+}