@kernlang/review 3.3.4 → 3.3.6

package/dist/concept-rules/cross-stack-utils.js

@@ -0,0 +1,259 @@
+/**
+ * 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.
+ */
+/**
+ * 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 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 const CROSS_STACK_EXACT_CONFIDENCE = 0.9;
+/** Client URLs we consider "internal" to the reviewed project. */
+export const API_PATH_RE = /^\/api\//;
+export function hasFastApiEvidence(map) {
+    if (map.language !== 'py')
+        return false;
+    return map.edges.some((edge) => {
+        if (edge.kind !== 'dependency' || edge.payload.kind !== 'dependency')
+            return false;
+        return edge.payload.specifier === 'fastapi' || edge.payload.specifier.startsWith('fastapi.');
+    });
+}
+export function isFastApiRouteMissingResponseModel(node, map) {
+    if (node.language !== 'py')
+        return false;
+    if (node.kind !== 'entrypoint' || node.payload.kind !== 'entrypoint')
+        return false;
+    if (node.payload.subtype !== 'route')
+        return false;
+    if (node.payload.responseModel)
+        return false;
+    return map ? hasFastApiEvidence(map) : false;
+}
+/**
+ * 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 function collectRoutes(map, routes) {
+    for (const node of map.nodes) {
+        if (node.kind !== 'entrypoint' || node.payload.kind !== 'entrypoint' || node.payload.subtype !== 'route')
+            continue;
+        const path = node.payload.name;
+        if (typeof path !== 'string' || !path.startsWith('/'))
+            continue;
+        routes.push({ path, method: node.payload.httpMethod, node });
+    }
+}
+/**
+ * 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 function collectRoutesAcrossGraph(allConcepts) {
+    const routes = [];
+    // Build the mount index first so each route can look up its prefix.
+    const mountsByModule = new Map();
+    const mountsByRouter = new Map();
+    for (const [mountFile, map] of allConcepts) {
+        for (const node of map.nodes) {
+            if (node.kind !== 'entrypoint' || node.payload.kind !== 'entrypoint')
+                continue;
+            if (node.payload.subtype !== 'route-mount')
+                continue;
+            const prefix = node.payload.name;
+            const routerName = node.payload.routerName;
+            const sourceModule = node.payload.sourceModule;
+            if (sourceModule) {
+                const list = mountsByModule.get(sourceModule) ?? [];
+                list.push(prefix);
+                mountsByModule.set(sourceModule, list);
+            }
+            if (routerName) {
+                const list = mountsByRouter.get(routerName) ?? [];
+                list.push({ prefix, mountFile });
+                mountsByRouter.set(routerName, list);
+            }
+        }
+    }
+    for (const [routeFile, map] of allConcepts) {
+        for (const node of map.nodes) {
+            if (node.kind !== 'entrypoint' || node.payload.kind !== 'entrypoint')
+                continue;
+            if (node.payload.subtype !== 'route')
+                continue;
+            const path = node.payload.name;
+            if (typeof path !== 'string' || !path.startsWith('/'))
+                continue;
+            const prefix = resolveMountPrefix(routeFile, node.payload.routerName, mountsByModule, mountsByRouter);
+            const fullPath = prefix ? joinPaths(prefix, path) : path;
+            routes.push({ path: fullPath, method: node.payload.httpMethod, node });
+        }
+    }
+    return routes;
+}
+function resolveMountPrefix(routeFile, routerName, mountsByModule, mountsByRouter) {
+    // Module-based match. TS mounts emit a `sourceModule` that already carries a
+    // code extension (e.g. `routes/review.ts`) — use it as a path suffix directly.
+    // Python mounts emit a dotted module name (`app.api.nutrition_goals`) — translate
+    // to `app/api/nutrition_goals.py` first. The leading-slash boundary check in
+    // both branches prevents `blog/api.py` from false-matching module `api`.
+    for (const [sourceModule, prefixes] of mountsByModule) {
+        if (prefixes.length === 0)
+            continue;
+        const relTail = /\.(ts|tsx|js|jsx|mjs|cjs)$/i.test(sourceModule)
+            ? sourceModule
+            : `${sourceModule.replace(/\./g, '/')}.py`;
+        if (routeFile === relTail || routeFile.endsWith(`/${relTail}`))
+            return prefixes[0];
+    }
+    // Same-file match: `router = APIRouter(); app.include_router(router, prefix=…)`.
+    // The mount has no `sourceModule` but shares the file with the routes.
+    if (routerName) {
+        const entries = mountsByRouter.get(routerName);
+        if (entries) {
+            const sameFile = entries.find((e) => e.mountFile === routeFile);
+            if (sameFile)
+                return sameFile.prefix;
+        }
+    }
+    return undefined;
+}
+function joinPaths(prefix, path) {
+    const trimmedPrefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+    const trimmedPath = path.startsWith('/') ? path : `/${path}`;
+    if (trimmedPath === '/')
+        return trimmedPrefix || '/';
+    return `${trimmedPrefix}${trimmedPath}`;
+}
+/**
+ * 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 function normalizeClientUrl(raw) {
+    let url = raw.trim();
+    if (url.startsWith('`') && !url.startsWith('`/'))
+        return undefined;
+    url = url.replace(/^`|`$/g, '');
+    if (url.startsWith('http://') || url.startsWith('https://')) {
+        const pathStart = url.indexOf('/', url.indexOf('://') + 3);
+        url = pathStart === -1 ? '/' : url.slice(pathStart);
+    }
+    const q = url.indexOf('?');
+    if (q !== -1)
+        url = url.slice(0, q);
+    const h = url.indexOf('#');
+    if (h !== -1)
+        url = url.slice(0, h);
+    return url || 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 function findMatchingRoute(clientPath, routes) {
+    const clientSegments = trimTrailing(clientPath).split('/');
+    for (const route of routes) {
+        const routeSegments = trimTrailing(route.path).split('/');
+        if (routeSegments.length !== clientSegments.length)
+            continue;
+        let matched = true;
+        for (let i = 0; i < routeSegments.length; i++) {
+            const rs = routeSegments[i];
+            const cs = clientSegments[i];
+            if (isParamSegment(rs))
+                continue;
+            if (rs !== cs) {
+                matched = false;
+                break;
+            }
+        }
+        if (matched)
+            return route;
+    }
+    return undefined;
+}
+/** Boolean-returning thin wrapper preserved for callers that just need a yes/no. */
+export function hasMatchingRoute(clientPath, routes) {
+    return findMatchingRoute(clientPath, routes) !== undefined;
+}
+/**
+ * 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 function findRoutesAtPath(clientPath, routes) {
+    const clientSegments = trimTrailing(clientPath).split('/');
+    const matches = [];
+    for (const route of routes) {
+        const routeSegments = trimTrailing(route.path).split('/');
+        if (routeSegments.length !== clientSegments.length)
+            continue;
+        let matched = true;
+        for (let i = 0; i < routeSegments.length; i++) {
+            const rs = routeSegments[i];
+            const cs = clientSegments[i];
+            if (isParamSegment(rs))
+                continue;
+            if (rs !== cs) {
+                matched = false;
+                break;
+            }
+        }
+        if (matched)
+            matches.push(route);
+    }
+    return matches;
+}
+function trimTrailing(path) {
+    return path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path;
+}
+function isParamSegment(seg) {
+    return seg.startsWith(':') || (seg.startsWith('{') && seg.endsWith('}'));
+}
+//# sourceMappingURL=cross-stack-utils.js.map

package/dist/concept-rules/cross-stack-utils.js.map

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

package/dist/concept-rules/duplicate-route.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Rule: duplicate-route
+ *
+ * Server-side rule — fires when two or more route decorators declare the
+ * same `{path, method}` combination in the reviewed project. Real-bug
+ * classes:
+ *   - Someone renamed a handler but forgot to delete the old one; both fire,
+ *     order-dependent, one silently shadows the other.
+ *   - A copy-paste left an `@router.get("/users")` pair intact.
+ *   - A FastAPI router was mounted twice under the same prefix by accident.
+ *
+ * Fires on the SECOND and later occurrences (the first is the canonical
+ * declaration; duplicates are the bug). No-verb routes (`app.use`) key
+ * under `ANY` so two `use('/x')` calls still surface as duplicates.
+ *
+ * Path-only scope: does not cross-correlate client calls. Graph mode only.
+ */
+import type { ReviewFinding } from '../types.js';
+import type { ConceptRuleContext } from './index.js';
+export declare function duplicateRoute(ctx: ConceptRuleContext): ReviewFinding[];

package/dist/concept-rules/duplicate-route.js

@@ -0,0 +1,112 @@
+/**
+ * Rule: duplicate-route
+ *
+ * Server-side rule — fires when two or more route decorators declare the
+ * same `{path, method}` combination in the reviewed project. Real-bug
+ * classes:
+ *   - Someone renamed a handler but forgot to delete the old one; both fire,
+ *     order-dependent, one silently shadows the other.
+ *   - A copy-paste left an `@router.get("/users")` pair intact.
+ *   - A FastAPI router was mounted twice under the same prefix by accident.
+ *
+ * Fires on the SECOND and later occurrences (the first is the canonical
+ * declaration; duplicates are the bug). No-verb routes (`app.use`) key
+ * under `ANY` so two `use('/x')` calls still surface as duplicates.
+ *
+ * Path-only scope: does not cross-correlate client calls. Graph mode only.
+ */
+import { createFingerprint } from '../types.js';
+import { CROSS_STACK_EXACT_CONFIDENCE, collectRoutesAcrossGraph } from './cross-stack-utils.js';
+export function duplicateRoute(ctx) {
+    if (!ctx.allConcepts || ctx.allConcepts.size === 0)
+        return [];
+    const routes = collectRoutesAcrossGraph(ctx.allConcepts);
+    if (routes.length < 2)
+        return [];
+    // Group by `${METHOD} ${path}` for exact duplicates, BUT wildcard routes
+    // (`ALL`/`ANY`/undefined) shadow specific verbs on the same path. Codex
+    // review caught that the naïve keying missed `app.all('/x')` +
+    // `app.get('/x')` collisions. We do two passes:
+    //   1. Group routes at each path by wildcard-vs-specific classification.
+    //   2. Within a path, if there's a wildcard route AND any specific verb
+    //      route, they collide (pick the later one as the "duplicate").
+    //   3. Also flag same-path-same-method duplicates as before.
+    const byKey = new Map();
+    const byPath = new Map();
+    for (const r of routes) {
+        const method = (r.method ?? 'ANY').toUpperCase();
+        const key = `${method} ${r.path}`;
+        const keyList = byKey.get(key) ?? [];
+        keyList.push(r);
+        byKey.set(key, keyList);
+        const pathList = byPath.get(r.path) ?? [];
+        pathList.push(r);
+        byPath.set(r.path, pathList);
+    }
+    // Wildcard-vs-specific collisions: when a path has a wildcard-accepting
+    // route and any specific-verb route, the handlers shadow each other.
+    const WILDCARD = new Set(['ALL', 'ANY']);
+    for (const [, pathRoutes] of byPath) {
+        if (pathRoutes.length < 2)
+            continue;
+        const wildcards = pathRoutes.filter((r) => {
+            const m = (r.method ?? 'ANY').toUpperCase();
+            return WILDCARD.has(m);
+        });
+        if (wildcards.length === 0)
+            continue;
+        // Synthesize a collision key so the existing emission loop fires.
+        // Keep the wildcard as canonical (first), flag every specific-verb route
+        // on this path as the duplicate.
+        const specifics = pathRoutes.filter((r) => {
+            const m = (r.method ?? 'ANY').toUpperCase();
+            return !WILDCARD.has(m);
+        });
+        if (specifics.length === 0)
+            continue;
+        const collisionKey = `* ${wildcards[0].path}`;
+        if (!byKey.has(collisionKey))
+            byKey.set(collisionKey, [wildcards[0], ...specifics]);
+    }
+    const findings = [];
+    const seen = new Set();
+    for (const [key, list] of byKey) {
+        if (list.length < 2)
+            continue;
+        const isWildcardCollision = key.startsWith('* ');
+        const duplicates = list.slice(1);
+        for (const dup of duplicates) {
+            if (!dup.node || dup.node.primarySpan.file !== ctx.filePath)
+                continue;
+            const fingerprint = createFingerprint('duplicate-route', dup.node.primarySpan.startLine, dup.node.primarySpan.startCol);
+            if (seen.has(fingerprint))
+                continue;
+            seen.add(fingerprint);
+            const first = list[0];
+            const firstFile = first.node?.primarySpan.file ?? 'another file';
+            const firstLine = first.node?.primarySpan.startLine;
+            const firstRef = firstLine != null ? `${shortPath(firstFile)}:${firstLine}` : shortPath(firstFile);
+            const firstMethod = (first.method ?? 'ANY').toUpperCase();
+            const dupMethod = (dup.method ?? 'ANY').toUpperCase();
+            const message = isWildcardCollision
+                ? `Route \`${dupMethod} ${dup.path}\` is shadowed by wildcard route \`${firstMethod} ${dup.path}\` at ${firstRef}. The wildcard handler will match ${dupMethod} requests depending on registration order.`
+                : `Duplicate route declaration: \`${key}\` is already declared at ${firstRef}. One of the two handlers will silently shadow the other.`;
+            findings.push({
+                source: 'kern',
+                ruleId: 'duplicate-route',
+                severity: 'warning',
+                category: 'bug',
+                message,
+                primarySpan: dup.node.primarySpan,
+                fingerprint,
+                confidence: dup.node.confidence * CROSS_STACK_EXACT_CONFIDENCE,
+            });
+        }
+    }
+    return findings;
+}
+function shortPath(filePath) {
+    const parts = filePath.split('/');
+    return parts.slice(-2).join('/');
+}
+//# sourceMappingURL=duplicate-route.js.map

package/dist/concept-rules/duplicate-route.js.map

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

package/dist/concept-rules/index.js

@@ -4,11 +4,36 @@
  * These rules work on any language that emits concepts.
  * Language-agnostic by design.
  */
+import { authDrift } from './auth-drift.js';
 import { boundaryMutation } from './boundary-mutation.js';
+import { contractDrift } from './contract-drift.js';
+import { contractMethodDrift } from './contract-method-drift.js';
+import { duplicateRoute } from './duplicate-route.js';
 import { ignoredError } from './ignored-error.js';
+import { missingResponseModel } from './missing-response-model.js';
+import { orphanRoute } from './orphan-route.js';
+import { syncHandlerDoesIo } from './sync-handler-does-io.js';
+import { taintedAcrossWire } from './tainted-across-wire.js';
 import { unguardedEffect } from './unguarded-effect.js';
 import { unrecoveredEffect } from './unrecovered-effect.js';
-export const conceptRules = [boundaryMutation, ignoredError, unguardedEffect, unrecoveredEffect];
+import { untypedApiResponse } from './untyped-api-response.js';
+import { untypedBothEndsResponse } from './untyped-both-ends-response.js';
+export const conceptRules = [
+    authDrift,
+    boundaryMutation,
+    contractDrift,
+    contractMethodDrift,
+    duplicateRoute,
+    ignoredError,
+    missingResponseModel,
+    syncHandlerDoesIo,
+    orphanRoute,
+    taintedAcrossWire,
+    unguardedEffect,
+    unrecoveredEffect,
+    untypedApiResponse,
+    untypedBothEndsResponse,
+];
 export function runConceptRules(concepts, filePath, allConcepts, graphImports) {
     const ctx = { concepts, filePath, allConcepts, graphImports };
     const findings = [];

package/dist/concept-rules/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/concept-rules/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAa5D,MAAM,CAAC,MAAM,YAAY,GAAkB,CAAC,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,CAAC,CAAC;AAEhH,MAAM,UAAU,eAAe,CAC7B,QAAoB,EACpB,QAAgB,EAChB,WAAqC,EACrC,YAAoC;IAEpC,MAAM,GAAG,GAAuB,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;IAClF,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/concept-rules/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAa1E,MAAM,CAAC,MAAM,YAAY,GAAkB;IACzC,SAAS;IACT,gBAAgB;IAChB,aAAa;IACb,mBAAmB;IACnB,cAAc;IACd,YAAY;IACZ,oBAAoB;IACpB,iBAAiB;IACjB,WAAW;IACX,iBAAiB;IACjB,eAAe;IACf,iBAAiB;IACjB,kBAAkB;IAClB,uBAAuB;CACxB,CAAC;AAEF,MAAM,UAAU,eAAe,CAC7B,QAAoB,EACpB,QAAgB,EAChB,WAAqC,EACrC,YAAoC;IAEpC,MAAM,GAAG,GAAuB,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;IAClF,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/concept-rules/missing-response-model.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Rule: missing-response-model
+ *
+ * Fires on Python route decorators that do not declare a FastAPI
+ * `response_model=...`. Kept Python-scoped because other route mappers do
+ * not currently surface an equivalent response-schema signal.
+ */
+import type { ReviewFinding } from '../types.js';
+import type { ConceptRuleContext } from './index.js';
+export declare function missingResponseModel(ctx: ConceptRuleContext): ReviewFinding[];

package/dist/concept-rules/missing-response-model.js

@@ -0,0 +1,38 @@
+/**
+ * Rule: missing-response-model
+ *
+ * Fires on Python route decorators that do not declare a FastAPI
+ * `response_model=...`. Kept Python-scoped because other route mappers do
+ * not currently surface an equivalent response-schema signal.
+ */
+import { createFingerprint } from '../types.js';
+import { CROSS_STACK_HEURISTIC_CONFIDENCE, hasFastApiEvidence } from './cross-stack-utils.js';
+export function missingResponseModel(ctx) {
+    const findings = [];
+    if (!hasFastApiEvidence(ctx.concepts))
+        return findings;
+    for (const node of ctx.concepts.nodes) {
+        if (node.kind !== 'entrypoint')
+            continue;
+        if (node.payload.kind !== 'entrypoint')
+            continue;
+        if (node.payload.subtype !== 'route')
+            continue;
+        if (node.language !== 'py')
+            continue;
+        if (node.payload.responseModel)
+            continue;
+        findings.push({
+            source: 'kern',
+            ruleId: 'missing-response-model',
+            severity: 'warning',
+            category: 'bug',
+            message: `Route \`${node.payload.name}\` has no FastAPI response_model. Add response_model=... so backend response-shape drift is caught at the contract boundary.`,
+            primarySpan: node.primarySpan,
+            fingerprint: createFingerprint('missing-response-model', node.primarySpan.startLine, node.primarySpan.startCol),
+            confidence: node.confidence * CROSS_STACK_HEURISTIC_CONFIDENCE,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=missing-response-model.js.map

package/dist/concept-rules/missing-response-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-response-model.js","sourceRoot":"","sources":["../../src/concept-rules/missing-response-model.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gCAAgC,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG9F,MAAM,UAAU,oBAAoB,CAAC,GAAuB;IAC1D,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAEvD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY;YAAE,SAAS;QACzC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,YAAY;YAAE,SAAS;QACjD,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK,OAAO;YAAE,SAAS;QAC/C,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;YAAE,SAAS;QACrC,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa;YAAE,SAAS;QAEzC,QAAQ,CAAC,IAAI,CAAC;YACZ,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,wBAAwB;YAChC,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,WAAW,IAAI,CAAC,OAAO,CAAC,IAAI,8HAA8H;YACnK,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,iBAAiB,CAAC,wBAAwB,EAAE,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC;YAC/G,UAAU,EAAE,IAAI,CAAC,UAAU,GAAG,gCAAgC;SAC/D,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/concept-rules/orphan-route.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Rule: orphan-route
+ *
+ * Cross-stack rule — mirror of contract-drift. Fires when a server-side route
+ * exists that no client call in the reviewed graph targets. Real-bug classes:
+ *   - Handler was kept live after the frontend renamed the URL it hits.
+ *   - Endpoint was written before the UI that would call it (forgotten TODO).
+ *   - A dev-only test endpoint made it into production code.
+ *
+ * v1 scope: path-only match (any client call whose normalized path matches
+ * the route template suppresses the finding, regardless of HTTP method). The
+ * method axis is left to `contract-method-drift` — compounding both here
+ * would double-fire on the same line.
+ *
+ * Requires graph mode: silent in single-file review. Single-file can't know
+ * "no one calls this" because callers live in other files by definition.
+ */
+import type { ReviewFinding } from '../types.js';
+import type { ConceptRuleContext } from './index.js';
+export declare function orphanRoute(ctx: ConceptRuleContext): ReviewFinding[];

package/dist/concept-rules/orphan-route.js

@@ -0,0 +1,96 @@
+/**
+ * Rule: orphan-route
+ *
+ * Cross-stack rule — mirror of contract-drift. Fires when a server-side route
+ * exists that no client call in the reviewed graph targets. Real-bug classes:
+ *   - Handler was kept live after the frontend renamed the URL it hits.
+ *   - Endpoint was written before the UI that would call it (forgotten TODO).
+ *   - A dev-only test endpoint made it into production code.
+ *
+ * v1 scope: path-only match (any client call whose normalized path matches
+ * the route template suppresses the finding, regardless of HTTP method). The
+ * method axis is left to `contract-method-drift` — compounding both here
+ * would double-fire on the same line.
+ *
+ * Requires graph mode: silent in single-file review. Single-file can't know
+ * "no one calls this" because callers live in other files by definition.
+ */
+import { createFingerprint } from '../types.js';
+import { API_PATH_RE, CROSS_STACK_HEURISTIC_CONFIDENCE, collectRoutesAcrossGraph, findRoutesAtPath, normalizeClientUrl, } from './cross-stack-utils.js';
+export function orphanRoute(ctx) {
+    if (!ctx.allConcepts || ctx.allConcepts.size === 0)
+        return [];
+    const serverRoutes = collectRoutesAcrossGraph(ctx.allConcepts);
+    if (serverRoutes.length === 0)
+        return [];
+    // Collect every client-call path in the graph once so each route checks
+    // against a shared set rather than re-walking allConcepts.
+    //
+    // Codex review: if ANY network effect has an unresolved target (imported
+    // constant, URL builder, variable expression), the rule MUST abstain —
+    // the unresolved call could be hitting any of the "orphan" routes and
+    // we'd fire a false positive. Only run the rule when every client call
+    // is statically resolvable.
+    const clientPaths = new Set();
+    let hasUnresolvedTarget = false;
+    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') {
+                hasUnresolvedTarget = true;
+                continue;
+            }
+            const normalized = normalizeClientUrl(target);
+            if (!normalized) {
+                hasUnresolvedTarget = true;
+                continue;
+            }
+            if (!API_PATH_RE.test(normalized))
+                continue;
+            clientPaths.add(normalized);
+        }
+    }
+    // Gate: backend-only project (no client calls) — silent.
+    // Gate: any unresolved client targets — silent (Codex P2).
+    if (clientPaths.size === 0)
+        return [];
+    if (hasUnresolvedTarget)
+        return [];
+    const findings = [];
+    const seenFingerprints = new Set();
+    for (const route of serverRoutes) {
+        if (!route.node || route.node.primarySpan.file !== ctx.filePath)
+            continue;
+        if (clientCallMatches(route.path, clientPaths))
+            continue;
+        const fingerprint = createFingerprint('orphan-route', route.node.primarySpan.startLine, route.node.primarySpan.startCol);
+        // Router-mount expansion can cause the same per-file route to surface
+        // twice under different prefixes when two mounts share a router (rare
+        // but legal). Dedupe by fingerprint so we emit one finding per span.
+        if (seenFingerprints.has(fingerprint))
+            continue;
+        seenFingerprints.add(fingerprint);
+        const methodLabel = route.method ? `${route.method} ` : '';
+        findings.push({
+            source: 'kern',
+            ruleId: 'orphan-route',
+            severity: 'warning',
+            category: 'bug',
+            message: `Server defines \`${methodLabel}${route.path}\` but no client in the reviewed project calls this path. Either remove the handler or add the frontend caller.`,
+            primarySpan: route.node.primarySpan,
+            fingerprint,
+            confidence: route.node.confidence * CROSS_STACK_HEURISTIC_CONFIDENCE,
+        });
+    }
+    return findings;
+}
+function clientCallMatches(routePath, clientPaths) {
+    for (const cp of clientPaths) {
+        if (findRoutesAtPath(cp, [{ path: routePath, method: undefined }]).length > 0)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=orphan-route.js.map

package/dist/concept-rules/orphan-route.js.map

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

package/dist/concept-rules/sync-handler-does-io.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rule: sync-handler-does-io
+ *
+ * Fires when a route handler is explicitly synchronous and performs
+ * network/db/fs I/O in the same function container.
+ */
+import type { ReviewFinding } from '../types.js';
+import type { ConceptRuleContext } from './index.js';
+export declare function syncHandlerDoesIo(ctx: ConceptRuleContext): ReviewFinding[];