angular-compat-matrix 0.0.0-stage → 0.2.0

package/dist/tools.js

@@ -0,0 +1,152 @@
+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 { 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() {
+    if (process.env.NG_MATRIX_CACHE)
+        return process.env.NG_MATRIX_CACHE;
+    if (process.platform === 'win32' && process.env.LOCALAPPDATA)
+        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,
+ * so each Angular major's CLI and the pinned pnpm are downloaded once, not on every run.
+ */
+export function ensureTool(cacheDir, name, version, offline = false) {
+    const key = `${name}@${version}`;
+    let promise = pending.get(key);
+    if (!promise) {
+        promise = install(cacheDir, name, version, offline);
+        pending.set(key, promise);
+    }
+    return promise;
+}
+async function install(cacheDir, name, version, offline) {
+    const home = join(cacheDir, 'tools', `${name.replace('/', '+')}@${version}`);
+    const pkgDir = join(home, 'node_modules', ...name.split('/'));
+    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 });
+    const args = ['install', `${name}@${version}`, '--prefix', tmp, '--no-save', '--no-package-lock', '--ignore-scripts'];
+    if (offline)
+        args.push('--offline');
+    const result = await npm(args, { cwd: tmp });
+    if (result.code !== 0) {
+        rmSync(tmp, { recursive: true, force: true });
+        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 {
+        renameSync(tmp, home);
+    }
+    catch {
+        // Another ng-matrix process got there first; theirs is as good as ours.
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    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];
+    if (!path)
+        throw new Error(`${pkgDir} has no "${bin}" command.`);
+    return join(pkgDir, path);
+}
+/**
+ * pnpm 11+ is a native binary that an install script puts in place of the `pnpm` bin; tools are
+ * installed with scripts off, so ng-matrix enters through `bin/pnpm.mjs`, as Corepack does, which
+ * finds the binary in the `@pnpm/exe.<platform>` optional dependency.
+ */
+export function pnpmEntry(pkgDir) {
+    const entry = join(pkgDir, 'bin', 'pnpm.mjs');
+    return existsSync(entry) ? entry : binOf(pkgDir, 'pnpm');
+}
+/**
+ * A folder with `pnpm` (and `pnpm.cmd` on Windows) that runs the cached pnpm, for PATH, so an
+ * author's test command (`pnpm test`, or a script that calls pnpm) finds the same pnpm.
+ */
+export function pnpmShimDir(cacheDir, pkgDir) {
+    const dir = join(cacheDir, 'tools', `pnpm-shim@${PNPM_VERSION}`);
+    mkdirSync(dir, { recursive: true });
+    const entry = pnpmEntry(pkgDir);
+    writeFileSync(join(dir, 'pnpm'), `#!/bin/sh\nexec "${process.execPath}" "${entry}" "$@"\n`, { mode: 0o755 });
+    writeFileSync(join(dir, 'pnpm.cmd'), `@"${process.execPath}" "${entry}" %*\r\n`);
+    return dir;
+}
+/** PATH with `dir` first, under whichever spelling of the key this platform uses. */
+export function withPath(env, dir) {
+    const key = Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH';
+    return { ...env, [key]: `${dir}${delimiter}${env[key] ?? ''}` };
+}

package/dist/versions.js

@@ -0,0 +1,138 @@
+import semver from 'semver';
+/** How long a major is supported after its x.0.0 release: 6 months active, then 12 months LTS. */
+export const SUPPORT_MONTHS = 18;
+/** Majors older than this are only checked on request, best effort. */
+export const OLDEST_DEFAULT_MAJOR = 17;
+export function stableVersions(packument) {
+    return Object.keys(packument.versions)
+        .filter((v) => semver.valid(v) && !semver.prerelease(v))
+        .sort(semver.rcompare);
+}
+export function latestOfMajor(packument, major) {
+    return stableVersions(packument).find((v) => semver.major(v) === major);
+}
+export function majorsOf(packument) {
+    return [...new Set(stableVersions(packument).map((v) => semver.major(v)))].sort((a, b) => a - b);
+}
+export function isSupported(packument, major, now) {
+    const released = packument.time[`${major}.0.0`];
+    const newest = Math.max(...majorsOf(packument));
+    if (major === newest)
+        return true;
+    if (!released)
+        return false;
+    const end = new Date(released);
+    end.setMonth(end.getMonth() + SUPPORT_MONTHS);
+    return now < end;
+}
+export function supportedMajors(packument, now) {
+    return majorsOf(packument).filter((major) => isSupported(packument, major, now));
+}
+/** The `next` tag, when it's ahead of `latest`. It may be a minor pre-release, not a new major. */
+export function nextVersion(packument) {
+    const next = packument['dist-tags'].next;
+    const latest = packument['dist-tags'].latest;
+    if (!next || !semver.valid(next))
+        return undefined;
+    if (latest && semver.lte(next, latest))
+        return undefined;
+    return next;
+}
+/** Newest version of a package (pre-releases only when asked) that satisfies a range. */
+export function newestSatisfying(packument, range, includePrerelease = false) {
+    return Object.keys(packument.versions)
+        .filter((v) => semver.valid(v) && (includePrerelease || !semver.prerelease(v)))
+        .sort(semver.rcompare)
+        .find((v) => semver.satisfies(v, range, { includePrerelease: true }));
+}
+export async function loadVersionSources(registry) {
+    const [core, cli, compilerCli] = await Promise.all([
+        registry.get('@angular/core'),
+        registry.get('@angular/cli'),
+        registry.get('@angular/compiler-cli'),
+    ]);
+    return { core, cli, compilerCli };
+}
+export function describeMajor(sources, major, now, useNext) {
+    const version = useNext && semver.major(useNext) === major ? useNext : latestOfMajor(sources.core, major);
+    if (!version)
+        throw new Error(`Angular ${major} isn't published on npm.`);
+    const prerelease = Boolean(semver.prerelease(version));
+    const cliVersion = (prerelease ? sameOrNewestPrerelease(sources.cli, version) : latestOfMajor(sources.cli, major)) ?? version;
+    const compilerVersion = sources.compilerCli.versions[version] ? version : latestOfMajor(sources.compilerCli, major);
+    const coreMeta = sources.core.versions[version];
+    const cliMeta = sources.cli.versions[cliVersion];
+    const compilerMeta = compilerVersion ? sources.compilerCli.versions[compilerVersion] : undefined;
+    const nodeRanges = [coreMeta.engines?.node, cliMeta?.engines?.node].filter((r) => Boolean(r));
+    return {
+        major,
+        version,
+        cliVersion,
+        releasedAt: sources.core.time[`${major}.0.0`],
+        supported: isSupported(sources.core, major, now),
+        nodeRanges,
+        typescriptRange: compilerMeta?.peerDependencies?.typescript,
+        rxjsRange: coreMeta.peerDependencies?.rxjs,
+        zoneRange: coreMeta.peerDependencies?.['zone.js'],
+        prerelease,
+    };
+}
+function sameOrNewestPrerelease(packument, version) {
+    if (packument.versions[version])
+        return version;
+    const major = semver.major(version);
+    return Object.keys(packument.versions)
+        .filter((v) => semver.valid(v) && semver.major(v) === major)
+        .sort(semver.rcompare)[0];
+}
+/** Parses `--versions`: `22`, `18-22`, `20,22`, or a mix. */
+export function parseVersionList(text) {
+    const majors = new Set();
+    for (const part of text.split(',').map((p) => p.trim()).filter(Boolean)) {
+        const range = /^(\d+)\s*-\s*(\d+)$/.exec(part);
+        if (range) {
+            const [from, to] = [Number(range[1]), Number(range[2])].sort((a, b) => a - b);
+            for (let m = from; m <= to; m++)
+                majors.add(m);
+        }
+        else if (/^\d+$/.test(part)) {
+            majors.add(Number(part));
+        }
+        else {
+            throw new Error(`--versions: "${part}" isn't a major or a range like 18-22`);
+        }
+    }
+    return [...majors].sort((a, b) => a - b);
+}
+/**
+ * Default majors: the supported ones, plus every major the package's `@angular/core` range claims
+ * (back to Angular 17), plus the newest, so "works but not claimed" shows up.
+ */
+export function defaultMajors(core, coreRange, now) {
+    const all = majorsOf(core);
+    const chosen = new Set(supportedMajors(core, now));
+    chosen.add(Math.max(...all));
+    if (coreRange) {
+        for (const major of all) {
+            if (major < OLDEST_DEFAULT_MAJOR)
+                continue;
+            const version = latestOfMajor(core, major);
+            if (version && claimsMajor(coreRange, major, version))
+                chosen.add(major);
+        }
+    }
+    return [...chosen].sort((a, b) => a - b);
+}
+function claimsMajor(range, major, latest) {
+    try {
+        return (semver.satisfies(latest, range, { includePrerelease: true }) ||
+            semver.intersects(range, `>=${major}.0.0 <${major + 1}.0.0-0`, { includePrerelease: true }));
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether this Node can run a major, reading `engines` as minimums (they have no upper bound). */
+export function nodeSatisfies(node, ranges) {
+    return ranges.every((range) => semver.satisfies(node, range, { includePrerelease: true }));
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "angular-compat-matrix",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "library",
+    "compatibility",
+    "peer-dependencies",
+    "ng-packagr",
+    "ci"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/berserker5619/angular-compat-matrix.git"
+  },
+  "bugs": "https://github.com/berserker5619/angular-compat-matrix/issues",
+  "homepage": "https://github.com/berserker5619/angular-compat-matrix#readme",
+  "license": "MIT",
+  "author": "Nizamudeen S",
+  "type": "module",
+  "bin": {
+    "angular-compat-matrix": "dist/cli.js",
+    "ng-matrix": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"test/unit/*.test.ts\"",
+    "test:fixtures": "node test/fixtures/run.ts",
+    "record-registry": "node scripts/record-registry.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "semver": "^7.7.3",
+    "tar": "^7.5.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "@types/semver": "^7.7.1",
+    "typescript": "~5.9.3"
+  }
+}