@kernlang/review 3.3.5 → 3.3.6

package/dist/mappers/ts-concepts.js

@@ -10,6 +10,24 @@ const EXTRACTOR_VERSION = '1.0.0';
 // ── Network effect signatures ────────────────────────────────────────────
 const NETWORK_CALLS = new Set(['fetch', 'axios', 'got', 'request', 'superagent', 'ky']);
 const NETWORK_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'request']);
+// ── Wrapped HTTP-client detection ────────────────────────────────────────
+// ~75% of production React/Next/Expo apps route through a wrapper (custom
+// ApiClient class, axios.create instance, tRPC-generated client). The fixed
+// NETWORK_CALLS set misses those, so the cross-stack wedge rules
+// (contract-drift, untyped-api-response, tainted-across-wire) silently
+// find nothing on real repos. collectClientIdentifiers() scans the file
+// for wrapper patterns and returns the local identifiers that behave like
+// HTTP clients; extractEffects() then treats `<name>.get/post/…` calls on
+// those identifiers as network effects.
+const CLIENT_HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete']);
+// Names considered client-shaped for imported identifiers. Kept narrow on
+// purpose — false positives here cascade into the wedge rules and poison
+// the pitch. Matches: api, http, client, apiClient, httpClient, fetcher,
+// requester, ApiClient, HttpClient, MyApiClient, etc.
+const CLIENT_NAME_PATTERN = /^(api|http|client|apiClient|httpClient|fetcher|requester)$|Client$/;
+// Wrapper factories — if a variable is initialized with one of these calls,
+// the variable is a client instance (axios.create, ky.create, got.extend).
+const CLIENT_FACTORY_CALLS = new Set(['axios.create', 'ky.create', 'ky.extend', 'got.extend']);
 const DB_CALLS = new Set([
     'query',
     'execute',
@@ -237,6 +255,7 @@ function hasIntentComment(text) {
 }
 // ── effect ───────────────────────────────────────────────────────────────
 function extractEffects(sf, filePath, nodes) {
+    const clientIdents = collectClientIdentifiers(sf);
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
         const callee = call.getExpression();
         let funcName = '';
@@ -250,15 +269,17 @@ function extractEffects(sf, filePath, nodes) {
             objName = pa.getExpression().getText();
         }
         // Network effects
-        if (NETWORK_CALLS.has(funcName) ||
-            (NETWORK_METHODS.has(funcName) && /axios|got|ky|http|request|superagent/i.test(objName))) {
+        const isDirectNetwork = NETWORK_CALLS.has(funcName);
+        const isKnownLibraryMethod = NETWORK_METHODS.has(funcName) && /axios|got|ky|http|request|superagent/i.test(objName);
+        const isWrappedClientCall = CLIENT_HTTP_METHODS.has(funcName) && clientIdents.has(objName);
+        if (isDirectNetwork || isKnownLibraryMethod || isWrappedClientCall) {
             const isAsync = isInAsyncContext(call);
             nodes.push({
                 id: conceptId(filePath, 'effect', call.getStart()),
                 kind: 'effect',
                 primarySpan: span(filePath, call),
                 evidence: call.getText().substring(0, 120),
-                confidence: NETWORK_CALLS.has(funcName) ? 1.0 : 0.8,
+                confidence: isDirectNetwork ? 1.0 : isWrappedClientCall ? 0.75 : 0.8,
                 language: 'ts',
                 containerId: getContainerId(call, filePath),
                 payload: {
@@ -266,8 +287,10 @@ function extractEffects(sf, filePath, nodes) {
                     subtype: 'network',
                     async: isAsync,
                     target: extractTarget(call),
-                    responseAsserted: isResponseAsserted(call),
+                    responseAsserted: isResponseAsserted(call, isWrappedClientCall),
                     bodyKind: extractBodyKind(call, funcName),
+                    method: extractHttpMethod(call, funcName, isDirectNetwork, isKnownLibraryMethod, isWrappedClientCall),
+                    hasAuthHeader: extractHasAuthHeader(call, funcName),
                 },
             });
             continue;
@@ -302,7 +325,7 @@ function extractEffects(sf, filePath, nodes) {
     }
 }
 // ── entrypoint ───────────────────────────────────────────────────────────
-const ROUTE_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'all', 'use']);
+const ROUTE_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'all']);
 function extractEntrypoints(sf, filePath, nodes) {
     // Express/Fastify route handlers: app.get('/path', handler)
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
@@ -311,14 +334,20 @@ function extractEntrypoints(sf, filePath, nodes) {
             continue;
         const pa = callee;
         const methodName = pa.getName();
-        if (!ROUTE_METHODS.has(methodName))
-            continue;
         const objText = pa.getExpression().getText();
         if (!/app|router|server/i.test(objText))
             continue;
         const args = call.getArguments();
         if (args.length < 2)
             continue;
+        if (methodName === 'use') {
+            const mount = extractRouteMount(call, filePath);
+            if (mount)
+                nodes.push(mount);
+            continue;
+        }
+        if (!ROUTE_METHODS.has(methodName))
+            continue;
         // First arg is the route path
         let routePath;
         if (args[0].getKind() === SyntaxKind.StringLiteral) {
@@ -336,7 +365,7 @@ function extractEntrypoints(sf, filePath, nodes) {
                 kind: 'entrypoint',
                 subtype: 'route',
                 name: routePath || methodName,
-                httpMethod: methodName === 'use' ? undefined : methodName.toUpperCase(),
+                httpMethod: methodName.toUpperCase(),
             },
         });
     }
@@ -371,6 +400,119 @@ function extractEntrypoints(sf, filePath, nodes) {
         }
     }
 }
+// Express `app.use('/api/prefix', ...middlewares, subRouter)`: emit a
+// route-mount concept so `collectRoutesAcrossGraph` can join the sub-router's
+// bare paths (`router.get('/foo')`) with the mount prefix (`/api/prefix/foo`).
+// Mirrors the FastAPI `app.include_router()` emission in review-python.
+// Caller must have already filtered to `.use()` calls whose object matches
+// `app|router|server`.
+function extractRouteMount(call, mountFile) {
+    const args = call.getArguments();
+    if (args.length < 2)
+        return undefined;
+    if (args[0].getKind() !== SyntaxKind.StringLiteral)
+        return undefined;
+    const prefix = args[0].getLiteralValue();
+    if (!prefix.startsWith('/'))
+        return undefined;
+    // The sub-router is the LAST arg; intermediate args are middlewares.
+    const last = args[args.length - 1];
+    if (last.getKind() !== SyntaxKind.Identifier)
+        return undefined;
+    const ident = last;
+    const routerName = ident.getText();
+    const sourceModule = resolveImportedFileSuffix(ident, mountFile);
+    // Emit even when resolution fails — the same-file fallback in
+    // resolveMountPrefix can still match if the router is declared locally.
+    return {
+        id: conceptId(mountFile, 'entrypoint', call.getStart()),
+        kind: 'entrypoint',
+        primarySpan: span(mountFile, call),
+        evidence: call.getText().substring(0, 120),
+        confidence: 0.9,
+        language: 'ts',
+        containerId: getContainerId(call, mountFile),
+        payload: {
+            kind: 'entrypoint',
+            subtype: 'route-mount',
+            name: prefix,
+            routerName,
+            sourceModule,
+        },
+    };
+}
+// Given an identifier used in a mount call, resolve it back to the file it
+// was imported from, and return a trailing path suffix (relative to the mount
+// file's directory, with extension) usable by `cross-stack-utils`'s
+// `routeFile.endsWith('/' + sourceModule)` matcher.
+//
+// Returns `undefined` when the identifier is declared locally (no import),
+// when the import cannot be resolved to a source file, or when the import
+// is external (node_modules).
+function resolveImportedFileSuffix(ident, mountFile) {
+    const symbol = ident.getSymbol();
+    if (!symbol)
+        return undefined;
+    for (const decl of symbol.getDeclarations()) {
+        const kind = decl.getKind();
+        if (kind !== SyntaxKind.ImportClause && kind !== SyntaxKind.ImportSpecifier)
+            continue;
+        const importDecl = decl.getFirstAncestorByKind(SyntaxKind.ImportDeclaration);
+        if (!importDecl)
+            continue;
+        const resolved = importDecl.getModuleSpecifierSourceFile();
+        if (resolved) {
+            return pathSuffixBetween(mountFile, resolved.getFilePath());
+        }
+        // ts-morph couldn't resolve (no project config) — fall back to parsing the
+        // specifier string and swapping common JS→TS extensions.
+        const specifier = importDecl.getModuleSpecifierValue();
+        const guess = guessResolvedSuffix(specifier, mountFile);
+        if (guess)
+            return guess;
+    }
+    return undefined;
+}
+function pathSuffixBetween(mountFile, targetFile) {
+    // Return targetFile relative to the mount file's directory when possible.
+    // Fallback: the last 2-3 path components of the target. This just needs to
+    // be a unique trailing suffix for `routeFile.endsWith('/' + suffix)` to match.
+    const parts = targetFile.split('/');
+    const mountParts = mountFile.split('/');
+    // Find longest common prefix
+    let commonLen = 0;
+    while (commonLen < parts.length - 1 &&
+        commonLen < mountParts.length - 1 &&
+        parts[commonLen] === mountParts[commonLen]) {
+        commonLen++;
+    }
+    const tail = parts.slice(commonLen).join('/');
+    return tail || parts.slice(-2).join('/');
+}
+function guessResolvedSuffix(specifier, mountFile) {
+    if (!specifier.startsWith('.'))
+        return undefined;
+    const mountDir = mountFile.split('/').slice(0, -1).join('/');
+    const segments = [];
+    for (const seg of specifier.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..') {
+            if (mountDir.length === 0)
+                continue;
+            segments.pop();
+        }
+        else {
+            segments.push(seg);
+        }
+    }
+    if (segments.length === 0)
+        return undefined;
+    const base = segments[segments.length - 1];
+    const swapped = base.replace(/\.(js|mjs|cjs)$/i, '.ts');
+    segments[segments.length - 1] = /\.(ts|tsx)$/i.test(swapped) ? swapped : `${swapped}.ts`;
+    return segments.join('/');
+}
 // ── Next.js handlers & server actions ────────────────────────────────────
 const NEXTJS_HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
 function hasUseServerDirective(sf) {
@@ -994,12 +1136,42 @@ function extractTarget(call) {
     if (first.getKind() === SyntaxKind.StringLiteral) {
         return first.getLiteralValue();
     }
-    if (first.getKind() === SyntaxKind.TemplateExpression ||
-        first.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
-        return first.getText().substring(0, 80);
+    if (first.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+        return first.getLiteralValue();
+    }
+    if (first.getKind() === SyntaxKind.TemplateExpression) {
+        return extractTemplateUrl(first);
     }
     return undefined;
 }
+// Convert a template literal like `${API_BASE}/api/review/${slug}` into a
+// server-route-shaped path like `/api/review/:slug` so cross-stack rules can
+// correlate it against backend routes. Without this every `fetch(` \`${BASE}/…\` `)`
+// call is silently dropped by `normalizeClientUrl` (which rejects targets that
+// start with \`$ instead of \`/).
+function extractTemplateUrl(tmpl) {
+    const head = tmpl.getHead();
+    let out = head.getLiteralText();
+    const spans = tmpl.getTemplateSpans();
+    for (let i = 0; i < spans.length; i++) {
+        const span = spans[i];
+        const expr = span.getExpression();
+        const exprText = expr.getText();
+        const isBareIdent = expr.getKind() === SyntaxKind.Identifier;
+        if (i === 0 && out === '' && isBareIdent && looksLikeBaseUrlName(exprText)) {
+            // Drop a leading `${BASE_URL}` interpolation so the path starts with `/`.
+        }
+        else {
+            out += `:${isBareIdent ? exprText : 'param'}`;
+        }
+        out += span.getLiteral().getLiteralText();
+    }
+    return out.length > 0 ? out : undefined;
+}
+function looksLikeBaseUrlName(name) {
+    return (/(^|_)(base|url|host|origin|endpoint|api|server)(_|$)/i.test(name) ||
+        /(Base|Url|Host|Origin|Endpoint|Api|Server)$/.test(name));
+}
 /**
  * Given a network call (fetch/axios/…), decide whether the eventual JSON
  * payload is consumed with a type annotation, `as T` cast, or `satisfies T`
@@ -1013,7 +1185,14 @@ function extractTarget(call) {
  * the server's declared response shape as `any`). Kept intentionally
  * conservative — false positives here poison the pitch.
  */
-function isResponseAsserted(call) {
+function isResponseAsserted(call, isWrappedClientCall = false) {
+    // Generic type argument on the call itself, e.g. `apiClient.get<User>(url)`.
+    // Wrapped clients (~75% of prod apps) almost always rely on this — the
+    // wrapper pre-parses JSON and returns a typed payload, so the caller never
+    // sees a `.json()` call. Treating the generic as the assertion is the only
+    // way the `untyped-api-response` rule can fire on wrapped-client codebases.
+    if (call.getTypeArguments().length > 0)
+        return true;
     // Walk outward from the network call looking for JSON consumption. Only
     // after we've seen `.json()` (or a `.then(r => r.json())` callback) does
     // it make sense to rule the *payload* typed vs untyped — a raw Response
@@ -1022,8 +1201,14 @@ function isResponseAsserted(call) {
     // 550a57ec caught the false positive for the split pattern
     // `const res = await fetch(url); const data: User[] = await res.json();`
     // where the raw Response variable has no annotation.
+    //
+    // Wrapped clients pre-parse JSON inside the wrapper, so there's no
+    // `.json()` call to observe at the call-site. For those we treat the
+    // wrapped call itself as if JSON consumption had already happened — the
+    // payload is whatever `apiClient.get(...)` returns, and we classify the
+    // enclosing binding's type annotation directly.
     let cursor = call;
-    let sawJsonConsumption = false;
+    let sawJsonConsumption = isWrappedClientCall;
     for (let depth = 0; depth < 8; depth++) {
         const parent = cursor.getParent();
         if (!parent)
@@ -1140,6 +1325,122 @@ function extractBodyKind(call, funcName) {
     // we don't have enough info to tell without type checker dataflow.
     return undefined;
 }
+/**
+ * Derive the HTTP method of a network call. Returns uppercase method string
+ * (`GET`, `POST`, …) when confident, `undefined` when the method lives in a
+ * runtime variable we can't read statically (e.g. `axios({ method: verb })`).
+ * Feeds the `contract-method-drift` cross-stack rule.
+ *
+ * Resolution rules (in order):
+ *   1. Wrapped client (`apiClient.post(…)`) or library method (`axios.get(…)`)
+ *      → `funcName.toUpperCase()`. `funcName === 'request'` is intentionally
+ *      skipped — for `axios.request({ method })` we'd need to read the config.
+ *   2. Raw `fetch(url, { method: 'POST' })` — read the string literal. Any
+ *      spread (`{ method: 'GET', ...opts }`) downgrades to `undefined` since
+ *      we can't tell if opts overrides method at runtime.
+ *   3. Raw `fetch(url)` / `axios(url)` with no options arg → `GET` (WHATWG +
+ *      axios spec default).
+ *   4. Raw call with variable options arg → `undefined` (requires dataflow).
+ */
+function extractHttpMethod(call, funcName, isDirectNetwork, isKnownLibraryMethod, isWrappedClientCall) {
+    if (isKnownLibraryMethod || isWrappedClientCall) {
+        if (funcName === 'request')
+            return undefined;
+        return funcName.toUpperCase();
+    }
+    if (!isDirectNetwork)
+        return undefined;
+    const args = call.getArguments();
+    if (args.length < 2)
+        return 'GET';
+    const opts = args[1];
+    if (opts.getKind() === SyntaxKind.ObjectLiteralExpression) {
+        const obj = opts;
+        const hasSpread = obj.getProperties().some((p) => p.getKind() === SyntaxKind.SpreadAssignment);
+        if (hasSpread)
+            return undefined;
+        const methodProp = obj.getProperty('method');
+        if (!methodProp)
+            return 'GET';
+        if (methodProp.getKind() !== SyntaxKind.PropertyAssignment)
+            return undefined;
+        const initializer = methodProp.getInitializer();
+        if (!initializer)
+            return undefined;
+        const iKind = initializer.getKind();
+        if (iKind === SyntaxKind.StringLiteral) {
+            return initializer.getLiteralValue().toUpperCase();
+        }
+        if (iKind === SyntaxKind.NoSubstitutionTemplateLiteral) {
+            return initializer.getLiteralValue().toUpperCase();
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Detect whether a network call's options literal carries an `Authorization`
+ * header. Returns `true`/`false` when the options object is inspectable,
+ * `undefined` when it's a variable, spread, or missing. Only looks at raw
+ * `fetch(…)` — wrapped clients typically inject auth inside the wrapper.
+ * Feeds the `auth-drift` rule, which only fires when the mapper is confident.
+ */
+function extractHasAuthHeader(call, funcName) {
+    if (funcName !== 'fetch')
+        return undefined;
+    const args = call.getArguments();
+    if (args.length < 2)
+        return false;
+    const opts = args[1];
+    if (opts.getKind() !== SyntaxKind.ObjectLiteralExpression)
+        return undefined;
+    const obj = opts;
+    if (obj.getProperties().some((p) => p.getKind() === SyntaxKind.SpreadAssignment))
+        return undefined;
+    // Cookie / session auth: `fetch(url, { credentials: 'include' })` or
+    // `'same-origin'` sends session cookies without an Authorization header.
+    // We can't tell from the call alone whether the server accepts that auth
+    // channel, so downgrade to `undefined` and let auth-drift stay silent.
+    // Codex review: without this, cookie-based apps fire auth-drift on every
+    // protected route even though they're authenticated.
+    const credentialsProp = obj.getProperty('credentials');
+    if (credentialsProp && credentialsProp.getKind() === SyntaxKind.PropertyAssignment) {
+        const init = credentialsProp.getInitializer();
+        if (init) {
+            const k = init.getKind();
+            if (k === SyntaxKind.StringLiteral || k === SyntaxKind.NoSubstitutionTemplateLiteral) {
+                const v = init.getLiteralValue();
+                if (v === 'include' || v === 'same-origin')
+                    return undefined;
+            }
+            else {
+                // Runtime-computed credentials flag — can't tell.
+                return undefined;
+            }
+        }
+    }
+    const headersProp = obj.getProperty('headers');
+    if (!headersProp)
+        return false;
+    if (headersProp.getKind() !== SyntaxKind.PropertyAssignment)
+        return undefined;
+    const headersInit = headersProp.getInitializer();
+    if (!headersInit)
+        return undefined;
+    if (headersInit.getKind() !== SyntaxKind.ObjectLiteralExpression)
+        return undefined;
+    const headersObj = headersInit;
+    if (headersObj.getProperties().some((p) => p.getKind() === SyntaxKind.SpreadAssignment))
+        return undefined;
+    for (const prop of headersObj.getProperties()) {
+        if (prop.getKind() === SyntaxKind.PropertyAssignment) {
+            const pa = prop;
+            if (/^['"]?authorization['"]?$/i.test(pa.getName()))
+                return true;
+        }
+    }
+    return false;
+}
 function classifyBodyExpression(expr) {
     if (!expr)
         return undefined;
@@ -1239,4 +1540,96 @@ function containsAssertion(node) {
     }
     return false;
 }
+/**
+ * Scan `sf` for identifiers that behave like HTTP client wrappers, so that
+ * `extractEffects` can emit `effect.network` for `<name>.get/post/…` calls
+ * that would otherwise slip through the fixed NETWORK_CALLS/library-method
+ * filter.
+ *
+ * Three evidence sources (all single-file, no cross-file graph resolution):
+ *   1. Local class declarations whose bodies call a known network primitive
+ *      somewhere — that class IS a client wrapper. The class name is used
+ *      in pass 2 to mark `new <ClassName>()` instances.
+ *   2. Local variable initializers that match a client factory
+ *      (`axios.create(...)`, `ky.create(...)`, `got.extend(...)`) or
+ *      `new <ClientClass>(...)` where <ClientClass> was found in pass 1.
+ *   3. Imported identifiers from a relative / alias path whose local name
+ *      matches CLIENT_NAME_PATTERN. Third-party imports are skipped —
+ *      library HTTP clients are already covered by NETWORK_CALLS.
+ *
+ * False-positive surface is narrow on purpose: a match only translates into
+ * a network effect when the identifier is later called with `.get/post/put/
+ * patch/delete`, so a name match alone never produces a finding.
+ */
+function collectClientIdentifiers(sf) {
+    const clients = new Set();
+    // Pass 1 — wrapper classes defined in this file.
+    const clientClassNames = new Set();
+    for (const cls of sf.getDescendantsOfKind(SyntaxKind.ClassDeclaration)) {
+        if (classCallsNetwork(cls)) {
+            const name = cls.getName();
+            if (name)
+                clientClassNames.add(name);
+        }
+    }
+    // Pass 2 — local instances: `const api = axios.create(...)`, `new ApiClient()`.
+    for (const decl of sf.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+        const nameNode = decl.getNameNode();
+        if (nameNode.getKind() !== SyntaxKind.Identifier)
+            continue;
+        const init = decl.getInitializer();
+        if (!init)
+            continue;
+        const identName = nameNode.getText();
+        if (init.getKind() === SyntaxKind.NewExpression) {
+            const className = init.getExpression().getText();
+            if (clientClassNames.has(className))
+                clients.add(identName);
+            continue;
+        }
+        if (init.getKind() === SyntaxKind.CallExpression) {
+            const calleeText = init.getExpression().getText();
+            if (CLIENT_FACTORY_CALLS.has(calleeText))
+                clients.add(identName);
+        }
+    }
+    // Pass 3 — imported clients with client-shaped names from local paths.
+    for (const imp of sf.getImportDeclarations()) {
+        const spec = imp.getModuleSpecifierValue();
+        if (!spec)
+            continue;
+        const isLocal = spec.startsWith('.') || spec.startsWith('@/') || spec.startsWith('~/') || spec.startsWith('@shared/');
+        if (!isLocal)
+            continue;
+        for (const named of imp.getNamedImports()) {
+            const local = named.getAliasNode()?.getText() ?? named.getNameNode().getText();
+            if (CLIENT_NAME_PATTERN.test(local))
+                clients.add(local);
+        }
+        const def = imp.getDefaultImport();
+        if (def && CLIENT_NAME_PATTERN.test(def.getText()))
+            clients.add(def.getText());
+    }
+    return clients;
+}
+function classCallsNetwork(cls) {
+    for (const call of cls.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const callee = call.getExpression();
+        const k = callee.getKind();
+        if (k === SyntaxKind.Identifier) {
+            if (NETWORK_CALLS.has(callee.getText()))
+                return true;
+            continue;
+        }
+        if (k === SyntaxKind.PropertyAccessExpression) {
+            const pa = callee;
+            const methodName = pa.getName();
+            const objText = pa.getExpression().getText();
+            if (NETWORK_METHODS.has(methodName) && /^(axios|got|ky|superagent|request|http)$/.test(objText)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 //# sourceMappingURL=ts-concepts.js.map