@kernlang/review 3.3.8 → 3.4.0

package/dist/mappers/ts-concepts.js

@@ -49,6 +49,32 @@ const DB_CALLS = new Set([
     'findOne',
     'countDocuments',
 ]);
+const DB_COLLECTION_READ_CALLS = new Set([
+    'findMany',
+    'find',
+    'select',
+    'query',
+    'aggregate',
+    'toArray',
+    'all',
+    'fetchAll',
+]);
+const DB_WRITE_CALLS = new Set([
+    'create',
+    'createMany',
+    'insert',
+    'insertOne',
+    'insertMany',
+    'update',
+    'updateMany',
+    'updateOne',
+    'delete',
+    'deleteMany',
+    'deleteOne',
+    'remove',
+    'save',
+    'upsert',
+]);
 const FS_CALLS = new Set([
     'readFile',
     'readFileSync',
@@ -274,6 +300,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 sentFieldsInfo = extractSentFields(call, funcName);
+            const queryParamsInfo = extractQueryParams(call);
+            const hasAuthHeader = extractHasAuthHeader(call, funcName);
             nodes.push({
                 id: conceptId(filePath, 'effect', call.getStart()),
                 kind: 'effect',
@@ -290,7 +319,13 @@ function extractEffects(sf, filePath, nodes) {
                     responseAsserted: isResponseAsserted(call, isWrappedClientCall),
                     bodyKind: extractBodyKind(call, funcName),
                     method: extractHttpMethod(call, funcName, isDirectNetwork, isKnownLibraryMethod, isWrappedClientCall),
-                    hasAuthHeader: extractHasAuthHeader(call, funcName),
+                    hasAuthHeader,
+                    sentFields: sentFieldsInfo.fields,
+                    sentFieldsResolved: sentFieldsInfo.resolved,
+                    handlesApiErrors: extractHandlesApiErrors(call, isWrappedClientCall),
+                    authPropagation: extractAuthPropagation(call, funcName, objName, isWrappedClientCall, hasAuthHeader),
+                    queryParams: queryParamsInfo.params,
+                    queryParamsResolved: queryParamsInfo.resolved,
                 },
             });
             continue;
@@ -353,6 +388,23 @@ function extractEntrypoints(sf, filePath, nodes) {
         if (args[0].getKind() === SyntaxKind.StringLiteral) {
             routePath = args[0].getLiteralValue();
         }
+        // Inline, same-file named, or statically imported handler. The id we
+        // compute for same-file handlers must match the function_declaration
+        // concept emitted for the same function, so downstream rules can
+        // dereference `handlerConceptId`. Imported handlers are still analyzed
+        // when TypeScript can resolve their body, but are not linked into this
+        // file's concept map.
+        const resolvedHandler = resolveExpressRouteHandler(args, filePath);
+        const handlerFn = resolvedHandler?.fn;
+        const handlerConceptId = resolvedHandler && isSameConceptSourceFile(resolvedHandler.conceptFilePath, filePath)
+            ? conceptId(filePath, 'function_declaration', resolvedHandler.conceptStart)
+            : undefined;
+        const bodyFieldsInfo = handlerFn
+            ? extractHandlerBodyFields(handlerFn)
+            : { fields: undefined, resolved: false };
+        const routeAnalysis = handlerFn
+            ? analyzeExpressRouteHandler(handlerFn, args, methodName.toUpperCase(), routePath)
+            : EMPTY_ROUTE_ANALYSIS;
         nodes.push({
             id: conceptId(filePath, 'entrypoint', call.getStart()),
             kind: 'entrypoint',
@@ -366,6 +418,16 @@ function extractEntrypoints(sf, filePath, nodes) {
                 subtype: 'route',
                 name: routePath || methodName,
                 httpMethod: methodName.toUpperCase(),
+                handlerConceptId,
+                bodyFields: bodyFieldsInfo.fields,
+                bodyFieldsResolved: bodyFieldsInfo.resolved,
+                errorStatusCodes: routeAnalysis.errorStatusCodes,
+                hasUnboundedCollectionQuery: routeAnalysis.hasUnboundedCollectionQuery,
+                hasDbWrite: routeAnalysis.hasDbWrite,
+                hasIdempotencyProtection: routeAnalysis.hasIdempotencyProtection,
+                hasBodyValidation: routeAnalysis.hasBodyValidation,
+                validatedBodyFields: routeAnalysis.validatedBodyFields,
+                bodyValidationResolved: routeAnalysis.bodyValidationResolved,
             },
         });
     }
@@ -400,6 +462,235 @@ function extractEntrypoints(sf, filePath, nodes) {
         }
     }
 }
+const EMPTY_ROUTE_ANALYSIS = {};
+const API_ERROR_STATUS_CODES = new Set([401, 403, 404, 422, 500]);
+const PAGINATION_RE = /\b(limit|take|offset|skip|cursor|page|pageSize|perPage)\b|\.limit\s*\(|\.take\s*\(/i;
+const IDEMPOTENCY_RE = /\b(idempotency|Idempotency-Key|transaction|\$transaction|unique|upsert|findUnique|findOne|on\s+conflict|getOrCreate|createOrGet)\b/i;
+function analyzeExpressRouteHandler(handlerFn, routeArgs, method, routePath) {
+    const text = handlerFn.getText();
+    const errorStatusCodes = extractExpressErrorStatusCodes(handlerFn);
+    const validation = extractExpressValidation(handlerFn, routeArgs);
+    return {
+        errorStatusCodes,
+        hasUnboundedCollectionQuery: hasUnboundedExpressCollectionQuery(handlerFn, method, routePath),
+        hasDbWrite: handlerHasDbWrite(handlerFn),
+        hasIdempotencyProtection: IDEMPOTENCY_RE.test(text),
+        hasBodyValidation: validation.has,
+        validatedBodyFields: validation.fields,
+        bodyValidationResolved: validation.resolved,
+    };
+}
+function resolveExpressRouteHandler(routeArgs, filePath) {
+    for (let i = routeArgs.length - 1; i >= 1; i--) {
+        const arg = routeArgs[i];
+        const kind = arg.getKind();
+        if (kind === SyntaxKind.ArrowFunction || kind === SyntaxKind.FunctionExpression) {
+            return {
+                fn: arg,
+                conceptStart: arg.getStart(),
+                conceptFilePath: filePath,
+            };
+        }
+        if (kind !== SyntaxKind.Identifier)
+            continue;
+        const resolved = resolveHandlerIdentifier(arg);
+        if (resolved)
+            return resolved;
+    }
+    return undefined;
+}
+function resolveHandlerIdentifier(ident) {
+    const symbol = ident.getSymbol();
+    if (!symbol)
+        return undefined;
+    for (const candidate of expandIdentifierSymbols(symbol)) {
+        for (const decl of candidate.getDeclarations()) {
+            const conceptFilePath = decl.getSourceFile().getFilePath();
+            if (isExternalSourcePath(conceptFilePath))
+                continue;
+            if (decl.getKind() === SyntaxKind.FunctionDeclaration) {
+                const fn = decl;
+                return { fn, conceptStart: fn.getStart(), conceptFilePath };
+            }
+            if (decl.getKind() !== SyntaxKind.VariableDeclaration)
+                continue;
+            const varDecl = decl;
+            const init = varDecl.getInitializer();
+            if (!init)
+                continue;
+            const initKind = init.getKind();
+            if (initKind !== SyntaxKind.ArrowFunction && initKind !== SyntaxKind.FunctionExpression)
+                continue;
+            return {
+                fn: init,
+                conceptStart: varDecl.getStart(),
+                conceptFilePath,
+            };
+        }
+    }
+    return undefined;
+}
+function expandIdentifierSymbols(symbol) {
+    const aliased = symbol.getAliasedSymbol();
+    return aliased ? [aliased, symbol] : [symbol];
+}
+function isSameConceptSourceFile(actualFilePath, conceptFilePath) {
+    const actual = actualFilePath.replace(/\\/g, '/').replace(/^\/+/, '');
+    const expected = conceptFilePath.replace(/\\/g, '/').replace(/^\/+/, '');
+    return actual === expected || actual.endsWith(`/${expected}`) || expected.endsWith(`/${actual}`);
+}
+function isExternalSourcePath(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    return normalized.includes('/node_modules/') || normalized.includes('/.pnpm/');
+}
+function extractExpressErrorStatusCodes(handlerFn) {
+    const codes = new Set();
+    for (const call of handlerFn.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const callee = call.getExpression();
+        if (callee.getKind() === SyntaxKind.Identifier && callee.getText() === 'next' && call.getArguments().length > 0) {
+            codes.add(500);
+            continue;
+        }
+        if (callee.getKind() !== SyntaxKind.PropertyAccessExpression)
+            continue;
+        const pa = callee;
+        const name = pa.getName();
+        if (name !== 'status' && name !== 'sendStatus')
+            continue;
+        const receiver = pa.getExpression().getText();
+        if (!/\b(res|reply|response)\b/i.test(receiver))
+            continue;
+        const code = numericLiteralValue(call.getArguments()[0]);
+        if (code !== undefined && API_ERROR_STATUS_CODES.has(code))
+            codes.add(code);
+    }
+    for (const throwStmt of handlerFn.getDescendantsOfKind(SyntaxKind.ThrowStatement)) {
+        if (throwStmt.getExpression())
+            codes.add(500);
+    }
+    return codes.size > 0 ? Array.from(codes).sort((a, b) => a - b) : undefined;
+}
+function numericLiteralValue(node) {
+    if (!node || node.getKind() !== SyntaxKind.NumericLiteral)
+        return undefined;
+    const value = Number(node.getText());
+    return Number.isFinite(value) ? value : undefined;
+}
+function hasUnboundedExpressCollectionQuery(handlerFn, method, routePath) {
+    if (method !== 'GET')
+        return false;
+    if (routePath && /[:{]/.test(routePath))
+        return false;
+    const text = handlerFn.getText();
+    if (PAGINATION_RE.test(text) || /\b(req|request)\.query\b/.test(text))
+        return false;
+    if (!handlerHasDbCollectionRead(handlerFn))
+        return false;
+    if (!/\.json\s*\(|send\s*\(/.test(text))
+        return false;
+    const lastSegment = routePath?.split('/').filter(Boolean).pop();
+    return Boolean(lastSegment?.endsWith('s')) || /\bfindMany\b|\.find\s*\(|\.toArray\s*\(/.test(text);
+}
+function handlerHasDbCollectionRead(handlerFn) {
+    return handlerFn.getDescendantsOfKind(SyntaxKind.CallExpression).some((call) => {
+        const callee = call.getExpression();
+        if (callee.getKind() !== SyntaxKind.PropertyAccessExpression)
+            return false;
+        const pa = callee;
+        if (!DB_COLLECTION_READ_CALLS.has(pa.getName()))
+            return false;
+        return isDbLikeReceiver(pa.getExpression().getText());
+    });
+}
+function handlerHasDbWrite(handlerFn) {
+    return handlerFn.getDescendantsOfKind(SyntaxKind.CallExpression).some((call) => {
+        const callee = call.getExpression();
+        if (callee.getKind() !== SyntaxKind.PropertyAccessExpression)
+            return false;
+        const pa = callee;
+        if (!DB_WRITE_CALLS.has(pa.getName()))
+            return false;
+        return isDbLikeReceiver(pa.getExpression().getText());
+    });
+}
+function isDbLikeReceiver(receiver) {
+    return (/\b(db|prisma|mongo|collection|repo|repository|model|client|knex|sequelize|typeorm|pool)\b/i.test(receiver) ||
+        /^[A-Z][A-Za-z0-9_]*(Model)?$/.test(receiver));
+}
+function extractExpressValidation(handlerFn, routeArgs) {
+    const fields = new Set();
+    let hasValidation = false;
+    let resolved = false;
+    for (const arg of routeArgs) {
+        if (arg === handlerFn)
+            continue;
+        if (arg.getStart() > handlerFn.getStart())
+            continue;
+        if (/\b(validate|validator|schema|zod|joi)\b/i.test(arg.getText()))
+            hasValidation = true;
+        for (const field of extractExpressValidatorFields(arg)) {
+            fields.add(field);
+            hasValidation = true;
+            resolved = true;
+        }
+    }
+    const handlerText = handlerFn.getText();
+    if (/\.(parse|safeParse|validate)\s*\(\s*(req|request)\.body\b/.test(handlerText))
+        hasValidation = true;
+    for (const call of handlerFn.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!isSchemaObjectCall(call))
+            continue;
+        if (!schemaCallValidatesRequestBody(call))
+            continue;
+        const arg = call.getArguments()[0];
+        if (!arg || arg.getKind() !== SyntaxKind.ObjectLiteralExpression)
+            continue;
+        const extracted = extractLiteralObjectFields(arg);
+        if (!extracted.resolved || !extracted.fields)
+            continue;
+        for (const field of extracted.fields)
+            fields.add(field);
+        hasValidation = true;
+        resolved = true;
+    }
+    return {
+        has: hasValidation,
+        fields: fields.size > 0 ? Array.from(fields).sort() : undefined,
+        resolved,
+    };
+}
+function extractExpressValidatorFields(node) {
+    const fields = [];
+    const calls = node.getKind() === SyntaxKind.CallExpression
+        ? [node, ...node.getDescendantsOfKind(SyntaxKind.CallExpression)]
+        : node.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of calls) {
+        const callee = call.getExpression().getText();
+        if (!/^(body|check|param|query)$/.test(callee) && !/\.(body|check|param|query)$/.test(callee))
+            continue;
+        const first = call.getArguments()[0];
+        if (!first || first.getKind() !== SyntaxKind.StringLiteral)
+            continue;
+        fields.push(first.getLiteralValue());
+    }
+    return fields;
+}
+function isSchemaObjectCall(call) {
+    const callee = call.getExpression().getText();
+    return callee === 'z.object' || callee === 'Joi.object' || callee.endsWith('.object');
+}
+function schemaCallValidatesRequestBody(call) {
+    let cursor = call;
+    for (let depth = 0; depth < 5; depth++) {
+        cursor = cursor.getParent();
+        if (!cursor)
+            return false;
+        const text = cursor.getText();
+        if (/\.(parse|safeParse|validate)\s*\(\s*(req|request)\.body\b/.test(text))
+            return true;
+    }
+    return false;
+}
 // 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`).
@@ -489,6 +780,81 @@ function pathSuffixBetween(mountFile, targetFile) {
     const tail = parts.slice(commonLen).join('/');
     return tail || parts.slice(-2).join('/');
 }
+// Walk an Express handler body and collect the REQUIRED body field names it
+// reads. Combines two evidence sources:
+//   1. Destructuring:  `const { name, email } = req.body;`
+//   2. Property access: `req.body.name`, `req.body['email']`
+//
+// Default-assignments in destructuring (`{ status = 'active' }`) mark the
+// field as optional and are excluded from the required set. A rest element
+// (`{ ...rest }`) or a dynamic key (`req.body[var]`) poisons the resolution
+// because the handler may need arbitrary fields we can't see.
+function extractHandlerBodyFields(fn) {
+    const body = fn.getBody();
+    if (!body)
+        return { fields: undefined, resolved: false };
+    const required = new Set();
+    let poisoned = false;
+    // 1. Destructuring: walk VariableDeclarations whose initializer is `req.body`
+    //    or a reference that aliases it. V1 matches only direct `req.body`.
+    for (const decl of body.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+        const init = decl.getInitializer();
+        if (!init || init.getText() !== 'req.body')
+            continue;
+        const name = decl.getNameNode();
+        if (name.getKind() !== SyntaxKind.ObjectBindingPattern) {
+            // `const body = req.body` whole-body alias — handler may read anything
+            // off `body.X` downstream. Poison the resolution for safety.
+            poisoned = true;
+            continue;
+        }
+        for (const el of name.getElements()) {
+            if (el.getDotDotDotToken()) {
+                // `{ ...rest } = req.body` — unknowable set of fields.
+                poisoned = true;
+                continue;
+            }
+            if (el.getInitializer()) {
+                // `{ status = 'active' }` — optional, skip (don't add to required).
+                continue;
+            }
+            const elName = el.getNameNode();
+            if (elName.getKind() === SyntaxKind.Identifier) {
+                // `{ name }` or `{ name: alias }` — the property name lives on
+                // `propertyNameNode` when aliased, `nameNode` otherwise.
+                const propName = el.getPropertyNameNode()?.getText() ?? elName.getText();
+                required.add(propName);
+            }
+            else {
+                // Nested destructuring or other exotic shape — give up for v1.
+                poisoned = true;
+            }
+        }
+    }
+    // 2. Property access: `req.body.name` / `req.body['name']`.
+    for (const pa of body.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+        if (pa.getExpression().getText() !== 'req.body')
+            continue;
+        required.add(pa.getName());
+    }
+    for (const el of body.getDescendantsOfKind(SyntaxKind.ElementAccessExpression)) {
+        if (el.getExpression().getText() !== 'req.body')
+            continue;
+        const arg = el.getArgumentExpression();
+        if (arg && arg.getKind() === SyntaxKind.StringLiteral) {
+            required.add(arg.getLiteralValue());
+        }
+        else {
+            // `req.body[key]` dynamic — unknowable.
+            poisoned = true;
+        }
+    }
+    if (poisoned)
+        return { fields: undefined, resolved: false };
+    if (required.size === 0)
+        return { fields: undefined, resolved: false };
+    return { fields: Array.from(required), resolved: true };
+}
 function guessResolvedSuffix(specifier, mountFile) {
     if (!specifier.startsWith('.'))
         return undefined;
@@ -1128,6 +1494,140 @@ 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 extractPayloadFields(payload);
+}
+function extractNetworkPayloadExpression(call, funcName) {
+    const args = call.getArguments();
+    if (args.length < 2)
+        return undefined;
+    if (AXIOS_STYLE_METHODS.has(funcName)) {
+        return args[1];
+    }
+    if (funcName !== 'fetch')
+        return undefined;
+    const opts = args[1];
+    if (opts.getKind() !== SyntaxKind.ObjectLiteralExpression)
+        return undefined;
+    const optsObj = opts;
+    const bodyProp = optsObj.getProperty('body');
+    if (!bodyProp)
+        return undefined;
+    if (bodyProp.getKind() !== SyntaxKind.PropertyAssignment) {
+        return undefined;
+    }
+    const init = bodyProp.getInitializer();
+    return init;
+}
+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 };
+        const stringifyArg = bodyCall.getArguments()[0];
+        return stringifyArg ? extractPayloadFields(stringifyArg) : { fields: undefined, resolved: false };
+    }
+    if (payload.getKind() === SyntaxKind.ObjectLiteralExpression) {
+        return extractLiteralObjectFields(payload);
+    }
+    if (payload.getKind() === SyntaxKind.Identifier || payload.getKind() === SyntaxKind.PropertyAccessExpression) {
+        return extractObjectFieldsFromType(payload);
+    }
+    return { fields: undefined, resolved: false };
+}
+function unwrapPayloadExpression(node) {
+    let current = node;
+    while (true) {
+        const kind = current.getKind();
+        if (kind === SyntaxKind.ParenthesizedExpression) {
+            current = current.getExpression();
+        }
+        else if (kind === SyntaxKind.AsExpression) {
+            current = current.getExpression();
+        }
+        else if (kind === SyntaxKind.TypeAssertionExpression) {
+            current = current.getExpression();
+        }
+        else if (kind === SyntaxKind.NonNullExpression) {
+            current = current.getExpression();
+        }
+        else if (kind === SyntaxKind.SatisfiesExpression) {
+            current = current.getExpression();
+        }
+        else {
+            return current;
+        }
+    }
+}
+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 };
+    const fields = new Set();
+    for (const prop of type.getProperties()) {
+        const declarations = prop.getDeclarations();
+        if (declarations.length === 0)
+            return { fields: undefined, resolved: false };
+        if (declarations.some((decl) => isExternalSourcePath(decl.getSourceFile().getFilePath()))) {
+            return { fields: undefined, resolved: false };
+        }
+        if (declarations.some((decl) => declarationIsOptional(decl)))
+            continue;
+        const name = prop.getName();
+        if (!/^[A-Za-z_$][\w$-]*$/.test(name))
+            return { fields: undefined, resolved: false };
+        fields.add(name);
+    }
+    return fields.size > 0 ? { fields: Array.from(fields).sort(), resolved: true } : { fields: [], resolved: true };
+}
+function declarationIsOptional(decl) {
+    const maybeOptional = decl;
+    return maybeOptional.hasQuestionToken?.() === true;
+}
+// Walk an object literal and return its identifier-keyed property names.
+// Spread (`...x`) or computed keys (`[x]: ...`) poison the resolution —
+// we mark unresolved rather than return a partial field list that would
+// produce false positives downstream.
+function extractLiteralObjectFields(obj) {
+    const fields = [];
+    for (const prop of obj.getProperties()) {
+        const kind = prop.getKind();
+        if (kind === SyntaxKind.SpreadAssignment)
+            return { fields: undefined, resolved: false };
+        if (kind === SyntaxKind.PropertyAssignment) {
+            const name = prop.getNameNode();
+            if (name.getKind() === SyntaxKind.ComputedPropertyName)
+                return { fields: undefined, resolved: false };
+            if (name.getKind() === SyntaxKind.Identifier || name.getKind() === SyntaxKind.StringLiteral) {
+                fields.push(name.getText().replace(/['"]/g, ''));
+            }
+            else {
+                return { fields: undefined, resolved: false };
+            }
+        }
+        else if (kind === SyntaxKind.ShorthandPropertyAssignment) {
+            fields.push(prop.getName());
+        }
+        else {
+            // Method definitions, getters, setters — unusual in a fetch body,
+            // treat as unresolved.
+            return { fields: undefined, resolved: false };
+        }
+    }
+    return { fields, resolved: true };
+}
 function extractTarget(call) {
     const args = call.getArguments();
     if (args.length === 0)
@@ -1144,6 +1644,29 @@ function extractTarget(call) {
     }
     return undefined;
 }
+function extractQueryParams(call) {
+    const target = extractTarget(call);
+    if (!target)
+        return { params: undefined, resolved: false };
+    const q = target.indexOf('?');
+    if (q === -1)
+        return { params: [], resolved: true };
+    const query = target.slice(q + 1).split('#')[0] ?? '';
+    if (query.length === 0)
+        return { params: [], resolved: true };
+    const params = [];
+    for (const part of query.split('&')) {
+        if (!part)
+            continue;
+        const [rawName] = part.split('=');
+        if (!rawName)
+            continue;
+        const name = rawName.replace(/^:+/, '');
+        if (/^[A-Za-z_][\w-]*$/.test(name))
+            params.push(name);
+    }
+    return { params, resolved: true };
+}
 // 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}/…\` `)`
@@ -1441,6 +1964,212 @@ function extractHasAuthHeader(call, funcName) {
     }
     return false;
 }
+function extractHandlesApiErrors(call, isWrappedClientCall) {
+    if (isWrappedClientCall)
+        return undefined;
+    if (isInsideTryWithCatch(call))
+        return true;
+    if (hasCatchInPromiseChain(call))
+        return true;
+    if (hasInlineStatusCheck(call))
+        return true;
+    if (hasAssignedResponseStatusCheck(call))
+        return true;
+    if (isPassedToApiResponseHelper(call))
+        return true;
+    if (hasNearbyErrorUiPath(call))
+        return true;
+    return false;
+}
+function isInsideTryWithCatch(node) {
+    let parent = node.getParent();
+    while (parent) {
+        if (parent.getKind() === SyntaxKind.TryStatement) {
+            const tryStmt = parent;
+            return Boolean(tryStmt.getCatchClause());
+        }
+        parent = parent.getParent();
+    }
+    return false;
+}
+function hasCatchInPromiseChain(node) {
+    let cursor = node;
+    for (let depth = 0; depth < 8; depth++) {
+        const parent = cursor.getParent();
+        if (!parent)
+            return false;
+        if (parent.getKind() === SyntaxKind.PropertyAccessExpression) {
+            const pa = parent;
+            if (pa.getName() === 'catch')
+                return true;
+        }
+        cursor = parent;
+    }
+    return false;
+}
+function hasInlineStatusCheck(call) {
+    let cursor = call;
+    for (let depth = 0; depth < 8; depth++) {
+        const parent = cursor.getParent();
+        if (!parent)
+            return false;
+        const text = parent.getText();
+        if (/\b\w+\.(ok|status|statusCode)\b/.test(text) &&
+            /\b(if|throw|reject|setError|toast\.error|Alert\.alert)\b/.test(text)) {
+            return true;
+        }
+        if (parent.getKind() === SyntaxKind.ExpressionStatement || parent.getKind() === SyntaxKind.VariableDeclaration) {
+            return false;
+        }
+        cursor = parent;
+    }
+    return false;
+}
+function hasAssignedResponseStatusCheck(call) {
+    const decl = enclosingVariableDeclaration(call);
+    if (!decl)
+        return false;
+    const name = decl.getName();
+    if (!/^[A-Za-z_$][\w$]*$/.test(name))
+        return false;
+    const block = nearestBlock(decl);
+    if (!block)
+        return false;
+    const escaped = escapeRegExp(name);
+    const text = block.getText();
+    return new RegExp(`\\b${escaped}\\.(ok|status|statusCode)\\b`).test(text);
+}
+function isPassedToApiResponseHelper(call) {
+    let cursor = call;
+    for (let depth = 0; depth < 4; depth++) {
+        const parent = cursor.getParent();
+        if (!parent)
+            return false;
+        const kind = parent.getKind();
+        if (kind === SyntaxKind.AwaitExpression || kind === SyntaxKind.ParenthesizedExpression) {
+            cursor = parent;
+            continue;
+        }
+        if (kind !== SyntaxKind.CallExpression)
+            return false;
+        const helperName = parent.getExpression().getText();
+        return /^(parse|handle|check|ensure|assert|unwrap)[A-Za-z0-9_$]*(Api|Response|Result)$/i.test(helperName);
+    }
+    return false;
+}
+function hasNearbyErrorUiPath(call) {
+    const container = nearestFunctionLike(call);
+    if (!container)
+        return false;
+    const text = container.getText();
+    return /\b(setError|setErrorMessage|showError|toast\.error|Alert\.alert|notifyError)\s*\(/.test(text);
+}
+function enclosingVariableDeclaration(node) {
+    let cursor = node;
+    for (let depth = 0; depth < 6; depth++) {
+        const parent = cursor.getParent();
+        if (!parent)
+            return undefined;
+        if (parent.getKind() === SyntaxKind.VariableDeclaration)
+            return parent;
+        cursor = parent;
+    }
+    return undefined;
+}
+function nearestBlock(node) {
+    let parent = node.getParent();
+    while (parent) {
+        if (parent.getKind() === SyntaxKind.Block)
+            return parent;
+        parent = parent.getParent();
+    }
+    return undefined;
+}
+function nearestFunctionLike(node) {
+    let parent = node.getParent();
+    while (parent) {
+        const kind = parent.getKind();
+        if (kind === SyntaxKind.FunctionDeclaration ||
+            kind === SyntaxKind.MethodDeclaration ||
+            kind === SyntaxKind.ArrowFunction ||
+            kind === SyntaxKind.FunctionExpression) {
+            return parent;
+        }
+        parent = parent.getParent();
+    }
+    return undefined;
+}
+function extractAuthPropagation(call, funcName, objName, isWrappedClientCall, hasAuthHeader) {
+    if (hasAuthHeader === true)
+        return 'present';
+    if (hasCookieOrSessionEvidence(call, funcName))
+        return 'present';
+    if (isWrappedClientCall)
+        return /auth|session|private|secure/i.test(objName) ? 'present' : 'unknown';
+    if (funcName === 'fetch')
+        return hasAuthHeader === false ? 'absent' : 'unknown';
+    const config = networkConfigArgument(call, funcName);
+    if (!config)
+        return 'absent';
+    if (config.getKind() !== SyntaxKind.ObjectLiteralExpression)
+        return 'unknown';
+    const obj = config;
+    if (obj.getProperties().some((p) => p.getKind() === SyntaxKind.SpreadAssignment))
+        return 'unknown';
+    return configObjectHasAuthEvidence(obj) ? 'present' : 'absent';
+}
+function hasCookieOrSessionEvidence(call, funcName) {
+    const config = funcName === 'fetch' ? call.getArguments()[1] : networkConfigArgument(call, funcName);
+    if (!config || config.getKind() !== SyntaxKind.ObjectLiteralExpression)
+        return false;
+    return configObjectHasAuthEvidence(config);
+}
+function networkConfigArgument(call, funcName) {
+    const args = call.getArguments();
+    if (funcName === 'fetch')
+        return args[1];
+    if (AXIOS_STYLE_METHODS.has(funcName))
+        return args[2];
+    return args[1];
+}
+function configObjectHasAuthEvidence(obj) {
+    const credentialsProp = obj.getProperty('credentials');
+    if (credentialsProp?.getKind() === SyntaxKind.PropertyAssignment) {
+        const init = credentialsProp.getInitializer();
+        if (init &&
+            (init.getKind() === SyntaxKind.StringLiteral || init.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral)) {
+            const value = init.getLiteralValue();
+            if (value === 'include' || value === 'same-origin')
+                return true;
+        }
+    }
+    const withCredentialsProp = obj.getProperty('withCredentials');
+    if (withCredentialsProp?.getKind() === SyntaxKind.PropertyAssignment) {
+        const init = withCredentialsProp.getInitializer();
+        if (init?.getKind() === SyntaxKind.TrueKeyword)
+            return true;
+    }
+    const headersProp = obj.getProperty('headers');
+    if (headersProp?.getKind() !== SyntaxKind.PropertyAssignment)
+        return false;
+    const headersInit = headersProp.getInitializer();
+    if (!headersInit || headersInit.getKind() !== SyntaxKind.ObjectLiteralExpression)
+        return false;
+    const headersObj = headersInit;
+    if (headersObj.getProperties().some((p) => p.getKind() === SyntaxKind.SpreadAssignment))
+        return false;
+    for (const prop of headersObj.getProperties()) {
+        if (prop.getKind() !== SyntaxKind.PropertyAssignment)
+            continue;
+        const name = prop.getName().replace(/['"]/g, '').toLowerCase();
+        if (name === 'authorization' || name === 'cookie' || name === 'x-session' || name === 'x-csrf-token')
+            return true;
+    }
+    return false;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 function classifyBodyExpression(expr) {
     if (!expr)
         return undefined;