angular-compat-matrix 0.0.0-stage → 0.2.0

package/dist/peers.js

@@ -0,0 +1,79 @@
+import semver from 'semver';
+import { newestSatisfying } from "./versions.js";
+/** Packages released in lockstep with `@angular/core`: same version number, always. */
+export const FRAMEWORK = new Set([
+    '@angular/animations',
+    '@angular/common',
+    '@angular/compiler',
+    '@angular/compiler-cli',
+    '@angular/core',
+    '@angular/elements',
+    '@angular/forms',
+    '@angular/language-service',
+    '@angular/localize',
+    '@angular/platform-browser',
+    '@angular/platform-browser-dynamic',
+    '@angular/platform-server',
+    '@angular/router',
+    '@angular/service-worker',
+    '@angular/upgrade',
+]);
+/** Peers a generated app already has at the right version, so they're never installed again. */
+const APP_PROVIDED = new Set(['rxjs', 'tslib', 'zone.js', 'typescript']);
+function isOptional(manifest, name) {
+    return Boolean(manifest.peerDependenciesMeta?.[name]?.optional);
+}
+/**
+ * The newest version of a non-framework peer (Angular Material, the CDK, a third-party package)
+ * that a real app on this Angular would use: one whose own `@angular/*` peers accept it,
+ * preferring versions the library's range allows.
+ */
+export function pickPeerVersion(packument, libraryRange, angularVersion) {
+    const pre = Boolean(semver.prerelease(angularVersion));
+    const candidates = Object.keys(packument.versions)
+        .filter((v) => semver.valid(v) && (pre || !semver.prerelease(v)))
+        .sort(semver.rcompare);
+    const acceptsAngular = (v) => {
+        const peers = packument.versions[v].peerDependencies ?? {};
+        const framework = Object.entries(peers).filter(([name]) => FRAMEWORK.has(name));
+        return framework.every(([, range]) => semver.satisfies(angularVersion, range, { includePrerelease: true }));
+    };
+    const inRange = (v) => semver.satisfies(v, libraryRange, { includePrerelease: true });
+    const hasFrameworkPeer = (v) => Object.keys(packument.versions[v].peerDependencies ?? {}).some((name) => FRAMEWORK.has(name));
+    // Packages that don't depend on Angular (say, a date library) just follow the library's range.
+    if (!candidates.some(hasFrameworkPeer))
+        return candidates.find(inRange) ?? newestSatisfying(packument, '*');
+    return (candidates.find((v) => acceptsAngular(v) && inRange(v)) ??
+        candidates.find(acceptsAngular) ??
+        candidates.find(inRange));
+}
+export async function planPeers(manifest, angularVersion, registry) {
+    const peers = manifest.peerDependencies ?? {};
+    const installs = {};
+    const checked = {};
+    const misses = [];
+    let angularPeers = 0;
+    for (const [name, range] of Object.entries(peers)) {
+        let version;
+        if (FRAMEWORK.has(name)) {
+            version = angularVersion;
+            installs[name] = angularVersion;
+        }
+        else if (!APP_PROVIDED.has(name)) {
+            version = pickPeerVersion(await registry.get(name), range, angularVersion);
+            if (version)
+                installs[name] = version;
+        }
+        // Optional peers are installed (the smoke app imports every entry point, and some entry point
+        // needs them, as angular-calendar's date-fns adapter needs date-fns) but claim nothing.
+        if (!name.startsWith('@angular/') || isOptional(manifest, name))
+            continue;
+        angularPeers++;
+        const against = version ?? 'none';
+        checked[name] = against;
+        if (!version || !semver.satisfies(version, range, { includePrerelease: true })) {
+            misses.push({ name, range, version: against });
+        }
+    }
+    return { claimed: angularPeers ? misses.length === 0 : null, misses, installs, checked };
+}

package/dist/progress.js

@@ -0,0 +1,65 @@
+export class Progress {
+    active = new Map();
+    timer;
+    isTTY;
+    rendered = false;
+    constructor(enabled) {
+        this.isTTY = enabled && Boolean(process.stderr.isTTY);
+        if (this.isTTY) {
+            this.timer = setInterval(() => this.render(), 1000);
+            this.timer.unref();
+        }
+    }
+    step(major, step) {
+        this.active.set(major, { step, started: Date.now() });
+        if (this.isTTY)
+            this.render();
+    }
+    done(major) {
+        this.active.delete(major);
+        if (this.isTTY)
+            this.render();
+    }
+    log(line) {
+        if (this.isTTY) {
+            this.clear();
+            process.stderr.write(`${line}\n`);
+            this.render();
+        }
+        else {
+            process.stderr.write(`${line}\n`);
+        }
+    }
+    render() {
+        if (!this.isTTY)
+            return;
+        if (this.active.size === 0) {
+            this.clear();
+            return;
+        }
+        const parts = [];
+        const now = Date.now();
+        for (const [major, item] of this.active) {
+            const elapsed = Math.floor((now - item.started) / 1000);
+            parts.push(`Angular ${major}: ${item.step} (${elapsed}s)`);
+        }
+        const text = `[ng-matrix] ${parts.join(' | ')}`;
+        process.stderr.write(`\r\x1b[K${text}`);
+        this.rendered = true;
+    }
+    clear() {
+        if (this.rendered) {
+            process.stderr.write('\r\x1b[K');
+            this.rendered = false;
+        }
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.isTTY) {
+            this.clear();
+        }
+    }
+}

package/dist/registry.js

@@ -0,0 +1,135 @@
+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']);
+export class Registry {
+    memory = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get(name) {
+        let pending = this.memory.get(name);
+        if (!pending) {
+            pending = this.load(name);
+            this.memory.set(name, pending);
+        }
+        return pending;
+    }
+    async load(name) {
+        const file = `${encodeURIComponent(name)}.json`;
+        if (this.options.recordedDir) {
+            const path = join(this.options.recordedDir, file);
+            if (!existsSync(path))
+                throw new Error(`No recorded registry answer for ${name} (${path})`);
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        const dir = join(this.options.cacheDir, 'registry');
+        const path = join(dir, file);
+        const cached = readCached(path);
+        const maxAge = this.options.maxAgeMs ?? DAY;
+        if (cached && (this.options.offline || Date.now() - cached.fetchedAt < maxAge))
+            return cached.packument;
+        if (this.options.offline)
+            throw new Error(`--offline: ${name} isn't in the registry cache yet. Run once online first.`);
+        const base = (this.options.registryUrl ?? process.env.npm_config_registry ?? 'https://registry.npmjs.org/').replace(/\/?$/, '/');
+        const url = base + name.replace('/', '%2f');
+        // Only @angular/core's publish dates are needed (to tell which majors are supported); everything
+        // else comes from the abbreviated document, which is much smaller for packages with many versions.
+        const accept = FULL_DOCUMENT.has(name)
+            ? 'application/json'
+            : 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8';
+        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);
+            }
+        }
+        if (!packument) {
+            if (cached)
+                return cached.packument;
+            throw new RegistryError(`Couldn't get ${name} from the npm registry (${base}): ${problem}.`);
+        }
+        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;
+        }
+    }
+    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 });
+        writeFileSync(tmp, JSON.stringify({ fetchedAt: Date.now(), packument }));
+        renameSync(tmp, path);
+    }
+    catch {
+        // Caching is an optimisation; the run goes on without it.
+        rmSync(tmp, { force: true });
+    }
+}
+export function trim(raw) {
+    const versions = {};
+    for (const [version, meta] of Object.entries(raw.versions ?? {})) {
+        const kept = { version };
+        if (meta.peerDependencies)
+            kept.peerDependencies = meta.peerDependencies;
+        if (meta.peerDependenciesMeta)
+            kept.peerDependenciesMeta = meta.peerDependenciesMeta;
+        if (meta.dependencies)
+            kept.dependencies = meta.dependencies;
+        if (meta.engines && typeof meta.engines === 'object')
+            kept.engines = meta.engines;
+        versions[version] = kept;
+    }
+    const time = {};
+    for (const version of Object.keys(versions))
+        if (raw.time?.[version])
+            time[version] = raw.time[version];
+    return { name: raw.name, 'dist-tags': raw['dist-tags'] ?? {}, versions, time };
+}

package/dist/report.js

@@ -0,0 +1,280 @@
+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.errorLines?.[0] ?? 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}` });
+            }
+            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(', ');
+            raw.push({
+                level: 'warning',
+                majors: [m],
+                key: `unclaimed:${ranges}`,
+                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 = [];
+    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 ?? []);
+        const full = failure?.[1].fullOutput;
+        if (!errors.length && !full)
+            continue;
+        lines.push('', `${rowLabel(version)}, ${failure ? CHECK_LABELS[failure[0]] : 'setup'}:`);
+        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';
+}
+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, 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';
+}