compatra 0.1.0

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

@@ -0,0 +1,49 @@
+// Migration recipes: deprecated SDK call -> replacement, for the cases where the replacement is
+// provably equivalent. A vendor spec says an endpoint is deprecated but never what to use instead,
+// so every recipe here was checked by hand against the vendor's spec and the real SDK. Anything
+// without a recipe is annotated for a human, never guessed at.
+//
+// Pure data, no ts-morph, so it is safe to import from the main barrel. The code that applies a
+// recipe lives in apply-migration.ts (subpath `@compatra/core/migrate`).
+const STRIPE_SPEC = "https://github.com/stripe/openapi/blob/master/openapi/spec3.json";
+export const MIGRATION_RECIPES = [
+    {
+        id: "stripe-customer-cards-list",
+        vendor: "stripe",
+        endpoint: "GET /v1/customers/{customer}/cards",
+        from: "customers.listCards",
+        to: "customers.listSources",
+        addParams: { object: "card" },
+        evidence: "Stripe's OpenAPI spec marks GET /v1/customers/{customer}/cards as deprecated and offers " +
+            "GET /v1/customers/{customer}/sources, which takes an `object` filter; `object: 'card'` returns the same Card objects.",
+        caveat: "Same objects at runtime. In TypeScript the return type widens from `Card` to `BankAccount | Card | Source`, " +
+            "so code that reads card fields may need narrowing (`item.object === 'card'`). Stripe's newer recommendation is the " +
+            "PaymentMethods API, which is a larger change and was not applied.",
+        docs: [
+            { label: "Stripe API: Cards (deprecated)", url: "https://docs.stripe.com/api/cards/list" },
+            { label: "Stripe API: Sources", url: "https://docs.stripe.com/api/sources" },
+            { label: "Stripe OpenAPI spec", url: STRIPE_SPEC },
+        ],
+    },
+    {
+        id: "stripe-customer-cards-retrieve",
+        vendor: "stripe",
+        endpoint: "GET /v1/customers/{customer}/cards/{id}",
+        from: "customers.retrieveCard",
+        to: "customers.retrieveSource",
+        evidence: "Stripe's OpenAPI spec marks GET /v1/customers/{customer}/cards/{id} as deprecated; " +
+            "GET /v1/customers/{customer}/sources/{id} takes the same customer and id and returns the same object for a card id.",
+        caveat: "Same object at runtime. In TypeScript the return type widens from `Card` to a `Card | BankAccount | Source` union, " +
+            "so code that reads card fields may need narrowing. Stripe's newer recommendation is the PaymentMethods API, " +
+            "which is a larger change and was not applied.",
+        docs: [
+            { label: "Stripe API: Cards (deprecated)", url: "https://docs.stripe.com/api/cards/retrieve" },
+            { label: "Stripe API: Sources", url: "https://docs.stripe.com/api/sources" },
+            { label: "Stripe OpenAPI spec", url: STRIPE_SPEC },
+        ],
+    },
+];
+/** The recipe for a flagged call, or null when there is no provably equivalent replacement. */
+export function findRecipe(vendor, endpoint, callText) {
+    return (MIGRATION_RECIPES.find((r) => r.vendor === vendor && r.endpoint === endpoint && (callText === r.from || callText.endsWith(`.${r.from}`))) ?? null);
+}

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

@@ -0,0 +1,24 @@
+export declare const RESOURCE_MATCHING_SUPPORTED: Set<string>;
+/**
+ * Extract the "resource" segment from a REST path, e.g. Stripe's
+ * `/v1/payment_intents/{id}/confirm` -> "payment_intents", GitHub's
+ * `/repos/{owner}/{repo}/issues` -> "issues".
+ *
+ * Known imperfection (documented, not silently hidden): GitHub's REST paths don't
+ * always line up 1:1 with octokit's SDK namespace grouping (e.g. `/notifications/*`
+ * is under octokit's `activity.*`, not a `notifications.*` namespace; `/app/*` is
+ * singular but octokit groups it under `apps.*`). Real cases like these won't match
+ * and fall back to today's vendor-wide behavior for that finding — a missed
+ * attribution, not a wrong one.
+ */
+export declare function extractResourceFromPath(vendor: string, path: string): string | null;
+/**
+ * Extract the "resource" segment from a raw SDK call-chain snippet (e.g.
+ * `"stripe.paymentIntents.confirm"` -> "payment_intents",
+ * `"octokit.rest.issues.create"` -> "issues"). The chain's first token is whichever
+ * local variable name the developer chose for the client (not necessarily "stripe"
+ * or "octokit") — always the second token, after dropping an optional literal
+ * `.rest.` wrapper some octokit call styles include.
+ */
+export declare function extractResourceFromUsage(vendor: string, snippet: string): string | null;
+export declare function resourcesMatch(vendor: string, path: string, snippet: string): boolean;

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

@@ -0,0 +1,84 @@
+// Heuristic, resource-level matching — not an exact SDK-method -> REST-operation
+// resolver (that's a much harder, vendor-specific problem; see README's scope-limits
+// section). Only attempted for vendors whose SDK conventions and REST paths both
+// follow a clean `resource.action()` / `/{resource}/...` shape.
+export const RESOURCE_MATCHING_SUPPORTED = new Set(["stripe", "github"]);
+// GitHub paths are scoped under an owner/repo/org/etc. prefix before the actual
+// resource segment (e.g. /repos/{owner}/{repo}/issues) — these are pure scoping
+// prefixes, never resources themselves, so they get stripped along with the
+// path-parameter segments that follow them. Words like "gists" or "notifications"
+// are deliberately NOT here — they're resources in their own right (octokit's
+// `gists.*` namespace), not containers to skip past.
+const GITHUB_SCOPE_PREFIXES = new Set(["repos", "orgs", "enterprises", "user", "users", "teams"]);
+// Normalizes both sides to the same shape: SDK chains are camelCase
+// ("codeScanning"), REST path segments are hyphenated ("code-scanning") — without
+// this, e.g. `octokit.rest.codeScanning.*` would never match `/code-scanning/*`.
+function normalize(s) {
+    return s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().replace(/-/g, "_");
+}
+function isPathParam(segment) {
+    return segment.startsWith("{") && segment.endsWith("}");
+}
+/**
+ * Extract the "resource" segment from a REST path, e.g. Stripe's
+ * `/v1/payment_intents/{id}/confirm` -> "payment_intents", GitHub's
+ * `/repos/{owner}/{repo}/issues` -> "issues".
+ *
+ * Known imperfection (documented, not silently hidden): GitHub's REST paths don't
+ * always line up 1:1 with octokit's SDK namespace grouping (e.g. `/notifications/*`
+ * is under octokit's `activity.*`, not a `notifications.*` namespace; `/app/*` is
+ * singular but octokit groups it under `apps.*`). Real cases like these won't match
+ * and fall back to today's vendor-wide behavior for that finding — a missed
+ * attribution, not a wrong one.
+ */
+export function extractResourceFromPath(vendor, path) {
+    // path is "METHOD /some/path" (diffPaths' format) or a bare "/some/path" — handle both.
+    const rawPath = path.includes(" ") ? path.split(" ")[1] : path;
+    const segments = rawPath.split("/").filter(Boolean);
+    if (vendor === "stripe") {
+        const withoutVersion = segments[0] === "v1" ? segments.slice(1) : segments;
+        return withoutVersion[0] ? normalize(withoutVersion[0]) : null;
+    }
+    if (vendor === "github") {
+        let i = 0;
+        while (i < segments.length) {
+            const seg = segments[i];
+            if (GITHUB_SCOPE_PREFIXES.has(seg)) {
+                i++;
+                while (i < segments.length && isPathParam(segments[i]))
+                    i++;
+                continue;
+            }
+            if (isPathParam(seg)) {
+                i++;
+                continue;
+            }
+            break;
+        }
+        return segments[i] ? normalize(segments[i]) : null;
+    }
+    return null;
+}
+/**
+ * Extract the "resource" segment from a raw SDK call-chain snippet (e.g.
+ * `"stripe.paymentIntents.confirm"` -> "payment_intents",
+ * `"octokit.rest.issues.create"` -> "issues"). The chain's first token is whichever
+ * local variable name the developer chose for the client (not necessarily "stripe"
+ * or "octokit") — always the second token, after dropping an optional literal
+ * `.rest.` wrapper some octokit call styles include.
+ */
+export function extractResourceFromUsage(vendor, snippet) {
+    if (!RESOURCE_MATCHING_SUPPORTED.has(vendor))
+        return null;
+    const parts = snippet.split(".").filter((p) => p !== "rest");
+    if (parts.length < 2)
+        return null;
+    return normalize(parts[1]);
+}
+export function resourcesMatch(vendor, path, snippet) {
+    const pathResource = extractResourceFromPath(vendor, path);
+    const usageResource = extractResourceFromUsage(vendor, snippet);
+    if (!pathResource || !usageResource)
+        return false;
+    return pathResource === usageResource;
+}

package/node_modules/@compatra/core/dist/shopify-fetcher.d.ts

@@ -0,0 +1,3 @@
+import type { FetchedSpec } from "./spec-fetcher.js";
+import type { GraphqlSpecSource } from "./spec-sources.js";
+export declare function fetchShopifySchema(source: GraphqlSpecSource): Promise<FetchedSpec>;

package/node_modules/@compatra/core/dist/shopify-fetcher.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+// Only what's needed to detect the breaking changes we care about: a root
+// Query/Mutation operation appearing/disappearing, or a type's field appearing/
+// disappearing/changing NON_NULL-ness or deprecated-ness — not full type resolution,
+// so this stays shallow (one level of `type.kind`) rather than the classic 7-level
+// introspection TypeRef fragment other tools use to fully resolve
+// NonNull(List(NonNull(...))). `includeDeprecated: true` is required — by default
+// Shopify's introspection omits deprecated fields entirely, which would make a
+// deprecation invisible as a "field removed" rather than the more specific,
+// earlier-warning "field deprecated" signal we actually want.
+const INTROSPECTION_QUERY = `
+  query IntrospectionQuery {
+    __schema {
+      queryType { name }
+      mutationType { name }
+      types {
+        kind
+        name
+        fields(includeDeprecated: true) { name isDeprecated deprecationReason type { kind } }
+        inputFields { name isDeprecated deprecationReason type { kind } }
+      }
+    }
+  }
+`;
+// GraphQL's nullability is a NON_NULL type-wrapper, not a separate `required` array
+// like OpenAPI — a field is "required-ish" only when its outermost kind is NON_NULL.
+// (For an output field this means "never null in a response," not "the caller must
+// supply it" the way it does for an input field — both are still meaningful,
+// real breaking-change signals, treated uniformly here as a documented simplification.)
+function isRequired(field) {
+    return field.type.kind === "NON_NULL";
+}
+function normalizeType(type) {
+    const fields = [...(type.fields ?? []), ...(type.inputFields ?? [])];
+    const deprecationReasons = {};
+    for (const field of fields) {
+        if (field.isDeprecated && field.deprecationReason) {
+            deprecationReasons[field.name] = field.deprecationReason;
+        }
+    }
+    return {
+        properties: fields.map((f) => f.name).sort(),
+        required: fields.filter(isRequired).map((f) => f.name).sort(),
+        deprecated: fields.filter((f) => f.isDeprecated).map((f) => f.name).sort(),
+        deprecationReasons: Object.keys(deprecationReasons).length > 0 ? deprecationReasons : undefined,
+    };
+}
+export async function fetchShopifySchema(source) {
+    const url = source.urls[0];
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch ${source.vendor} GraphQL schema (${url}): ${res.status} ${res.statusText}`);
+    }
+    const raw = await res.text();
+    const hash = createHash("sha256").update(raw).digest("hex");
+    const body = JSON.parse(raw);
+    if (body.errors?.length) {
+        throw new Error(`${source.vendor} GraphQL introspection returned errors: ${body.errors.map((e) => e.message).join("; ")}`);
+    }
+    const schema = body.data?.__schema;
+    if (!schema) {
+        throw new Error(`${source.vendor} GraphQL introspection returned no __schema`);
+    }
+    const typesByName = new Map(schema.types.map((t) => [t.name, t]));
+    const paths = [];
+    const deprecatedPaths = [];
+    const queryType = schema.queryType ? typesByName.get(schema.queryType.name) : undefined;
+    for (const field of queryType?.fields ?? []) {
+        const key = `QUERY ${field.name}`;
+        paths.push(key);
+        if (field.isDeprecated)
+            deprecatedPaths.push(key);
+    }
+    const mutationType = schema.mutationType ? typesByName.get(schema.mutationType.name) : undefined;
+    for (const field of mutationType?.fields ?? []) {
+        const key = `MUTATION ${field.name}`;
+        paths.push(key);
+        if (field.isDeprecated)
+            deprecatedPaths.push(key);
+    }
+    paths.sort();
+    deprecatedPaths.sort();
+    const schemas = {};
+    for (const type of schema.types) {
+        if (type.name.startsWith("__"))
+            continue; // introspection meta-types, not real API surface
+        if (type.kind !== "OBJECT" && type.kind !== "INPUT_OBJECT")
+            continue;
+        schemas[type.name] = normalizeType(type);
+    }
+    // GraphQL has no separate "request body" concept the way REST does — a
+    // mutation/query's arguments aren't a named, diffable schema the way an OpenAPI
+    // requestBody is. Left empty rather than attempting a forced analog.
+    return { paths, deprecatedPaths, schemas, requestSchemas: {}, hash };
+}

package/node_modules/@compatra/core/dist/spec-fetcher.d.ts

@@ -0,0 +1,15 @@
+import type { OpenApiSpecSource } from "./spec-sources.js";
+export interface NormalizedSchema {
+    properties: string[];
+    required: string[];
+    deprecated: string[];
+    deprecationReasons?: Record<string, string>;
+}
+export interface FetchedSpec {
+    paths: string[];
+    deprecatedPaths: string[];
+    schemas: Record<string, NormalizedSchema>;
+    requestSchemas: Record<string, NormalizedSchema>;
+    hash: string;
+}
+export declare function fetchVendorSpec(source: OpenApiSpecSource): Promise<FetchedSpec>;

package/node_modules/@compatra/core/dist/spec-fetcher.js

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import { parse as parseYaml } from "yaml";
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+// Tried in this order — first one present in `requestBody.content` wins. Covers every
+// real shape observed across tracked vendors: Stripe (form-urlencoded), GitHub/OpenAI
+// (json). multipart is a lower-priority fallback for completeness, not confirmed
+// against any tracked vendor's real usage.
+const REQUEST_BODY_CONTENT_TYPES = ["application/json", "application/x-www-form-urlencoded", "multipart/form-data"];
+function directPropsRequired(schema) {
+    const properties = Object.entries(schema.properties ?? {});
+    return {
+        properties: properties.map(([name]) => name).sort(),
+        required: [...(schema.required ?? [])].sort(),
+        deprecated: properties.filter(([, prop]) => prop.deprecated).map(([name]) => name).sort(),
+    };
+}
+function resolveRef(ref, components) {
+    return components[ref.replace(/^#\/components\/schemas\//, "")];
+}
+// One level of $ref resolution, and a flat allOf property/required merge (each
+// member also $ref-resolved one level) — covers every real request-body shape
+// observed across tracked vendors (Stripe/GitHub: inline; OpenAI: bare $ref wrapped
+// in allOf). A member needing further $ref/allOf resolution beyond that is left
+// out — a known, documented gap, not a crash (mirrors the response-shape polymorphic
+// schema gap in fetchAndParseOne below).
+function mergeAllOf(members, components) {
+    const properties = new Set();
+    const required = new Set();
+    const deprecated = new Set();
+    for (const member of members) {
+        const resolved = "$ref" in member ? resolveRef(member.$ref, components) : member;
+        if (!resolved)
+            continue;
+        for (const [prop, propSchema] of Object.entries(resolved.properties ?? {})) {
+            properties.add(prop);
+            if (propSchema.deprecated)
+                deprecated.add(prop);
+        }
+        for (const req of resolved.required ?? [])
+            required.add(req);
+    }
+    return { properties: [...properties].sort(), required: [...required].sort(), deprecated: [...deprecated].sort() };
+}
+function resolveRequestSchema(raw, components) {
+    if ("$ref" in raw) {
+        const resolved = resolveRef(raw.$ref, components);
+        if (!resolved)
+            return { properties: [], required: [], deprecated: [] };
+        if (resolved.allOf)
+            return mergeAllOf(resolved.allOf, components);
+        return directPropsRequired(resolved);
+    }
+    if (raw.allOf)
+        return mergeAllOf(raw.allOf, components);
+    return directPropsRequired(raw);
+}
+function extractRequestSchemas(paths, components) {
+    const requestSchemas = {};
+    for (const [path, methods] of Object.entries(paths)) {
+        for (const [method, operation] of Object.entries(methods)) {
+            if (!HTTP_METHODS.includes(method))
+                continue;
+            const content = operation.requestBody?.content;
+            if (!content)
+                continue;
+            const contentType = REQUEST_BODY_CONTENT_TYPES.find((ct) => content[ct]?.schema);
+            const rawSchema = contentType ? content[contentType]?.schema : undefined;
+            if (!rawSchema)
+                continue;
+            requestSchemas[`${method.toUpperCase()} ${path}`] = resolveRequestSchema(rawSchema, components);
+        }
+    }
+    return requestSchemas;
+}
+async function fetchAndParseOne(url, vendor, format) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch ${vendor} OpenAPI spec (${url}): ${res.status} ${res.statusText}`);
+    }
+    const raw = await res.text();
+    const spec = (format === "yaml" ? parseYaml(raw) : JSON.parse(raw));
+    const paths = [];
+    const deprecatedPaths = [];
+    for (const [path, methods] of Object.entries(spec.paths ?? {})) {
+        for (const [method, operation] of Object.entries(methods)) {
+            if (!HTTP_METHODS.includes(method))
+                continue;
+            const key = `${method.toUpperCase()} ${path}`;
+            paths.push(key);
+            if (operation.deprecated)
+                deprecatedPaths.push(key);
+        }
+    }
+    // Only property presence + required-ness + deprecated-ness, not full type info —
+    // enough to catch the breaking changes that matter (a field disappearing, a field
+    // becoming required, a field/operation getting marked deprecated as advance
+    // warning before it's actually removed) without needing to resolve every vendor's
+    // different $ref/allOf/anyOf composition style. A schema that's itself an
+    // allOf/anyOf/oneOf composition (no direct `properties` key) extracts as an empty
+    // property list — a known false-negative gap, not a crash (see README's
+    // scope-limits section).
+    const schemas = {};
+    for (const [name, schema] of Object.entries(spec.components?.schemas ?? {})) {
+        schemas[name] = directPropsRequired(schema);
+    }
+    const requestSchemas = extractRequestSchemas(spec.paths ?? {}, spec.components?.schemas ?? {});
+    return { raw, paths, deprecatedPaths, schemas, requestSchemas };
+}
+export async function fetchVendorSpec(source) {
+    // Most vendors have exactly one spec file; Twilio has ~60 per-product files that
+    // all get merged into one logical "twilio" spec — fetched in the source's fixed
+    // array order so the combined hash is deterministic across runs.
+    const files = await Promise.all(source.urls.map((url) => fetchAndParseOne(url, source.vendor, source.format)));
+    const hash = createHash("sha256")
+        .update(files.map((f) => f.raw).join("\n"))
+        .digest("hex");
+    const paths = [...new Set(files.flatMap((f) => f.paths))].sort();
+    const deprecatedPaths = [...new Set(files.flatMap((f) => f.deprecatedPaths))].sort();
+    // Merge by schema/operation-key name across files. A genuine name collision across
+    // distinct per-product spec files is expected to be rare — last-fetched wins, not
+    // specially reconciled beyond that.
+    const schemas = {};
+    const requestSchemas = {};
+    for (const file of files) {
+        Object.assign(schemas, file.schemas);
+        Object.assign(requestSchemas, file.requestSchemas);
+    }
+    return { paths, deprecatedPaths, schemas, requestSchemas, hash };
+}

package/node_modules/@compatra/core/dist/spec-sources.d.ts

@@ -0,0 +1,13 @@
+interface VendorSpecSourceBase {
+    vendor: string;
+    urls: string[];
+}
+export type OpenApiSpecSource = VendorSpecSourceBase & {
+    format: "json" | "yaml";
+};
+export type GraphqlSpecSource = VendorSpecSourceBase & {
+    format: "graphql";
+};
+export type VendorSpecSource = OpenApiSpecSource | GraphqlSpecSource;
+export declare const VENDOR_SPEC_SOURCES: VendorSpecSource[];
+export {};

package/node_modules/@compatra/core/dist/spec-sources.js

@@ -0,0 +1,109 @@
+// Shopify's Admin API is GraphQL-first with no OpenAPI/REST spec at all. A real,
+// unauthenticated introspection endpoint exists per API version
+// (shopify.dev/admin-graphql-direct-proxy/<version>). Pinned to a real, current
+// version rather than the "unstable" alias — "unstable" would avoid ever needing a
+// manual bump, but surfaces in-development changes a real pinned integration
+// wouldn't see yet, undermining the point of a tool about real breaking changes.
+// Shopify releases quarterly (Jan/Apr/Jul/Oct); this needs bumping roughly yearly as
+// old versions drop out of the proxy's rolling window — same maintenance tradeoff
+// already accepted for Twilio's hardcoded file list above.
+const SHOPIFY_API_VERSION = "2026-07";
+const TWILIO_BASE = "https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/json";
+// The real, current list of Twilio's per-product spec files (fetched from GitHub's
+// API — twilio/twilio-oai has 60 files under spec/json today, all confirmed same
+// OpenAPI 3.0.1 shape as the one already parsed). Hardcoded rather than fetched live
+// at scan time — avoids an extra GitHub API call/rate-limit dependency in the scan
+// path. A new Twilio product added later needs this list updated manually — a stated
+// limitation, not an oversight.
+const TWILIO_SPEC_FILES = [
+    "twilio_accounts_v1.json",
+    "twilio_api_v2010.json",
+    "twilio_bulkexports_v1.json",
+    "twilio_chat_v1.json",
+    "twilio_chat_v2.json",
+    "twilio_chat_v3.json",
+    "twilio_content_v1.json",
+    "twilio_content_v2.json",
+    "twilio_conversations_v1.json",
+    "twilio_conversations_v2.json",
+    "twilio_events_v1.json",
+    "twilio_flex_v1.json",
+    "twilio_flex_v2.json",
+    "twilio_frontline_v1.json",
+    "twilio_iam_organizations.json",
+    "twilio_iam_v1.json",
+    "twilio_insights_v1.json",
+    "twilio_insights_v2.json",
+    "twilio_insights_v3.json",
+    "twilio_intelligence_v2.json",
+    "twilio_intelligence_v3.json",
+    "twilio_ip_messaging_v1.json",
+    "twilio_ip_messaging_v2.json",
+    "twilio_knowledge_v1.json",
+    "twilio_knowledge_v2.json",
+    "twilio_lookups_v1.json",
+    "twilio_lookups_v2.json",
+    "twilio_marketplace_v1.json",
+    "twilio_memory_v1.json",
+    "twilio_messaging_v1.json",
+    "twilio_messaging_v2.json",
+    "twilio_messaging_v3.json",
+    "twilio_monitor_v1.json",
+    "twilio_monitor_v2.json",
+    "twilio_notify_v1.json",
+    "twilio_numbers_v1.json",
+    "twilio_numbers_v2.json",
+    "twilio_numbers_v3.json",
+    "twilio_oauth_v1.json",
+    "twilio_oauth_v2.json",
+    "twilio_preview.json",
+    "twilio_pricing_v1.json",
+    "twilio_pricing_v2.json",
+    "twilio_proxy_v1.json",
+    "twilio_routes_v2.json",
+    "twilio_routes_v3.json",
+    "twilio_serverless_v1.json",
+    "twilio_studio_v1.json",
+    "twilio_studio_v2.json",
+    "twilio_supersim_v1.json",
+    "twilio_sync_v1.json",
+    "twilio_taskrouter_v1.json",
+    "twilio_trunking_v1.json",
+    "twilio_trusthub_v1.json",
+    "twilio_verify_v2.json",
+    "twilio_video_v1.json",
+    "twilio_voice_v1.json",
+    "twilio_voice_v2.json",
+    "twilio_voice_v3.json",
+    "twilio_wireless_v1.json",
+];
+export const VENDOR_SPEC_SOURCES = [
+    {
+        vendor: "stripe",
+        urls: ["https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"],
+        format: "json",
+    },
+    {
+        vendor: "openai",
+        urls: ["https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml"],
+        format: "yaml",
+    },
+    {
+        vendor: "github",
+        urls: [
+            "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
+        ],
+        format: "json",
+    },
+    {
+        // All ~60 of Twilio's real per-product spec files, not just the core one.
+        vendor: "twilio",
+        urls: TWILIO_SPEC_FILES.map((file) => `${TWILIO_BASE}/${file}`),
+        format: "json",
+    },
+    {
+        vendor: "shopify",
+        urls: [`https://shopify.dev/admin-graphql-direct-proxy/${SHOPIFY_API_VERSION}`],
+        format: "graphql",
+    },
+];

package/node_modules/@compatra/core/dist/vendor-registry.d.ts

@@ -0,0 +1,12 @@
+export interface VendorMatch {
+    vendor: string;
+    packageName: string;
+    versionRange: string;
+}
+interface PackageJsonDependencies {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+export declare function moduleMatchesVendor(moduleSpecifier: string, vendor: string): boolean;
+export declare function detectVendorDependencies(packageJson: PackageJsonDependencies): VendorMatch[];
+export {};

package/node_modules/@compatra/core/dist/vendor-registry.js

@@ -0,0 +1,36 @@
+const VENDOR_PATTERNS = [
+    { vendor: "stripe", test: (name) => name === "stripe" },
+    { vendor: "openai", test: (name) => name === "openai" },
+    { vendor: "twilio", test: (name) => name === "twilio" },
+    {
+        vendor: "shopify",
+        test: (name) => name.startsWith("@shopify/") || name === "shopify-api-node",
+    },
+    { vendor: "github", test: (name) => name.startsWith("@octokit/") },
+];
+// package.json dependency keys are never subpaths, but an import/require specifier can
+// be (e.g. "stripe/esm", "@octokit/rest/dist/foo") — check both the full specifier and
+// its first path segment so vendor patterns written for plain package names still match.
+export function moduleMatchesVendor(moduleSpecifier, vendor) {
+    const pattern = VENDOR_PATTERNS.find((p) => p.vendor === vendor);
+    if (!pattern)
+        return false;
+    const firstSegment = moduleSpecifier.startsWith("@")
+        ? moduleSpecifier.split("/").slice(0, 2).join("/")
+        : moduleSpecifier.split("/")[0];
+    return pattern.test(moduleSpecifier) || pattern.test(firstSegment);
+}
+export function detectVendorDependencies(packageJson) {
+    const allDependencies = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+    };
+    const matches = [];
+    for (const [packageName, versionRange] of Object.entries(allDependencies)) {
+        const pattern = VENDOR_PATTERNS.find((p) => p.test(packageName));
+        if (pattern) {
+            matches.push({ vendor: pattern.vendor, packageName, versionRange });
+        }
+    }
+    return matches;
+}

package/node_modules/@compatra/core/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@compatra/core",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./ast": "./dist/extract-usages.js",
+    "./migrate": "./dist/apply-migration.js"
+  },
+  "dependencies": {
+    "ts-morph": "^28.0.0",
+    "yaml": "^2.9.1"
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "compatra",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Find third-party API calls in your code that use endpoints the vendor has already deprecated, migrate the ones with a safe replacement, and check whether your tests would notice.",
+  "keywords": [
+    "api",
+    "deprecation",
+    "stripe",
+    "openai",
+    "twilio",
+    "github",
+    "migration",
+    "ci"
+  ],
+  "homepage": "https://github.com/apps/compatra",
+  "license": "MIT",
+  "bin": {
+    "compatra": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "prebuild": "cd ../core && npm run build",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build && node scripts/vendor-core.mjs add",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "scan": "node dist/index.js",
+    "postpack": "node scripts/vendor-core.mjs remove"
+  },
+  "dependencies": {
+    "@compatra/core": "0.1.0",
+    "ts-morph": "^28.0.0",
+    "yaml": "^2.9.1"
+  },
+  "bundleDependencies": [
+    "@compatra/core"
+  ]
+}