compatra 0.1.0

package/dist/scan.js

@@ -0,0 +1,94 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { EXCLUDED_PREFIXES, MAX_FILES, SOURCE_EXTENSIONS, extractVendorUsages, } from "@compatra/core/ast";
+import { RESOURCE_MATCHING_SUPPORTED, VENDOR_SPEC_SOURCES, detectVendorDependencies, fetchShopifySchema, fetchVendorSpec, matchDeprecatedEndpoints, moduleMatchesVendor, } from "@compatra/core";
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", ".next", "coverage", ".turbo"]);
+/** Source files under `root`, using the same extensions, exclusions and cap as the hosted scanner. */
+export async function listSourceFiles(root) {
+    const found = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory: skip rather than fail the whole scan
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            const rel = path.relative(root, full).split(path.sep).join("/");
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith("."))
+                    continue;
+                if (EXCLUDED_PREFIXES.some((p) => `${rel}/`.startsWith(p)))
+                    continue;
+                await walk(full);
+            }
+            else if (SOURCE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
+                found.push(rel);
+            }
+        }
+    }
+    await walk(root);
+    found.sort();
+    return { files: found.slice(0, MAX_FILES), truncated: found.length > MAX_FILES };
+}
+async function loadDeprecatedPaths(vendor) {
+    const source = VENDOR_SPEC_SOURCES.find((s) => s.vendor === vendor);
+    if (!source)
+        return [];
+    const spec = source.format === "graphql" ? await fetchShopifySchema(source) : await fetchVendorSpec(source);
+    return spec.deprecatedPaths;
+}
+/**
+ * Read a project the way the hosted scanner reads a repository: find vendor SDKs in
+ * package.json, locate their real call sites, then compare those against endpoints the vendor
+ * has already marked deprecated. Network is only used for the vendors' public specs.
+ */
+export async function scanProject(root) {
+    const pkgRaw = await readFile(path.join(root, "package.json"), "utf8");
+    const dependencies = detectVendorDependencies(JSON.parse(pkgRaw));
+    const { files, truncated } = await listSourceFiles(root);
+    const callSites = [];
+    for (const rel of files) {
+        let source;
+        try {
+            source = await readFile(path.join(root, rel), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const vendor of new Set(dependencies.map((d) => d.vendor))) {
+            for (const usage of extractVendorUsages(rel, source, (m) => moduleMatchesVendor(m, vendor))) {
+                callSites.push({ ...usage, vendor });
+            }
+        }
+    }
+    // Only real call chains can be matched to an endpoint; a bare constructor cannot.
+    const checkable = callSites.filter((c) => RESOURCE_MATCHING_SUPPORTED.has(c.vendor) && c.snippet.includes("."));
+    const vendorsToCheck = [...new Set(checkable.map((c) => c.vendor))].sort();
+    const unsupported = [...new Set(dependencies.map((d) => d.vendor))]
+        .filter((v) => !RESOURCE_MATCHING_SUPPORTED.has(v))
+        .sort();
+    const checked = [];
+    const hits = [];
+    let specError = null;
+    for (const vendor of vendorsToCheck) {
+        let deprecated;
+        try {
+            deprecated = await loadDeprecatedPaths(vendor);
+        }
+        catch (error) {
+            // Offline or the vendor's spec host is down: report it rather than claiming "all clear".
+            specError = error instanceof Error ? error.message : String(error);
+            continue;
+        }
+        checked.push({ vendor, deprecatedEndpoints: deprecated.length });
+        for (const site of checkable.filter((c) => c.vendor === vendor)) {
+            for (const endpoint of matchDeprecatedEndpoints(vendor, site.snippet, deprecated)) {
+                hits.push({ ...site, endpoint });
+            }
+        }
+    }
+    return { root, dependencies, callSites, filesScanned: files.length, truncated, checked, unsupported, hits, specError };
+}

package/dist/verify.js

@@ -0,0 +1,110 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { classify, passed } from "./classify.js";
+import { buildFault, FAULT_SUPPORTED } from "./faults.js";
+import { scanProject } from "./scan.js";
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_ENDPOINTS = 5;
+const OUTPUT_TAIL_BYTES = 2000;
+// ../dist works whether we run from src/ (tests) or dist/ (installed), as both sit beside dist/.
+const injectPreload = () => pathToFileURL(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "dist", "inject.js")).href;
+/** Stops a test run and everything it started; killing only the shell would leave the tests running. */
+function stopTree(pid, detached) {
+    if (!pid)
+        return;
+    try {
+        if (process.platform === "win32")
+            spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+        else if (detached)
+            process.kill(-pid, "SIGKILL");
+        else
+            process.kill(pid, "SIGKILL");
+    }
+    catch {
+        // already exited
+    }
+}
+/** Runs the user's test command. It is their command in their checkout, on their machine or runner. */
+function runTests(command, cwd, env, timeoutMs) {
+    return new Promise((resolve) => {
+        // detached puts the shell in its own process group so a timeout can stop the whole test tree.
+        const detached = process.platform !== "win32";
+        const child = spawn(command, { cwd, env, shell: true, detached });
+        let output = "";
+        let timedOut = false;
+        const keep = (chunk) => {
+            output = (output + chunk.toString()).slice(-OUTPUT_TAIL_BYTES);
+        };
+        child.stdout.on("data", keep);
+        child.stderr.on("data", keep);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            stopTree(child.pid, detached);
+        }, timeoutMs);
+        child.on("close", (exitCode) => {
+            clearTimeout(timer);
+            resolve({ exitCode, timedOut, output });
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            resolve({ exitCode: null, timedOut: false, output: error.message });
+        });
+    });
+}
+async function countHits(logFile) {
+    try {
+        return (await readFile(logFile, "utf8")).split("\n").filter(Boolean).length;
+    }
+    catch {
+        return 0; // no file means nothing was ever hit
+    }
+}
+/** The distinct endpoints a scan flagged, one per vendor+endpoint, ready to hand to verifyProject. */
+export function uniqueEndpoints(hits) {
+    return [...new Map(hits.map((h) => [`${h.vendor} ${h.endpoint}`, { vendor: h.vendor, endpoint: h.endpoint }])).values()];
+}
+export async function verifyProject(options) {
+    const { root, testCommand, anyHost = false, timeoutMs = DEFAULT_TIMEOUT_MS, maxEndpoints = DEFAULT_MAX_ENDPOINTS } = options;
+    const wanted = options.endpoints ?? uniqueEndpoints((await scanProject(root)).hits);
+    const skipped = [];
+    const faults = [];
+    for (const input of wanted) {
+        const fault = FAULT_SUPPORTED.has(input.vendor) ? buildFault(input.vendor, input.endpoint, anyHost) : null;
+        if (fault)
+            faults.push(fault);
+        else
+            skipped.push(input);
+    }
+    const truncated = faults.length > maxEndpoints;
+    const toRun = faults.slice(0, maxEndpoints);
+    if (toRun.length === 0)
+        return { root, testCommand, baseline: null, verdicts: [], skipped, truncated };
+    const base = await runTests(testCommand, root, process.env, timeoutMs);
+    const baseline = { passed: passed(base), timedOut: base.timedOut, exitCode: base.exitCode, outputTail: base.output };
+    const result = { root, testCommand, baseline, verdicts: [], skipped, truncated };
+    // Without a green baseline a failing run tells us nothing, so don't spend the time.
+    if (!baseline.passed)
+        return result;
+    const scratch = await mkdtemp(path.join(tmpdir(), "compatra-verify-"));
+    try {
+        for (const [index, fault] of toRun.entries()) {
+            const hitLog = path.join(scratch, `hits-${index}.log`);
+            const existing = process.env.NODE_OPTIONS ? `${process.env.NODE_OPTIONS} ` : "";
+            const injected = await runTests(testCommand, root, {
+                ...process.env,
+                NODE_OPTIONS: `${existing}--import=${injectPreload()}`,
+                COMPATRA_FAULTS: JSON.stringify([fault]),
+                COMPATRA_FAULT_LOG: hitLog,
+            }, timeoutMs);
+            const hits = await countHits(hitLog);
+            result.verdicts.push({ vendor: fault.vendor, endpoint: fault.endpoint, hits, ...classify(base, injected, hits) });
+        }
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+    return result;
+}

package/node_modules/@compatra/core/dist/apply-migration.d.ts

@@ -0,0 +1,29 @@
+import { type MigrationRecipe } from "./migrations.js";
+export interface MigrationSite {
+    /** 1-based line the scan reported for the call. */
+    line: number;
+    vendor: string;
+    endpoint: string;
+    /** The call's access chain, e.g. "stripe.customers.listCards". */
+    snippet: string;
+}
+export interface AppliedMigration {
+    line: number;
+    recipe: MigrationRecipe;
+}
+export interface SkippedMigration {
+    line: number;
+    snippet: string;
+    reason: string;
+}
+export interface MigrationResult {
+    output: string;
+    applied: AppliedMigration[];
+    skipped: SkippedMigration[];
+}
+/**
+ * Rewrites the flagged calls that have a recipe. Sites without one, or whose call has a shape we
+ * will not touch (spread arguments, a filter already set, a callback), are reported in `skipped`
+ * with the reason and left exactly as they were.
+ */
+export declare function applyMigrations(filePath: string, source: string, sites: MigrationSite[]): MigrationResult;

package/node_modules/@compatra/core/dist/apply-migration.js

@@ -0,0 +1,139 @@
+// Applies migration recipes to a source file. Kept apart from migrations.ts because it needs
+// ts-morph (see the `@compatra/core/migrate` subpath), which is slow to load.
+import { NewLineKind, Node, Project, SyntaxKind, } from "ts-morph";
+import { findRecipe } from "./migrations.js";
+const leaf = (path) => path.slice(path.lastIndexOf(".") + 1);
+const prefix = (path) => path.slice(0, path.lastIndexOf("."));
+/** Calls whose callee ends with `recipe.from` and that start on `line`, in source order. */
+function callsOnLine(file, line, recipe) {
+    return file.getDescendantsOfKind(SyntaxKind.CallExpression).filter((call) => {
+        const callee = call.getExpression();
+        if (!Node.isPropertyAccessExpression(callee))
+            return false;
+        if (callee.getName() !== leaf(recipe.from))
+            return false;
+        if (!`${callee.getExpression().getText()}.${callee.getName()}`.endsWith(`.${recipe.from}`))
+            return false;
+        return call.getStartLineNumber() === line || callee.getNameNode().getStartLineNumber() === line;
+    });
+}
+/**
+ * The object literal's text with one more property, written in the object's own style: an inline
+ * `{ a: 1 }` stays inline, a multi-line object gets a new line at the same indent, and a trailing
+ * comma is kept if the object had one.
+ */
+function withProperty(literal, property) {
+    const text = literal.getText();
+    const last = literal.getProperties().at(-1);
+    if (!last)
+        return `{ ${property} }`;
+    const end = last.getEnd() - literal.getStart();
+    const comma = /^\s*,/.exec(text.slice(end));
+    const insertAt = comma ? end + comma[0].length : end;
+    const before = text.slice(0, insertAt);
+    const after = text.slice(insertAt);
+    if (!text.includes("\n")) {
+        return comma ? `${before} ${property},${after}` : `${before}, ${property}${after}`;
+    }
+    // Match the file's own line endings so a CRLF file does not end up with mixed ones.
+    const newline = text.includes("\r\n") ? "\r\n" : "\n";
+    const indent = /^\s*/.exec(literal.getSourceFile().getFullText().slice(last.getStartLinePos(), last.getStart()))?.[0] ?? "";
+    return comma ? `${before}${newline}${indent}${property},${after}` : `${before},${newline}${indent}${property}${after}`;
+}
+/** Why the params argument cannot take `key` safely, or null when it can. Inspects only; changes nothing. */
+function paramRefusal(call, key) {
+    const params = call.getArguments()[1];
+    if (!params)
+        return null;
+    if (!Node.isObjectLiteralExpression(params)) {
+        // A variable or expression could be a params object or, in older SDKs, a callback: spreading a
+        // callback would silently corrupt the call, and we cannot tell the two apart without types.
+        return "the second argument is not an object literal, so it cannot be told apart from a callback";
+    }
+    if (params.getProperty(key))
+        return `the call already passes \`${key}\``;
+    if (params.getProperties().some((p) => Node.isSpreadAssignment(p))) {
+        return `the params object contains a spread, so \`${key}\` might already be set`;
+    }
+    return null;
+}
+/**
+ * Adds `key: value` as the params argument. This replaces a verbatim text range rather than a
+ * node: ts-morph's node-level insertion re-indents or reformats the whole literal, and a migration
+ * must not churn formatting it has no business touching. It forgets the tree, so callers re-query.
+ */
+function addParam(call, key, value) {
+    const property = `${key}: ${JSON.stringify(value)}`;
+    const params = call.getArguments()[1];
+    const file = call.getSourceFile();
+    if (!params) {
+        const args = call.getArguments();
+        const at = args[args.length - 1].getEnd();
+        file.replaceText([at, at], `, { ${property} }`);
+        return;
+    }
+    file.replaceText([params.getStart(), params.getEnd()], withProperty(params, property));
+}
+/**
+ * Rewrites the flagged calls that have a recipe. Sites without one, or whose call has a shape we
+ * will not touch (spread arguments, a filter already set, a callback), are reported in `skipped`
+ * with the reason and left exactly as they were.
+ */
+export function applyMigrations(filePath, source, sites) {
+    // ts-morph rewrites the newlines of any text it inserts to this style, so match the file's own.
+    const newLineKind = source.includes("\r\n") ? NewLineKind.CarriageReturnLineFeed : NewLineKind.LineFeed;
+    const project = new Project({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true, manipulationSettings: { newLineKind } });
+    const file = project.createSourceFile(filePath, source, { overwrite: true });
+    const applied = [];
+    const skipped = [];
+    // Highest line first, so an edit never shifts the line numbers of sites still to do.
+    for (const site of [...sites].sort((a, b) => b.line - a.line)) {
+        const skip = (reason) => skipped.push({ line: site.line, snippet: site.snippet, reason });
+        const recipe = findRecipe(site.vendor, site.endpoint, site.snippet);
+        if (!recipe) {
+            skip("no provably equivalent replacement is known for this endpoint");
+            continue;
+        }
+        if (prefix(recipe.from) !== prefix(recipe.to)) {
+            skip("recipe changes more than the method name, which this engine does not do");
+            continue;
+        }
+        if (callsOnLine(file, site.line, recipe).length === 0) {
+            skip("the call was not found on that line (the file may have changed since the scan)");
+            continue;
+        }
+        // Last call on the line first. Edits forget the tree and a rewritten call stops matching, so
+        // re-find the calls each time and take the last one that starts before the one just handled.
+        // (Earlier positions are unaffected by an edit further along, so this reaches every call.)
+        let handledStart = Infinity;
+        for (;;) {
+            const call = callsOnLine(file, site.line, recipe)
+                .filter((c) => c.getStart() < handledStart)
+                .at(-1);
+            if (!call)
+                break;
+            handledStart = call.getStart();
+            const args = call.getArguments();
+            if (args.length === 0) {
+                skip("the call has no arguments, so its shape is not what the recipe expects");
+                continue;
+            }
+            if (args.some((a) => Node.isSpreadElement(a))) {
+                skip("the call spreads its arguments, so the argument positions are unknown");
+                continue;
+            }
+            const [param] = Object.entries(recipe.addParams ?? {});
+            const refusal = param ? paramRefusal(call, param[0]) : null;
+            if (refusal) {
+                skip(refusal);
+                continue;
+            }
+            // Rename first (it keeps the tree valid), then the verbatim param edit, which does not.
+            call.getExpression().getNameNode().replaceWithText(leaf(recipe.to));
+            if (param)
+                addParam(call, param[0], param[1]);
+            applied.push({ line: site.line, recipe });
+        }
+    }
+    return { output: file.getFullText(), applied, skipped };
+}

package/node_modules/@compatra/core/dist/deprecation-match.d.ts

@@ -0,0 +1,2 @@
+/** The deprecated endpoints (from `deprecatedPaths`, "METHOD /path") this call plausibly uses. */
+export declare function matchDeprecatedEndpoints(vendor: string, snippet: string, deprecatedPaths: string[]): string[];

package/node_modules/@compatra/core/dist/deprecation-match.js

@@ -0,0 +1,86 @@
+import { RESOURCE_MATCHING_SUPPORTED, extractResourceFromPath, extractResourceFromUsage } from "./resource-match.js";
+// Precision-first: does this SDK call plausibly use one of the vendor's CURRENTLY
+// deprecated endpoints? Resource-level matching alone is far too coarse here —
+// `stripe.customers.create` shares the `customers` resource with the deprecated
+// `customers/{id}/cards`, but doesn't use it — so a deprecated endpoint only counts when the
+// call's own method name carries the endpoint's distinguishing segments
+// (`customers.listCards` -> `.../cards`). Recall is deliberately lower than precision: a
+// missed match is silence, a wrong one is a false alarm on a customer's first day.
+const singular = (t) => (t.length > 3 && t.endsWith("s") ? t.slice(0, -1) : t);
+// "listBankAccounts" / "bank_accounts" / "bank-accounts" -> ["list","bank","accounts"]
+function tokenize(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((t) => singular(t.toLowerCase()));
+}
+const COLLECTION_VERBS = new Set(["list", "search"]);
+const ITEM_VERBS = new Set(["retrieve", "get", "update", "del", "delete", "remove"]);
+const isParam = (segment) => segment.startsWith("{") && segment.endsWith("}");
+// Segments that tell THIS endpoint apart from its resource's other endpoints: everything
+// after the resource, minus path parameters.
+function distinguishingTokens(vendor, path) {
+    const rawPath = path.includes(" ") ? path.split(" ")[1] : path;
+    const segments = rawPath.split("/").filter(Boolean);
+    const resource = extractResourceFromPath(vendor, path);
+    const resourceIndex = segments.findIndex((s) => !isParam(s) && tokenize(s).join("_") === tokenize(resource ?? "").join("_"));
+    if (resourceIndex < 0)
+        return [];
+    return segments
+        .slice(resourceIndex + 1)
+        .filter((s) => !isParam(s))
+        .flatMap(tokenize);
+}
+// SDK verbs that correspond to an HTTP method on a collection/item, used only when the
+// path has no distinguishing segment of its own.
+function verbsFor(method, endsWithParam) {
+    switch (method.toUpperCase()) {
+        case "GET":
+            return endsWithParam ? ["retrieve", "get"] : ["list", "search"];
+        case "POST":
+            return endsWithParam ? ["update"] : ["create"];
+        case "DELETE":
+            return ["del", "delete", "remove", "cancel"];
+        case "PUT":
+        case "PATCH":
+            return ["update"];
+        default:
+            return [];
+    }
+}
+/** The deprecated endpoints (from `deprecatedPaths`, "METHOD /path") this call plausibly uses. */
+export function matchDeprecatedEndpoints(vendor, snippet, deprecatedPaths) {
+    if (!RESOURCE_MATCHING_SUPPORTED.has(vendor))
+        return [];
+    const resource = extractResourceFromUsage(vendor, snippet);
+    if (!resource)
+        return [];
+    // The chain minus the client variable (first token) and octokit's literal `.rest`.
+    const chain = snippet.split(".").filter((p) => p !== "rest").slice(1).join(".");
+    const usageTokens = new Set(tokenize(chain));
+    if (usageTokens.size < 2)
+        return []; // a bare constructor / namespace, not a call
+    return deprecatedPaths.filter((deprecated) => {
+        if (extractResourceFromPath(vendor, deprecated) !== resource)
+            return false;
+        const [method, path = ""] = deprecated.split(" ");
+        const segments = path.split("/").filter(Boolean);
+        const endsWithParam = isParam(segments[segments.length - 1] ?? "");
+        const distinguishing = distinguishingTokens(vendor, deprecated);
+        if (distinguishing.length > 0) {
+            if (!distinguishing.every((t) => usageTokens.has(t)))
+                return false;
+            // Same sub-resource, but list-vs-single must agree: `listCards` is the collection
+            // endpoint, `retrieveCard` the single-item one.
+            const wantsCollection = [...COLLECTION_VERBS].some((v) => usageTokens.has(v));
+            const wantsItem = [...ITEM_VERBS].some((v) => usageTokens.has(v));
+            if (endsWithParam && wantsCollection && !wantsItem)
+                return false;
+            if (!endsWithParam && wantsItem && !wantsCollection)
+                return false;
+            return true;
+        }
+        return verbsFor(method, endsWithParam).some((v) => usageTokens.has(v));
+    });
+}

package/node_modules/@compatra/core/dist/extract-usages.d.ts

@@ -0,0 +1,14 @@
+export interface CodeUsage {
+    filePath: string;
+    line: number;
+    snippet: string;
+}
+export declare const SOURCE_EXTENSIONS: string[];
+export declare const EXCLUDED_PREFIXES: string[];
+export declare const MAX_FILES = 200;
+/**
+ * Pure AST extraction: given one file's content, find every place a vendor's SDK is
+ * imported (ES `import` or CommonJS `require`) and then actually called or accessed,
+ * returning the line and the access-chain text (e.g. "stripe.charges.create").
+ */
+export declare function extractVendorUsages(filePath: string, sourceCode: string, matchesModule: (moduleSpecifier: string) => boolean): CodeUsage[];

package/node_modules/@compatra/core/dist/extract-usages.js

@@ -0,0 +1,100 @@
+import { Project, SyntaxKind } from "ts-morph";
+export const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
+export const EXCLUDED_PREFIXES = ["node_modules/", "dist/", "build/", ".next/", "out/"];
+export const MAX_FILES = 200;
+const DECLARATION_SITE_KINDS = new Set([
+    SyntaxKind.ImportSpecifier,
+    SyntaxKind.ImportClause,
+    SyntaxKind.NamespaceImport,
+    SyntaxKind.VariableDeclaration,
+    SyntaxKind.BindingElement,
+]);
+/**
+ * Pure AST extraction: given one file's content, find every place a vendor's SDK is
+ * imported (ES `import` or CommonJS `require`) and then actually called or accessed,
+ * returning the line and the access-chain text (e.g. "stripe.charges.create").
+ */
+export function extractVendorUsages(filePath, sourceCode, matchesModule) {
+    const project = new Project({ useInMemoryFileSystem: true });
+    let sourceFile;
+    try {
+        sourceFile = project.createSourceFile(filePath, sourceCode);
+    }
+    catch {
+        return []; // unparseable file — skip, not fatal to the overall scan
+    }
+    const localIdentifiers = new Set();
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+        if (!matchesModule(importDecl.getModuleSpecifierValue()))
+            continue;
+        const defaultImport = importDecl.getDefaultImport();
+        if (defaultImport)
+            localIdentifiers.add(defaultImport.getText());
+        const namespaceImport = importDecl.getNamespaceImport();
+        if (namespaceImport)
+            localIdentifiers.add(namespaceImport.getText());
+        for (const named of importDecl.getNamedImports()) {
+            localIdentifiers.add(named.getAliasNode()?.getText() ?? named.getName());
+        }
+    }
+    for (const callExpr of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (callExpr.getExpression().getText() !== "require")
+            continue;
+        const arg = callExpr.getArguments()[0];
+        if (!arg || arg.getKind() !== SyntaxKind.StringLiteral)
+            continue;
+        if (!matchesModule(arg.getText().slice(1, -1)))
+            continue;
+        const varDecl = callExpr.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
+        if (!varDecl)
+            continue;
+        const nameNode = varDecl.getNameNode();
+        if (nameNode.getKind() === SyntaxKind.Identifier) {
+            localIdentifiers.add(nameNode.getText());
+        }
+        else if (nameNode.getKind() === SyntaxKind.ObjectBindingPattern) {
+            for (const element of nameNode.asKindOrThrow(SyntaxKind.ObjectBindingPattern).getElements()) {
+                localIdentifiers.add(element.getName());
+            }
+        }
+    }
+    // Propagate one level: `const stripe = new Stripe(key)` binds a new local name
+    // ("stripe") that real code then calls methods on — not the imported class name
+    // itself. Without this, only the `new Stripe(...)` construction line would count.
+    for (const varDecl of sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+        const initializer = varDecl.getInitializer();
+        if (!initializer || initializer.getKind() !== SyntaxKind.NewExpression)
+            continue;
+        const newExpr = initializer.asKindOrThrow(SyntaxKind.NewExpression);
+        if (!localIdentifiers.has(newExpr.getExpression().getText()))
+            continue;
+        const nameNode = varDecl.getNameNode();
+        if (nameNode.getKind() === SyntaxKind.Identifier) {
+            localIdentifiers.add(nameNode.getText());
+        }
+    }
+    if (localIdentifiers.size === 0)
+        return [];
+    const usages = [];
+    const seen = new Set();
+    for (const identifier of sourceFile.getDescendantsOfKind(SyntaxKind.Identifier)) {
+        if (!localIdentifiers.has(identifier.getText()))
+            continue;
+        const parent = identifier.getParent();
+        if (parent && DECLARATION_SITE_KINDS.has(parent.getKind()))
+            continue;
+        let node = parent;
+        let chain = identifier.getText();
+        while (node?.getKind() === SyntaxKind.PropertyAccessExpression) {
+            chain = node.getText();
+            node = node.getParent();
+        }
+        const line = identifier.getStartLineNumber();
+        const key = `${line}:${chain}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        usages.push({ filePath, line, snippet: chain });
+    }
+    return usages;
+}

package/node_modules/@compatra/core/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./vendor-registry.js";
+export * from "./spec-sources.js";
+export * from "./spec-fetcher.js";
+export * from "./shopify-fetcher.js";
+export * from "./resource-match.js";
+export * from "./deprecation-match.js";
+export * from "./migrations.js";

package/node_modules/@compatra/core/dist/index.js

@@ -0,0 +1,11 @@
+// The analysis engine, with no database, no GitHub client and no server dependencies, so the
+// same code runs in the hosted app, the CLI and the GitHub Action and cannot drift between them.
+// The ts-morph-backed AST extractor is deliberately NOT re-exported here: it costs seconds to
+// load, so it lives behind "@compatra/core/ast" and only the code scanner and CLI pay for it.
+export * from "./vendor-registry.js";
+export * from "./spec-sources.js";
+export * from "./spec-fetcher.js";
+export * from "./shopify-fetcher.js";
+export * from "./resource-match.js";
+export * from "./deprecation-match.js";
+export * from "./migrations.js";

package/node_modules/@compatra/core/dist/migrations.d.ts

@@ -0,0 +1,22 @@
+export interface MigrationRecipe {
+    id: string;
+    vendor: string;
+    /** The deprecated endpoint exactly as the scan names it, e.g. "GET /v1/customers/{customer}/cards". */
+    endpoint: string;
+    /** SDK method path relative to the client, e.g. "customers.listCards". Same prefix as `to`. */
+    from: string;
+    to: string;
+    /** Literal params the replacement needs that the old call implied (added to the params argument). */
+    addParams?: Record<string, string>;
+    /** Why we believe this is equivalent, in terms the vendor's own spec backs up. */
+    evidence: string;
+    /** What can still differ after the rewrite. Shown to the developer, never hidden. */
+    caveat: string;
+    docs: {
+        label: string;
+        url: string;
+    }[];
+}
+export declare const MIGRATION_RECIPES: MigrationRecipe[];
+/** The recipe for a flagged call, or null when there is no provably equivalent replacement. */
+export declare function findRecipe(vendor: string, endpoint: string, callText: string): MigrationRecipe | null;