angular-compat-matrix 0.0.0-stage → 0.2.0

package/dist/build.js

@@ -0,0 +1,167 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { writeTsconfig } from "./app.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'));
+    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: stepTimeout(),
+    });
+    if (result.code === 0)
+        return { pass: true, errorLines: [], 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) {
+    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 (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;
+}

package/dist/cleanup.js

@@ -0,0 +1,117 @@
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { killAllChildren } from "./exec.js";
+/*
+ * Temporary apps and half-written cache entries must not outlive a run, however it ends:
+ * normally, with Ctrl+C, or killed outright. Each work folder records the pid that owns it,
+ * and each cache write goes through `<name>.<pid>.tmp`, so whatever a dead run left behind
+ * can be told apart from what a running one is still using.
+ */
+const PREFIX = 'ng-matrix-';
+const OWNER = '.ng-matrix-pid';
+export function createWorkDir() {
+    const dir = mkdtempSync(join(tmpdir(), PREFIX));
+    writeFileSync(join(dir, OWNER), String(process.pid));
+    return dir;
+}
+export function isAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export function removeDir(dir) {
+    // On Windows a just-killed build can hold files open for a moment.
+    rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+}
+/** Removes work folders whose run is gone. Folders without an owner file (0.1.0) go after a day. */
+export function sweepWorkDirs(base = tmpdir()) {
+    const removed = [];
+    let entries;
+    try {
+        entries = readdirSync(base).filter((name) => name.startsWith(PREFIX));
+    }
+    catch {
+        return removed;
+    }
+    for (const name of entries) {
+        const dir = join(base, name);
+        try {
+            const owner = join(dir, OWNER);
+            const stale = existsSync(owner)
+                ? !isAlive(Number(readFileSync(owner, 'utf8')))
+                : Date.now() - statSync(dir).mtimeMs > 24 * 60 * 60 * 1000;
+            if (stale) {
+                removeDir(dir);
+                removed.push(dir);
+            }
+        }
+        catch {
+            // Not ours to judge, or already gone.
+        }
+    }
+    return removed;
+}
+/** Removes `<name>.<pid>.tmp` entries in the cache left by runs that are gone. */
+export function sweepCache(cacheDir) {
+    const removed = [];
+    for (const sub of ['tools', 'registry']) {
+        const dir = join(cacheDir, sub);
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const match = /\.(\d+)\.tmp$/.exec(name);
+            if (!match || isAlive(Number(match[1])))
+                continue;
+            try {
+                removeDir(join(dir, name));
+                removed.push(join(dir, name));
+            }
+            catch {
+                // Try again next run.
+            }
+        }
+    }
+    return removed;
+}
+/**
+ * On Ctrl+C (or SIGTERM, or a closed terminal): stop every child, remove the work folder unless
+ * --keep, and exit. A second Ctrl+C exits at once.
+ */
+export function cleanUpOnInterrupt(workDir, keep, log) {
+    let stopping = false;
+    const handler = (signal) => {
+        if (stopping)
+            process.exit(130);
+        stopping = true;
+        log(`Interrupted (${signal}): stopping, then ${keep ? `keeping ${workDir} (--keep)` : `removing ${workDir}`}.`);
+        killAllChildren();
+        if (!keep) {
+            try {
+                removeDir(workDir);
+            }
+            catch (error) {
+                log(`Couldn't remove ${workDir}: ${error.message}. The next run removes it.`);
+            }
+        }
+        process.exit(signal === 'SIGINT' || signal === 'SIGBREAK' ? 130 : 143);
+    };
+    const signals = process.platform === 'win32' ? ['SIGINT', 'SIGTERM', 'SIGBREAK'] : ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    for (const signal of signals)
+        process.on(signal, handler);
+    return () => {
+        for (const signal of signals)
+            process.off(signal, handler);
+    };
+}

package/dist/cli.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { cleanUpOnInterrupt, createWorkDir, removeDir, sweepCache, sweepWorkDirs } from "./cleanup.js";
+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 { SCHEMA_VERSION } from "./model.js";
+import { angularImports, scanPackage, summarize } from "./partial.js";
+import { Registry, RegistryError } from "./registry.js";
+import { exitCode, findings, renderJson, renderMarkdown, renderTerminal } from "./report.js";
+import { defaultConcurrency, runAll } from "./run.js";
+import { setStepTimeout, setVerbose } from "./exec.js";
+import { Progress } from "./progress.js";
+import { ALLOW_SCRIPTS_WARNING } from "./scripts.js";
+import { cacheStats, cleanCache, defaultCacheDir, formatBytes } 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)
+  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: 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
+  --json                 Shorthand for --format 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)
+  --step-timeout <min>   Longest any one step (ng new, install, build, tests) may take (default: 20)
+  --keep                 Keep the temporary apps, for debugging
+  --allow-scripts        Let the package's (and its dependencies') install scripts run. By
+                         default only the Angular toolchain's own builds run (esbuild, lmdb...)
+  --offline              Use only cached registry answers and packages
+  --cwd <dir>            The library's workspace (default: the current folder)
+  --verbose              Show commands run and full build/install output for failures
+  -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 (error instanceof RegistryError) {
+        process.stderr.write(`ng-matrix: ${error.message}\n`);
+    }
+    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' },
+            'allow-scripts': { type: 'boolean', default: false },
+            format: { type: 'string', default: 'terminal' },
+            json: { type: 'boolean', default: false },
+            pm: { type: 'string' },
+            build: { type: 'string' },
+            'skip-build': { type: 'boolean', default: false },
+            tarball: { type: 'string' },
+            package: { type: 'string' },
+            concurrency: { type: 'string' },
+            'step-timeout': { 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] === 'cache') {
+        const cacheDir = defaultCacheDir();
+        const sub = positionals[1];
+        if (!sub) {
+            const stats = cacheStats(cacheDir);
+            process.stdout.write(`Location: ${cacheDir}\nSize:     ${formatBytes(stats.bytes)} (${stats.count} files)\n`);
+            return 0;
+        }
+        if (sub === 'clean') {
+            cleanCache(cacheDir);
+            process.stdout.write(`Cleaned cache at ${cacheDir}\n`);
+            return 0;
+        }
+        fail(`Unknown cache command "ng-matrix cache ${sub}". See --help.`);
+    }
+    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.json ? 'json' : values.format;
+    if (!['terminal', 'markdown', 'json'].includes(format))
+        fail(`--format must be terminal, markdown or json, not "${format}".`);
+    if (values.verbose)
+        setVerbose(true);
+    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;
+    if (values['step-timeout'] !== undefined) {
+        const minutes = Number(values['step-timeout']);
+        if (!(minutes > 0))
+            fail(`--step-timeout must be a number of minutes above 0, not "${values['step-timeout']}".`);
+        setStepTimeout(minutes * 60_000);
+    }
+    const progress = new Progress(format !== 'json');
+    const log = (line) => progress.log(`[ng-matrix] ${line}`);
+    const cacheDir = defaultCacheDir();
+    const registry = new Registry({
+        cacheDir,
+        offline: values.offline,
+        recordedDir: process.env.NG_MATRIX_RECORDED_REGISTRY,
+    });
+    // Leftovers from runs that were killed before they could clean up.
+    sweepWorkDirs();
+    sweepCache(cacheDir);
+    const workDir = createWorkDir();
+    const stopListening = cleanUpOnInterrupt(workDir, values.keep, log);
+    if (values.keep)
+        log(`Working in ${workDir} (--keep)`);
+    if (values['allow-scripts'])
+        log(ALLOW_SCRIPTS_WARNING);
+    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,
+            allowScripts: values['allow-scripts'],
+            log,
+            progress,
+        }, angular, concurrency);
+        const report = {
+            schemaVersion: SCHEMA_VERSION,
+            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,
+            installScripts: values['allow-scripts'] ? 'all' : 'toolchain-only',
+            node: process.version,
+            versions,
+            findings: findings(versions, library.manifest, angularImports(library.dir)),
+            exitCode: exitCode(versions),
+        };
+        const render = format === 'json' ? (r) => renderJson(r, values.verbose) : 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 {
+        progress.stop();
+        stopListening();
+        if (!values.keep)
+            removeDir(workDir);
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (error) => process.exit(explain(error)));