@opencodehub/mcp 0.1.0

package/dist/tools/route-map.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `route_map` — enumerate HTTP `Route` nodes with handlers + consumers.
+ *
+ * One row per Route, filtered by optional repo / route URL substring /
+ * method. For every row we also pull:
+ *   - handlers  = ids of nodes pointing at the route via HANDLES_ROUTE
+ *                 (typically Files for framework routes, Operations for
+ *                 OpenAPI specs).
+ *   - consumers = ids of nodes pointing at the route via FETCHES (the
+ *                 `from_id` side — the symbol doing the outbound call).
+ *   - responseKeys = the TEXT[] response-shape keys populated by the
+ *                    `routes` phase when static detection identified the
+ *                    response body.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext, type ToolResult } from "./shared.js";
+interface RouteMapArgs {
+    readonly repo?: string | undefined;
+    readonly repo_uri?: string | undefined;
+    readonly route?: string | undefined;
+    readonly method?: string | undefined;
+    readonly framework?: string | undefined;
+}
+export declare function runRouteMap(ctx: ToolContext, args: RouteMapArgs): Promise<ToolResult>;
+export declare function registerRouteMapTool(server: McpServer, ctx: ToolContext): void;
+export {};
+//# sourceMappingURL=route-map.d.ts.map

package/dist/tools/route-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-map.d.ts","sourceRoot":"","sources":["../../src/tools/route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAsBrB,UAAU,YAAY;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAkF3F;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAiB9E"}

package/dist/tools/route-map.js

@@ -0,0 +1,119 @@
+/**
+ * `route_map` — enumerate HTTP `Route` nodes with handlers + consumers.
+ *
+ * One row per Route, filtered by optional repo / route URL substring /
+ * method. For every row we also pull:
+ *   - handlers  = ids of nodes pointing at the route via HANDLES_ROUTE
+ *                 (typically Files for framework routes, Operations for
+ *                 OpenAPI specs).
+ *   - consumers = ids of nodes pointing at the route via FETCHES (the
+ *                 `from_id` side — the symbol doing the outbound call).
+ *   - responseKeys = the TEXT[] response-shape keys populated by the
+ *                    `routes` phase when static detection identified the
+ *                    response body.
+ */
+// biome-ignore-all lint/complexity/useLiteralKeys: dot-access disallowed on Record index signatures
+import { z } from "zod";
+import { toolErrorFromUnknown } from "../error-envelope.js";
+import { withNextSteps } from "../next-step-hints.js";
+import { stalenessFromMeta } from "../staleness.js";
+import { fromToolResult, repoArgShape, toToolResult, withStore, } from "./shared.js";
+const RouteMapInput = {
+    ...repoArgShape,
+    route: z.string().optional().describe("Substring match against Route.url (e.g. '/api/users')."),
+    method: z.string().optional().describe("Exact match against Route.method (e.g. 'GET')."),
+    framework: z
+        .string()
+        .optional()
+        .describe("Reserved for a future framework filter; currently ignored."),
+};
+export async function runRouteMap(ctx, args) {
+    const call = await withStore(ctx, args, async (store, resolved) => {
+        try {
+            const graph = store.graph;
+            const opts = { limit: 500 };
+            if (args.route !== undefined && args.route.length > 0)
+                opts.pathLike = args.route;
+            if (args.method !== undefined &&
+                ["GET", "POST", "PUT", "DELETE", "PATCH"].includes(args.method)) {
+                opts.methods = [args.method];
+            }
+            let listed = await graph.listRoutes(opts);
+            if (args.method !== undefined &&
+                !["GET", "POST", "PUT", "DELETE", "PATCH"].includes(args.method)) {
+                listed = listed.filter((r) => r.method === args.method);
+            }
+            const sortedRoutes = [...listed].sort((a, b) => {
+                if (a.url !== b.url)
+                    return a.url < b.url ? -1 : 1;
+                const am = a.method ?? "";
+                const bm = b.method ?? "";
+                return am < bm ? -1 : am > bm ? 1 : 0;
+            });
+            const routes = [];
+            for (const r of sortedRoutes) {
+                const [handlers, consumers] = await Promise.all([
+                    fetchRelationFromIds(graph, r.id, "HANDLES_ROUTE"),
+                    fetchRelationFromIds(graph, r.id, "FETCHES"),
+                ]);
+                routes.push({
+                    id: r.id,
+                    url: stringOr(r.url, ""),
+                    method: stringOr(r.method, ""),
+                    filePath: stringOr(r.filePath, ""),
+                    responseKeys: r.responseKeys ?? [],
+                    handlers,
+                    consumers,
+                });
+            }
+            const header = `Routes (${routes.length}) for ${resolved.name}${args.route ? ` · url~${args.route}` : ""}${args.method ? ` · method=${args.method}` : ""}:`;
+            const body = routes.length === 0
+                ? "(no routes matched — verify the `routes` phase ran on a supported framework)"
+                : routes
+                    .map((r) => `- ${r.method} ${r.url}  handlers=${r.handlers.length} consumers=${r.consumers.length} keys=${r.responseKeys.length}`)
+                    .join("\n");
+            const next = routes.length === 0
+                ? [
+                    "call `list_repos` to confirm the repo is indexed",
+                    "re-index with `codehub analyze` to emit Route nodes",
+                ]
+                : [
+                    `call \`api_impact\` with route="${routes[0]?.url ?? ""}" to score blast radius`,
+                    `call \`shape_check\` with route="${routes[0]?.url ?? ""}" to compare responseKeys vs consumer ACCESSES`,
+                ];
+            return withNextSteps(`${header}\n${body}`, { routes, total: routes.length }, next, stalenessFromMeta(resolved.meta));
+        }
+        catch (err) {
+            return toolErrorFromUnknown(err);
+        }
+    });
+    return toToolResult(call);
+}
+export function registerRouteMapTool(server, ctx) {
+    server.registerTool("route_map", {
+        title: "Map HTTP routes to handlers and consumers",
+        description: "Enumerate Route nodes filtered by url substring and/or method. For each route returns the static responseKeys (when detected), the HANDLES_ROUTE handlers (Files or Operations pointing at the route), and the FETCHES consumers (caller symbols). Read-only.",
+        inputSchema: RouteMapInput,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => fromToolResult(await runRouteMap(ctx, args)));
+}
+async function fetchRelationFromIds(graph, routeId, type) {
+    const edges = await graph.listEdgesByType(type, { toIds: [routeId] });
+    return edges
+        .map((e) => e.from)
+        .filter((s) => s.length > 0)
+        .sort();
+}
+function stringOr(v, fallback) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    return fallback;
+}
+//# sourceMappingURL=route-map.js.map

package/dist/tools/route-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-map.js","sourceRoot":"","sources":["../../src/tools/route-map.ts"],"names":[],"mappings":"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"}

package/dist/tools/scan.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `scan` — run Priority-1 scanners against a repo and return merged SARIF.
+ *
+ * Unlike every other OpenCodeHub tool, `scan` has filesystem effects:
+ * it spawns external scanner binaries and writes `.codehub/scan.sarif`
+ * on disk. Annotations reflect that:
+ *
+ *   readOnlyHint    = false   — we write SARIF to disk
+ *   destructiveHint = false   — we never delete anything
+ *   openWorldHint   = true    — we spawn untrusted subprocesses
+ *   idempotentHint  = false   — two scans can differ (tool output drift)
+ *
+ * The tool returns the merged SARIF plus a summary by tool + severity so
+ * agents can reason about results without fetching the whole log.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext, type ToolResult } from "./shared.js";
+interface ScanArgs {
+    readonly repo?: string | undefined;
+    readonly repo_uri?: string | undefined;
+    readonly scanners?: readonly string[] | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+export declare function runScan(ctx: ToolContext, args: ScanArgs): Promise<ToolResult>;
+export declare function registerScanTool(server: McpServer, ctx: ToolContext): void;
+export {};
+//# sourceMappingURL=scan.d.ts.map

package/dist/tools/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/tools/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAezE,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAyBrB,UAAU,QAAQ;IAChB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAsDnF;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAiB1E"}

package/dist/tools/scan.js

@@ -0,0 +1,136 @@
+/**
+ * `scan` — run Priority-1 scanners against a repo and return merged SARIF.
+ *
+ * Unlike every other OpenCodeHub tool, `scan` has filesystem effects:
+ * it spawns external scanner binaries and writes `.codehub/scan.sarif`
+ * on disk. Annotations reflect that:
+ *
+ *   readOnlyHint    = false   — we write SARIF to disk
+ *   destructiveHint = false   — we never delete anything
+ *   openWorldHint   = true    — we spawn untrusted subprocesses
+ *   idempotentHint  = false   — two scans can differ (tool output drift)
+ *
+ * The tool returns the merged SARIF plus a summary by tool + severity so
+ * agents can reason about results without fetching the whole log.
+ */
+// biome-ignore-all lint/complexity/useLiteralKeys: dot-access disallowed on Record index signatures
+import { mkdir, writeFile } from "node:fs/promises";
+import { ALL_SPECS, createDefaultWrappers, filterSpecsByProfile, runScanners, } from "@opencodehub/scanners";
+import { resolveRepoMetaDir } from "@opencodehub/storage";
+import { z } from "zod";
+import { toolErrorFromUnknown } from "../error-envelope.js";
+import { withNextSteps } from "../next-step-hints.js";
+import { stalenessFromMeta } from "../staleness.js";
+import { fromToolResult, repoArgShape, toToolResult, withStore, } from "./shared.js";
+const ScanInput = {
+    ...repoArgShape,
+    scanners: z
+        .array(z.string())
+        .optional()
+        .describe("Explicit scanner ids. When omitted, scanners are gated by the ProjectProfile languages."),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(600_000)
+        .optional()
+        .describe("Per-scanner wall-clock timeout in ms (default 300000)."),
+};
+export async function runScan(ctx, args) {
+    const call = await withStore(ctx, args, async (store, resolved) => {
+        try {
+            const specs = await selectScanners(store.graph, args.scanners);
+            if (specs.length === 0) {
+                return withNextSteps(`No scanners selected for ${resolved.name}.`, { sarif: { version: "2.1.0", runs: [] }, summary: emptySummary() }, [
+                    "pass explicit scanners=['semgrep'] to override profile gating",
+                    "run `codehub analyze --force` to refresh the ProjectProfile",
+                ], stalenessFromMeta(resolved.meta));
+            }
+            const wrappers = createDefaultWrappers(specs);
+            const runnerOpts = args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {};
+            const result = await runScanners(resolved.repoPath, wrappers, runnerOpts);
+            // Persist merged SARIF to `.codehub/scan.sarif` for later ingestion.
+            await mkdir(resolveRepoMetaDir(resolved.repoPath), { recursive: true });
+            const sarifPath = `${resolveRepoMetaDir(resolved.repoPath)}/scan.sarif`;
+            await writeFile(sarifPath, `${JSON.stringify(result.sarif, null, 2)}\n`, "utf8");
+            const summary = summarize(result.sarif);
+            const errored = result.errored.map((e) => `${e.spec.id}: ${e.error}`);
+            const header = `scan — ${summary.total} findings across ${Object.keys(summary.byTool).length} scanner(s); wrote ${sarifPath}`;
+            const lines = [header];
+            for (const [tool, count] of Object.entries(summary.byTool).sort()) {
+                lines.push(`  ${tool}: ${count}`);
+            }
+            if (errored.length > 0) {
+                lines.push("Errored scanners:");
+                for (const e of errored)
+                    lines.push(`  - ${e}`);
+            }
+            const next = [
+                "call `list_findings` to browse the ingested findings",
+                "call `codehub ingest-sarif` to re-ingest if you edit the SARIF",
+            ];
+            return withNextSteps(lines.join("\n"), { sarif: result.sarif, summary, errored, outputPath: sarifPath }, next, stalenessFromMeta(resolved.meta));
+        }
+        catch (err) {
+            return toolErrorFromUnknown(err);
+        }
+    });
+    return toToolResult(call);
+}
+export function registerScanTool(server, ctx) {
+    server.registerTool("scan", {
+        title: "Run Priority-1 scanners",
+        description: "Spawn Semgrep + Betterleaks + OSV-Scanner (+ Bandit/Biome when the project profile supports them), merge their SARIF outputs, write `.codehub/scan.sarif`, and return a summary. Selected scanners default to the polyglot set filtered by ProjectProfile.languages. IMPORTANT: this tool has filesystem effects and spawns external processes.",
+        inputSchema: ScanInput,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+            idempotentHint: false,
+        },
+    }, async (args) => fromToolResult(await runScan(ctx, args)));
+}
+async function selectScanners(graph, explicit) {
+    if (explicit !== undefined && explicit.length > 0) {
+        const wanted = new Set(explicit);
+        return ALL_SPECS.filter((s) => wanted.has(s.id));
+    }
+    const profile = await readProfile(graph);
+    return filterSpecsByProfile(ALL_SPECS, profile);
+}
+async function readProfile(graph) {
+    try {
+        const nodes = await graph.listNodesByKind("ProjectProfile", { limit: 1 });
+        const first = nodes[0];
+        if (!first)
+            return {};
+        return {
+            languages: first.languages ?? [],
+            iacTypes: first.iacTypes ?? [],
+            apiContracts: first.apiContracts ?? [],
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function summarize(sarif) {
+    const byTool = {};
+    const bySeverity = {};
+    let total = 0;
+    for (const run of sarif.runs) {
+        const tool = run.tool.driver.name;
+        const count = run.results?.length ?? 0;
+        byTool[tool] = (byTool[tool] ?? 0) + count;
+        total += count;
+        for (const result of run.results ?? []) {
+            const level = result.level ?? "note";
+            bySeverity[level] = (bySeverity[level] ?? 0) + 1;
+        }
+    }
+    return { total, byTool, bySeverity };
+}
+function emptySummary() {
+    return { total: 0, byTool: {}, bySeverity: {} };
+}
+//# sourceMappingURL=scan.js.map

package/dist/tools/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../src/tools/scan.ts"],"names":[],"mappings":"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"}

package/dist/tools/shape-check.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `shape_check` — compare a Route's static responseKeys against the
+ * property names each consumer file actually reads off the response.
+ *
+ * For every Route matching `route` (URL substring) we:
+ *   1. Find FETCHES edges pointing AT the route. Each `from_id` is a
+ *      symbol (Function / Method / Constructor) that issued the call.
+ *   2. Group those consumer symbols by file.
+ *   3. Walk outgoing ACCESSES from every symbol in each consumer file to
+ *      its Property target; collect Property.name as the accessed key.
+ *   4. Compare that set against Route.responseKeys (populated by the
+ *      `routes` phase when the response literal was statically known).
+ *
+ * Per-consumer status:
+ *   - MATCH    — every accessed key is in responseKeys.
+ *   - MISMATCH — at least one accessed key is NOT in responseKeys.
+ *   - PARTIAL  — no accessed keys found (can't check).
+ *
+ * `classifyShape` is exported so `api_impact` can reuse it for its
+ * `mismatches` count without re-walking the graph.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IGraphStore } from "@opencodehub/storage";
+import { type ToolContext, type ToolResult } from "./shared.js";
+export type ShapeStatus = "MATCH" | "MISMATCH" | "PARTIAL";
+export interface ConsumerShape {
+    readonly file: string;
+    readonly accessedKeys: readonly string[];
+    readonly status: ShapeStatus;
+    readonly missing: readonly string[];
+}
+export interface RouteShape {
+    readonly url: string;
+    readonly method: string;
+    readonly responseKeys: readonly string[];
+    readonly consumers: readonly ConsumerShape[];
+}
+interface ShapeCheckArgs {
+    readonly repo?: string | undefined;
+    readonly repo_uri?: string | undefined;
+    readonly route?: string | undefined;
+}
+export declare function runShapeCheck(ctx: ToolContext, args: ShapeCheckArgs): Promise<ToolResult>;
+export declare function registerShapeCheckTool(server: McpServer, ctx: ToolContext): void;
+/** Load every Route matching the filter and classify each consumer file. */
+export declare function loadRouteShapes(graph: IGraphStore, routeFilter: string | undefined): Promise<readonly RouteShape[]>;
+/** Classify a set of accessed keys against responseKeys. */
+export declare function classifyShape(accessedKeys: readonly string[], responseKeys: readonly string[]): {
+    status: ShapeStatus;
+    missing: readonly string[];
+};
+export {};
+//# sourceMappingURL=shape-check.d.ts.map

package/dist/tools/shape-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-check.d.ts","sourceRoot":"","sources":["../../src/tools/shape-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAOrB,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;CAC9C;AAED,UAAU,cAAc;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAsC/F;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAiBhF;AAED,4EAA4E;AAC5E,wBAAsB,eAAe,CACnC,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAmBhC;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAC3B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAMrD"}

package/dist/tools/shape-check.js

@@ -0,0 +1,161 @@
+/**
+ * `shape_check` — compare a Route's static responseKeys against the
+ * property names each consumer file actually reads off the response.
+ *
+ * For every Route matching `route` (URL substring) we:
+ *   1. Find FETCHES edges pointing AT the route. Each `from_id` is a
+ *      symbol (Function / Method / Constructor) that issued the call.
+ *   2. Group those consumer symbols by file.
+ *   3. Walk outgoing ACCESSES from every symbol in each consumer file to
+ *      its Property target; collect Property.name as the accessed key.
+ *   4. Compare that set against Route.responseKeys (populated by the
+ *      `routes` phase when the response literal was statically known).
+ *
+ * Per-consumer status:
+ *   - MATCH    — every accessed key is in responseKeys.
+ *   - MISMATCH — at least one accessed key is NOT in responseKeys.
+ *   - PARTIAL  — no accessed keys found (can't check).
+ *
+ * `classifyShape` is exported so `api_impact` can reuse it for its
+ * `mismatches` count without re-walking the graph.
+ */
+// biome-ignore-all lint/complexity/useLiteralKeys: dot-access disallowed on Record index signatures
+import { z } from "zod";
+import { toolErrorFromUnknown } from "../error-envelope.js";
+import { withNextSteps } from "../next-step-hints.js";
+import { stalenessFromMeta } from "../staleness.js";
+import { fromToolResult, repoArgShape, toToolResult, withStore, } from "./shared.js";
+const ShapeCheckInput = {
+    ...repoArgShape,
+    route: z.string().optional().describe("Substring match against Route.url."),
+};
+export async function runShapeCheck(ctx, args) {
+    const call = await withStore(ctx, args, async (store, resolved) => {
+        try {
+            const routes = await loadRouteShapes(store.graph, args.route);
+            const header = `shape_check — ${routes.length} route(s) for ${resolved.name}${args.route ? ` · url~${args.route}` : ""}:`;
+            const lines = [header];
+            let mismatchTotal = 0;
+            for (const r of routes) {
+                lines.push(`${r.method} ${r.url} keys=${r.responseKeys.length}`);
+                for (const c of r.consumers) {
+                    if (c.status === "MISMATCH")
+                        mismatchTotal += 1;
+                    const miss = c.missing.length > 0 ? ` missing=[${c.missing.join(",")}]` : "";
+                    lines.push(`  [${c.status}] ${c.file} accessed=${c.accessedKeys.length}${miss}`);
+                }
+            }
+            if (routes.length === 0) {
+                lines.push("(no routes matched — check the url filter)");
+            }
+            const next = routes.length === 0
+                ? ["call `route_map` with the same filter to list available routes"]
+                : mismatchTotal > 0
+                    ? [
+                        "investigate each MISMATCH — consumer reads a key not in responseKeys",
+                        "call `context` on the consumer file for upstream callers",
+                    ]
+                    : ["no mismatches — consumer shape matches Route.responseKeys"];
+            return withNextSteps(lines.join("\n"), { routes }, next, stalenessFromMeta(resolved.meta));
+        }
+        catch (err) {
+            return toolErrorFromUnknown(err);
+        }
+    });
+    return toToolResult(call);
+}
+export function registerShapeCheckTool(server, ctx) {
+    server.registerTool("shape_check", {
+        title: "Route response-shape mismatch check",
+        description: "For each Route matching the filter, walk ACCESSES edges from the consumer files that FETCH this route and compare accessed property names against Route.responseKeys. Returns MATCH / MISMATCH / PARTIAL per consumer. Read-only.",
+        inputSchema: ShapeCheckInput,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => fromToolResult(await runShapeCheck(ctx, args)));
+}
+/** Load every Route matching the filter and classify each consumer file. */
+export async function loadRouteShapes(graph, routeFilter) {
+    const opts = { limit: 500 };
+    if (routeFilter !== undefined && routeFilter.length > 0)
+        opts.pathLike = routeFilter;
+    const listed = await graph.listRoutes(opts);
+    const sorted = [...listed].sort((a, b) => {
+        if (a.url !== b.url)
+            return a.url < b.url ? -1 : 1;
+        const am = a.method ?? "";
+        const bm = b.method ?? "";
+        return am < bm ? -1 : am > bm ? 1 : 0;
+    });
+    const accessesEdges = await graph.listEdgesByType("ACCESSES");
+    const routes = [];
+    for (const r of sorted) {
+        const responseKeys = r.responseKeys ?? [];
+        const consumers = await collectConsumerShapes(graph, accessesEdges, r.id, responseKeys);
+        routes.push({ url: r.url, method: r.method ?? "", responseKeys, consumers });
+    }
+    return routes;
+}
+/** Classify a set of accessed keys against responseKeys. */
+export function classifyShape(accessedKeys, responseKeys) {
+    if (accessedKeys.length === 0)
+        return { status: "PARTIAL", missing: [] };
+    const known = new Set(responseKeys);
+    const missing = accessedKeys.filter((k) => !known.has(k));
+    if (missing.length === 0)
+        return { status: "MATCH", missing: [] };
+    return { status: "MISMATCH", missing };
+}
+async function collectConsumerShapes(graph, accessesEdges, routeId, responseKeys) {
+    const fetches = await graph.listEdgesByType("FETCHES", { toIds: [routeId] });
+    const consumerSymbolIds = fetches
+        .map((e) => e.from)
+        .filter((s) => s.length > 0)
+        .sort();
+    if (consumerSymbolIds.length === 0)
+        return [];
+    const consumerSymbols = await graph.listNodes({ ids: consumerSymbolIds });
+    const consumerById = new Map();
+    for (const n of consumerSymbols)
+        consumerById.set(n.id, n);
+    const consumerFiles = new Set();
+    for (const sid of consumerSymbolIds) {
+        const n = consumerById.get(sid);
+        if (n && n.filePath.length > 0)
+            consumerFiles.add(n.filePath);
+    }
+    // Snapshot all nodes referenced by ACCESSES edges so per-file walks
+    // don't fan out per-iteration.
+    const accessedIds = new Set();
+    for (const e of accessesEdges) {
+        accessedIds.add(e.from);
+        accessedIds.add(e.to);
+    }
+    const accessedNodes = accessedIds.size > 0 ? await graph.listNodes({ ids: [...accessedIds] }) : [];
+    const accByID = new Map();
+    for (const n of accessedNodes)
+        accByID.set(n.id, n);
+    const out = [];
+    const sortedFiles = [...consumerFiles].sort();
+    for (const file of sortedFiles) {
+        const accessedSet = new Set();
+        for (const e of accessesEdges) {
+            const src = accByID.get(e.from);
+            if (!src || src.filePath !== file)
+                continue;
+            const target = accByID.get(e.to);
+            if (!target || target.kind !== "Property")
+                continue;
+            if (target.name && target.name.length > 0)
+                accessedSet.add(target.name);
+        }
+        const accessedKeys = Array.from(accessedSet).sort();
+        const { status, missing } = classifyShape(accessedKeys, responseKeys);
+        out.push({ file, accessedKeys, status, missing });
+    }
+    return out;
+}
+//# sourceMappingURL=shape-check.js.map

package/dist/tools/shape-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-check.js","sourceRoot":"","sources":["../../src/tools/shape-check.ts"],"names":[],"mappings":"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"}