angular-compat-matrix 0.0.0-stage → 0.1.0

package/dist/report.js

@@ -0,0 +1,233 @@
+import { CHECK_LABELS, CHECKS } from "./model.js";
+const FAILING_CHECKS = ['install', 'partial', 'aot', 'strict', 'tests'];
+function firstFailure(version) {
+    for (const name of FAILING_CHECKS) {
+        if (version.checks[name].status === 'fail')
+            return [name, version.checks[name]];
+    }
+    return undefined;
+}
+/** Everything that ran, passed. */
+function works(version) {
+    return !version.setupError && !firstFailure(version);
+}
+/** CI goes red only for broken promises (2 means ng-matrix itself couldn't check a version). */
+export function exitCode(versions) {
+    if (versions.some((v) => v.setupError))
+        return 2;
+    return versions.some((v) => v.claimed === true && firstFailure(v)) ? 1 : 0;
+}
+export function findings(versions, manifest, 
+/** The `@angular/*` packages the published code imports. */
+angularImports = ['@angular/core']) {
+    const raw = [];
+    for (const version of versions) {
+        const m = version.major;
+        if (version.setupError) {
+            raw.push({ level: 'error', majors: [m], key: `setup:${version.setupError}`, text: `ng-matrix couldn't set up the app: ${version.setupError}` });
+            continue;
+        }
+        const failure = firstFailure(version);
+        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);
+            if (version.claimed === true) {
+                raw.push({ level: 'error', majors: [m], key: `fail:${name}:${why}`, text: `${CHECK_LABELS[name]}: ${why}` });
+            }
+            else if (version.claimed === false) {
+                raw.push({
+                    level: 'note',
+                    majors: [m],
+                    key: `outside:${name}`,
+                    text: `${CHECK_LABELS[name]} fails, but the peer range doesn't claim this version, so that's expected.`,
+                });
+            }
+            else {
+                raw.push({ level: 'warning', majors: [m], key: `fail:${name}:${why}`, text: `${CHECK_LABELS[name]}: ${why}` });
+            }
+        }
+        else if (version.claimed === false) {
+            const ranges = version.peerMisses.map((miss) => `${miss.name} "${miss.range}"`).join(', ');
+            raw.push({
+                level: 'warning',
+                majors: [m],
+                key: `unclaimed:${ranges}`,
+                text: `works, but peerDependencies doesn't allow it (${ranges}). Widen the range to include it.`,
+            });
+        }
+    }
+    // One finding per distinct problem, listing every major it applies to.
+    const merged = [];
+    const byKey = new Map();
+    for (const finding of raw) {
+        const existing = byKey.get(finding.key);
+        if (existing)
+            existing.majors.push(...finding.majors);
+        else {
+            const copy = { level: finding.level, majors: [...finding.majors], text: finding.text };
+            byKey.set(finding.key, copy);
+            merged.push(copy);
+        }
+    }
+    const hasAngularPeer = Object.keys(manifest.peerDependencies ?? {}).some((n) => n.startsWith('@angular/'));
+    if (!hasAngularPeer)
+        merged.push(missingPeersFinding(versions, angularImports));
+    const order = { error: 0, warning: 1, note: 2 };
+    return merged.sort((a, b) => order[a.level] - order[b.level]);
+}
+/**
+ * A package without `@angular/*` peers claims nothing, so nothing tells a package manager which
+ * Angular it needs. The hint suggests a range from the majors that passed every check, for each
+ * Angular package the published code imports.
+ */
+function missingPeersFinding(versions, angularImports) {
+    const working = versions.filter((v) => works(v) && !v.prerelease).map((v) => v.major);
+    const text = "The package declares no @angular/* peer dependency, so it claims no version and package managers can't warn about a mismatch.";
+    if (!working.length)
+        return { level: 'warning', majors: [], text: `${text} No version passed in this run, so there's no range to suggest.` };
+    const range = [...new Set(working)].sort((a, b) => a - b).map((m) => `^${m}.0.0`).join(' || ');
+    const packages = [...new Set(['@angular/core', ...angularImports])].sort();
+    const suggested = Object.fromEntries(packages.map((name) => [name, range]));
+    const lines = packages.map((name) => `"${name}": "${range}"`).join(', ');
+    return {
+        level: 'warning',
+        majors: [],
+        text: `${text} From the versions that passed: ${lines}.`,
+        suggestedPeerDependencies: suggested,
+    };
+}
+export function majorsText(majors) {
+    const sorted = [...new Set(majors)].sort((a, b) => a - b);
+    const runs = [];
+    for (let i = 0; i < sorted.length; i++) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1)
+            j++;
+        runs.push(j > i ? `${sorted[i]}–${sorted[j]}` : String(sorted[i]));
+        i = j;
+    }
+    return runs.join(', ');
+}
+// ---------------------------------------------------------------- terminal
+const SYMBOL = { pass: '✓', fail: '✗', 'not-run': '—', off: '', none: '·' };
+function symbol(check) {
+    if (check.status === 'pass' && check.advisory)
+        return '✓?';
+    return SYMBOL[check.status];
+}
+function columns(report) {
+    return CHECKS.filter((c) => c !== 'tests' || report.versions.some((v) => v.checks.tests.status !== 'off'));
+}
+function rowLabel(version) {
+    return version.prerelease ? `Angular ${version.angularVersion}` : `Angular ${version.major}`;
+}
+function center(text, width) {
+    const length = [...text].length;
+    const left = Math.floor((width - length) / 2);
+    return ' '.repeat(Math.max(0, left)) + text + ' '.repeat(Math.max(0, width - length - left));
+}
+export function headline(report) {
+    const parts = [];
+    if (report.library.compiledWith)
+        parts.push(`compiled with Angular ${report.library.compiledWith}`);
+    if (report.library.highestMinVersion)
+        parts.push(`highest minVersion ${report.library.highestMinVersion}`);
+    return `${report.library.name}@${report.library.version}${parts.length ? ` (${parts.join('; ')})` : ''}`;
+}
+export function renderTerminal(report, verbose = false) {
+    const cols = columns(report);
+    const labelWidth = Math.max(...report.versions.map((v) => rowLabel(v).length), 10) + 2;
+    const widths = cols.map((c) => CHECK_LABELS[c].length + 2);
+    const lines = [headline(report), ''];
+    lines.push(' '.repeat(labelWidth) + cols.map((c, i) => center(CHECK_LABELS[c], widths[i])).join(''));
+    for (const version of report.versions) {
+        const cells = version.setupError
+            ? cols.map((c, i) => center(c === 'peer' ? symbol(version.checks.peer) : '!', widths[i]))
+            : cols.map((c, i) => center(symbol(version.checks[c]), widths[i]));
+        lines.push(rowLabel(version).padEnd(labelWidth) + cells.join('').trimEnd());
+    }
+    if (report.versions.some((v) => v.checks.partial.advisory)) {
+        lines.push('', '✓? partial passed on minVersion alone, which has been too low before; the build decides.');
+    }
+    if (report.findings.length)
+        lines.push('');
+    for (const finding of report.findings) {
+        const mark = finding.level === 'error' ? '✗' : finding.level === 'warning' ? '!' : '·';
+        const where = finding.majors.length ? `${majorsText(finding.majors)}: ` : '';
+        lines.push(wrap(`${mark} ${where}${finding.text}`, 88, '  '));
+    }
+    const failing = report.versions.filter((v) => firstFailure(v) || v.setupError);
+    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)
+            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()}`);
+    }
+    lines.push('', exitSummary(report));
+    return lines.join('\n') + '\n';
+}
+function exitSummary(report) {
+    if (report.exitCode === 2)
+        return "Couldn't check every version; see above.";
+    if (report.exitCode === 1)
+        return 'A version the peer range claims is broken.';
+    return 'Every version the peer range claims works.';
+}
+function wrap(text, width, indent) {
+    const words = text.split(' ');
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        if (current && (current + ' ' + word).length > width) {
+            lines.push(current);
+            current = indent + word;
+        }
+        else
+            current = current ? `${current} ${word}` : word;
+    }
+    if (current)
+        lines.push(current);
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------- markdown
+const MD = { pass: '✅', fail: '❌', 'not-run': '—', off: '', none: 'n/a' };
+export function renderMarkdown(report) {
+    const cols = columns(report);
+    const date = report.checkedAt.slice(0, 10);
+    const compiled = report.library.compiledWith ? `, compiled with Angular ${report.library.compiledWith}` : '';
+    const lines = [
+        '## Angular compatibility',
+        '',
+        `Checked on ${date} for \`${report.library.name}@${report.library.version}\`${compiled}, by installing the packed package into a fresh app of each version with ${report.packageManager} and building it ([angular-compat-matrix](https://github.com/berserker5619/angular-compat-matrix)).`,
+        '',
+        `| Angular | ${cols.map((c) => CHECK_LABELS[c][0].toUpperCase() + CHECK_LABELS[c].slice(1)).join(' | ')} |`,
+        `| :-- | ${cols.map(() => ':-:').join(' | ')} |`,
+    ];
+    for (const version of report.versions) {
+        const cells = cols.map((c) => {
+            if (version.setupError && c !== 'peer')
+                return '⚠️';
+            const check = version.checks[c];
+            return check.status === 'pass' && check.advisory ? '✅*' : MD[check.status];
+        });
+        lines.push(`| ${version.prerelease ? version.angularVersion : `${version.major} (${version.angularVersion})`} | ${cells.join(' | ')} |`);
+    }
+    if (report.findings.length)
+        lines.push('');
+    for (const finding of report.findings) {
+        const mark = finding.level === 'error' ? '❌' : finding.level === 'warning' ? '⚠️' : 'ℹ️';
+        const where = finding.majors.length ? `**${majorsText(finding.majors)}:** ` : '';
+        lines.push(`- ${mark} ${where}${finding.text}`);
+    }
+    if (report.versions.some((v) => v.checks.partial.advisory)) {
+        lines.push('', '\\* Passed on `minVersion` alone, which has been too low before; the build decides.');
+    }
+    return lines.join('\n') + '\n';
+}
+export function renderJson(report) {
+    return JSON.stringify(report, null, 2) + '\n';
+}

package/dist/run.js

@@ -0,0 +1,200 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+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 { installLibrary } from "./install.js";
+import { CHECKS, result } from "./model.js";
+import { judgePartial } from "./partial.js";
+import { planPeers } from "./peers.js";
+import { entryPoints, hasSignalWriteBrand, readPublicApi, renderSmoke, writeSmoke } from "./smoke.js";
+import { runLibraryTests, swapVersions } from "./tests.js";
+/** About what one Angular production build needs; versions beyond what memory allows wait their turn. */
+const MEMORY_PER_VERSION = 2.5 * 1024 ** 3;
+export function defaultConcurrency(versions) {
+    const byMemory = Math.floor(freemem() / MEMORY_PER_VERSION);
+    return Math.max(1, Math.min(versions, byMemory, availableParallelism()));
+}
+export async function runAll(ctx, majors, concurrency) {
+    const reports = new Array(majors.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < majors.length) {
+            const index = next++;
+            reports[index] = await checkVersion(ctx, majors[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, majors.length) }, worker));
+    return reports;
+}
+function installedAngular(appDir, fallback) {
+    try {
+        const require = createRequire(join(appDir, 'package.json'));
+        return JSON.parse(readFileSync(require.resolve('@angular/core/package.json'), 'utf8')).version;
+    }
+    catch {
+        return fallback;
+    }
+}
+export async function checkVersion(ctx, angular) {
+    const started = Date.now();
+    const tag = `Angular ${angular.major}`;
+    const checks = Object.fromEntries(CHECKS.map((c) => [c, result('not-run')]));
+    if (!ctx.tests)
+        checks.tests = result('off', 'Not requested (--tests).');
+    const report = {
+        major: angular.major,
+        angularVersion: angular.version,
+        supported: angular.supported,
+        prerelease: angular.prerelease,
+        claimed: null,
+        peerMisses: [],
+        checks,
+        durationMs: 0,
+    };
+    const finish = () => {
+        report.durationMs = Date.now() - started;
+        ctx.log(`${tag}: done in ${Math.round(report.durationMs / 1000)} s`);
+        return report;
+    };
+    // Peer range: reported, but never stops the other checks.
+    const plan = await planPeers(ctx.library.manifest, angular.version, ctx.registry);
+    report.claimed = plan.claimed;
+    report.peerMisses = plan.misses;
+    checks.peer =
+        plan.claimed === null
+            ? result('none', 'The package declares no @angular/* peer dependency.')
+            : plan.claimed
+                ? result('pass', `Claimed: ${Object.entries(plan.checked).map(([n, v]) => `${n}@${v}`).join(', ')}.`)
+                : result('fail', plan.misses.map((m) => `${m.name} "${m.range}" doesn't allow ${m.version}`).join('; ') + '.');
+    const versionDir = join(ctx.workDir, `angular-${angular.major}`);
+    mkdirSync(versionDir, { recursive: true });
+    let appDir;
+    try {
+        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)
+            : await generateApp(angular, ctx.pm, versionDir, ctx.cacheDir, ctx.offline);
+        if (ctx.keep)
+            report.appDir = appDir;
+    }
+    catch (error) {
+        report.setupError = error.message;
+        if (!ctx.keep)
+            rmSync(versionDir, { recursive: true, force: true, maxRetries: 3 });
+        return finish();
+    }
+    try {
+        ctx.log(`${tag}: installing ${ctx.library.manifest.name} with ${ctx.pm}`);
+        const installStarted = Date.now();
+        const installed = await installLibrary({
+            appDir,
+            pm: ctx.pm,
+            libraryName: ctx.library.manifest.name,
+            tarball: ctx.library.tarball,
+            plan,
+            angularMajor: angular.major,
+            cacheDir: ctx.cacheDir,
+            offline: ctx.offline,
+        });
+        checks.install = result(installed.pass ? 'pass' : 'fail', installed.message, {
+            errorLines: installed.errorLines,
+            durationMs: Date.now() - installStarted,
+        });
+        if (!installed.pass)
+            return finish();
+        const actual = installedAngular(appDir, angular.version);
+        report.angularVersion = actual;
+        const partial = judgePartial(ctx.summary, actual);
+        checks.partial = result(partial.pass ? 'pass' : 'fail', partial.message, {
+            advisory: partial.advisory,
+            hint: partial.pass ? undefined : 'Build the library with the oldest Angular you support, or take this version out of the peer range.',
+        });
+        if (!partial.pass)
+            return finish();
+        let files;
+        if (!ctx.consumer) {
+            try {
+                const api = readPublicApi(appDir, entryPoints(ctx.library.manifest));
+                writeSmoke(appDir, renderSmoke(api, { signalWriteBrand: hasSignalWriteBrand(appDir) }));
+                files = ['src/ngm-main.ts'];
+            }
+            catch (error) {
+                checks.aot = result('fail', `Couldn't generate the smoke app from the package's typings: ${error.message}`, {
+                    hint: 'If the typings are fine, give ng-matrix an example app with --consumer.',
+                });
+                return finish();
+            }
+        }
+        const project = configureBuild(appDir, files?.[0]);
+        ctx.log(`${tag}: AOT build`);
+        const aot = await ngBuild(appDir, project.tsConfig, { strictTemplates: false, skipLibCheck: true }, files);
+        checks.aot = result(aot.pass ? 'pass' : 'fail', aot.pass ? 'Production build succeeded.' : 'Production build failed.', {
+            errorLines: aot.errorLines,
+            hint: aot.hint,
+            durationMs: aot.durationMs,
+        });
+        if (!aot.pass)
+            return finish();
+        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)
+            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.log(`${tag}: library tests`);
+                const tests = await runLibraryTests({
+                    workspace: ctx.workspace,
+                    into: join(versionDir, 'tests'),
+                    angular,
+                    peerVersions: plan.installs,
+                    pm: ctx.pm,
+                    command: ctx.testCommand,
+                    registry: ctx.registry,
+                    cacheDir: ctx.cacheDir,
+                    offline: ctx.offline,
+                });
+                checks.tests = result(tests.pass ? 'pass' : 'fail', tests.message, {
+                    errorLines: tests.errorLines,
+                    durationMs: tests.durationMs,
+                });
+            }
+        }
+        return finish();
+    }
+    finally {
+        if (!ctx.keep)
+            rmSync(versionDir, { recursive: true, force: true, maxRetries: 3 });
+    }
+}
+/** Copies the author's example app and moves its Angular dependencies to this version. */
+async function copyConsumer(ctx, angular, peerVersions, versionDir) {
+    const source = ctx.consumer;
+    if (!existsSync(join(source, 'angular.json')))
+        throw new Error(`--consumer ${source} has no angular.json.`);
+    const appDir = join(versionDir, 'app');
+    const skip = new Set(['node_modules', '.angular', 'dist', '.git']);
+    cpSync(source, appDir, {
+        recursive: true,
+        filter: (path) => !relative(source, path).split(sep).some((part) => skip.has(part)),
+    });
+    for (const lock of ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'])
+        rmSync(join(appDir, lock), { force: true });
+    const manifestPath = join(appDir, 'package.json');
+    const manifest = readJson(manifestPath);
+    const request = { angular, peerVersions };
+    if (manifest.dependencies)
+        manifest.dependencies = swapVersions(manifest.dependencies, request);
+    if (manifest.devDependencies)
+        manifest.devDependencies = swapVersions(manifest.devDependencies, request);
+    // The package under test comes from the tarball, not from wherever the example points.
+    delete manifest.dependencies?.[ctx.library.manifest.name];
+    delete manifest.devDependencies?.[ctx.library.manifest.name];
+    writeJson(manifestPath, manifest);
+    return appDir;
+}