@kernlang/review 3.3.4 → 3.3.6

package/dist/cache.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync
 import { homedir } from 'os';
 import { dirname, join, resolve } from 'path';
 // Version stamp for cache invalidation — changes when rules/analyzers change
-const REVIEW_CACHE_VERSION = '3.2.3-review-cache-2';
+const REVIEW_CACHE_VERSION = '3.2.3-review-cache-3';
 const IMPORT_SPECIFIER_RE = /(?:import|export)\s+(?:[^'"`]*?\s+from\s+)?['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)/g;
 const EXTENSION_FALLBACK = {
     '.js': ['.ts', '.tsx', '.mts', '.cts'],

package/dist/concept-rules/auth-drift.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Rule: auth-drift
+ *
+ * Cross-stack rule — fires when a frontend network call targets a server
+ * route file that declares an auth guard (FastAPI `Depends(get_current_user)`,
+ * Flask `@login_required`, early-return `if (!req.user)` Express patterns),
+ * but the client call sends no Authorization header.
+ *
+ * Real-bug classes:
+ *   - Protected endpoint called from a public page or before login finished.
+ *   - Frontend forgot to add the Bearer token after a refactor that moved
+ *     auth out of a wrapper.
+ *   - Endpoint was auth-gated late in the PR but the client still fires
+ *     unauthenticated.
+ *
+ * v1 scope:
+ *   - Only fires on raw `fetch(...)`. Wrapped clients typically inject auth
+ *     inside the wrapper; the TS mapper already reports
+ *     `hasAuthHeader: undefined` for them.
+ *   - Auth guard is "present" when any guard concept of subtype 'auth' lives
+ *     in the same file as a matching server route. File granularity is
+ *     coarse on purpose — FastAPI's idiomatic `APIRouter(dependencies=[...])`
+ *     puts the guard on the router, not each handler.
+ *
+ * Confidence: `CROSS_STACK_EXACT_CONFIDENCE` (0.9). Graph mode only.
+ */
+import type { ReviewFinding } from '../types.js';
+import type { ConceptRuleContext } from './index.js';
+export declare function authDrift(ctx: ConceptRuleContext): ReviewFinding[];

package/dist/concept-rules/auth-drift.js

@@ -0,0 +1,127 @@
+/**
+ * Rule: auth-drift
+ *
+ * Cross-stack rule — fires when a frontend network call targets a server
+ * route file that declares an auth guard (FastAPI `Depends(get_current_user)`,
+ * Flask `@login_required`, early-return `if (!req.user)` Express patterns),
+ * but the client call sends no Authorization header.
+ *
+ * Real-bug classes:
+ *   - Protected endpoint called from a public page or before login finished.
+ *   - Frontend forgot to add the Bearer token after a refactor that moved
+ *     auth out of a wrapper.
+ *   - Endpoint was auth-gated late in the PR but the client still fires
+ *     unauthenticated.
+ *
+ * v1 scope:
+ *   - Only fires on raw `fetch(...)`. Wrapped clients typically inject auth
+ *     inside the wrapper; the TS mapper already reports
+ *     `hasAuthHeader: undefined` for them.
+ *   - Auth guard is "present" when any guard concept of subtype 'auth' lives
+ *     in the same file as a matching server route. File granularity is
+ *     coarse on purpose — FastAPI's idiomatic `APIRouter(dependencies=[...])`
+ *     puts the guard on the router, not each handler.
+ *
+ * Confidence: `CROSS_STACK_EXACT_CONFIDENCE` (0.9). Graph mode only.
+ */
+import { createFingerprint } from '../types.js';
+import { API_PATH_RE, CROSS_STACK_EXACT_CONFIDENCE, collectRoutesAcrossGraph, findMatchingRoute, normalizeClientUrl, } from './cross-stack-utils.js';
+export function authDrift(ctx) {
+    if (!ctx.allConcepts || ctx.allConcepts.size === 0)
+        return [];
+    const serverRoutes = collectRoutesAcrossGraph(ctx.allConcepts);
+    if (serverRoutes.length === 0)
+        return [];
+    // Map each file to the set of containerIds that have an auth guard AND
+    // record which files have BOTH guarded and unguarded routes ("mixed").
+    // Codex review flagged that file-level presence was too coarse: a file
+    // with `/api/me` (guarded) + `/api/public` (not) would false-positive on
+    // the public endpoint. The fix: only fire when we can prove the SPECIFIC
+    // route is guarded (matching containerId), OR when every route in the
+    // file shares the file's guard scope. Mixed files stay silent.
+    const authGuardContainers = collectAuthGuardContainers(ctx.allConcepts);
+    if (authGuardContainers.size === 0)
+        return [];
+    const findings = [];
+    for (const [, conceptMap] of ctx.allConcepts) {
+        for (const node of conceptMap.nodes) {
+            if (node.kind !== 'effect' || node.payload.kind !== 'effect' || node.payload.subtype !== 'network')
+                continue;
+            if (node.primarySpan.file !== ctx.filePath)
+                continue;
+            // Must be explicitly `false`. `undefined` = mapper couldn't tell; stay silent.
+            if (node.payload.hasAuthHeader !== false)
+                continue;
+            const target = node.payload.target;
+            if (typeof target !== 'string')
+                continue;
+            const normalized = normalizeClientUrl(target);
+            if (!normalized || !API_PATH_RE.test(normalized))
+                continue;
+            const route = findMatchingRoute(normalized, serverRoutes);
+            if (!route?.node)
+                continue;
+            const serverFile = route.node.primarySpan.file;
+            const fileGuards = authGuardContainers.get(serverFile);
+            if (!fileGuards)
+                continue;
+            // Proof that this specific route is guarded:
+            //  (a) the route's containerId matches an auth-guard containerId
+            //      (FastAPI pattern: `@router.get` + `Depends(...)` share the
+            //      function body), OR
+            //  (b) the file contains exactly one route (Express pattern: guard
+            //      is inside the handler callback, not the app.get call, so
+            //      containers differ but there's no ambiguity about which route
+            //      the guard protects).
+            // Mixed multi-route files with no container match fall through to
+            // silent — Codex review called out this false-positive class.
+            const routeContainer = route.node.containerId;
+            const routeIsGuardedByContainer = routeContainer !== undefined && fileGuards.routeContainers.has(routeContainer);
+            const routeIsGuardedBySingleRouteFile = fileGuards.totalRoutesInFile === 1;
+            if (!routeIsGuardedByContainer && !routeIsGuardedBySingleRouteFile)
+                continue;
+            findings.push({
+                source: 'kern',
+                ruleId: 'auth-drift',
+                severity: 'warning',
+                category: 'bug',
+                message: `Frontend calls \`${target}\` without an Authorization header, but the server route requires authentication (guard declared in ${shortPath(serverFile)}). Add the Authorization header or change the server guard.`,
+                primarySpan: node.primarySpan,
+                fingerprint: createFingerprint('auth-drift', node.primarySpan.startLine, node.primarySpan.startCol),
+                confidence: node.confidence * CROSS_STACK_EXACT_CONFIDENCE,
+            });
+        }
+    }
+    return findings;
+}
+function collectAuthGuardContainers(allConcepts) {
+    const result = new Map();
+    for (const [filePath, map] of allConcepts) {
+        const routeContainers = new Set();
+        let routeCount = 0;
+        for (const node of map.nodes) {
+            if (node.kind === 'entrypoint' && node.payload.kind === 'entrypoint' && node.payload.subtype === 'route') {
+                routeCount++;
+                continue;
+            }
+            if (node.kind !== 'guard' || node.payload.kind !== 'guard')
+                continue;
+            if (node.payload.subtype !== 'auth')
+                continue;
+            // The guard's containerId is the scope that enforces auth. Routes
+            // sharing that containerId (same function body) are considered
+            // guarded.
+            if (node.containerId !== undefined)
+                routeContainers.add(node.containerId);
+        }
+        if (routeContainers.size > 0) {
+            result.set(filePath, { routeContainers, totalRoutesInFile: routeCount });
+        }
+    }
+    return result;
+}
+function shortPath(filePath) {
+    const parts = filePath.split('/');
+    return parts.slice(-2).join('/');
+}
+//# sourceMappingURL=auth-drift.js.map

package/dist/concept-rules/auth-drift.js.map

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

package/dist/concept-rules/contract-drift.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Rule: contract-drift
+ *
+ * Cross-stack rule — fires when a frontend (TS) network call targets an API
+ * path that has no matching server-side route in the reviewed project.
+ *
+ * This is the moat rule for TS ↔ Python projects: Pydantic schemas drift,
+ * endpoints get renamed, frontend hits `/api/users/:id` but the FastAPI
+ * handler was moved to `/api/v2/users/:id`. ESLint and Bandit can't see
+ * this because they each only see one side of the wire.
+ *
+ * v1 scope: URL-path drift only (is there a server for this client?). Body
+ * shape / Pydantic field correlation is a follow-up once the mappers emit
+ * body concepts — see the TODO comments in ts-concepts.ts / review-python.
+ *
+ * Requires graph mode: `ctx.allConcepts` must be populated. Single-file
+ * review silently returns no findings (can't correlate from one file).
+ */
+import type { ReviewFinding } from '../types.js';
+import type { ConceptRuleContext } from './index.js';
+export declare function contractDrift(ctx: ConceptRuleContext): ReviewFinding[];

package/dist/concept-rules/contract-drift.js

@@ -0,0 +1,65 @@
+/**
+ * Rule: contract-drift
+ *
+ * Cross-stack rule — fires when a frontend (TS) network call targets an API
+ * path that has no matching server-side route in the reviewed project.
+ *
+ * This is the moat rule for TS ↔ Python projects: Pydantic schemas drift,
+ * endpoints get renamed, frontend hits `/api/users/:id` but the FastAPI
+ * handler was moved to `/api/v2/users/:id`. ESLint and Bandit can't see
+ * this because they each only see one side of the wire.
+ *
+ * v1 scope: URL-path drift only (is there a server for this client?). Body
+ * shape / Pydantic field correlation is a follow-up once the mappers emit
+ * body concepts — see the TODO comments in ts-concepts.ts / review-python.
+ *
+ * Requires graph mode: `ctx.allConcepts` must be populated. Single-file
+ * review silently returns no findings (can't correlate from one file).
+ */
+import { createFingerprint } from '../types.js';
+import { API_PATH_RE, CROSS_STACK_HEURISTIC_CONFIDENCE, collectRoutesAcrossGraph, hasMatchingRoute, normalizeClientUrl, } from './cross-stack-utils.js';
+export function contractDrift(ctx) {
+    // Graph mode only — URL correlation is useless within a single file.
+    if (!ctx.allConcepts || ctx.allConcepts.size === 0)
+        return [];
+    const serverRoutes = collectRoutesAcrossGraph(ctx.allConcepts);
+    const clientCalls = [];
+    for (const [, conceptMap] of ctx.allConcepts) {
+        for (const node of conceptMap.nodes) {
+            if (node.kind !== 'effect' || node.payload.kind !== 'effect' || node.payload.subtype !== 'network')
+                continue;
+            const target = node.payload.target;
+            if (typeof target !== 'string')
+                continue;
+            const normalized = normalizeClientUrl(target);
+            if (!normalized || !API_PATH_RE.test(normalized))
+                continue;
+            clientCalls.push({ target, normalizedPath: normalized, node });
+        }
+    }
+    // Rule gate: need at least one route AND one client call, otherwise the
+    // project isn't a full-stack app and we'd fire on every external API hit.
+    if (serverRoutes.length === 0 || clientCalls.length === 0)
+        return [];
+    const findings = [];
+    for (const call of clientCalls) {
+        // Only report on calls that happen in files from the reviewed project —
+        // avoids firing on third-party SDK targets.
+        if (call.node.primarySpan.file !== ctx.filePath)
+            continue;
+        if (hasMatchingRoute(call.normalizedPath, serverRoutes))
+            continue;
+        findings.push({
+            source: 'kern',
+            ruleId: 'contract-drift',
+            severity: 'warning',
+            category: 'bug',
+            message: `Frontend calls \`${call.target}\` but no server-side route matches this path in the reviewed project. Either the endpoint was renamed/removed on the backend or the frontend is targeting the wrong URL.`,
+            primarySpan: call.node.primarySpan,
+            fingerprint: createFingerprint('contract-drift', call.node.primarySpan.startLine, call.node.primarySpan.startCol),
+            confidence: call.node.confidence * CROSS_STACK_HEURISTIC_CONFIDENCE,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=contract-drift.js.map

package/dist/concept-rules/contract-drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-drift.js","sourceRoot":"","sources":["../../src/concept-rules/contract-drift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,WAAW,EACX,gCAAgC,EAChC,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAShC,MAAM,UAAU,aAAa,CAAC,GAAuB;IACnD,qEAAqE;IACrE,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE9D,MAAM,YAAY,GAAG,wBAAwB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC/D,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,KAAK,MAAM,CAAC,EAAE,UAAU,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QAC7C,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;YACpC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS;gBAAE,SAAS;YAC7G,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YACnC,IAAI,OAAO,MAAM,KAAK,QAAQ;gBAAE,SAAS;YACzC,MAAM,UAAU,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,CAAC,UAAU,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC;gBAAE,SAAS;YAC3D,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErE,MAAM,QAAQ,GAAoB,EAAE,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,wEAAwE;QACxE,4CAA4C;QAC5C,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,KAAK,GAAG,CAAC,QAAQ;YAAE,SAAS;QAC1D,IAAI,gBAAgB,CAAC,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC;YAAE,SAAS;QAElE,QAAQ,CAAC,IAAI,CAAC;YACZ,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,gBAAgB;YACxB,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,oBAAoB,IAAI,CAAC,MAAM,2KAA2K;YACnN,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW;YAClC,WAAW,EAAE,iBAAiB,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC;YACjH,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,gCAAgC;SACpE,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/concept-rules/contract-method-drift.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rule: contract-method-drift
+ *
+ * Cross-stack rule — fires when a frontend network call targets an API path
+ * the server DOES define, but only for different HTTP methods. Sibling to
+ * `contract-drift`:
+ *   - contract-drift        : "no server route exists at this path"
+ *   - contract-method-drift : "server routes exist at this path, just not
+ *                             for your verb"
+ *
+ * Keeping them separate matters: the messages and fixes differ (rename the
+ * client URL vs. change the verb), the fingerprints can't collide on the
+ * same line, and the existing contract-drift `continue` gate stays intact.
+ *
+ * Confidence multiplier: `CROSS_STACK_EXACT_CONFIDENCE` (0.9) — once the path
+ * matches, a method mismatch is unambiguous.
+ *
+ * Requires graph mode; silent in single-file review.
+ */
+import type { ReviewFinding } from '../types.js';
+import type { ConceptRuleContext } from './index.js';
+export declare function contractMethodDrift(ctx: ConceptRuleContext): ReviewFinding[];

package/dist/concept-rules/contract-method-drift.js

@@ -0,0 +1,105 @@
+/**
+ * Rule: contract-method-drift
+ *
+ * Cross-stack rule — fires when a frontend network call targets an API path
+ * the server DOES define, but only for different HTTP methods. Sibling to
+ * `contract-drift`:
+ *   - contract-drift        : "no server route exists at this path"
+ *   - contract-method-drift : "server routes exist at this path, just not
+ *                             for your verb"
+ *
+ * Keeping them separate matters: the messages and fixes differ (rename the
+ * client URL vs. change the verb), the fingerprints can't collide on the
+ * same line, and the existing contract-drift `continue` gate stays intact.
+ *
+ * Confidence multiplier: `CROSS_STACK_EXACT_CONFIDENCE` (0.9) — once the path
+ * matches, a method mismatch is unambiguous.
+ *
+ * Requires graph mode; silent in single-file review.
+ */
+import { createFingerprint } from '../types.js';
+import { API_PATH_RE, CROSS_STACK_EXACT_CONFIDENCE, collectRoutesAcrossGraph, findRoutesAtPath, normalizeClientUrl, } from './cross-stack-utils.js';
+// Verbs the TS/Python mappers emit for handlers that intentionally accept any
+// method (Express `app.all()` emits `ALL`; `app.use()` emits `undefined`).
+const WILDCARD_METHODS = new Set(['ALL', 'ANY']);
+export function contractMethodDrift(ctx) {
+    if (!ctx.allConcepts || ctx.allConcepts.size === 0)
+        return [];
+    const serverRoutes = collectRoutesAcrossGraph(ctx.allConcepts);
+    if (serverRoutes.length === 0)
+        return [];
+    const clientCalls = [];
+    for (const [, conceptMap] of ctx.allConcepts) {
+        for (const node of conceptMap.nodes) {
+            if (node.kind !== 'effect' || node.payload.kind !== 'effect' || node.payload.subtype !== 'network')
+                continue;
+            const target = node.payload.target;
+            const method = node.payload.method;
+            if (typeof target !== 'string' || typeof method !== 'string')
+                continue;
+            const normalized = normalizeClientUrl(target);
+            if (!normalized || !API_PATH_RE.test(normalized))
+                continue;
+            clientCalls.push({ target, normalizedPath: normalized, method, node });
+        }
+    }
+    if (clientCalls.length === 0)
+        return [];
+    const findings = [];
+    for (const call of clientCalls) {
+        if (call.node.primarySpan.file !== ctx.filePath)
+            continue;
+        const routesAtPath = findRoutesAtPath(call.normalizedPath, serverRoutes);
+        if (routesAtPath.length === 0)
+            continue;
+        const hasMethodMatch = routesAtPath.some((r) => methodMatches(r.method, call.method));
+        if (hasMethodMatch)
+            continue;
+        const serverMethods = collectKnownMethods(routesAtPath);
+        if (serverMethods.length === 0)
+            continue;
+        const methodList = serverMethods.join(', ');
+        const hint = serverMethods.length === 1 ? ` Did you mean \`${serverMethods[0]} ${call.target}\`?` : '';
+        findings.push({
+            source: 'kern',
+            ruleId: 'contract-method-drift',
+            severity: 'warning',
+            category: 'bug',
+            message: `Frontend calls \`${call.method} ${call.target}\` but the server only defines [${methodList}] for this path.${hint}`,
+            primarySpan: call.node.primarySpan,
+            fingerprint: createFingerprint('contract-method-drift', call.node.primarySpan.startLine, call.node.primarySpan.startCol),
+            confidence: call.node.confidence * CROSS_STACK_EXACT_CONFIDENCE,
+        });
+    }
+    return findings;
+}
+function methodMatches(routeMethod, clientMethod) {
+    if (!routeMethod)
+        return true;
+    const r = routeMethod.toUpperCase();
+    if (WILDCARD_METHODS.has(r))
+        return true;
+    const c = clientMethod.toUpperCase();
+    if (r === c)
+        return true;
+    // Express and Starlette/FastAPI both auto-respond to HEAD on GET routes
+    // (returning headers, no body). Firing method-drift on `HEAD /api/x`
+    // against `app.get('/api/x')` is a false positive — the server DOES
+    // satisfy the request. Codex review called this out.
+    if (c === 'HEAD' && r === 'GET')
+        return true;
+    return false;
+}
+function collectKnownMethods(routes) {
+    const set = new Set();
+    for (const r of routes) {
+        if (!r.method)
+            continue;
+        const m = r.method.toUpperCase();
+        if (WILDCARD_METHODS.has(m))
+            continue;
+        set.add(m);
+    }
+    return Array.from(set).sort();
+}
+//# sourceMappingURL=contract-method-drift.js.map

package/dist/concept-rules/contract-method-drift.js.map

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

package/dist/concept-rules/cross-stack-utils.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared utilities for cross-stack concept rules.
+ *
+ * Every rule that correlates a frontend network call against a server-side
+ * route — contract-drift, untyped-api-response, and the upcoming
+ * tainted-across-wire — uses the same URL normalisation + route matching
+ * pipeline. Centralising it here means a bug fix (or new matching case like
+ * Next.js catch-all `[...slug]`) applies to every rule in one place.
+ */
+import type { ConceptMap, ConceptNode } from '@kernlang/core';
+/**
+ * Multiplier applied to a node's base confidence when firing a cross-stack
+ * finding. Each current rule matches only on URL-path shape — no HTTP-method
+ * correlation, no body-type correlation — so we intentionally cap confidence
+ * below 1.0 to reflect the heuristic nature. Upgrade per-rule once the
+ * matching is richer (e.g. once the Python mapper surfaces response_model=,
+ * untyped-api-response can bump its own multiplier).
+ */
+export declare const CROSS_STACK_HEURISTIC_CONFIDENCE = 0.7;
+/**
+ * Multiplier for rules where the correlation is unambiguous: the path matches
+ * exactly AND a second dimension (HTTP method, auth header, …) disagrees.
+ * `contract-method-drift`, `duplicate-route`, and `auth-drift` use this —
+ * once the path matches, a verb mismatch, duplicate declaration, or missing
+ * Authorization header is a real bug, not a heuristic.
+ */
+export declare const CROSS_STACK_EXACT_CONFIDENCE = 0.9;
+/** Client URLs we consider "internal" to the reviewed project. */
+export declare const API_PATH_RE: RegExp;
+export interface ServerRoute {
+    path: string;
+    method: string | undefined;
+    /** Present when the caller needs to cite the server route in a finding. */
+    node?: ConceptNode;
+}
+export declare function hasFastApiEvidence(map: ConceptMap): boolean;
+export declare function isFastApiRouteMissingResponseModel(node: ConceptNode, map?: ConceptMap): boolean;
+/**
+ * Pull every server-side route out of a concept map. Callers typically fold
+ * this across `ctx.allConcepts` to collect routes for the whole project.
+ *
+ * Per-file use (legacy signature): just emits the decorator path as-is.
+ *
+ * Cross-project use (preferred): call `collectRoutesAcrossGraph` instead,
+ * which joins route-mount concepts (FastAPI `app.include_router(prefix=…)`)
+ * with the per-file route decorators so `@router.get("/current")` mounted
+ * under `prefix="/api/nutrition-goals"` surfaces as `/api/nutrition-goals/current`.
+ * Without that join the wedge rules silently find nothing on every FastAPI
+ * app that follows the standard APIRouter pattern.
+ */
+export declare function collectRoutes(map: ConceptMap, routes: ServerRoute[]): void;
+/**
+ * Graph-wide route collection with FastAPI router-prefix expansion.
+ *
+ * Walks every concept map twice:
+ *   1. Collect `route-mount` concepts (FastAPI `app.include_router(<router>,
+ *      prefix=…)` calls). Each mount carries `prefix`, `routerName`, and —
+ *      when the router was imported from another module — `sourceModule`
+ *      like `app.api.nutrition_goals`.
+ *   2. For each per-file `route` concept, look up a matching mount by
+ *      `sourceModule` ↔ file path suffix (Python `app.api.nutrition_goals`
+ *      resolves to any file path ending in `app/api/nutrition_goals.py`),
+ *      falling back to a project-wide `routerName` match when the mount
+ *      is in the same file as the routes.
+ *
+ * Per-file routes with no mount are still emitted with their declared path
+ * — Flask / Express routes and FastAPI apps that decorate directly on
+ * `@app.get(...)` already carry the full path.
+ */
+export declare function collectRoutesAcrossGraph(allConcepts: ReadonlyMap<string, ConceptMap>): ServerRoute[];
+/**
+ * Strip scheme/host, query string, and fragment from a client URL so it can
+ * match against a server route template. Returns undefined when the input
+ * isn't a recognisable path (e.g. a bare variable reference or an
+ * unresolved template expression).
+ */
+export declare function normalizeClientUrl(raw: string): string | undefined;
+/**
+ * Match a client-side concrete path against server-side route templates.
+ * Returns the first matching route (so callers can cite it in findings) or
+ * `undefined`. Server templates may contain params — Express/Koa `:id`,
+ * FastAPI `{id}` — which match any single segment. Trailing slashes are
+ * normalised on both sides. Case-sensitive (matches Express/FastAPI default
+ * behaviour).
+ */
+export declare function findMatchingRoute(clientPath: string, routes: readonly ServerRoute[]): ServerRoute | undefined;
+/** Boolean-returning thin wrapper preserved for callers that just need a yes/no. */
+export declare function hasMatchingRoute(clientPath: string, routes: readonly ServerRoute[]): boolean;
+/**
+ * Return every server route whose path template matches the client path,
+ * regardless of HTTP method. Used by `contract-method-drift` and
+ * `orphan-route` to distinguish "no server exists here" (contract-drift
+ * territory) from "server exists but only responds to a different verb /
+ * no one calls it" (method-drift / orphan-route territory).
+ */
+export declare function findRoutesAtPath(clientPath: string, routes: readonly ServerRoute[]): ServerRoute[];