upstreamfix 0.1.0 → 0.1.3

package/README.md

@@ -2,17 +2,17 @@
 
 **UpstreamFix previews code changes for supported breaking SDK upgrades, reports cases that need a developer, and can commit verified changes on a dedicated Git branch.**
 
-> **Experimental (0.1.0).** Review every proposed change and test your application before using a migration in production. The source code is available in the [public GitHub repository](https://github.com/ivanDev237/upstreamfix).
+> **Experimental (0.x).** Review every proposed change and test your application before using a migration in production. The source code is available in the [public GitHub repository](https://github.com/ivanDev237/upstreamfix).
 
 ## Demo
 
-![Illustrative terminal walkthrough of listing, scanning, and previewing a migration](docs/upstreamfix-demo.gif)
+[View the illustrative terminal walkthrough](https://github.com/ivanDev237/upstreamfix/blob/main/docs/upstreamfix-demo.gif) of listing, scanning, and previewing a migration.
 
 The frames show the intended command flow. Output varies with the project and migration findings.
 
 ## Quick start
 
-Once a release is available on npm, start with `npx upstreamfix@latest list`. To inspect a project without changing its files, run:
+Start with `npx upstreamfix@latest list`. To inspect a project without changing its files, run:
 
 ```sh
 npx --yes upstreamfix@latest list
@@ -32,10 +32,27 @@ The report path is explicit; preview commands do not create report files unless
 
 Run `upstreamfix list` for the catalog included in the installed version. Run `upstreamfix scan --cwd <project>` to select migrations from package versions declared in root or nested `package.json` files.
 
+## Detecting SDK changes
+
+These commands report evidence for review. They do not create migration rules or pull requests.
+
+```sh
+upstreamfix watch --state /path/to/upstreamfix-watch.json
+upstreamfix diff-api firebase-admin 13.10.0 14.0.0
+upstreamfix impact --cwd /path/to/project
+upstreamfix probe stripe@23.0.0 --cwd /path/to/project
+```
+
+`watch` checks the npm `latest` tags of catalog packages. The first run records a baseline; later runs record newly observed **major** versions in the chosen JSON file. It makes small registry requests and updates the file atomically. `diff-api` downloads two exact npm tarballs, verifies their published integrity values, and compares public TypeScript declarations. Removed or changed declarations are clues; apparent renames are explicitly hypotheses. The archive size is capped and no package scripts run.
+
+`impact` reads declared versions in root and nested manifests, looks up each catalog package's latest npm version, and estimates automatic versus manual source findings using the catalog's current rules. It does not install dependencies or modify the project. Its counts are estimates, not a compatibility guarantee.
+
+`probe` needs a Git project with a root npm lockfile and TypeScript. It shows an estimated cold download first and exits without downloading. Add `--yes` after reviewing that estimate. It copies the project, installs the locked baseline and an exact target SDK version with lifecycle scripts disabled, and runs both compiler checks in a pinned Docker image with no network and a read-only project mount. Existing compiler errors are separated from new candidates. A new error is **not proof** that the SDK caused it. The original files and lockfile remain untouched. pnpm/Yarn projects and projects without a readable TypeScript check currently return "measurement unavailable". Docker and registry access are required only for the confirmed probe.
+
 ## What is not supported
 
 - The GitHub Action exits without changing a repository; automatic pull requests are not available.
-- UpstreamFix does not watch package registries, discover new API changes, or invent migrations. It only previews migration rules already included in the release.
+- `watch`, `diff-api`, and `probe` can identify new version and type-change candidates. They do not generate or approve safe migration rules automatically.
 - Only migrations shown by `upstreamfix list` are supported. Unsupported, ambiguous, or semantic API changes require manual work.
 - Lockfile previews cover standalone root projects using npm v3, pnpm, or Yarn Classic lockfiles. Regenerating a lockfile may contact the package registry; pnpm or Yarn must already be installed and match any `packageManager` pin. Workspaces, Yarn Berry, shrinkwrap, project package-manager configuration files, and local or non-registry dependencies are left for manual review.
 

package/dist/cli.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
 import { mkdir, writeFile } from 'node:fs/promises';
+import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { renderMarkdownReport, renderTerminalReport } from './core/report.js';
+import { renderMarkdownReport, renderTerminalReport, sanitizeTerminalText } from './core/report.js';
 import { runMigration } from './core/runner.js';
 import { verifyProposedMigration } from './core/verify.js';
 import { writeMigrationOnBranch } from './core/write-branch.js';
 import { assertWritesEnabled } from './core/safety.js';
 import { findApplicableMigrations, migrations } from './migrations/index.js';
+import { watchPackages } from './core/watch.js';
+import { diffPublishedApi } from './core/diff-api.js';
+import { analyzeImpact } from './core/impact.js';
+import { probeProject } from './core/probe.js';
 function existingMigration(value) {
     if (!migrations.some((migration) => migration.id === value)) {
         throw new InvalidArgumentError(`Unknown migration "${value}". Available: ${migrations.map((migration) => migration.id).join(', ')}`);
@@ -17,11 +22,56 @@ function existingMigration(value) {
 }
 export function createProgram() {
     const program = new Command();
+    const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
     program
         .name('upstreamfix')
+        .version(packageVersion)
         .description('Prepare and review automated code migrations for breaking SDK changes.')
         .showHelpAfterError()
         .exitOverride();
+    program
+        .command('probe')
+        .description('Compare TypeScript diagnostics before and after an exact SDK upgrade in a temporary copy.')
+        .argument('<package@version>', 'exact target, for example stripe@23.0.0')
+        .option('-C, --cwd <directory>', 'Git project directory to probe', process.cwd())
+        .option('--timeout <seconds>', 'maximum time per probe command', parsePositiveInteger)
+        .option('--yes', 'confirm dependency and Docker image downloads after reviewing the estimate')
+        .action(async (target, options) => {
+        const result = await probeProject(options.cwd, target, { confirmed: options.yes, ...(options.timeout ? { timeoutMs: options.timeout * 1000 } : {}) });
+        console.log(result.estimatedDownload);
+        if (result.status === 'confirmation-required') {
+            console.log('No downloads started. Re-run with --yes to perform the probe.');
+            return;
+        }
+        console.log(JSON.stringify(result, null, 2));
+        if (result.status === 'unavailable')
+            process.exitCode = 1;
+    });
+    program
+        .command('impact')
+        .description('Estimate affected usages of catalog SDK upgrades in a project without writing files.')
+        .option('-C, --cwd <directory>', 'project directory to analyze', process.cwd())
+        .action(async (options) => {
+        console.log(JSON.stringify(await analyzeImpact(options.cwd), null, 2));
+    });
+    program
+        .command('diff-api')
+        .description('Compare published TypeScript declarations of two exact npm package versions.')
+        .argument('<package>', 'npm package name')
+        .argument('<old>', 'exact old version')
+        .argument('<new>', 'exact new version')
+        .action(async (packageName, oldVersion, newVersion) => {
+        const report = await diffPublishedApi(packageName, oldVersion, newVersion);
+        console.log(JSON.stringify(report, null, 2));
+    });
+    program
+        .command('watch')
+        .description('Check npm for new major versions of catalog packages and update a JSON state file.')
+        .requiredOption('--state <file>', 'JSON state file to update atomically')
+        .action(async (options) => {
+        const result = await watchPackages(options.state, migrations.map((migration) => migration.packageName));
+        console.log(result.events.length ? JSON.stringify(result.events, null, 2) : 'No new major versions since the previous check.');
+    });
     program
         .command('list')
         .description('List the migrations included in this UpstreamFix release.')
@@ -46,12 +96,15 @@ export function createProgram() {
         .option('--verify', 'verify proposed changes in a temporary project copy')
         .option('--node-runtime <major>', 'confirm Firebase Admin v14 will run on Node.js 22+ and add engines.node when absent', parseNodeRuntime)
         .option('--verify-timeout <seconds>', 'maximum time per verification command', parsePositiveInteger)
+        .option('--allow-yarn-lock-install', 'allow a full Yarn Classic installation to regenerate yarn.lock (estimated 50–400 MB)')
         .option('--report <file>', 'write the Markdown report to this explicit path (relative paths use --cwd)')
         .action(async (migrationId, options) => {
         const migration = migrations.find((candidate) => candidate.id === migrationId);
         if (options.nodeRuntime && migration.id !== 'firebase-admin@14')
             throw new Error('--node-runtime 22 is supported only for firebase-admin@14.');
         const cwd = path.resolve(options.cwd);
+        if (options.allowYarnLockInstall)
+            console.log('Yarn Classic lockfile regeneration may download about 50–400 MB without a warm cache.');
         if (options.allowDirty && !options.write)
             throw new Error('--allow-dirty can only be used together with --write.');
         let writeResult;
@@ -61,10 +114,11 @@ export function createProgram() {
                 cwd,
                 allowDirty: options.allowDirty,
                 nodeRuntime: options.nodeRuntime,
+                allowYarnLockInstall: options.allowYarnLockInstall,
                 timeoutMs: (options.verifyTimeout ?? 300) * 1000,
             });
         }
-        const outcome = writeResult?.outcome ?? await runMigration(migration, { cwd, dryRun: true, nodeRuntime: options.nodeRuntime });
+        const outcome = writeResult?.outcome ?? await runMigration(migration, { cwd, dryRun: true, nodeRuntime: options.nodeRuntime, allowYarnLockInstall: options.allowYarnLockInstall });
         const verification = writeResult?.verification ?? (options.verify
             ? await verifyProposedMigration(cwd, outcome.proposedDiff, { packageName: migration.packageName, fileChanges: outcome.proposedFiles, timeoutMs: (options.verifyTimeout ?? 300) * 1000 })
             : undefined);
@@ -81,7 +135,7 @@ export function createProgram() {
         if (verification?.status === 'failed')
             process.exitCode = 1;
         if (!options.write)
-            console.log('Preview only. No project files were written.');
+            console.log(options.report ? 'Preview only. Only the requested report file was written.' : 'Preview only. No project files were written.');
     });
     program
         .command('scan')
@@ -92,9 +146,12 @@ export function createProgram() {
         .option('--verify', 'verify each proposed migration in a temporary project copy')
         .option('--node-runtime <major>', 'confirm Firebase Admin v14 will run on Node.js 22+ and add engines.node when absent', parseNodeRuntime)
         .option('--verify-timeout <seconds>', 'maximum time per verification command', parsePositiveInteger)
+        .option('--allow-yarn-lock-install', 'allow a full Yarn Classic installation to regenerate yarn.lock (estimated 50–400 MB)')
         .option('--report <file>', 'write Markdown reports to this explicit path (relative paths use --cwd)')
         .action(async (options) => {
         const cwd = path.resolve(options.cwd);
+        if (options.allowYarnLockInstall)
+            console.log('Yarn Classic lockfile regeneration may download about 50–400 MB without a warm cache.');
         if (options.allowDirty && !options.write)
             throw new Error('--allow-dirty can only be used together with --write.');
         const reports = [];
@@ -105,26 +162,29 @@ export function createProgram() {
             console.log('No supported migration applies to the dependencies declared in this project.');
             return;
         }
-        for (const migration of applicable) {
-            let writeResult;
-            if (options.write) {
-                assertWritesEnabled(false);
-                writeResult = await writeMigrationOnBranch(migration, {
-                    cwd,
-                    allowDirty: options.allowDirty,
-                    nodeRuntime: migration.id === 'firebase-admin@14' ? options.nodeRuntime : undefined,
-                    timeoutMs: (options.verifyTimeout ?? 300) * 1000,
-                });
-                commits.push({ branch: writeResult.branch, commit: writeResult.commit });
+        await withCompletedBranchNotice(async (recordCommit) => {
+            for (const migration of applicable) {
+                let writeResult;
+                if (options.write) {
+                    assertWritesEnabled(false);
+                    writeResult = await writeMigrationOnBranch(migration, {
+                        cwd,
+                        allowDirty: options.allowDirty,
+                        nodeRuntime: migration.id === 'firebase-admin@14' ? options.nodeRuntime : undefined,
+                        allowYarnLockInstall: options.allowYarnLockInstall,
+                        timeoutMs: (options.verifyTimeout ?? 300) * 1000,
+                    });
+                    recordCommit({ branch: writeResult.branch, commit: writeResult.commit });
+                }
+                const outcome = writeResult?.outcome ?? await runMigration(migration, { cwd, dryRun: true, nodeRuntime: migration.id === 'firebase-admin@14' ? options.nodeRuntime : undefined, allowYarnLockInstall: options.allowYarnLockInstall });
+                const verification = writeResult?.verification ?? (options.verify
+                    ? await verifyProposedMigration(cwd, outcome.proposedDiff, { packageName: migration.packageName, fileChanges: outcome.proposedFiles, timeoutMs: (options.verifyTimeout ?? 300) * 1000 })
+                    : undefined);
+                if (verification?.status === 'failed')
+                    verificationFailed = true;
+                reports.push(renderMarkdownReport(migration, outcome, !options.write, verification));
             }
-            const outcome = writeResult?.outcome ?? await runMigration(migration, { cwd, dryRun: true, nodeRuntime: migration.id === 'firebase-admin@14' ? options.nodeRuntime : undefined });
-            const verification = writeResult?.verification ?? (options.verify
-                ? await verifyProposedMigration(cwd, outcome.proposedDiff, { packageName: migration.packageName, fileChanges: outcome.proposedFiles, timeoutMs: (options.verifyTimeout ?? 300) * 1000 })
-                : undefined);
-            if (verification?.status === 'failed')
-                verificationFailed = true;
-            reports.push(renderMarkdownReport(migration, outcome, !options.write, verification));
-        }
+        }, commits);
         const report = reports.join('\n---\n\n');
         console.log(renderTerminalReport(report));
         if (options.report) {
@@ -138,14 +198,28 @@ export function createProgram() {
         if (verificationFailed)
             process.exitCode = 1;
         if (!options.write)
-            console.log('Preview only. No project files were written.');
+            console.log(options.report ? 'Preview only. Only the requested report file was written.' : 'Preview only. No project files were written.');
     });
     return program;
 }
+export function completedBranchNotice(commits) {
+    return `The scan stopped after creating these branches:\n${commits.map((item) => `- ${item.branch}: ${item.commit}`).join('\n')}`;
+}
+export async function withCompletedBranchNotice(work, commits = []) {
+    try {
+        return await work((commit) => commits.push(commit));
+    }
+    catch (error) {
+        if (commits.length > 0)
+            console.error(completedBranchNotice(commits));
+        throw error;
+    }
+}
 function parsePositiveInteger(value) {
     const parsed = Number(value);
-    if (!Number.isInteger(parsed) || parsed < 1)
-        throw new Error('Timeout must be a positive integer number of seconds.');
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 86_400) {
+        throw new InvalidArgumentError('Verification timeout must be an integer from 1 to at most 86400 seconds (24 hours).');
+    }
     return parsed;
 }
 function parseNodeRuntime(value) {
@@ -153,15 +227,21 @@ function parseNodeRuntime(value) {
         throw new InvalidArgumentError('Only --node-runtime 22 is supported for firebase-admin@14.');
     return 22;
 }
-const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : '';
-if (invokedPath === fileURLToPath(import.meta.url)) {
+let invokedPath = '';
+export function safeCliError(error) {
+    return `upstreamfix: ${sanitizeTerminalText(error instanceof Error ? error.message : String(error))}`;
+}
+try {
+    invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
+}
+catch { /* An unresolved argv path is not this CLI. */ }
+if (invokedPath === realpathSync(fileURLToPath(import.meta.url))) {
     createProgram().parseAsync().catch((error) => {
         if (error instanceof CommanderError && error.exitCode === 0) {
             process.exitCode = 0;
             return;
         }
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`upstreamfix: ${message}`);
+        console.error(safeCliError(error));
         process.exitCode = 1;
     });
 }

package/dist/core/diagnostic-diff.js

@@ -1,17 +1,20 @@
 /** Parse the ordinary, non-pretty `tsc` output without executing project code. */
 export function parseTypeScriptDiagnostics(output) {
     const diagnostics = [];
-    // A failed command can prepend text on the same line as the first tsc
-    // diagnostic; begin at the source path, never at the command wrapper.
-    const pattern = /(?:^|\s)([^\s():]+\.(?:[cm]?tsx?|jsx?))\((\d+),(\d+)\): error TS(\d+): ([^\r\n]+)/g;
-    for (const match of output.matchAll(pattern)) {
-        const file = match[1].replaceAll('\\', '/').replace(/^\/workspace\//, '').replace(/^\.\//, '');
+    const clean = output.replace(/\u001b\[[0-9;]*m/g, '');
+    const pattern = /^(.+?\.(?:[cm]?tsx?|jsx?))(?:\((\d+),(\d+)\):|:(\d+):(\d+)\s+-) error TS(\d+): (.+)$/;
+    for (const line of clean.split(/\r?\n/)) {
+        const match = pattern.exec(line);
+        if (!match)
+            continue;
+        const rawPath = match[1].trim().replace(/^npm error\s+/, '');
+        const file = rawPath.replaceAll('\\', '/').replace(/^\/workspace\//, '').replace(/^\.\//, '');
         diagnostics.push({
             file,
-            line: Number(match[2]),
-            column: Number(match[3]),
-            code: Number(match[4]),
-            message: match[5].trim().replace(/\s+/g, ' '),
+            line: Number(match[2] ?? match[4]),
+            column: Number(match[3] ?? match[5]),
+            code: Number(match[6]),
+            message: match[7].trim().replace(/\s+/g, ' '),
         });
     }
     return diagnostics;

package/dist/core/diff-api.js

@@ -0,0 +1,211 @@
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import path from 'node:path';
+import { Node, Project, SyntaxKind } from 'ts-morph';
+import { readBoundedJson } from './watch.js';
+const maxArchiveBytes = 15 * 1024 * 1024;
+const maxUnpackedBytes = 40 * 1024 * 1024;
+export function validateExactVersion(version) {
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?$/.test(version)) {
+        throw new Error(`An exact npm version is required; received ${version}.`);
+    }
+}
+function tarString(buffer, start, length) {
+    return buffer.subarray(start, start + length).toString('utf8').split('\0')[0].trim();
+}
+export function unpackDeclarationFiles(archive, integrity) {
+    if (archive.length > maxArchiveBytes)
+        throw new Error('Package archive exceeds the size limit.');
+    if (integrity) {
+        const match = /^(sha512|sha1)-([A-Za-z0-9+/=]+)$/.exec(integrity);
+        if (!match || createHash(match[1]).update(archive).digest('base64') !== match[2])
+            throw new Error('Package archive integrity mismatch.');
+    }
+    const unpacked = gunzipSync(archive, { maxOutputLength: maxUnpackedBytes });
+    const files = new Map();
+    let nextPath;
+    for (let offset = 0; offset + 512 <= unpacked.length;) {
+        const header = unpacked.subarray(offset, offset + 512);
+        if (header.every((byte) => byte === 0))
+            break;
+        const headerName = [tarString(header, 345, 155), tarString(header, 0, 100)].filter(Boolean).join('/');
+        const size = Number.parseInt(tarString(header, 124, 12), 8);
+        const kind = tarString(header, 156, 1) || '0';
+        if (!Number.isSafeInteger(size) || size < 0 || offset + 512 + size > unpacked.length)
+            throw new Error('Invalid package archive entry size.');
+        const body = unpacked.subarray(offset + 512, offset + 512 + size);
+        if (kind === 'L') {
+            nextPath = body.toString('utf8').split('\0')[0];
+        }
+        else if (kind === 'x') {
+            const records = body.toString('utf8');
+            const pathRecord = /(?:^|\n)\d+ path=([^\n]+)/.exec(records);
+            if (pathRecord)
+                nextPath = pathRecord[1];
+        }
+        else {
+            const name = nextPath ?? headerName;
+            nextPath = undefined;
+            const parts = name.split('/');
+            if (parts.some((part) => part === '..' || part === '.') || name.startsWith('/') || name.includes('\\') || /^[A-Za-z]:/.test(name)) {
+                throw new Error(`Package archive has an unsafe path: ${name}`);
+            }
+            if (!['0', '5'].includes(kind))
+                throw new Error(`Package archive contains an unsupported link or entry: ${name}`);
+            const relative = name.startsWith('package/') ? name.slice('package/'.length) : name;
+            if (kind === '0' && (/\.d\.(?:ts|mts|cts)$/.test(relative) || relative === 'package.json')) {
+                files.set(relative, body.toString('utf8'));
+            }
+        }
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+    if (!files.has('package.json'))
+        throw new Error('Package archive has no package.json.');
+    return files;
+}
+function declaredEntries(files) {
+    const manifest = JSON.parse(files.get('package.json'));
+    const candidates = new Set();
+    if (typeof manifest.types === 'string')
+        candidates.add(manifest.types);
+    if (typeof manifest.typings === 'string')
+        candidates.add(manifest.typings);
+    if (typeof manifest.main === 'string')
+        candidates.add(manifest.main);
+    function visit(value) {
+        if (!value || typeof value !== 'object')
+            return;
+        for (const [key, item] of Object.entries(value)) {
+            if (key === 'types' && typeof item === 'string')
+                candidates.add(item);
+            else
+                visit(item);
+        }
+    }
+    visit(manifest.exports);
+    visit(manifest.typesVersions);
+    if (candidates.size === 0 && files.has('index.d.ts'))
+        candidates.add('index.d.ts');
+    const resolved = new Set();
+    for (const candidate of candidates) {
+        const entry = path.posix.normalize(candidate.replace(/^\.\//, ''));
+        if (entry.startsWith('../') || path.posix.isAbsolute(entry))
+            continue;
+        for (const form of [entry, `${entry}.d.ts`, `${entry}.d.mts`, `${entry}.d.cts`, path.posix.join(entry, 'index.d.ts'), entry.replace(/\.[cm]?js$/, '.d.ts')]) {
+            if (files.has(form))
+                resolved.add(form);
+        }
+    }
+    return [...resolved];
+}
+function declarations(files) {
+    const project = new Project({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true, compilerOptions: { noResolve: false } });
+    for (const [name, content] of files) {
+        if (/\.d\.(?:ts|mts|cts)$/.test(name))
+            project.createSourceFile(`/package/${name}`, content, { overwrite: true });
+    }
+    const symbols = new Map();
+    for (const entry of declaredEntries(files)) {
+        const source = project.getSourceFile(`/package/${entry}`);
+        if (!source)
+            continue;
+        const prefix = entry === 'index.d.ts' ? '' : `${entry}:`;
+        const collect = (declarations, scope) => {
+            for (const [name, nodes] of declarations) {
+                if (nodes.length === 0)
+                    continue;
+                const key = `${scope}${name}`;
+                symbols.set(key, { symbol: key, after: nodes.map((node) => node.getText().replace(/\s+/g, ' ').trim()).join(' | '), source: entry });
+                const members = new Map();
+                for (const node of nodes) {
+                    if (!Node.isInterfaceDeclaration(node) && !Node.isClassDeclaration(node))
+                        continue;
+                    for (const member of node.getMembers()) {
+                        const memberName = member.getName?.();
+                        if (!memberName)
+                            continue;
+                        members.set(memberName, [...(members.get(memberName) ?? []), member.getText().replace(/\s+/g, ' ').trim()]);
+                    }
+                }
+                for (const [memberName, texts] of members) {
+                    const memberKey = `${key}.${memberName}`;
+                    symbols.set(memberKey, { symbol: memberKey, after: texts.join(' | '), source: entry });
+                }
+            }
+        };
+        collect(source.getExportedDeclarations(), prefix);
+        for (const module of source.getDescendantsOfKind(SyntaxKind.ModuleDeclaration)) {
+            collect(module.getExportedDeclarations(), `${prefix}${module.getName()}.`);
+        }
+    }
+    return symbols;
+}
+export function compareApiFromTarballs(packageName, oldVersion, newVersion, oldArchive, newArchive, oldIntegrity, newIntegrity) {
+    const before = declarations(unpackDeclarationFiles(oldArchive, oldIntegrity));
+    const after = declarations(unpackDeclarationFiles(newArchive, newIntegrity));
+    if (before.size === 0 || after.size === 0)
+        throw new Error('No exported type symbols were resolved from one or both package archives; the API comparison is incomplete.');
+    const removed = [];
+    const changed = [];
+    const added = [];
+    for (const [symbol, previous] of before) {
+        const current = after.get(symbol);
+        if (!current)
+            removed.push({ ...previous, before: previous.after, after: undefined });
+        else if (previous.after !== current.after)
+            changed.push({ symbol, before: previous.after, after: current.after, source: current.source });
+    }
+    for (const [symbol, current] of after)
+        if (!before.has(symbol))
+            added.push(current);
+    const normalize = (finding, declaration) => declaration?.replace(finding.symbol.split('.').at(-1), '') ?? '';
+    const addedByText = new Map();
+    for (const candidate of added) {
+        const key = normalize(candidate, candidate.after);
+        addedByText.set(key, [...(addedByText.get(key) ?? []), candidate]);
+    }
+    const renameHypotheses = [];
+    for (const old of removed) {
+        for (const candidate of addedByText.get(normalize(old, old.before)) ?? []) {
+            renameHypotheses.push({ from: old.symbol, to: candidate.symbol, reason: 'Similar declaration text; hypothesis only, verify against vendor guidance.' });
+            if (renameHypotheses.length >= 1000)
+                break;
+        }
+        if (renameHypotheses.length >= 1000)
+            break;
+    }
+    return { package: packageName, oldVersion, newVersion, removed, changed, added, renameHypotheses };
+}
+async function boundedArchive(url, fetcher) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' || parsed.hostname !== 'registry.npmjs.org' || parsed.port || parsed.username || parsed.password) {
+        throw new Error('The package tarball must be served directly by the npm registry over HTTPS.');
+    }
+    const response = await fetcher(url, { signal: AbortSignal.timeout(20_000), redirect: 'error' });
+    if (!response.ok)
+        throw new Error(`Package download failed (${response.status}).`);
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of response.body ?? []) {
+        bytes += chunk.byteLength;
+        if (bytes > maxArchiveBytes)
+            throw new Error('Package archive exceeds the size limit.');
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+export async function diffPublishedApi(packageName, oldVersion, newVersion, fetcher = fetch) {
+    if (!/^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i.test(packageName))
+        throw new Error('Invalid npm package name.');
+    validateExactVersion(oldVersion);
+    validateExactVersion(newVersion);
+    const load = async (version) => {
+        const metadata = await readBoundedJson(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/${version}`, undefined, fetcher);
+        if (!metadata.dist?.tarball || !metadata.dist.integrity)
+            throw new Error(`Missing tarball integrity for ${packageName}@${version}.`);
+        return { archive: await boundedArchive(metadata.dist.tarball, fetcher), integrity: metadata.dist.integrity };
+    };
+    const old = await load(oldVersion);
+    const next = await load(newVersion);
+    return compareApiFromTarballs(packageName, oldVersion, newVersion, old.archive, next.archive, old.integrity, next.integrity);
+}

package/dist/core/docker-mount.js

@@ -0,0 +1,6 @@
+/** Docker's --mount uses comma-separated fields; --volume keeps commas in host paths literal. */
+export function dockerBindArgs(source, target, readonly = false) {
+    if (source.includes(','))
+        return ['--volume', `${source}:${target}${readonly ? ':ro' : ''}`];
+    return ['--mount', `type=bind,source=${source},target=${target}${readonly ? ',readonly' : ''}`];
+}

package/dist/core/impact.js

@@ -0,0 +1,72 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { IGNORED_PROJECT_DIRECTORIES, isSupportedSourceMajor } from './project-discovery.js';
+import { runMigration } from './runner.js';
+import { npmLatestVersion } from './watch.js';
+import { migrations } from '../migrations/index.js';
+import { parseManifest } from './manifest.js';
+async function declaredVersions(root) {
+    const found = new Map();
+    const warnings = [];
+    async function visit(directory) {
+        for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.isSymbolicLink())
+                continue;
+            const absolute = path.join(directory, entry.name);
+            if (entry.isDirectory() && !IGNORED_PROJECT_DIRECTORIES.has(entry.name))
+                await visit(absolute);
+            if (entry.isFile() && entry.name === 'package.json') {
+                let manifest;
+                try {
+                    manifest = parseManifest(await readFile(absolute, 'utf8'));
+                }
+                catch {
+                    warnings.push(`Invalid manifest: ${path.relative(root, absolute)}`);
+                    continue;
+                }
+                for (const section of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+                    for (const [name, version] of Object.entries(manifest[section] ?? {})) {
+                        if (typeof version !== 'string')
+                            continue;
+                        if (section === 'peerDependencies' && ['dependencies', 'devDependencies', 'optionalDependencies'].some((runtime) => typeof manifest[runtime]?.[name] === 'string'))
+                            continue;
+                        const versions = found.get(name) ?? new Set();
+                        versions.add(version);
+                        found.set(name, versions);
+                    }
+                }
+            }
+        }
+    }
+    await visit(root);
+    return { found, warnings };
+}
+export async function analyzeImpact(cwd, lookup = npmLatestVersion) {
+    const { found: versions, warnings } = await declaredVersions(path.resolve(cwd));
+    const packages = [...new Set(migrations.map((migration) => migration.packageName))].filter((name) => versions.has(name)).sort();
+    const results = [];
+    for (const packageName of packages) {
+        const declared = [...versions.get(packageName)].sort();
+        const declaredVersion = declared.join(', ');
+        const latestVersion = await lookup(packageName);
+        if (!/^\d+\.\d+\.\d+/.test(latestVersion))
+            throw new Error(`Invalid registry version for ${packageName}.`);
+        const latestMajor = Number(latestVersion.split('.')[0]);
+        if (declared.length > 1) {
+            results.push({ package: packageName, declaredVersion, latestVersion, latestMajor, affected: 0, automatic: 0, manual: 0, automaticShare: null,
+                note: `Multiple declared versions need separate review; no migration rate was inferred. ${warnings.join('; ')}` });
+            continue;
+        }
+        const migration = migrations.find((candidate) => candidate.packageName === packageName && isSupportedSourceMajor(declared[0], candidate.fromMajor));
+        if (!migration) {
+            results.push({ package: packageName, declaredVersion, latestVersion, latestMajor, affected: 0, automatic: 0, manual: 0, automaticShare: null, note: `No catalog migration matches this declared version; affected usages are unknown. ${warnings.join('; ')}`.trim() });
+            continue;
+        }
+        const outcome = await runMigration(migration, { cwd, dryRun: true, analysisOnly: true });
+        const automatic = outcome.changes.length;
+        const manual = outcome.manual.length;
+        const affected = automatic + manual;
+        results.push({ package: packageName, declaredVersion, latestVersion, latestMajor, migration: migration.id, affected, automatic, manual, automaticShare: affected ? automatic / affected : null, ...(warnings.length ? { note: warnings.join('; ') } : {}) });
+    }
+    return results;
+}

package/dist/core/manifest.js

@@ -0,0 +1,4 @@
+/** Parse a JSON package manifest while accepting the UTF-8 BOM used by some editors. */
+export function parseManifest(contents) {
+    return JSON.parse(contents.replace(/^\uFEFF/, ''));
+}

package/dist/core/node-range.js

@@ -0,0 +1,19 @@
+/** Conservative check that every supported arm of an engines.node range starts at or above a required major. */
+export function guaranteesNodeMajor(range, minimum) {
+    const arms = range.trim().split(/\s*\|\|\s*/);
+    return arms.length > 0 && arms.every((arm) => {
+        const parts = arm.trim().replace(/^(>=|>|\^|~)\s+(?=\d)/, '$1').split(/\s+/);
+        const first = /^(>=|>|\^|~)?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/.exec(parts[0] ?? '');
+        if (!first)
+            return false;
+        const major = Number(first[2]);
+        if (major < minimum)
+            return false;
+        if (parts.length === 1)
+            return true;
+        return parts.slice(1).every((part) => {
+            const bound = /^(<|<=)(\d+)(?:\.\d+){0,2}$/.exec(part);
+            return Boolean(bound && Number(bound[2]) > minimum);
+        });
+    });
+}