compatra 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Compatra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# compatra
+
+Find third-party API calls in your code that use endpoints the vendor has **already deprecated** —
+before the deprecation becomes a broken integration.
+
+Runs locally. No account, no sign-up, and it never uploads your code.
+
+```bash
+npx compatra scan
+```
+
+## What it does
+
+1. Reads `package.json` for supported vendor SDKs (Stripe, OpenAI, GitHub/Octokit, Twilio, Shopify).
+2. Parses your source with ts-morph to find where those SDKs are **actually called**, not just imported.
+3. Downloads each vendor's public API spec and collects the endpoints they mark deprecated.
+4. Reports call sites that look like they use one.
+
+```
+  Vendor SDKs in this project
+    Stripe   stripe@^17.0.0
+
+  3 call sites across 1 file · 1 file scanned
+
+  Checked against endpoints these vendors already deprecated
+    Stripe 6 deprecated
+
+  1 call site may use a deprecated endpoint
+
+    src/billing.ts:3
+      stripe.customers.listCards
+      → GET /v1/customers/{customer}/cards (deprecated by Stripe)
+```
+
+## Usage
+
+```
+compatra scan [path]        scan a project (default: current directory)
+compatra verify [path]      run your tests with each deprecated endpoint simulated as gone
+compatra fix [path]         rewrite deprecated calls that have a provably equivalent replacement
+
+  --json                    machine-readable output
+  --fail-on-finding         exit 1 when a deprecated endpoint is in use (for CI)
+  --no-color                plain output
+  -h, --help                show help
+  -v, --version             show version
+```
+
+## Fix: rewrite the calls that have a safe replacement
+
+```bash
+compatra fix --dry-run     # show what would change
+compatra fix               # apply it
+```
+
+A vendor's spec says an endpoint is deprecated but never says what to use instead, so `fix` does
+**not** guess. It rewrites a call only when there is a hand-checked recipe whose replacement is
+provably equivalent, and leaves every other flagged call exactly as it was, with the reason.
+
+Today that is Stripe's deprecated customer card reads:
+
+| Before | After |
+|---|---|
+| `stripe.customers.listCards(id)` | `stripe.customers.listSources(id, { object: "card" })` |
+| `stripe.customers.retrieveCard(id, cardId)` | `stripe.customers.retrieveSource(id, cardId)` |
+
+For each recipe the output shows why we believe it is equivalent (what Stripe's own spec says),
+what can still differ, and links to the vendor docs. Checked against the real `stripe` package:
+the request changes from `GET /v1/customers/{id}/cards` to `GET /v1/customers/{id}/sources` carrying
+`object=card`, and the same test suite passes before and after.
+
+**What it refuses, on purpose.** A call whose second argument is a variable or callback (it cannot
+be told apart from a callback, and spreading a callback would corrupt the call), one that already
+sets the filter, one with spread arguments, and any endpoint without a recipe. Formatting is
+preserved: inline objects stay inline, multi-line ones get a line at the same indent, CRLF files
+stay CRLF.
+
+**Caveats we state rather than hide.** The runtime objects are the same, but in TypeScript the
+return type widens from `Card` to a union, so you may need to narrow. Stripe's current
+recommendation is the PaymentMethods API, which is a larger change than this tool makes.
+
+## Verify: does your test suite notice?
+
+```bash
+compatra verify --test "npm test"
+```
+
+Finding a deprecated call says it *might* matter. `verify` shows whether it *would*: it runs **your own
+test command** once as it is, then once per flagged endpoint with that endpoint answering
+`404 Not Found`, and compares.
+
+| Result | Meaning |
+|---|---|
+| `BROKEN` | Your tests pass normally and fail when this endpoint goes away. A real break reaches your code. |
+| `HANDLED` | A test sent a request to the endpoint and your tests still passed: the code copes, or nothing asserts on the result. |
+| `NOT EXERCISED` | Tests are green, but none sent a request there. Proves nothing either way. Tests that mock the SDK land here. |
+| `INCONCLUSIVE` | The suite is red or timed out on its own, or it failed without ever touching the endpoint. |
+
+The point of the split is that "your tests passed" is only evidence when a test actually reached
+the endpoint, so the report never counts an untouched endpoint as safe.
+
+**How it works.** Compatra loads a small preload (`node --import`) into your test processes. It
+redirects requests for the flagged endpoint to a tiny local server that answers 404 and counts the
+hit; every other request goes to the original `http`, `https` or `fetch` function untouched. Your
+tests run on your machine (or your CI runner) and nothing is uploaded.
+
+```
+compatra verify [path]
+
+  --test <command>          your test command (default: "npm test")
+  --endpoint "<vendor> <METHOD> <path>"
+                            simulate this endpoint instead of the ones the scan finds (repeatable)
+  --any-host                match on any host, for tests that point an SDK at stripe-mock
+  --timeout <seconds>       per test run (default: 600)
+  --fail-on-broken          exit 1 when a simulated failure breaks your tests
+```
+
+Exit codes: `1` for a `BROKEN` result with `--fail-on-broken`, `2` when your suite does not pass
+as it is.
+
+**Before and after a fix.** Run it on the old code, then on the migrated code with the same
+`--endpoint`. `BROKEN` before and no longer `BROKEN` after is evidence the migration took: the
+test that used to reach the old endpoint no longer does.
+
+**Limits, stated plainly.**
+
+- Needs Node 22 or newer. Only the JavaScript/TypeScript test process is instrumented.
+- Covers requests made through `http`, `https` or `fetch`, which includes the vendors' own SDKs.
+  It cannot see a test that mocks the SDK itself (those show as `NOT EXERCISED`).
+- Simulates one failure, an HTTP 404. It shows whether your suite would notice a removal; it does
+  not prove your code is correct, and it does not model changed response shapes.
+- Each endpoint costs one full run of your test suite (the first five are simulated).
+- Stripe, OpenAI, GitHub and Twilio only. Shopify (GraphQL) has no per-endpoint model yet.
+- By default an endpoint is matched on the vendor's real host, so tests that point an SDK at a
+  local stand-in need `--any-host`.
+- Tried with `node --test`, vitest and jest, against the real `stripe` package. Other runners that
+  run your tests in Node processes should work because the preload is inherited, but those are untried.
+
+## What it does not claim
+
+Matching is by SDK method name against the endpoint's path, so a result is **worth a look, not
+proof**. It is deliberately strict: `stripe.customers.listCards` is reported against
+`/customers/{id}/cards`, while `stripe.customers.create` is not, even though both touch the
+`customers` resource. That means real uses can be missed — silence is not a guarantee.
+
+Only Stripe and GitHub calls can currently be mapped to endpoints. Other vendors are detected and
+listed, but not call-checked, and the output says so rather than implying an all-clear. If a
+vendor's spec cannot be downloaded, the report says the check is incomplete.
+
+Network is used only to fetch vendors' public API specifications.
+
+## Limits
+
+JavaScript and TypeScript projects with a `package.json` at the path you scan. The first 200 source
+files, skipping `node_modules`, build output and dot-directories — the same rules the hosted
+scanner uses, so local and hosted results agree.
+
+## Continuous monitoring
+
+This is a point-in-time check. For monitoring that watches vendors for *new* changes, maps them to
+your code, alerts you and opens fix PRs, install the GitHub App:
+<https://github.com/apps/compatra>
+
+## Requirements
+
+Node 22 or newer. `npx compatra scan` runs it without installing anything; `npm install --save-dev
+compatra` adds it to a project. It has two runtime dependencies (`ts-morph` and `yaml`) and nothing
+else.
+
+To work on it from source (a monorepo checkout):
+
+```bash
+npm install && npm run build -w cli
+node cli/dist/index.js scan /path/to/project
+```

package/dist/classify.js

@@ -0,0 +1,19 @@
+// What a pair of test runs proves about one flagged endpoint. The point of the four-way split is
+// that "your tests passed" is only evidence when a test actually reached the endpoint.
+export const passed = (run) => !run.timedOut && run.exitCode === 0;
+export function classify(baseline, injected, hits) {
+    if (!passed(baseline)) {
+        return { verdict: "inconclusive", reason: "your tests do not pass even without the simulated failure, so there is nothing to compare against" };
+    }
+    if (injected.timedOut) {
+        return { verdict: "inconclusive", reason: "the run with the simulated failure timed out" };
+    }
+    if (!passed(injected)) {
+        return hits > 0
+            ? { verdict: "broken", reason: `your tests pass normally but fail when this endpoint stops working (${hits} request${hits === 1 ? "" : "s"} hit it)` }
+            : { verdict: "inconclusive", reason: "the run failed, but no request ever reached this endpoint, so the failure is probably unrelated (a flaky test?)" };
+    }
+    return hits > 0
+        ? { verdict: "handled", reason: `${hits} request${hits === 1 ? "" : "s"} reached this endpoint and your tests still passed: the code copes with it failing, or no test asserts on the result` }
+        : { verdict: "unexercised", reason: "no test sent a request to this endpoint, so this proves nothing about it either way (tests that mock the SDK never do, and neither does code that has already moved off it)" };
+}

package/dist/faults.js

@@ -0,0 +1,49 @@
+// Turns a deprecated endpoint from a vendor spec into a fault we can inject at the HTTP layer,
+// and decides whether an outgoing request is that endpoint. Pure: the interceptor that applies
+// it lives in inject.ts, so this is what gets unit-tested.
+// Where each vendor's REST API lives. Shopify is GraphQL, so it has no per-endpoint fault.
+const VENDOR_API = {
+    stripe: { host: "api.stripe.com", pathPrefix: "" },
+    // OpenAI's spec lists paths relative to its /v1 base URL.
+    openai: { host: "api.openai.com", pathPrefix: "/v1" },
+    github: { host: "api.github.com", pathPrefix: "" },
+    // Twilio spreads its products over subdomains (api., verify., ...).
+    twilio: { host: "twilio.com", pathPrefix: "" },
+};
+export const FAULT_SUPPORTED = new Set(Object.keys(VENDOR_API));
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** "/v1/customers/{customer}/cards" -> a regex matching any concrete id in the placeholder slot. */
+export function pathTemplateToPattern(template) {
+    const body = template
+        .split(/(\{[^}]+\})/)
+        .map((part) => (/^\{[^}]+\}$/.test(part) ? "[^/]+" : escapeRegExp(part)))
+        .join("");
+    return `^${body}/?$`;
+}
+/** Parses "GET /v1/customers/{customer}/cards" into its method and path, or null if it isn't that shape. */
+export function parseEndpoint(endpoint) {
+    const match = /^([A-Za-z]+)\s+(\/\S*)$/.exec(endpoint.trim());
+    return match ? { method: match[1].toUpperCase(), path: match[2] } : null;
+}
+export function buildFault(vendor, endpoint, anyHost = false) {
+    const api = VENDOR_API[vendor];
+    const parsed = parseEndpoint(endpoint);
+    if (!api || !parsed)
+        return null;
+    return {
+        vendor,
+        endpoint,
+        method: parsed.method,
+        pathPattern: pathTemplateToPattern(api.pathPrefix + parsed.path),
+        hostSuffix: anyHost ? null : api.host,
+    };
+}
+export function faultMatches(fault, method, hostname, pathname) {
+    if (fault.method !== method.toUpperCase())
+        return false;
+    if (fault.hostSuffix !== null && hostname !== fault.hostSuffix && !hostname.endsWith(`.${fault.hostSuffix}`))
+        return false;
+    // The pattern is built by pathTemplateToPattern from a spec path with every regex character escaped.
+    // eslint-disable-next-line security/detect-non-literal-regexp
+    return new RegExp(fault.pathPattern).test(pathname);
+}

package/dist/fix.js

@@ -0,0 +1,30 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { applyMigrations } from "@compatra/core/migrate";
+import { scanProject } from "./scan.js";
+/**
+ * Rewrites the flagged calls that have a provably equivalent replacement (see core's migration
+ * recipes) and leaves every other flagged call exactly as it was, reporting why.
+ */
+export async function fixProject(root, options = {}) {
+    const { dryRun = false } = options;
+    const hits = options.hits ?? (await scanProject(root)).hits;
+    const byFile = new Map();
+    for (const hit of hits)
+        byFile.set(hit.filePath, [...(byFile.get(hit.filePath) ?? []), hit]);
+    const rootWithSep = path.resolve(root) + path.sep;
+    const files = [];
+    for (const [filePath, fileHits] of byFile) {
+        const absolute = path.resolve(root, filePath);
+        // The paths come from our own scan, but never write outside the project regardless.
+        if (!absolute.startsWith(rootWithSep))
+            continue;
+        const source = await readFile(absolute, "utf8");
+        const result = applyMigrations(filePath, source, fileHits.map((h) => ({ line: h.line, vendor: h.vendor, endpoint: h.endpoint, snippet: h.snippet })));
+        const changed = result.output !== source;
+        if (changed && !dryRun)
+            await writeFile(absolute, result.output, "utf8");
+        files.push({ filePath, changed, applied: result.applied, skipped: result.skipped });
+    }
+    return { root, dryRun, flagged: hits.length, files };
+}

package/dist/index.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { fixProject } from "./fix.js";
+import { formatFixReport, formatReport, formatVerifyReport, makePaint } from "./report.js";
+import { scanProject } from "./scan.js";
+import { verifyProject } from "./verify.js";
+const HELP = `
+compatra — find third-party API calls that use endpoints the vendor already deprecated
+
+  compatra scan [path]        scan a project (default: current directory)
+  compatra verify [path]      run your tests with each deprecated endpoint simulated as gone
+  compatra fix [path]         rewrite deprecated calls that have a provably equivalent replacement
+
+Options
+  --json                      machine-readable output
+  --fail-on-finding           scan: exit 1 when a deprecated endpoint is in use (for CI)
+  --no-color                  plain output
+  -h, --help                  show this
+  -v, --version               show version
+
+fix options
+  --dry-run                   show what would change without writing anything
+
+verify options
+  --test <command>            your test command (default: "npm test")
+  --endpoint "<vendor> <METHOD> <path>"
+                              simulate this endpoint instead of the deprecated ones the scan finds,
+                              e.g. --endpoint "stripe GET /v1/customers/{customer}/cards" (repeatable)
+  --any-host                  match the endpoint on any host, for tests that point an SDK at
+                              stripe-mock or a local proxy instead of the vendor's real host
+  --timeout <seconds>         per test run (default: 600)
+  --fail-on-broken            exit 1 when a simulated failure breaks your tests
+
+verify runs your test command in your checkout, once as it is and once per endpoint with that
+endpoint answering 404. Needs Node 22 or newer.
+`;
+function parseEndpointFlag(value) {
+    const [vendor, ...rest] = value.trim().split(/\s+/);
+    if (!vendor || rest.length < 2) {
+        throw new Error(`--endpoint expects "<vendor> <METHOD> <path>", got "${value}"`);
+    }
+    return { vendor: vendor.toLowerCase(), endpoint: rest.join(" ") };
+}
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean" },
+            "fail-on-finding": { type: "boolean" },
+            "fail-on-broken": { type: "boolean" },
+            "no-color": { type: "boolean" },
+            "any-host": { type: "boolean" },
+            "dry-run": { type: "boolean" },
+            test: { type: "string" },
+            endpoint: { type: "string", multiple: true },
+            timeout: { type: "string" },
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+        },
+    });
+    if (values.help)
+        return void process.stdout.write(HELP);
+    if (values.version)
+        return void console.log("0.1.0");
+    const isCommand = positionals[0] === "scan" || positionals[0] === "verify" || positionals[0] === "fix";
+    const command = isCommand ? positionals[0] : "scan";
+    const root = path.resolve((isCommand ? positionals[1] : positionals[0]) ?? ".");
+    const colour = !values["no-color"] && !process.env.NO_COLOR && process.stdout.isTTY;
+    const paint = makePaint(Boolean(colour));
+    try {
+        if (command === "fix") {
+            const result = await fixProject(root, { dryRun: values["dry-run"] });
+            process.stdout.write(values.json ? `${JSON.stringify(result, null, 2)}\n` : formatFixReport(result, paint));
+            return;
+        }
+        if (command === "verify") {
+            const timeoutSeconds = Number(values.timeout ?? 600);
+            if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)
+                throw new Error(`--timeout expects a number of seconds, got "${values.timeout}"`);
+            const result = await verifyProject({
+                root,
+                testCommand: values.test ?? "npm test",
+                endpoints: values.endpoint?.map(parseEndpointFlag),
+                anyHost: values["any-host"],
+                timeoutMs: timeoutSeconds * 1000,
+            });
+            process.stdout.write(values.json ? `${JSON.stringify(result, null, 2)}\n` : formatVerifyReport(result, paint));
+            if (result.baseline && !result.baseline.passed)
+                process.exitCode = 2;
+            else if (values["fail-on-broken"] && result.verdicts.some((v) => v.verdict === "broken"))
+                process.exitCode = 1;
+            return;
+        }
+        const result = await scanProject(root);
+        process.stdout.write(values.json ? `${JSON.stringify(result, null, 2)}\n` : formatReport(result, paint));
+        if (values["fail-on-finding"] && result.hits.length > 0)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const hint = message.includes("package.json")
+            ? `No package.json found in ${root}. Run this from a Node.js project, or pass its path.`
+            : message;
+        process.stderr.write(`\n  ${hint}\n\n`);
+        process.exitCode = 1;
+    }
+}
+main(process.argv.slice(2)).catch((error) => {
+    // parseArgs rejects unknown flags here, before any command runs.
+    process.stderr.write(`compatra: ${error instanceof Error ? error.message : String(error)}\n${HELP}`);
+    process.exitCode = 1;
+});

package/dist/inject.js

@@ -0,0 +1,107 @@
+// Loaded into the user's test process with `node --import` (see verify.ts).
+//
+// Requests to a flagged endpoint are redirected to a small real HTTP server in this process that
+// answers "endpoint removed" (404) and records the hit; that is how we tell "tests survived it"
+// from "no test ever got there". Every other request calls the original http/https/fetch function
+// untouched, so the only thing that can change a test's outcome is the simulated failure itself.
+import { appendFileSync } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import { syncBuiltinESMExports } from "node:module";
+import { faultMatches } from "./faults.js";
+const faults = JSON.parse(process.env.COMPATRA_FAULTS ?? "[]");
+const hitLog = process.env.COMPATRA_FAULT_LOG;
+const server = http.createServer((req, res) => {
+    if (hitLog)
+        appendFileSync(hitLog, `${JSON.stringify({ method: req.method, path: req.url })}\n`);
+    req.resume();
+    req.on("end", () => {
+        res.writeHead(404, { "content-type": "application/json", "x-compatra-fault": "simulated-removal" });
+        // Carries the fields the vendors' own SDKs read an error from (Stripe/OpenAI `error`, GitHub/Twilio `message`).
+        const message = "Simulated by Compatra: this endpoint no longer exists.";
+        res.end(JSON.stringify({ message, error: { type: "invalid_request_error", message } }));
+    });
+});
+// Top-level await: Node finishes this module before the test runner starts, so the port is known
+// before any request can be made. unref so the server never keeps a process alive.
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+server.unref();
+const faultPort = server.address().port;
+const isFaulted = (method, hostname, pathname) => faults.some((f) => faultMatches(f, method, hostname, pathname));
+/** http.request accepts (url, options?, cb?) or (options, cb?). Pull the parts a fault matches on. */
+function describeRequest(args, defaultProtocol) {
+    const [first, second] = args;
+    const url = typeof first === "string" ? new URL(first) : first instanceof URL ? first : null;
+    const options = (url ? (typeof second === "object" && second !== null ? second : {}) : first);
+    const protocol = options.protocol ?? url?.protocol ?? defaultProtocol;
+    const hostname = String(options.hostname ?? options.host ?? url?.hostname ?? "localhost").replace(/:\d+$/, "");
+    const rawPath = options.path ?? (url ? `${url.pathname}${url.search}` : "/");
+    const pathname = rawPath.split("?")[0];
+    return { url, options, protocol, hostname, rawPath, pathname, method: (options.method ?? "GET").toUpperCase() };
+}
+// The fault server speaks plain http, so redirected requests always go through http.request,
+// even when the caller used https (https.request rejects an http: target).
+const httpRequest = http.request;
+function redirect(args, defaultProtocol) {
+    const d = describeRequest(args, defaultProtocol);
+    if (d.options.socketPath || !isFaulted(d.method, d.hostname, d.pathname))
+        return null;
+    // Keep everything the caller set except where the request goes. agent is dropped because an
+    // https.Agent cannot serve the plain-http fault server.
+    const options = { ...d.options };
+    delete options.agent;
+    const target = {
+        ...options,
+        protocol: "http:",
+        hostname: "127.0.0.1",
+        host: "127.0.0.1",
+        port: faultPort,
+        path: d.rawPath,
+        method: d.method,
+    };
+    // (url, cb), (url, options, cb) and (options, cb) all put the callback somewhere after the first argument.
+    const callback = args.slice(1).find((a) => typeof a === "function");
+    const req = callback ? httpRequest(target, callback) : httpRequest(target);
+    if (d.protocol === "https:") {
+        // Some SDKs (older stripe-node) hold the request body until the socket reports
+        // "secureConnect". A plain-http socket never does, so report it once connected.
+        req.once("socket", (socket) => {
+            if (socket.connecting)
+                socket.once("connect", () => socket.emit("secureConnect"));
+        });
+    }
+    return req;
+}
+function patch(mod, defaultProtocol) {
+    const request = mod.request;
+    const get = mod.get;
+    mod.request = ((...args) => redirect(args, defaultProtocol) ?? request(...args));
+    mod.get = ((...args) => {
+        const redirected = redirect(args, defaultProtocol);
+        if (!redirected)
+            return get(...args);
+        // get() is request() plus an automatic end(); a redirected request must end too.
+        redirected.end();
+        return redirected;
+    });
+}
+patch(http, "http:");
+patch(https, "https:");
+const realFetch = globalThis.fetch;
+globalThis.fetch = ((input, init) => {
+    const raw = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return realFetch(input, init); // relative URL or something odd: not ours to judge
+    }
+    if (!isFaulted(method, url.hostname, url.pathname))
+        return realFetch(input, init);
+    const target = `http://127.0.0.1:${faultPort}${url.pathname}${url.search}`;
+    return realFetch(input instanceof Request ? new Request(target, input) : target, init);
+});
+// Let ESM named imports (import { request } from "node:http") see the patched functions too.
+syncBuiltinESMExports();

package/dist/report.js

@@ -0,0 +1,145 @@
+const VENDOR_LABELS = {
+    stripe: "Stripe",
+    openai: "OpenAI",
+    github: "GitHub",
+    twilio: "Twilio",
+    shopify: "Shopify",
+};
+const label = (v) => VENDOR_LABELS[v] ?? v;
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+// Colour only when writing to a terminal that wants it, so piped and CI output stays plain.
+export function makePaint(enabled) {
+    const wrap = (code) => (s) => (enabled ? `\u001b[${code}m${s}\u001b[0m` : s);
+    return {
+        bold: wrap("1"),
+        dim: wrap("2"),
+        red: wrap("31"),
+        green: wrap("32"),
+        amber: wrap("33"),
+        cyan: wrap("36"),
+    };
+}
+export function formatReport(result, paint) {
+    const { bold, dim, green, amber, cyan } = paint;
+    const out = ["", bold("Compatra") + dim("  ·  third-party API reliability"), dim(`  ${result.root}`), ""];
+    if (result.dependencies.length === 0) {
+        out.push("  No supported vendor SDKs found in package.json.", dim("  Compatra currently recognises Stripe, OpenAI, GitHub (Octokit), Twilio and Shopify."), "");
+        return out.join("\n");
+    }
+    out.push(bold("  Vendor SDKs in this project"));
+    for (const dep of result.dependencies) {
+        out.push(`    ${label(dep.vendor).padEnd(8)} ${dim(`${dep.packageName}@${dep.versionRange}`)}`);
+    }
+    const fileCount = new Set(result.callSites.map((c) => c.filePath)).size;
+    out.push("", `  ${plural(result.callSites.length, "call site")} across ${plural(fileCount, "file")}` +
+        dim(` · ${plural(result.filesScanned, "file")} scanned${result.truncated ? " (capped)" : ""}`));
+    if (result.checked.length > 0) {
+        const summary = result.checked
+            .map((c) => `${label(c.vendor)} ${dim(`${c.deprecatedEndpoints} deprecated`)}`)
+            .join(dim("  ·  "));
+        out.push("", bold("  Checked against endpoints these vendors already deprecated"), `    ${summary}`);
+    }
+    out.push("");
+    if (result.hits.length > 0) {
+        out.push(amber(`  ${plural(result.hits.length, "call site")} may use a deprecated endpoint`), "");
+        for (const hit of result.hits) {
+            out.push(`    ${cyan(`${hit.filePath}:${hit.line}`)}`);
+            out.push(`      ${hit.snippet}`);
+            out.push(`      ${dim("→")} ${amber(hit.endpoint)} ${dim(`(deprecated by ${label(hit.vendor)})`)}`);
+            out.push("");
+        }
+        out.push(dim("  Worth a look rather than proof: matching is by SDK method name."));
+    }
+    else if (result.checked.length > 0) {
+        out.push(green("  No call site uses an endpoint these vendors have deprecated."));
+    }
+    else {
+        out.push(dim("  Nothing could be call-checked in this project yet."));
+    }
+    if (result.unsupported.length > 0) {
+        out.push(dim(`  Not call-checked yet: ${result.unsupported.map(label).join(", ")} — detected, but only Stripe and GitHub`), dim("  calls can be mapped to endpoints in this version."));
+    }
+    if (result.specError) {
+        out.push(amber(`  Could not reach every vendor spec, so this is incomplete: ${result.specError}`));
+    }
+    out.push("", dim("  This is a point-in-time check. Continuous monitoring, impact alerts and fix PRs:"), dim("  https://github.com/apps/compatra"), "");
+    return out.join("\n");
+}
+const VERDICT_TITLE = {
+    broken: "BROKEN",
+    handled: "HANDLED",
+    unexercised: "NOT EXERCISED",
+    inconclusive: "INCONCLUSIVE",
+};
+export function formatVerifyReport(result, paint) {
+    const { bold, dim, red, green, amber } = paint;
+    const out = ["", bold("Compatra verify") + dim("  ·  does your test suite notice when an endpoint goes away?"), dim(`  ${result.root}`), ""];
+    if (!result.baseline) {
+        out.push("  No deprecated endpoint to simulate, so your tests were not run.", "");
+        for (const s of result.skipped)
+            out.push(dim(`  Skipped ${s.endpoint}: no HTTP model for ${label(s.vendor)} yet.`));
+        return out.join("\n");
+    }
+    out.push(`  Test command: ${bold(result.testCommand)}`);
+    if (!result.baseline.passed) {
+        out.push("", red(result.baseline.timedOut ? "  Your tests timed out before any failure was simulated." : "  Your tests fail as they are, so nothing was simulated."), dim("  A failing run tells us nothing until the suite passes on its own. Last output:"), "", ...result.baseline.outputTail.trimEnd().split("\n").map((line) => dim(`    ${line}`)), "");
+        return out.join("\n");
+    }
+    out.push(green("  Passes as it is."), "");
+    for (const v of result.verdicts) {
+        const paintVerdict = { broken: red, handled: green, unexercised: amber, inconclusive: dim }[v.verdict];
+        out.push(`  ${paintVerdict(VERDICT_TITLE[v.verdict].padEnd(13))} ${bold(v.endpoint)} ${dim(`(${label(v.vendor)})`)}`);
+        out.push(dim(`                ${v.reason}`), "");
+    }
+    if (result.truncated) {
+        out.push(dim("  More endpoints were flagged than were simulated; each one costs a full run of your tests."), "");
+    }
+    for (const s of result.skipped) {
+        out.push(dim(`  Skipped ${s.endpoint}: no HTTP model for ${label(s.vendor)} yet.`));
+    }
+    out.push(dim("  The simulated failure is an HTTP 404 on that one endpoint, applied to requests your tests make."), dim("  It shows whether your suite would notice. It does not prove your code is correct."), "");
+    return out.join("\n");
+}
+export function formatFixReport(result, paint) {
+    const { bold, dim, green, amber, cyan } = paint;
+    const out = ["", bold("Compatra fix") + dim("  ·  rewrite deprecated calls that have a provably equivalent replacement"), dim(`  ${result.root}`), ""];
+    const applied = result.files.flatMap((f) => f.applied.map((a) => ({ file: f.filePath, ...a })));
+    const skipped = result.files.flatMap((f) => f.skipped.map((s) => ({ file: f.filePath, ...s })));
+    if (result.flagged === 0) {
+        out.push("  No deprecated call sites to fix.", "");
+        return out.join("\n");
+    }
+    if (applied.length > 0) {
+        out.push(green(`  ${result.dryRun ? "Would rewrite" : "Rewrote"} ${plural(applied.length, "call")} in ${plural(new Set(applied.map((a) => a.file)).size, "file")}`), "");
+        for (const a of applied) {
+            out.push(`    ${cyan(`${a.file}:${a.line}`)}  ${a.recipe.from} ${dim("→")} ${a.recipe.to}`);
+        }
+        out.push("");
+        for (const recipe of new Map(applied.map((a) => [a.recipe.id, a.recipe])).values()) {
+            out.push(bold(`  ${recipe.from} → ${recipe.to}`));
+            out.push(dim(`    Why:   ${recipe.evidence}`));
+            out.push(amber(`    Check: ${recipe.caveat}`));
+            for (const doc of recipe.docs)
+                out.push(dim(`    ${doc.label}: ${doc.url}`));
+            out.push("");
+        }
+    }
+    else {
+        out.push(amber("  Nothing was rewritten."), "");
+    }
+    if (skipped.length > 0) {
+        out.push(bold(`  Left for you (${skipped.length})`));
+        for (const s of skipped) {
+            out.push(`    ${cyan(`${s.file}:${s.line}`)}  ${s.snippet}`);
+            out.push(dim(`      ${s.reason}`));
+        }
+        out.push("");
+    }
+    out.push(dim(result.dryRun ? "  Nothing was written. Run without --dry-run to apply." : "  Review the changes (git diff) and run your tests."), ...(result.dryRun || applied.length === 0
+        ? []
+        : [
+            dim("  To see whether your tests ever reached the old endpoint, run compatra verify on the original"),
+            dim("  code and again now with the same --endpoint: BROKEN before and not after means the change took."),
+        ]), "");
+    return out.join("\n");
+}