compatra 0.1.0 → 0.1.1

package/README.md

@@ -11,7 +11,8 @@ npx compatra scan
 
 ## What it does
 
-1. Reads `package.json` for supported vendor SDKs (Stripe, OpenAI, GitHub/Octokit, Twilio, Shopify).
+1. Reads `package.json` for supported vendor SDKs (Stripe, OpenAI, Twilio, Shopify, and GitHub via
+   `octokit`, `@octokit/*`, `@actions/github` or `probot`).
 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.
@@ -143,6 +144,18 @@ proof**. It is deliberately strict: `stripe.customers.listCards` is reported aga
 `/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.
 
+**GitHub calls** are followed through the ways code actually gets a client: `new Octokit()`,
+`Octokit.plugin(...)`, `github.getOctokit(token)` (`@actions/github`) and probot's `context.octokit`.
+A call is matched to a deprecated operation exactly, by its Octokit method name (Octokit generates
+those from the spec's operation IDs; `teams.getLegacy` is `teams/get-legacy`) or, for
+`octokit.request("GET /teams/{team_id}")`, by its route string. Checked against GitHub's own spec:
+every deprecated operation is flagged and none of the ~2,400 non-deprecated ones are
+(`core/scripts/check-github-matching.mjs` repeats that check), and against the real method names
+of three Octokit versions. Two honest limits: current Octokit no longer generates methods for most
+deprecated endpoints, so today these calls mostly show up as route strings or in older Octokit
+versions; and a client that reaches a function only through its parameters is not followed unless it
+is probot's `.octokit`.
+
 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.

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { fixProject } from "./fix.js";
@@ -35,6 +36,12 @@ verify options
 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.
 `;
+// The version lives in package.json only, so `-v` cannot drift from what was published. From
+// dist/ (installed or built) and from src/ (tests) the manifest is one directory up.
+function packageVersion() {
+    const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return manifest.version;
+}
 function parseEndpointFlag(value) {
     const [vendor, ...rest] = value.trim().split(/\s+/);
     if (!vendor || rest.length < 2) {
@@ -63,7 +70,7 @@ async function main(argv) {
     if (values.help)
         return void process.stdout.write(HELP);
     if (values.version)
-        return void console.log("0.1.0");
+        return void console.log(packageVersion());
     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]) ?? ".");

package/dist/scan.js

@@ -1,7 +1,7 @@
 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";
+import { RESOURCE_MATCHING_SUPPORTED, VENDOR_SPEC_SOURCES, clientHintsFor, 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) {
@@ -33,12 +33,12 @@ export async function listSourceFiles(root) {
     found.sort();
     return { files: found.slice(0, MAX_FILES), truncated: found.length > MAX_FILES };
 }
-async function loadDeprecatedPaths(vendor) {
+async function loadDeprecated(vendor) {
     const source = VENDOR_SPEC_SOURCES.find((s) => s.vendor === vendor);
     if (!source)
-        return [];
+        return { paths: [] };
     const spec = source.format === "graphql" ? await fetchShopifySchema(source) : await fetchVendorSpec(source);
-    return spec.deprecatedPaths;
+    return { paths: spec.deprecatedPaths, operationIds: spec.deprecatedOperationIds };
 }
 /**
  * Read a project the way the hosted scanner reads a repository: find vendor SDKs in
@@ -59,7 +59,7 @@ export async function scanProject(root) {
             continue;
         }
         for (const vendor of new Set(dependencies.map((d) => d.vendor))) {
-            for (const usage of extractVendorUsages(rel, source, (m) => moduleMatchesVendor(m, vendor))) {
+            for (const usage of extractVendorUsages(rel, source, (m) => moduleMatchesVendor(m, vendor), clientHintsFor(vendor))) {
                 callSites.push({ ...usage, vendor });
             }
         }
@@ -76,16 +76,16 @@ export async function scanProject(root) {
     for (const vendor of vendorsToCheck) {
         let deprecated;
         try {
-            deprecated = await loadDeprecatedPaths(vendor);
+            deprecated = await loadDeprecated(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 });
+        checked.push({ vendor, deprecatedEndpoints: deprecated.paths.length });
         for (const site of checkable.filter((c) => c.vendor === vendor)) {
-            for (const endpoint of matchDeprecatedEndpoints(vendor, site.snippet, deprecated)) {
+            for (const endpoint of matchDeprecatedEndpoints(vendor, site.snippet, deprecated.paths, deprecated.operationIds)) {
                 hits.push({ ...site, endpoint });
             }
         }

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

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

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

@@ -15,6 +15,40 @@ function tokenize(text) {
         .filter(Boolean)
         .map((t) => singular(t.toLowerCase()));
 }
+// `octokit.request("GET /teams/{team_id}")` -> "GET /teams/{team_id}" (as the extractor writes it).
+function routeFromSnippet(snippet) {
+    const match = /\(("[A-Z]+ \/[^"]*")\)$/.exec(snippet);
+    if (!match)
+        return null;
+    try {
+        return JSON.parse(match[1]);
+    }
+    catch {
+        return null;
+    }
+}
+// "code-scanning" / "codeScanning" / "get-legacy" / "getLegacy" all -> the same form. Separators
+// are dropped rather than converted because camelCase cannot tell `getAClassroom` from
+// `get-a-classroom`: the single letter "A" merges with the next word.
+const snake = (s) => s.toLowerCase().replace(/[-_]/g, "");
+/**
+ * `octokit.rest.teams.getLegacy` <-> the operationId `teams/get-legacy`. The client variable and
+ * octokit's literal `.rest` are dropped, and the next two segments are the scope and the method.
+ * A chain shorter than that (a bare client, `octokit.paginate`) matches nothing.
+ */
+function matchGithubByOperationId(snippet, deprecatedPaths, operationIds) {
+    const [scope, method] = snippet.split(".").slice(1).filter((part) => part !== "rest");
+    if (!scope || !method)
+        return [];
+    const wanted = `${snake(scope)}/${snake(method)}`;
+    return deprecatedPaths.filter((endpoint) => {
+        const id = operationIds[endpoint];
+        if (!id)
+            return false;
+        const [idScope, ...idRest] = id.split("/");
+        return `${snake(idScope)}/${snake(idRest.join("/"))}` === wanted;
+    });
+}
 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("}");
@@ -50,9 +84,17 @@ function verbsFor(method, endsWithParam) {
     }
 }
 /** The deprecated endpoints (from `deprecatedPaths`, "METHOD /path") this call plausibly uses. */
-export function matchDeprecatedEndpoints(vendor, snippet, deprecatedPaths) {
+export function matchDeprecatedEndpoints(vendor, snippet, deprecatedPaths, operationIds) {
     if (!RESOURCE_MATCHING_SUPPORTED.has(vendor))
         return [];
+    // A route-string call names its endpoint outright, so compare it exactly, with or without operation IDs.
+    const route = vendor === "github" ? routeFromSnippet(snippet) : null;
+    if (route)
+        return deprecatedPaths.filter((endpoint) => endpoint === route);
+    // Octokit builds its method names from the spec's operation IDs, so with those in hand the
+    // match is exact rather than a guess from words in the path.
+    if (vendor === "github" && operationIds)
+        return matchGithubByOperationId(snippet, deprecatedPaths, operationIds);
     const resource = extractResourceFromUsage(vendor, snippet);
     if (!resource)
         return [];

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

@@ -1,3 +1,4 @@
+import type { ClientHints } from "./vendor-registry.js";
 export interface CodeUsage {
     filePath: string;
     line: number;
@@ -10,5 +11,9 @@ 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").
+ *
+ * `hints` describes vendors whose client is not always made with `new Import()`: it names
+ * factory calls that return a client (`getOctokit(token)`) and properties that hold one
+ * (probot's `context.octokit`). Without hints only the import and `new` are followed.
  */
-export declare function extractVendorUsages(filePath: string, sourceCode: string, matchesModule: (moduleSpecifier: string) => boolean): CodeUsage[];
+export declare function extractVendorUsages(filePath: string, sourceCode: string, matchesModule: (moduleSpecifier: string) => boolean, hints?: ClientHints): CodeUsage[];

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

@@ -9,12 +9,41 @@ const DECLARATION_SITE_KINDS = new Set([
     SyntaxKind.VariableDeclaration,
     SyntaxKind.BindingElement,
 ]);
+// `await x()`, `(x())`, `x() as T`, `x()!` all still evaluate to whatever x() returns.
+const TRANSPARENT_WRAPPERS = new Set([
+    SyntaxKind.AwaitExpression,
+    SyntaxKind.ParenthesizedExpression,
+    SyntaxKind.AsExpression,
+    SyntaxKind.NonNullExpression,
+    SyntaxKind.TypeAssertionExpression,
+    SyntaxKind.SatisfiesExpression,
+]);
+function unwrap(node) {
+    let current = node;
+    while (TRANSPARENT_WRAPPERS.has(current.getKind())) {
+        const inner = current.getExpression();
+        current = inner;
+    }
+    return current;
+}
+/** The leftmost identifier of `a.b.c(...)`, i.e. `a`, or null when the chain starts with something else. */
+function rootIdentifierText(node) {
+    let current = node;
+    while (current.getKind() === SyntaxKind.PropertyAccessExpression) {
+        current = current.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getExpression();
+    }
+    return current.getKind() === SyntaxKind.Identifier ? current.getText() : null;
+}
 /**
  * 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").
+ *
+ * `hints` describes vendors whose client is not always made with `new Import()`: it names
+ * factory calls that return a client (`getOctokit(token)`) and properties that hold one
+ * (probot's `context.octokit`). Without hints only the import and `new` are followed.
  */
-export function extractVendorUsages(filePath, sourceCode, matchesModule) {
+export function extractVendorUsages(filePath, sourceCode, matchesModule, hints) {
     const project = new Project({ useInMemoryFileSystem: true });
     let sourceFile;
     try {
@@ -58,36 +87,86 @@ export function extractVendorUsages(filePath, sourceCode, matchesModule) {
             }
         }
     }
-    // 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());
+    // Propagate: `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. With hints, a factory call does the same
+    // (`const octokit = github.getOctokit(token)`, `const MyOctokit = Octokit.plugin(retry)`).
+    // Repeat until nothing new is found, so the order the declarations appear in does not matter
+    // (`new MyOctokit()` may come before the line that defines MyOctokit's own plugin chain).
+    const factories = new Set(hints?.factories ?? []);
+    const variableDeclarations = sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const varDecl of variableDeclarations) {
+            const nameNode = varDecl.getNameNode();
+            if (nameNode.getKind() !== SyntaxKind.Identifier || localIdentifiers.has(nameNode.getText()))
+                continue;
+            const initializer = varDecl.getInitializer();
+            if (!initializer)
+                continue;
+            const value = unwrap(initializer);
+            let derivesFromVendor = false;
+            if (value.getKind() === SyntaxKind.NewExpression) {
+                derivesFromVendor = localIdentifiers.has(value.asKindOrThrow(SyntaxKind.NewExpression).getExpression().getText());
+            }
+            else if (factories.size > 0 && value.getKind() === SyntaxKind.CallExpression) {
+                const callee = value.asKindOrThrow(SyntaxKind.CallExpression).getExpression();
+                if (callee.getKind() === SyntaxKind.Identifier) {
+                    // A bare `getOctokit(token)` only counts when getOctokit was imported from the vendor.
+                    derivesFromVendor = factories.has(callee.getText()) && localIdentifiers.has(callee.getText());
+                }
+                else if (callee.getKind() === SyntaxKind.PropertyAccessExpression) {
+                    const access = callee.asKindOrThrow(SyntaxKind.PropertyAccessExpression);
+                    const root = rootIdentifierText(access);
+                    derivesFromVendor = factories.has(access.getName()) && root !== null && localIdentifiers.has(root);
+                }
+            }
+            if (derivesFromVendor) {
+                localIdentifiers.add(nameNode.getText());
+                grew = true;
+            }
         }
     }
     if (localIdentifiers.size === 0)
         return [];
+    const accessors = new Set(hints?.accessors ?? []);
     const usages = [];
     const seen = new Set();
     for (const identifier of sourceFile.getDescendantsOfKind(SyntaxKind.Identifier)) {
-        if (!localIdentifiers.has(identifier.getText()))
-            continue;
+        const text = identifier.getText();
         const parent = identifier.getParent();
-        if (parent && DECLARATION_SITE_KINDS.has(parent.getKind()))
+        // `context.octokit.issues.create(...)`: the client is a property, so the chain starts at
+        // the property itself (`octokit.issues.create`), the same shape a variable would give.
+        const isPropertyName = parent?.getKind() === SyntaxKind.PropertyAccessExpression &&
+            parent.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getNameNode() === identifier;
+        const isAccessor = accessors.has(text) && isPropertyName;
+        if (!isAccessor && !localIdentifiers.has(text))
+            continue;
+        if (!isAccessor && parent && DECLARATION_SITE_KINDS.has(parent.getKind()))
             continue;
+        let chain = text;
         let node = parent;
-        let chain = identifier.getText();
-        while (node?.getKind() === SyntaxKind.PropertyAccessExpression) {
-            chain = node.getText();
-            node = node.getParent();
+        if (isAccessor) {
+            // Skip the `context.octokit` access itself; only what follows it belongs to the chain.
+            node = parent.getParent();
+            let previous = parent;
+            while (node?.getKind() === SyntaxKind.PropertyAccessExpression) {
+                const access = node.asKindOrThrow(SyntaxKind.PropertyAccessExpression);
+                if (access.getExpression() !== previous)
+                    break;
+                chain += `.${access.getName()}`;
+                previous = node;
+                node = node.getParent();
+            }
+        }
+        else {
+            while (node?.getKind() === SyntaxKind.PropertyAccessExpression) {
+                // A chain formatted across lines (`octokit.rest.issues\n    .listComments`) is still one
+                // chain: drop the line breaks and indentation so it matches like any other.
+                chain = node.getText().replace(/\s+/g, "");
+                node = node.getParent();
+            }
         }
         const line = identifier.getStartLineNumber();
         const key = `${line}:${chain}`;
@@ -96,5 +175,59 @@ export function extractVendorUsages(filePath, sourceCode, matchesModule) {
         seen.add(key);
         usages.push({ filePath, line, snippet: chain });
     }
+    // `octokit.request("GET /teams/{team_id}")`: the modern way to reach an endpoint the SDK no
+    // longer wraps in a named method. The route is right there in the call, so record it in the
+    // snippet and let the matcher compare it exactly.
+    const routeCalls = new Set(hints?.routeCalls ?? []);
+    if (routeCalls.size > 0) {
+        for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            const callee = call.getExpression();
+            if (callee.getKind() !== SyntaxKind.PropertyAccessExpression)
+                continue;
+            const access = callee.asKindOrThrow(SyntaxKind.PropertyAccessExpression);
+            if (!routeCalls.has(access.getName()))
+                continue;
+            // Only calls on a client we can tell is one: rooted at a traced name, or through `.octokit`.
+            const calleeText = access.getText();
+            const accessorAt = [...accessors].map((a) => calleeText.indexOf(`${a}.`)).filter((i) => i >= 0)[0];
+            const root = rootIdentifierText(access);
+            if (accessorAt === undefined && !(root !== null && localIdentifiers.has(root)))
+                continue;
+            const route = routeFromArgument(call.getArguments()[0]);
+            if (!route)
+                continue;
+            const chain = accessorAt !== undefined ? calleeText.slice(accessorAt) : calleeText;
+            const line = call.getStartLineNumber();
+            const snippet = `${chain}(${JSON.stringify(route)})`;
+            const key = `${line}:${snippet}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            usages.push({ filePath, line, snippet });
+        }
+    }
     return usages;
 }
+const ROUTE = /^([A-Za-z]+)\s+(\/\S*)$/;
+/** "GET /teams/{team_id}" from a string literal, or from `{ method: "GET", url: "/teams/{team_id}" }`. */
+function routeFromArgument(arg) {
+    if (!arg)
+        return null;
+    const literal = (node) => node && (node.getKind() === SyntaxKind.StringLiteral || node.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral)
+        ? node.getText().slice(1, -1)
+        : null;
+    const direct = literal(arg);
+    if (direct !== null) {
+        const match = ROUTE.exec(direct.trim());
+        return match ? `${match[1].toUpperCase()} ${match[2]}` : null;
+    }
+    if (arg.getKind() === SyntaxKind.ObjectLiteralExpression) {
+        const object = arg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+        const property = (name) => object.getProperty(name)?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer();
+        const method = literal(property("method"));
+        const url = literal(property("url"));
+        if (method && url && url.startsWith("/"))
+            return `${method.toUpperCase()} ${url}`;
+    }
+    return null;
+}

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

@@ -8,6 +8,12 @@ export interface NormalizedSchema {
 export interface FetchedSpec {
     paths: string[];
     deprecatedPaths: string[];
+    /**
+     * "METHOD /path" -> the spec's operationId, for the deprecated operations that have one. SDKs
+     * that generate their method names from operation IDs (Octokit) can be matched to an operation
+     * exactly with it. Optional: snapshots stored before this existed do not carry it.
+     */
+    deprecatedOperationIds?: Record<string, string>;
     schemas: Record<string, NormalizedSchema>;
     requestSchemas: Record<string, NormalizedSchema>;
     hash: string;

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

@@ -81,14 +81,18 @@ async function fetchAndParseOne(url, vendor, format) {
     const spec = (format === "yaml" ? parseYaml(raw) : JSON.parse(raw));
     const paths = [];
     const deprecatedPaths = [];
+    const deprecatedOperationIds = {};
     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)
+            if (operation.deprecated) {
                 deprecatedPaths.push(key);
+                if (operation.operationId)
+                    deprecatedOperationIds[key] = operation.operationId;
+            }
         }
     }
     // Only property presence + required-ness + deprecated-ness, not full type info —
@@ -104,7 +108,7 @@ async function fetchAndParseOne(url, vendor, format) {
         schemas[name] = directPropsRequired(schema);
     }
     const requestSchemas = extractRequestSchemas(spec.paths ?? {}, spec.components?.schemas ?? {});
-    return { raw, paths, deprecatedPaths, schemas, requestSchemas };
+    return { raw, paths, deprecatedPaths, deprecatedOperationIds, schemas, requestSchemas };
 }
 export async function fetchVendorSpec(source) {
     // Most vendors have exactly one spec file; Twilio has ~60 per-product files that
@@ -121,9 +125,11 @@ export async function fetchVendorSpec(source) {
     // specially reconciled beyond that.
     const schemas = {};
     const requestSchemas = {};
+    const deprecatedOperationIds = {};
     for (const file of files) {
         Object.assign(schemas, file.schemas);
         Object.assign(requestSchemas, file.requestSchemas);
+        Object.assign(deprecatedOperationIds, file.deprecatedOperationIds);
     }
-    return { paths, deprecatedPaths, schemas, requestSchemas, hash };
+    return { paths, deprecatedPaths, deprecatedOperationIds, schemas, requestSchemas, hash };
 }

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

@@ -3,6 +3,20 @@ export interface VendorMatch {
     packageName: string;
     versionRange: string;
 }
+/**
+ * How a vendor's client is reached when a plain `const c = new Import()` trace cannot see it.
+ * Used by the AST extractor; kept beside the package patterns so one place says what "GitHub
+ * code" looks like.
+ */
+export interface ClientHints {
+    /** Property names that hold a ready-made client, e.g. probot's `context.octokit`. */
+    accessors: string[];
+    /** Function or method names that return a client or a client class, e.g. `getOctokit(token)`. */
+    factories: string[];
+    /** Client methods called with a "METHOD /path" route string, e.g. `octokit.request("GET /teams/{id}")`. */
+    routeCalls: string[];
+}
+export declare function clientHintsFor(vendor: string): ClientHints | undefined;
 interface PackageJsonDependencies {
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;

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

@@ -6,8 +6,21 @@ const VENDOR_PATTERNS = [
         vendor: "shopify",
         test: (name) => name.startsWith("@shopify/") || name === "shopify-api-node",
     },
-    { vendor: "github", test: (name) => name.startsWith("@octokit/") },
+    {
+        vendor: "github",
+        // `octokit` is the umbrella package, `@actions/github` is what Actions authors use, and
+        // `probot` is what GitHub Apps are built on; all three hand out an Octokit client.
+        test: (name) => name.startsWith("@octokit/") || name === "octokit" || name === "@actions/github" || name === "probot",
+    },
 ];
+const CLIENT_HINTS = {
+    // getOctokit: @actions/github. plugin/defaults: `Octokit.plugin(...)` and `Octokit.defaults(...)`
+    // return a subclass that is then constructed. octokit: probot's `context.octokit` / `app.octokit`.
+    github: { accessors: ["octokit"], factories: ["getOctokit", "plugin", "defaults"], routeCalls: ["request", "paginate", "iterator"] },
+};
+export function clientHintsFor(vendor) {
+    return CLIENT_HINTS[vendor];
+}
 // 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.

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

@@ -1,6 +1,6 @@
 {
   "name": "@compatra/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compatra",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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": [
@@ -38,7 +38,7 @@
     "postpack": "node scripts/vendor-core.mjs remove"
   },
   "dependencies": {
-    "@compatra/core": "0.1.0",
+    "@compatra/core": "0.1.1",
     "ts-morph": "^28.0.0",
     "yaml": "^2.9.1"
   },