@kernlang/review 3.4.2 → 3.4.3-canary.11.1.8a8b6d69

package/dist/mappers/ts-concepts.js

@@ -5,7 +5,7 @@
  * Phase 2: entrypoint, guard, state_mutation, call, dependency
  */
 import { conceptId, conceptSpan } from '@kernlang/core';
-import { SyntaxKind } from 'ts-morph';
+import { SyntaxKind, VariableDeclarationKind } from 'ts-morph';
 const EXTRACTOR_VERSION = '1.0.0';
 // ── Network effect signatures ────────────────────────────────────────────
 const NETWORK_CALLS = new Set(['fetch', 'axios', 'got', 'request', 'superagent', 'ky']);
@@ -282,6 +282,7 @@ function hasIntentComment(text) {
 // ── effect ───────────────────────────────────────────────────────────────
 function extractEffects(sf, filePath, nodes) {
     const clientIdents = collectClientIdentifiers(sf);
+    const constLiterals = buildConstLiteralMap(sf);
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
         const callee = call.getExpression();
         let funcName = '';
@@ -300,8 +301,9 @@ function extractEffects(sf, filePath, nodes) {
         const isWrappedClientCall = CLIENT_HTTP_METHODS.has(funcName) && clientIdents.has(objName);
         if (isDirectNetwork || isKnownLibraryMethod || isWrappedClientCall) {
             const isAsync = isInAsyncContext(call);
+            const target = extractTarget(call, constLiterals);
             const sentFieldsInfo = extractSentFields(call, funcName);
-            const queryParamsInfo = extractQueryParams(call);
+            const queryParamsInfo = extractQueryParams(call, constLiterals);
             const hasAuthHeader = extractHasAuthHeader(call, funcName);
             nodes.push({
                 id: conceptId(filePath, 'effect', call.getStart()),
@@ -315,13 +317,16 @@ function extractEffects(sf, filePath, nodes) {
                     kind: 'effect',
                     subtype: 'network',
                     async: isAsync,
-                    target: extractTarget(call),
+                    target,
+                    host: extractHost(target),
+                    handledErrorStatusCodes: extractHandledErrorStatusCodes(call),
                     responseAsserted: isResponseAsserted(call, isWrappedClientCall),
                     bodyKind: extractBodyKind(call, funcName),
                     method: extractHttpMethod(call, funcName, isDirectNetwork, isKnownLibraryMethod, isWrappedClientCall),
                     hasAuthHeader,
                     sentFields: sentFieldsInfo.fields,
                     sentFieldsResolved: sentFieldsInfo.resolved,
+                    sentFieldTypes: sentFieldsInfo.types,
                     handlesApiErrors: extractHandlesApiErrors(call, isWrappedClientCall),
                     authPropagation: extractAuthPropagation(call, funcName, objName, isWrappedClientCall, hasAuthHeader),
                     queryParams: queryParamsInfo.params,
@@ -1494,16 +1499,10 @@ function isInAsyncContext(node) {
     }
     return false;
 }
-// Extract the field names a network call sends on the wire. High-confidence
-// sources:
-//   - literal objects: `JSON.stringify({ a, b })`, `axios.post(url, { a, b })`
-//   - typed payload variables: `JSON.stringify(input)` where `input: CreateUser`
-// Everything else returns `{ fields: undefined, resolved: false }` so
-// body-shape-drift stays silent on opaque shapes rather than guessing.
 function extractSentFields(call, funcName) {
     const payload = extractNetworkPayloadExpression(call, funcName);
     if (!payload)
-        return { fields: undefined, resolved: false };
+        return { fields: undefined, resolved: false, types: undefined };
     return extractPayloadFields(payload);
 }
 function extractNetworkPayloadExpression(call, funcName) {
@@ -1532,10 +1531,11 @@ function extractPayloadFields(node) {
     const payload = unwrapPayloadExpression(node);
     if (payload.getKind() === SyntaxKind.CallExpression) {
         const bodyCall = payload;
-        if (bodyCall.getExpression().getText() !== 'JSON.stringify')
-            return { fields: undefined, resolved: false };
+        if (bodyCall.getExpression().getText() !== 'JSON.stringify') {
+            return { fields: undefined, resolved: false, types: undefined };
+        }
         const stringifyArg = bodyCall.getArguments()[0];
-        return stringifyArg ? extractPayloadFields(stringifyArg) : { fields: undefined, resolved: false };
+        return stringifyArg ? extractPayloadFields(stringifyArg) : { fields: undefined, resolved: false, types: undefined };
     }
     if (payload.getKind() === SyntaxKind.ObjectLiteralExpression) {
         return extractLiteralObjectFields(payload);
@@ -1543,7 +1543,7 @@ function extractPayloadFields(node) {
     if (payload.getKind() === SyntaxKind.Identifier || payload.getKind() === SyntaxKind.PropertyAccessExpression) {
         return extractObjectFieldsFromType(payload);
     }
-    return { fields: undefined, resolved: false };
+    return { fields: undefined, resolved: false, types: undefined };
 }
 function unwrapPayloadExpression(node) {
     let current = node;
@@ -1571,26 +1571,91 @@ function unwrapPayloadExpression(node) {
 }
 function extractObjectFieldsFromType(node) {
     const type = node.getType();
-    if (type.isAny() || type.isUnknown() || type.isUnion())
-        return { fields: undefined, resolved: false };
-    if (type.getStringIndexType() || type.getNumberIndexType())
-        return { fields: undefined, resolved: false };
+    if (type.isAny() || type.isUnknown() || type.isUnion()) {
+        return { fields: undefined, resolved: false, types: undefined };
+    }
+    if (type.getStringIndexType() || type.getNumberIndexType()) {
+        return { fields: undefined, resolved: false, types: undefined };
+    }
     const fields = new Set();
+    const types = {};
     for (const prop of type.getProperties()) {
         const declarations = prop.getDeclarations();
         if (declarations.length === 0)
-            return { fields: undefined, resolved: false };
+            return { fields: undefined, resolved: false, types: undefined };
         if (declarations.some((decl) => isExternalSourcePath(decl.getSourceFile().getFilePath()))) {
-            return { fields: undefined, resolved: false };
+            return { fields: undefined, resolved: false, types: undefined };
         }
         if (declarations.some((decl) => declarationIsOptional(decl)))
             continue;
         const name = prop.getName();
         if (!/^[A-Za-z_$][\w$-]*$/.test(name))
-            return { fields: undefined, resolved: false };
+            return { fields: undefined, resolved: false, types: undefined };
         fields.add(name);
+        // Coarse type tag from the property's TS type at the use site.
+        const propType = prop.getTypeAtLocation(node);
+        types[name] = coarsenTsType(propType);
+    }
+    if (fields.size === 0) {
+        return { fields: [], resolved: true, types: {} };
+    }
+    return { fields: Array.from(fields).sort(), resolved: true, types };
+}
+// Map a ts-morph Type to a coarse tag. Conservative: anything we don't
+// recognise becomes 'unknown' rather than silently dropped — body-shape-drift
+// can then choose to skip 'unknown' tags or treat them as wildcards.
+function coarsenTsType(type) {
+    if (type.isAny() || type.isUnknown() || type.isNever())
+        return 'unknown';
+    if (type.isString() || type.isStringLiteral())
+        return 'string';
+    if (type.isNumber() || type.isNumberLiteral())
+        return 'number';
+    if (type.isBoolean() || type.isBooleanLiteral())
+        return 'boolean';
+    if (type.isNull())
+        return 'null';
+    // Bare `undefined` is NOT 'null' on the wire — `JSON.stringify({x: undefined})`
+    // omits the key entirely. We tag it `unknown` so downstream rules don't
+    // confuse it with an explicit-null field. Codex review caught this.
+    if (type.isUndefined())
+        return 'unknown';
+    if (type.isArray() || type.isTuple())
+        return 'array';
+    if (type.isUnion()) {
+        // Drop nullability branches (`T | null | undefined → T`) before
+        // coarsening — `null`/`undefined` are absorbed since the rule's question
+        // is "what is the shape of the present value?" not "is the field
+        // optional?". Then if the remaining branches all coarsen to one tag,
+        // return it; else `unknown`.
+        const branches = type.getUnionTypes().filter((t) => !t.isNull() && !t.isUndefined());
+        if (branches.length === 0)
+            return 'null';
+        if (branches.length === 1)
+            return coarsenTsType(branches[0]);
+        const tags = new Set(branches.map(coarsenTsType));
+        if (tags.size === 1)
+            return [...tags][0];
+        return 'unknown';
+    }
+    // Branded primitives (`string & { __brand: 'UserId' }`) are very common
+    // for ID/count types. We walk the intersection branches: if any branch
+    // coarsens to a primitive, take that tag — the brand is structural noise
+    // we don't need on the wire. Codex review caught the original
+    // implementation collapsing brands to 'unknown'.
+    if (type.isIntersection()) {
+        const branchTags = type.getIntersectionTypes().map(coarsenTsType);
+        for (const tag of branchTags) {
+            if (tag === 'string' || tag === 'number' || tag === 'boolean')
+                return tag;
+        }
+        if (branchTags.every((t) => t === 'object'))
+            return 'object';
+        return 'unknown';
     }
-    return fields.size > 0 ? { fields: Array.from(fields).sort(), resolved: true } : { fields: [], resolved: true };
+    if (type.isObject())
+        return 'object';
+    return 'unknown';
 }
 function declarationIsOptional(decl) {
     const maybeOptional = decl;
@@ -1602,33 +1667,282 @@ function declarationIsOptional(decl) {
 // produce false positives downstream.
 function extractLiteralObjectFields(obj) {
     const fields = [];
+    const types = {};
     for (const prop of obj.getProperties()) {
         const kind = prop.getKind();
         if (kind === SyntaxKind.SpreadAssignment)
-            return { fields: undefined, resolved: false };
+            return { fields: undefined, resolved: false, types: undefined };
         if (kind === SyntaxKind.PropertyAssignment) {
-            const name = prop.getNameNode();
-            if (name.getKind() === SyntaxKind.ComputedPropertyName)
-                return { fields: undefined, resolved: false };
+            const pa = prop;
+            const name = pa.getNameNode();
+            if (name.getKind() === SyntaxKind.ComputedPropertyName) {
+                return { fields: undefined, resolved: false, types: undefined };
+            }
             if (name.getKind() === SyntaxKind.Identifier || name.getKind() === SyntaxKind.StringLiteral) {
-                fields.push(name.getText().replace(/['"]/g, ''));
+                const fieldName = name.getText().replace(/['"]/g, '');
+                fields.push(fieldName);
+                // Type tag from the value expression. Tries syntactic recognition
+                // first (cheap, exact for literals), then falls back to TS type
+                // inference for variables / property accesses.
+                const init = pa.getInitializer();
+                types[fieldName] = init ? coarsenValueExpression(init) : 'unknown';
             }
             else {
-                return { fields: undefined, resolved: false };
+                return { fields: undefined, resolved: false, types: undefined };
             }
         }
         else if (kind === SyntaxKind.ShorthandPropertyAssignment) {
-            fields.push(prop.getName());
+            const sh = prop;
+            const fieldName = sh.getName();
+            fields.push(fieldName);
+            // Shorthand: `{ foo }` is sugar for `{ foo: foo }`. Use the binding's
+            // inferred TS type at this location.
+            const ident = sh.getNameNode();
+            types[fieldName] = coarsenTsType(ident.getType());
         }
         else {
             // Method definitions, getters, setters — unusual in a fetch body,
             // treat as unresolved.
-            return { fields: undefined, resolved: false };
+            return { fields: undefined, resolved: false, types: undefined };
+        }
+    }
+    return { fields, resolved: true, types };
+}
+// Coarsen the value-expression of a literal object property. Syntactic
+// fast paths cover the common literal cases without invoking the TS type
+// checker; everything else falls through to type-based coarsening.
+function coarsenValueExpression(expr) {
+    const k = expr.getKind();
+    if (k === SyntaxKind.StringLiteral ||
+        k === SyntaxKind.NoSubstitutionTemplateLiteral ||
+        k === SyntaxKind.TemplateExpression) {
+        return 'string';
+    }
+    if (k === SyntaxKind.NumericLiteral)
+        return 'number';
+    if (k === SyntaxKind.TrueKeyword || k === SyntaxKind.FalseKeyword)
+        return 'boolean';
+    if (k === SyntaxKind.NullKeyword)
+        return 'null';
+    if (k === SyntaxKind.ObjectLiteralExpression)
+        return 'object';
+    if (k === SyntaxKind.ArrayLiteralExpression)
+        return 'array';
+    // PrefixUnary: the unary operator dictates the result type, NOT the
+    // operand. `+x`, `-x`, `~x` always yield number even if x is a string
+    // (`+'1'` is type `number`); `!x` always yields boolean. Recursing into
+    // the operand would lie. Codex review caught this.
+    if (k === SyntaxKind.PrefixUnaryExpression) {
+        const op = expr.getOperatorToken();
+        if (op === SyntaxKind.PlusToken || op === SyntaxKind.MinusToken || op === SyntaxKind.TildeToken) {
+            return 'number';
+        }
+        if (op === SyntaxKind.ExclamationToken) {
+            return 'boolean';
+        }
+        // Unknown prefix operator — fall through to TS type checker.
+        return coarsenTsType(expr.getType());
+    }
+    // Parenthesized / as-cast / non-null: unwrap and recurse.
+    if (k === SyntaxKind.ParenthesizedExpression) {
+        return coarsenValueExpression(expr.getExpression());
+    }
+    if (k === SyntaxKind.AsExpression) {
+        return coarsenValueExpression(expr.getExpression());
+    }
+    if (k === SyntaxKind.NonNullExpression) {
+        return coarsenValueExpression(expr.getExpression());
+    }
+    // Fallback: ask the TS type checker. Catches `Identifier`,
+    // `PropertyAccessExpression`, `ConditionalExpression` (`x ?? null`),
+    // `BinaryExpression`, etc.
+    return coarsenTsType(expr.getType());
+}
+function declKey(decl) {
+    return `${decl.getSourceFile().getFilePath()}:${decl.getStart()}`;
+}
+// Extract a literal string from a const initializer. Handles:
+//   const X = 'lit';
+//   const X = `lit`;                                 (no substitutions)
+//   const X = process.env.FOO || 'fallback';         (env-with-fallback)
+//   const X = process.env.FOO ?? 'fallback';         (nullish-coalescing)
+//
+// The `||` / `??` fallback case is the dominant real-world shape — audiofacets
+// has 10+ `const API_URL = process.env.X || "https://..."` sites that the
+// pure-literal collector silently dropped. Resolution captures the FALLBACK
+// branch as the "no-env-set" value. At runtime when env IS set the URL
+// differs, but for cross-stack matching the path part is identical and
+// `host` is "best effort, stay silent if not absolute" anyway.
+//
+// Conservative: only the right-hand side of `||`/`??` is taken as the literal.
+// Chained `a || b || 'lit'` bails (right is BinaryExpression, not literal).
+// Ternaries and other shapes stay out of scope.
+function literalStringFromInit(init) {
+    if (init.getKind() === SyntaxKind.StringLiteral) {
+        return init.getLiteralValue();
+    }
+    if (init.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+        return init.getLiteralValue();
+    }
+    if (init.getKind() === SyntaxKind.BinaryExpression) {
+        const bin = init;
+        const op = bin.getOperatorToken().getKind();
+        if (op === SyntaxKind.BarBarToken || op === SyntaxKind.QuestionQuestionToken) {
+            const right = bin.getRight();
+            if (right.getKind() === SyntaxKind.StringLiteral) {
+                return right.getLiteralValue();
+            }
+            if (right.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+                return right.getLiteralValue();
+            }
         }
     }
-    return { fields, resolved: true };
+    return undefined;
+}
+function buildConstLiteralMap(sf) {
+    const candidates = [];
+    for (const decl of sf.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+        const stmt = decl.getVariableStatement();
+        if (!stmt)
+            continue;
+        if (stmt.getDeclarationKind() !== VariableDeclarationKind.Const)
+            continue;
+        if (decl.getNameNode().getKind() !== SyntaxKind.Identifier)
+            continue; // skip destructure
+        const init = decl.getInitializer();
+        if (!init)
+            continue;
+        candidates.push({ decl, key: declKey(decl), init });
+    }
+    const direct = new Map();
+    for (const { key, init } of candidates) {
+        const lit = literalStringFromInit(init);
+        if (lit !== undefined)
+            direct.set(key, lit);
+    }
+    // Pass 2: template-with-refs against pass 1. One hop — no transitive
+    // resolution. A `const A = \`\${B}/x\`` whose `B` is itself a
+    // template-with-refs won't resolve here; that's a phase-1 cap.
+    const all = new Map(direct);
+    for (const { key, init } of candidates) {
+        if (init.getKind() !== SyntaxKind.TemplateExpression)
+            continue;
+        const lit = resolveTemplateAgainst(init, direct);
+        if (lit !== undefined)
+            all.set(key, lit);
+    }
+    return all;
 }
-function extractTarget(call) {
+function resolveTemplateAgainst(tmpl, map) {
+    let out = tmpl.getHead().getLiteralText();
+    for (const span of tmpl.getTemplateSpans()) {
+        const expr = span.getExpression();
+        if (expr.getKind() !== SyntaxKind.Identifier)
+            return undefined;
+        const inner = lookupConstLiteral(expr, map);
+        if (inner === undefined)
+            return undefined;
+        out += inner;
+        out += span.getLiteral().getLiteralText();
+    }
+    return out;
+}
+// Symbol-based lookup. Resolves the identifier to its binding via the TS
+// type checker, then checks whether that binding is a literal const we
+// collected. Returns `undefined` for any identifier that does NOT bind to
+// a single same-file VariableDeclaration in the map — including parameters,
+// `let` / `var`, function names, and shadowing declarations. (Phase 2A
+// extends this to follow named imports from relative paths to a sibling
+// source file.)
+//
+// Same-file filter on the in-file declarations: TypeScript's symbol for a
+// name that shadows a global (e.g. `URL`, `Request`, `Response`) returns
+// BOTH the local declaration AND the lib.dom.d.ts ambient. We only care
+// about the in-file declaration; the lib ambient never has a literal value.
+function lookupConstLiteral(ident, map) {
+    const sym = ident.getSymbol();
+    if (!sym)
+        return undefined;
+    const sfPath = ident.getSourceFile().getFilePath();
+    const inFile = [];
+    const importSpecs = [];
+    for (const d of sym.getDeclarations()) {
+        if (d.getSourceFile().getFilePath() !== sfPath)
+            continue;
+        const k = d.getKind();
+        if (k === SyntaxKind.VariableDeclaration) {
+            inFile.push(d);
+        }
+        else if (k === SyntaxKind.ImportSpecifier) {
+            importSpecs.push(d);
+        }
+    }
+    // Same-file binding wins (phase 1 path).
+    if (inFile.length === 1 && importSpecs.length === 0) {
+        return map.get(declKey(inFile[0]));
+    }
+    // Phase 2A: cross-file named import. Single ImportSpecifier in this file,
+    // no in-file VariableDeclaration. Follow the import to its source.
+    if (importSpecs.length === 1 && inFile.length === 0) {
+        return resolveImportedConst(importSpecs[0]);
+    }
+    return undefined;
+}
+// Phase 2A: follow `import { X } from './c'` to the source file and resolve
+// the imported const. Same FP gates as phase 1: the source decl must be a
+// single exported `const X = <literal>` (or env-fallback / no-sub template
+// or template-with-refs against the source file's own const map).
+//
+// Out of scope (phase 2A):
+//   - Default imports (`import X from './c'`)
+//   - Namespace imports (`import * as M from './c'; M.X`)
+//   - Non-relative module specifiers (`react`, `@/lib/x`, `@shared/y`)
+//   - Re-export chains beyond what ts-morph's symbol resolver already follows
+function resolveImportedConst(spec) {
+    const imp = spec.getImportDeclaration();
+    const moduleSpec = imp.getModuleSpecifierValue();
+    if (!moduleSpec)
+        return undefined;
+    if (!moduleSpec.startsWith('./') && !moduleSpec.startsWith('../'))
+        return undefined;
+    const srcSf = imp.getModuleSpecifierSourceFile();
+    if (!srcSf)
+        return undefined;
+    // The imported name as declared in the source module. `import { X as Y }`
+    // means we look for `X` in the source, regardless of `Y` alias here.
+    const importedName = spec.getNameNode().getText();
+    for (const decl of srcSf.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+        if (decl.getNameNode().getKind() !== SyntaxKind.Identifier)
+            continue;
+        if (decl.getName() !== importedName)
+            continue;
+        const stmt = decl.getVariableStatement();
+        if (!stmt)
+            continue;
+        if (stmt.getDeclarationKind() !== VariableDeclarationKind.Const)
+            continue;
+        if (!stmt.isExported())
+            continue;
+        const init = decl.getInitializer();
+        if (!init)
+            return undefined;
+        // Direct literal / no-sub template / env-fallback.
+        const direct = literalStringFromInit(init);
+        if (direct !== undefined)
+            return direct;
+        // Template-with-refs in the SOURCE file's scope. Build that file's own
+        // const map and resolve the template against it. resolveTemplateAgainst
+        // recurses through lookupConstLiteral, so chained imports
+        // (`c.ts → d.ts`) work via the same gate.
+        if (init.getKind() === SyntaxKind.TemplateExpression) {
+            const srcMap = buildConstLiteralMap(srcSf);
+            return resolveTemplateAgainst(init, srcMap);
+        }
+        return undefined;
+    }
+    return undefined;
+}
+function extractTarget(call, consts) {
     const args = call.getArguments();
     if (args.length === 0)
         return undefined;
@@ -1640,12 +1954,116 @@ function extractTarget(call) {
         return first.getLiteralValue();
     }
     if (first.getKind() === SyntaxKind.TemplateExpression) {
-        return extractTemplateUrl(first);
+        return extractTemplateUrl(first, consts);
+    }
+    if (first.getKind() === SyntaxKind.Identifier && consts) {
+        return lookupConstLiteral(first, consts);
     }
     return undefined;
 }
-function extractQueryParams(call) {
-    const target = extractTarget(call);
+// Phase 1 of surface-fingerprinting: pull the host out of an absolute URL so
+// downstream cross-stack rules can later filter third-party calls (e.g. a
+// frontend `fetch` to `stripe.com/api/charges` shouldn't match against the
+// partner backend's `/api/charges` route). Phase 2 will use this — phase 1
+// only captures it.
+//
+// Accepts the already-extracted target string (lit / no-substitution / template
+// post-extraction). Rejects targets where the host slot is a placeholder like
+// `:HOST` produced by `extractTemplateUrl` from `https://${HOST}/...` — those
+// aren't real DNS names. Returns the host lower-cased so case-insensitive
+// comparison is free downstream.
+const HOST_LIKE_RE = /^[a-z0-9][a-z0-9.-]*(:[0-9]+)?$/i;
+function extractHost(target) {
+    if (!target)
+        return undefined;
+    if (!target.startsWith('http://') && !target.startsWith('https://'))
+        return undefined;
+    const hostStart = target.indexOf('://') + 3;
+    const pathStart = target.indexOf('/', hostStart);
+    const host = pathStart === -1 ? target.slice(hostStart) : target.slice(hostStart, pathStart);
+    if (!HOST_LIKE_RE.test(host))
+        return undefined;
+    return host.toLowerCase();
+}
+// Phase 1 of error-contract-drift: pull the literal status codes the
+// call-site EXPLICITLY branches on. Phase 2 will compare these against
+// the server's `errorStatusCodes` to flag PRs that introduce a server
+// status the client doesn't handle.
+//
+// Buddies' converged 0.9 gate: ONLY explicit status-dispatch counts.
+// Generic `catch (e) { log(e) }` and `if (!response.ok) {…}` checks do
+// not — those treat every failure identically and are not contract
+// evidence. We walk a bounded distance from the network call (the
+// enclosing function), look for `<X>.status === N` and `case N:` in
+// switches over `<X>.status`, where `<X>` is any expression — keeping
+// it permissive on the receiver lets us catch the common patterns
+// (`response.status`, `err.status`, `err.response.status`,
+// `result.status`) without trying to bind the response variable back
+// to this specific call.
+//
+// Returns:
+//   - empty array — saw the call, walked the scope, found no explicit
+//     status branch (the call-site is generic-handle-only).
+//   - non-empty sorted array — explicit codes the call-site branches on.
+//   - undefined — analysis was inconclusive (no enclosing function /
+//     scope walk wasn't safe).
+const STATUS_PROP_RE = /(?:^|\.)status$/;
+const STATUS_LIKELY_RECEIVER_RE = /\b(res|response|reply|err|error|e|ex|result|r)\b/i;
+function extractHandledErrorStatusCodes(call) {
+    const enclosing = call.getFirstAncestorByKind(SyntaxKind.FunctionDeclaration) ??
+        call.getFirstAncestorByKind(SyntaxKind.ArrowFunction) ??
+        call.getFirstAncestorByKind(SyntaxKind.FunctionExpression) ??
+        call.getFirstAncestorByKind(SyntaxKind.MethodDeclaration);
+    if (!enclosing)
+        return undefined;
+    const codes = new Set();
+    // Pattern 1: binary `===` / `==` of a `<X>.status` against a numeric literal.
+    for (const bin of enclosing.getDescendantsOfKind(SyntaxKind.BinaryExpression)) {
+        const op = bin.getOperatorToken().getText();
+        if (op !== '===' && op !== '==')
+            continue;
+        const left = bin.getLeft();
+        const right = bin.getRight();
+        const code = numericLiteralValue(left) ?? numericLiteralValue(right);
+        if (code === undefined)
+            continue;
+        const other = code === numericLiteralValue(left) ? right : left;
+        if (!isStatusPropertyAccess(other))
+            continue;
+        codes.add(code);
+    }
+    // Pattern 2: `case N:` inside a `switch (<X>.status) {…}`.
+    for (const sw of enclosing.getDescendantsOfKind(SyntaxKind.SwitchStatement)) {
+        const expr = sw.getExpression();
+        if (!isStatusPropertyAccess(expr))
+            continue;
+        for (const caseClause of sw.getDescendantsOfKind(SyntaxKind.CaseClause)) {
+            const code = numericLiteralValue(caseClause.getExpression());
+            if (code !== undefined)
+                codes.add(code);
+        }
+    }
+    return Array.from(codes).sort((a, b) => a - b);
+}
+// Recogniser for `<expr>.status` shape. The `<expr>` is intentionally
+// loose — we accept any property access whose final property name is
+// `status` AND whose receiver text mentions a known response/error
+// identifier somewhere. That accepts `response.status`, `err.status`,
+// `err.response.status`, `result.status`, `e.response?.status`, …
+// without binding to the specific response variable from THIS call.
+// False-positive tax: a stray `obj.status === 200` for some unrelated
+// object would count, but the `STATUS_LIKELY_RECEIVER_RE` filter on
+// the receiver text keeps it tight.
+function isStatusPropertyAccess(node) {
+    if (!node)
+        return false;
+    const text = node.getText();
+    if (!STATUS_PROP_RE.test(text.replace(/\?\./g, '.')))
+        return false;
+    return STATUS_LIKELY_RECEIVER_RE.test(text);
+}
+function extractQueryParams(call, consts) {
+    const target = extractTarget(call, consts);
     if (!target)
         return { params: undefined, resolved: false };
     const q = target.indexOf('?');
@@ -1672,7 +2090,7 @@ function extractQueryParams(call) {
 // 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) {
+function extractTemplateUrl(tmpl, consts) {
     const head = tmpl.getHead();
     let out = head.getLiteralText();
     const spans = tmpl.getTemplateSpans();
@@ -1681,6 +2099,20 @@ function extractTemplateUrl(tmpl) {
         const expr = span.getExpression();
         const exprText = expr.getText();
         const isBareIdent = expr.getKind() === SyntaxKind.Identifier;
+        // Phase 1 const resolution: substitute `${IDENT}` with its same-file literal
+        // value when the symbol-resolved binding is a literal const we collected.
+        // Lifts host extraction and route matching on the common
+        // `${API_BASE}/users/${id}` shape. Symbol-based (not name-based) so that
+        // a shadowing parameter / `let` / inner non-literal const cannot
+        // fabricate a wrong absolute URL.
+        if (isBareIdent && consts) {
+            const resolved = lookupConstLiteral(expr, consts);
+            if (resolved !== undefined) {
+                out += resolved;
+                out += span.getLiteral().getLiteralText();
+                continue;
+            }
+        }
         if (i === 0 && out === '' && isBareIdent && looksLikeBaseUrlName(exprText)) {
             // Drop a leading `${BASE_URL}` interpolation so the path starts with `/`.
         }