angular-compat-matrix 0.1.0 → 0.2.0

package/dist/registry.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 const DAY = 24 * 60 * 60 * 1000;
 const FULL_DOCUMENT = new Set(['@angular/core']);
@@ -26,9 +26,7 @@ export class Registry {
         }
         const dir = join(this.options.cacheDir, 'registry');
         const path = join(dir, file);
-        const cached = existsSync(path)
-            ? JSON.parse(readFileSync(path, 'utf8'))
-            : undefined;
+        const cached = readCached(path);
         const maxAge = this.options.maxAgeMs ?? DAY;
         if (cached && (this.options.offline || Date.now() - cached.fetchedAt < maxAge))
             return cached.packument;
@@ -41,26 +39,78 @@ export class Registry {
         const accept = FULL_DOCUMENT.has(name)
             ? 'application/json'
             : 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8';
-        let response;
-        try {
-            response = await fetch(url, { headers: { accept } });
+        const timeoutMs = this.options.timeoutMs ?? 30_000;
+        let packument;
+        let problem = '';
+        // Two tries: one dropped connection shouldn't end a run that takes minutes.
+        for (let attempt = 1; attempt <= 2 && !packument; attempt++) {
+            try {
+                const response = await fetch(url, { headers: { accept }, signal: AbortSignal.timeout(timeoutMs) });
+                if (response.status === 404)
+                    throw new RegistryError(`${name} isn't on the npm registry (${base}).`);
+                if (!response.ok) {
+                    problem = `it answered ${response.status} ${response.statusText}`;
+                    continue;
+                }
+                packument = trim((await response.json()));
+            }
+            catch (error) {
+                if (error instanceof RegistryError)
+                    throw error;
+                problem = describeFetchError(error, timeoutMs);
+            }
         }
-        catch (error) {
+        if (!packument) {
             if (cached)
                 return cached.packument;
-            throw new Error(`Couldn't reach the npm registry for ${name}: ${error.message}`);
+            throw new RegistryError(`Couldn't get ${name} from the npm registry (${base}): ${problem}.`);
         }
-        if (!response.ok) {
-            if (cached)
-                return cached.packument;
-            throw new Error(`The npm registry answered ${response.status} for ${name}`);
+        writeCached(dir, path, packument);
+        return packument;
+    }
+}
+export class RegistryError extends Error {
+}
+function describeFetchError(error, timeoutMs) {
+    if (error.name === 'TimeoutError' || error.name === 'AbortError')
+        return `no answer within ${timeoutMs / 1000} s`;
+    const cause = error.cause;
+    const code = cause?.code;
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN')
+        return 'the host name could not be resolved (are you offline?)';
+    if (code === 'ECONNREFUSED')
+        return 'the connection was refused';
+    if (code === 'ECONNRESET')
+        return 'the connection was reset';
+    return cause?.message ?? error.message;
+}
+/** A cache entry, or nothing when it's missing or unreadable (a crashed write, a full disk): it's refetched. */
+function readCached(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const entry = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof entry.fetchedAt === 'number' && entry.packument && typeof entry.packument.versions === 'object') {
+            return entry;
         }
-        const packument = trim((await response.json()));
+    }
+    catch {
+        // fall through
+    }
+    rmSync(path, { force: true });
+    return undefined;
+}
+/** Writes through a temporary file, so a crash or a full disk never leaves a half-written entry. */
+function writeCached(dir, path, packument) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
         mkdirSync(dir, { recursive: true });
-        const tmp = `${path}.${process.pid}.tmp`;
         writeFileSync(tmp, JSON.stringify({ fetchedAt: Date.now(), packument }));
         renameSync(tmp, path);
-        return packument;
+    }
+    catch {
+        // Caching is an optimisation; the run goes on without it.
+        rmSync(tmp, { force: true });
     }
 }
 export function trim(raw) {

package/dist/report.js

@@ -31,7 +31,7 @@ angularImports = ['@angular/core']) {
         if (failure) {
             const [name, check] = failure;
             // Partial's message names the declaration; a build's message is just "failed", so its hint says more.
-            const why = name === 'partial' && check.hint ? `${check.message} ${check.hint}` : (check.hint ?? check.message);
+            const why = name === 'partial' && check.hint ? `${check.message} ${check.hint}` : (check.hint ?? check.errorLines?.[0] ?? check.message);
             if (version.claimed === true) {
                 raw.push({ level: 'error', majors: [m], key: `fail:${name}:${why}`, text: `${CHECK_LABELS[name]}: ${why}` });
             }
@@ -46,6 +46,15 @@ angularImports = ['@angular/core']) {
             else {
                 raw.push({ level: 'warning', majors: [m], key: `fail:${name}:${why}`, text: `${CHECK_LABELS[name]}: ${why}` });
             }
+            if (version.skippedInstallScripts?.length) {
+                const list = version.skippedInstallScripts.join(', ');
+                raw.push({
+                    level: 'note',
+                    majors: [m],
+                    key: `scripts:${list}`,
+                    text: `Install scripts didn't run for ${list} (the default). If the failure comes from one of them, check again with --allow-scripts.`,
+                });
+            }
         }
         else if (version.claimed === false) {
             const ranges = version.peerMisses.map((miss) => `${miss.name} "${miss.range}"`).join(', ');
@@ -56,6 +65,24 @@ angularImports = ['@angular/core']) {
                 text: `works, but peerDependencies doesn't allow it (${ranges}). Widen the range to include it.`,
             });
         }
+        if (version.omittedEntryPoints?.length) {
+            for (const item of version.omittedEntryPoints) {
+                raw.push({
+                    level: 'warning',
+                    majors: [m],
+                    key: `undeclared:${item.entry}:${item.missingPackage}`,
+                    text: `entry point ${item.entry} imports ${item.missingPackage}, which isn't declared in dependencies or peers`,
+                });
+            }
+        }
+        if (version.dtsErrors) {
+            raw.push({
+                level: 'warning',
+                majors: [m],
+                key: 'skipLibCheck:dts-errors',
+                text: 'library typings have errors with skipLibCheck: false',
+            });
+        }
     }
     // One finding per distinct problem, listing every major it applies to.
     const merged = [];
@@ -161,11 +188,18 @@ export function renderTerminal(report, verbose = false) {
     for (const version of failing) {
         const failure = firstFailure(version);
         const errors = version.setupError ? version.setupError.split('\n').slice(1) : (failure?.[1].errorLines ?? []);
-        if (!errors.length)
+        const full = failure?.[1].fullOutput;
+        if (!errors.length && !full)
             continue;
         lines.push('', `${rowLabel(version)}, ${failure ? CHECK_LABELS[failure[0]] : 'setup'}:`);
-        for (const line of errors.slice(0, verbose ? errors.length : 6))
-            lines.push(`  ${line.trim()}`);
+        if (verbose && full) {
+            for (const line of full.split(/\r?\n/))
+                lines.push(`  ${line}`);
+        }
+        else {
+            for (const line of errors.slice(0, 6))
+                lines.push(`  ${line.trim()}`);
+        }
     }
     lines.push('', exitSummary(report));
     return lines.join('\n') + '\n';
@@ -228,6 +262,19 @@ export function renderMarkdown(report) {
     }
     return lines.join('\n') + '\n';
 }
-export function renderJson(report) {
-    return JSON.stringify(report, null, 2) + '\n';
+export function renderJson(report, verbose = false) {
+    if (verbose) {
+        return JSON.stringify(report, null, 2) + '\n';
+    }
+    const stripped = {
+        ...report,
+        versions: report.versions.map((v) => ({
+            ...v,
+            checks: Object.fromEntries(Object.entries(v.checks).map(([name, check]) => {
+                const { fullOutput: _full, ...rest } = check;
+                return [name, rest];
+            })),
+        })),
+    };
+    return JSON.stringify(stripped, null, 2) + '\n';
 }

package/dist/run.js

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module';
 import { freemem, availableParallelism } from 'node:os';
 import { join, relative, sep } from 'node:path';
 import { configureBuild, generateApp, readJson, writeJson } from "./app.js";
-import { ngBuild } from "./build.js";
+import { findUndeclaredImports, isDtsOnlyFailure, ngBuild } from "./build.js";
 import { installLibrary } from "./install.js";
 import { CHECKS, result } from "./model.js";
 import { judgePartial } from "./partial.js";
@@ -55,9 +55,16 @@ export async function checkVersion(ctx, angular) {
     };
     const finish = () => {
         report.durationMs = Date.now() - started;
+        ctx.progress?.done(angular.major);
         ctx.log(`${tag}: done in ${Math.round(report.durationMs / 1000)} s`);
         return report;
     };
+    // A timeout, a full disk or a network error says nothing about the package: this version
+    // wasn't checked (exit 2), rather than failing a check.
+    const notChecked = (step, why, lines) => {
+        report.setupError = [`${step} on ${tag}: ${why}.`, ...lines].join('\n');
+        return finish();
+    };
     // Peer range: reported, but never stops the other checks.
     const plan = await planPeers(ctx.library.manifest, angular.version, ctx.registry);
     report.claimed = plan.claimed;
@@ -72,6 +79,7 @@ export async function checkVersion(ctx, angular) {
     mkdirSync(versionDir, { recursive: true });
     let appDir;
     try {
+        ctx.progress?.step(angular.major, ctx.consumer ? 'creating consumer app' : `ng new (CLI ${angular.cliVersion})`);
         ctx.log(`${tag}: creating the app (${ctx.consumer ? 'your --consumer app' : `ng new, CLI ${angular.cliVersion}`})`);
         appDir = ctx.consumer
             ? await copyConsumer(ctx, angular, plan.installs, versionDir)
@@ -86,6 +94,7 @@ export async function checkVersion(ctx, angular) {
         return finish();
     }
     try {
+        ctx.progress?.step(angular.major, `installing with ${ctx.pm}`);
         ctx.log(`${tag}: installing ${ctx.library.manifest.name} with ${ctx.pm}`);
         const installStarted = Date.now();
         const installed = await installLibrary({
@@ -97,9 +106,16 @@ export async function checkVersion(ctx, angular) {
             angularMajor: angular.major,
             cacheDir: ctx.cacheDir,
             offline: ctx.offline,
+            allowScripts: ctx.allowScripts,
         });
+        if (installed.skippedScripts.length)
+            report.skippedInstallScripts = installed.skippedScripts;
+        if (installed.environment)
+            return notChecked('The install', installed.environment, installed.errorLines);
         checks.install = result(installed.pass ? 'pass' : 'fail', installed.message, {
             errorLines: installed.errorLines,
+            fullOutput: installed.fullOutput,
+            hint: installed.pass ? undefined : installed.errorLines[0],
             durationMs: Date.now() - installStarted,
         });
         if (!installed.pass)
@@ -114,9 +130,10 @@ export async function checkVersion(ctx, angular) {
         if (!partial.pass)
             return finish();
         let files;
+        let api;
         if (!ctx.consumer) {
             try {
-                const api = readPublicApi(appDir, entryPoints(ctx.library.manifest));
+                api = readPublicApi(appDir, entryPoints(ctx.library.manifest));
                 writeSmoke(appDir, renderSmoke(api, { signalWriteBrand: hasSignalWriteBrand(appDir) }));
                 files = ['src/ngm-main.ts'];
             }
@@ -128,25 +145,83 @@ export async function checkVersion(ctx, angular) {
             }
         }
         const project = configureBuild(appDir, files?.[0]);
+        ctx.progress?.step(angular.major, 'AOT build');
         ctx.log(`${tag}: AOT build`);
-        const aot = await ngBuild(appDir, project.tsConfig, { strictTemplates: false, skipLibCheck: true }, files);
+        let aot = await ngBuild(appDir, project.tsConfig, { strictTemplates: false, skipLibCheck: true }, files);
+        if (aot.environment)
+            return notChecked('The AOT build', aot.environment, aot.errorLines);
+        const omittedList = [];
+        while (!aot.pass && !ctx.consumer && api) {
+            const undeclared = findUndeclaredImports(aot.errorLines, ctx.library.manifest, api.entries);
+            if (!undeclared.length)
+                break;
+            const mainName = ctx.library.manifest.name;
+            const isMain = (entry) => entry === mainName || entry === '.';
+            const mainUndeclared = undeclared.find((u) => isMain(u.entry));
+            const omittedSet = new Set(undeclared.map((u) => u.entry));
+            const remainingEntries = api.entries.filter((e) => !omittedSet.has(e));
+            if (mainUndeclared || remainingEntries.length === 0) {
+                const item = mainUndeclared ?? undeclared[0];
+                const reason = `${item.entry} imports ${item.missingPackage}, which isn't declared in dependencies or peers. Every user of ${item.entry} needs ${item.missingPackage} installed.`;
+                checks.aot = result('fail', reason, {
+                    errorLines: aot.errorLines,
+                    fullOutput: aot.fullOutput,
+                    hint: reason,
+                    durationMs: aot.durationMs,
+                });
+                return finish();
+            }
+            omittedList.push(...undeclared);
+            api.entries = remainingEntries;
+            api.declarables = api.declarables.filter((d) => !d.entry || !omittedSet.has(d.entry));
+            api.pipes = api.pipes.filter((p) => !p.entry || !omittedSet.has(p.entry));
+            api.modules = api.modules.filter((m) => !omittedSet.has(m.entry));
+            api.services = api.services.filter((s) => !omittedSet.has(s.entry));
+            writeSmoke(appDir, renderSmoke(api, { signalWriteBrand: hasSignalWriteBrand(appDir) }));
+            ctx.log(`${tag}: re-running AOT build without omitted entry points: ${[...omittedSet].join(', ')}`);
+            aot = await ngBuild(appDir, project.tsConfig, { strictTemplates: false, skipLibCheck: true }, files);
+            if (aot.environment)
+                return notChecked('The AOT build', aot.environment, aot.errorLines);
+        }
+        if (omittedList.length) {
+            report.omittedEntryPoints = omittedList;
+        }
         checks.aot = result(aot.pass ? 'pass' : 'fail', aot.pass ? 'Production build succeeded.' : 'Production build failed.', {
             errorLines: aot.errorLines,
-            hint: aot.hint,
+            fullOutput: aot.fullOutput,
+            hint: aot.hint ?? aot.errorLines[0],
             durationMs: aot.durationMs,
         });
         if (!aot.pass)
             return finish();
+        ctx.progress?.step(angular.major, 'strict build');
         ctx.log(`${tag}: strict build`);
         const strict = await ngBuild(appDir, project.tsConfig, { strictTemplates: true, skipLibCheck: false }, files);
-        checks.strict = result(strict.pass ? 'pass' : 'fail', strict.pass ? 'Builds with strictTemplates: true and skipLibCheck: false.' : 'Fails with strictTemplates: true and skipLibCheck: false.', { errorLines: strict.errorLines, hint: strict.hint, durationMs: strict.durationMs });
-        if (!strict.pass)
+        if (strict.environment)
+            return notChecked('The strict build', strict.environment, strict.errorLines);
+        const dtsOnly = !strict.pass && isDtsOnlyFailure(strict.errorLines);
+        if (dtsOnly) {
+            report.dtsErrors = true;
+        }
+        const dtsHint = strict.hint ?? (dtsOnly ? 'library typings have errors with skipLibCheck: false' : undefined);
+        checks.strict = result(strict.pass || dtsOnly ? 'pass' : 'fail', strict.pass
+            ? 'Builds with strictTemplates: true and skipLibCheck: false.'
+            : dtsOnly
+                ? 'Builds with strictTemplates: true; library typings have errors with skipLibCheck: false.'
+                : (dtsHint ?? strict.errorLines[0] ?? 'Fails with strictTemplates: true and skipLibCheck: false.'), {
+            errorLines: strict.errorLines,
+            fullOutput: strict.fullOutput,
+            hint: dtsHint ?? strict.errorLines[0],
+            durationMs: strict.durationMs,
+        });
+        if (checks.strict.status === 'fail')
             return finish();
         if (ctx.tests) {
             if (!ctx.workspace) {
                 checks.tests = result('off', 'No workspace to test: the package came from --tarball or --package.');
             }
             else {
+                ctx.progress?.step(angular.major, 'library tests');
                 ctx.log(`${tag}: library tests`);
                 const tests = await runLibraryTests({
                     workspace: ctx.workspace,
@@ -158,9 +233,14 @@ export async function checkVersion(ctx, angular) {
                     registry: ctx.registry,
                     cacheDir: ctx.cacheDir,
                     offline: ctx.offline,
+                    allowScripts: ctx.allowScripts,
                 });
+                if (tests.environment)
+                    return notChecked('The library tests', tests.environment, tests.errorLines);
                 checks.tests = result(tests.pass ? 'pass' : 'fail', tests.message, {
                     errorLines: tests.errorLines,
+                    fullOutput: tests.fullOutput,
+                    hint: tests.pass ? undefined : tests.errorLines[0],
                     durationMs: tests.durationMs,
                 });
             }

package/dist/scripts.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { npm } from "./exec.js";
+/*
+ * Install scripts run arbitrary code on the machine. By default ng-matrix runs only the ones the
+ * Angular toolchain itself needs: every package with an install script in a fresh Angular 17 to 22
+ * app is on this list. The package under test and its dependencies run none, unless --allow-scripts.
+ */
+export const TOOLCHAIN_BUILDS = ['@parcel/watcher', 'esbuild', 'lmdb', 'msgpackr-extract'];
+/**
+ * In the toolchain's tree with an install script that isn't needed, so it stays off and isn't
+ * reported: fsevents (macOS only) ships a prebuilt binary; its script would rebuild it with node-gyp.
+ */
+const TOOLCHAIN_UNNEEDED = ['fsevents'];
+export const ALLOW_SCRIPTS_WARNING = '--allow-scripts: install scripts of the package under test and all of its dependencies will run on this machine.';
+/**
+ * `npm install` with scripts off, then `npm rebuild` of just the toolchain packages: npm has no
+ * allow-list that works on both npm 10 and 11, but this does.
+ */
+export async function npmInstall(args, options, allowScripts) {
+    if (allowScripts)
+        return npm(args, options);
+    const installed = await npm([...args, '--ignore-scripts'], options);
+    if (installed.code !== 0)
+        return installed;
+    const present = TOOLCHAIN_BUILDS.filter((name) => existsSync(join(options.cwd, 'node_modules', ...name.split('/'), 'package.json')));
+    if (!present.length)
+        return installed;
+    const rebuilt = await npm(['rebuild', ...present], options);
+    return {
+        code: rebuilt.code,
+        output: `${installed.output}\n${rebuilt.output}`,
+        durationMs: installed.durationMs + rebuilt.durationMs,
+        timedOut: rebuilt.timedOut,
+    };
+}
+/** pnpm-workspace.yaml lines: builds allowed for the toolchain only, or for everything. */
+export function pnpmBuildSettings(allowScripts) {
+    if (allowScripts)
+        return ['strictDepBuilds: false', 'dangerouslyAllowAllBuilds: true'];
+    return ['strictDepBuilds: false', 'allowBuilds:', ...TOOLCHAIN_BUILDS.map((name) => `  ${JSON.stringify(name)}: true`)];
+}
+/** `name@version` of every installed package whose install script npm didn't run: its lockfile marks them. */
+export function skippedByNpm(appDir) {
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(join(appDir, 'package-lock.json'), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const skipped = new Set();
+    for (const [path, entry] of Object.entries(lock.packages ?? {})) {
+        if (!entry.hasInstallScript || !path.includes('node_modules/'))
+            continue;
+        const name = path.slice(path.lastIndexOf('node_modules/') + 'node_modules/'.length);
+        if (TOOLCHAIN_BUILDS.includes(name) || TOOLCHAIN_UNNEEDED.includes(name))
+            continue;
+        // The lockfile lists every platform's optional packages; only what's on disk counts.
+        if (!existsSync(join(appDir, path, 'package.json')))
+            continue;
+        skipped.add(entry.version ? `${name}@${entry.version}` : name);
+    }
+    return [...skipped].sort();
+}
+/** pnpm says so itself: `Ignored build scripts: core-js@3.46.0, sharp@0.34.1.` */
+export function skippedByPnpm(output) {
+    const line = /Ignored build scripts:\s*(.+?)\.?\s*$/m.exec(output);
+    if (!line)
+        return [];
+    const names = line[1].split(/,\s*/).map((s) => s.trim()).filter(Boolean);
+    return [...new Set(names.filter((spec) => !TOOLCHAIN_UNNEEDED.includes(spec.replace(/(.)@[^@]*$/, '$1'))))].sort();
+}

package/dist/smoke.js

@@ -240,18 +240,20 @@ class ApiReader {
         return inputs;
     }
     /**
-     * Whether users write this input as a bare attribute (`<div myFlag>`): it takes a boolean,
-     * a string, or anything. A number or object input is bound to a value instead.
+     * Whether users write this input as a bare attribute (`<div myFlag>`): it takes a string,
+     * accepts string/boolean (e.g. booleanAttribute transform), or anything.
+     * If an input accepts strictly boolean (without accepting string or empty string), it must be bound
+     * with `[prop]="..."` because a bare attribute passes string `""`, causing TS2322 in strict templates.
      */
     usedBare(node, property) {
         const ts = this.ts;
         const write = this.inputWriteType(node, property);
         if (!write)
-            return true;
+            return false;
         const parts = write.isUnion() ? write.types : [write];
-        // A union of other string literals ('ltr' | 'rtl') is bound to a value, like a number.
-        const flags = ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.String | ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral;
-        return parts.some((part) => (part.flags & flags) !== 0 || (part.isStringLiteral() && part.value === ''));
+        // Accepts string, any, unknown, or empty string literal "" (from booleanAttribute or union)
+        const stringFlags = ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.String;
+        return parts.some((part) => (part.flags & stringFlags) !== 0 || (part.isStringLiteral() && part.value === ''));
     }
     /** The type a binding to the input must have: a signal input's write type, `ngAcceptInputType_*`, or the property's type. */
     inputWriteType(node, property) {

package/dist/tests.js

@@ -2,8 +2,9 @@ import { cpSync, rmSync, writeFileSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import semver from 'semver';
 import { readJson, writeJson } from "./app.js";
-import { errorLines, exec, npm, quietEnv } from "./exec.js";
+import { environmentProblem, errorLines, exec, npm, quietEnv, stepTimeout } from "./exec.js";
 import { FRAMEWORK } from "./peers.js";
+import { npmInstall, pnpmBuildSettings } from "./scripts.js";
 import { ensureTool, PNPM_VERSION, pnpmEntry, pnpmShimDir, withPath } from "./tools.js";
 /** Packages released with the Angular CLI, versioned with it. */
 const TOOLING = /^(@angular\/(cli|build|ssr|pwa)|@angular-devkit\/.+|@schematics\/angular)$/;
@@ -67,17 +68,17 @@ export async function runLibraryTests(request) {
         const args = ['install', '--legacy-peer-deps', '--no-audit', '--no-fund'];
         if (request.offline)
             args.push('--offline');
-        install = await npm(args, { cwd: request.into, env, timeoutMs: 15 * 60_000 });
+        install = await npmInstall(args, { cwd: request.into, env, timeoutMs: stepTimeout() }, request.allowScripts);
     }
     else {
-        writeFileSync(join(request.into, 'pnpm-workspace.yaml'), 'strictPeerDependencies: false\nstrictDepBuilds: false\n');
+        writeFileSync(join(request.into, 'pnpm-workspace.yaml'), ['strictPeerDependencies: false', ...pnpmBuildSettings(request.allowScripts)].join('\n') + '\n');
         const pnpm = await ensureTool(request.cacheDir, 'pnpm', PNPM_VERSION, request.offline);
         // The test command runs in a shell; it has to find this pnpm, not whatever is (or isn't) installed.
         env = withPath(env, pnpmShimDir(request.cacheDir, pnpm));
         install = await exec(process.execPath, [pnpmEntry(pnpm), 'install', '--no-frozen-lockfile'], {
             cwd: request.into,
             env,
-            timeoutMs: 15 * 60_000,
+            timeoutMs: stepTimeout(),
         });
     }
     if (install.code !== 0) {
@@ -85,16 +86,20 @@ export async function runLibraryTests(request) {
             pass: false,
             message: `Installing the workspace with Angular ${request.angular.version} failed.`,
             errorLines: errorLines(install.output),
+            fullOutput: install.output,
             durationMs: Date.now() - started,
+            environment: environmentProblem(install),
         };
     }
     const command = request.command ?? `${request.pm} test`;
-    const result = await exec(command, [], { cwd: request.into, env, shell: true, timeoutMs: 30 * 60_000 });
+    const result = await exec(command, [], { cwd: request.into, env, shell: true, timeoutMs: stepTimeout() });
     const tail = result.output.split(/\r?\n/).filter((l) => l.trim()).slice(-8);
     return {
         pass: result.code === 0,
         message: result.code === 0 ? `\`${command}\` passed.` : `\`${command}\` exited with ${result.code}.`,
         errorLines: result.code === 0 ? tail.slice(-3) : errorLines(result.output),
+        fullOutput: result.output,
         durationMs: Date.now() - started,
+        environment: result.code === 0 ? undefined : environmentProblem(result),
     };
 }

package/dist/tools.js

@@ -1,7 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { delimiter, dirname, join } from 'node:path';
-import { errorLines, npm } from "./exec.js";
+import { environmentProblem, errorLines, npm } from "./exec.js";
 /** The pnpm ng-matrix uses, pinned so its peer and build-script rules don't shift under it. */
 export const PNPM_VERSION = '12.15.0';
 export function defaultCacheDir() {
@@ -11,6 +11,57 @@ export function defaultCacheDir() {
         return join(process.env.LOCALAPPDATA, 'ng-matrix', 'Cache');
     return join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'ng-matrix');
 }
+export function cacheStats(cacheDir) {
+    let bytes = 0;
+    let count = 0;
+    if (!existsSync(cacheDir))
+        return { bytes: 0, count: 0 };
+    const stack = [cacheDir];
+    while (stack.length) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                try {
+                    bytes += statSync(full).size;
+                    count++;
+                }
+                catch {
+                    // ignore transient access errors
+                }
+            }
+        }
+    }
+    return { bytes, count };
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let val = bytes / 1024;
+    for (const unit of units) {
+        if (val < 1024 || unit === 'TB') {
+            return `${val >= 10 ? val.toFixed(1) : val.toFixed(2)} ${unit}`;
+        }
+        val /= 1024;
+    }
+    return `${bytes} B`;
+}
+export function cleanCache(cacheDir) {
+    if (existsSync(cacheDir)) {
+        rmSync(cacheDir, { recursive: true, force: true, maxRetries: 5 });
+    }
+}
 const pending = new Map();
 /**
  * Installs one npm package into the cache once (say, `@angular/cli@21.2.28`) and returns its folder,
@@ -28,8 +79,11 @@ export function ensureTool(cacheDir, name, version, offline = false) {
 async function install(cacheDir, name, version, offline) {
     const home = join(cacheDir, 'tools', `${name.replace('/', '+')}@${version}`);
     const pkgDir = join(home, 'node_modules', ...name.split('/'));
-    if (existsSync(join(pkgDir, 'package.json')))
+    if (isComplete(pkgDir))
         return pkgDir;
+    // A damaged entry (a truncated package.json, a missing bin) is downloaded again.
+    if (existsSync(home))
+        rmSync(home, { recursive: true, force: true, maxRetries: 5 });
     const tmp = `${home}.${process.pid}.tmp`;
     rmSync(tmp, { recursive: true, force: true });
     mkdirSync(tmp, { recursive: true });
@@ -39,7 +93,8 @@ async function install(cacheDir, name, version, offline) {
     const result = await npm(args, { cwd: tmp });
     if (result.code !== 0) {
         rmSync(tmp, { recursive: true, force: true });
-        throw new Error(`Couldn't download ${name}@${version}:\n${errorLines(result.output).join('\n')}`);
+        const why = environmentProblem(result);
+        throw new Error(`Couldn't download ${name}@${version}${why ? `: ${why}` : ''}:\n${errorLines(result.output).join('\n')}`);
     }
     mkdirSync(dirname(home), { recursive: true });
     try {
@@ -51,6 +106,17 @@ async function install(cacheDir, name, version, offline) {
     }
     return pkgDir;
 }
+/** A cached tool is usable when its package.json parses and every bin it declares is there. */
+export function isComplete(pkgDir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+        const bins = typeof manifest.bin === 'string' ? [manifest.bin] : Object.values(manifest.bin ?? {});
+        return bins.every((bin) => existsSync(join(pkgDir, bin)));
+    }
+    catch {
+        return false;
+    }
+}
 export function binOf(pkgDir, bin) {
     const manifest = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
     const path = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.[bin];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "angular-compat-matrix",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Find out which Angular versions your published library really works with: it installs the packed package into a fresh app for each Angular major, builds it, and reports a matrix.",
   "keywords": [
     "angular",