@kernlang/review-python 3.4.6-canary.44.1.a85ee2e8 → 3.4.6-canary.46.1.19dcfc19

package/dist/mapper.js

@@ -1,1286 +1 @@
-/**
- * Python Concept Mapper — tree-sitter based.
- *
- * Maps Python syntax → universal KERN concepts.
- * Phase 1: error_raise, error_handle, effect
- */
-import { conceptId, conceptSpan } from '@kernlang/core';
-import Parser from 'tree-sitter';
-import Python from 'tree-sitter-python';
-const EXTRACTOR_VERSION = '1.0.0';
-// ── Network call patterns ────────────────────────────────────────────────
-const NETWORK_MODULES = new Set(['requests', 'httpx', 'aiohttp', 'urllib']);
-const NETWORK_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'request', 'fetch']);
-const DB_MODULES = new Set(['psycopg2', 'asyncpg', 'pymongo', 'sqlalchemy', 'django']);
-const DB_METHODS = new Set([
-    'execute',
-    'executemany',
-    'fetchone',
-    'fetchall',
-    'fetchmany',
-    'query',
-    'find',
-    'find_one',
-    'insert_one',
-    'insert_many',
-    'update_one',
-    'delete_one',
-]);
-const _FS_FUNCTIONS = new Set(['open', 'read', 'write', 'readlines', 'writelines']);
-const PY_API_ERROR_STATUS_CODES = new Set([401, 403, 404, 422, 500]);
-const PY_API_SUCCESS_STATUS_CODES = new Set([200, 201, 202, 204, 206]);
-// FastAPI's documented default success status is 200, regardless of HTTP method
-// (Codex plan-review #1, FastAPI docs:
-// https://fastapi.tiangolo.com/tutorial/response-status-code/). 201 for POST is
-// a per-route opt-in via `status_code=201`, not a method-derived default.
-const FASTAPI_DEFAULT_SUCCESS_STATUS = 200;
-// Pagination anchor families — mirror the TS classification in
-// `packages/review/src/concept-rules/cross-stack-utils.ts`. The size keys
-// (`limit`, `take`, `page_size`, `per_page`) are intentionally NOT anchors
-// — they're compatible with either offset or cursor pagination.
-const PY_PAGE_ANCHORS = new Set(['page', 'page_number', 'pageNumber']);
-const PY_OFFSET_ANCHORS = new Set(['offset', 'skip']);
-const PY_CURSOR_ANCHORS = new Set(['cursor', 'after', 'before', 'next', 'previous']);
-const PY_PAGINATION_RE = /\b(limit|offset|skip|cursor|page|page_size|per_page)\b|\.limit\s*\(/i;
-const PY_DB_COLLECTION_RE = /\.(find|all|fetchall|to_list|scalars)\s*\(|\bselect\s*\(/i;
-const PY_DB_WRITE_RE = /\.(insert_one|insert_many|update_one|update_many|delete_one|delete_many|add|create|save|commit)\s*\(/i;
-const PY_IDEMPOTENCY_RE = /\b(idempotency(?:[_-]?key)?|Idempotency-Key|transaction|unique|upsert|get_or_create|on_conflict)\b/i;
-const STDLIB_MODULES = new Set([
-    'os',
-    'sys',
-    'json',
-    're',
-    'math',
-    'datetime',
-    'time',
-    'logging',
-    'argparse',
-    'collections',
-    'itertools',
-    'functools',
-    'pathlib',
-    'shutil',
-    'subprocess',
-    'threading',
-    'multiprocessing',
-    'abc',
-    'typing',
-    'io',
-    'pickle',
-    'random',
-    'hashlib',
-    'hmac',
-    'base64',
-    'csv',
-    'sqlite3',
-    'zlib',
-    'gzip',
-    'tarfile',
-    'zipfile',
-    'enum',
-    'struct',
-    'tempfile',
-    'unittest',
-    'urllib',
-    'uuid',
-    'xml',
-]);
-// ── Parser setup ─────────────────────────────────────────────────────────
-let parser = null;
-function getParser() {
-    if (!parser) {
-        parser = new Parser();
-        parser.setLanguage(Python);
-    }
-    return parser;
-}
-// ── Main Extractor ───────────────────────────────────────────────────────
-export function extractPythonConcepts(source, filePath) {
-    const tree = getParser().parse(source);
-    const nodes = [];
-    const edges = [];
-    extractErrorRaise(tree.rootNode, source, filePath, nodes);
-    extractErrorHandle(tree.rootNode, source, filePath, nodes);
-    extractEffects(tree.rootNode, source, filePath, nodes);
-    extractEntrypoints(tree.rootNode, source, filePath, nodes);
-    extractGuards(tree.rootNode, source, filePath, nodes);
-    extractStateMutation(tree.rootNode, source, filePath, nodes);
-    extractDependencyEdges(tree.rootNode, source, filePath, edges);
-    return {
-        filePath,
-        language: 'py',
-        nodes,
-        edges,
-        extractorVersion: EXTRACTOR_VERSION,
-    };
-}
-// ── error_raise ──────────────────────────────────────────────────────────
-function extractErrorRaise(root, source, filePath, nodes) {
-    // raise statements
-    walkNodes(root, 'raise_statement', (node) => {
-        const errorType = extractRaiseType(node);
-        nodes.push({
-            id: conceptId(filePath, 'error_raise', node.startIndex),
-            kind: 'error_raise',
-            primarySpan: nodeSpan(filePath, node),
-            evidence: nodeText(source, node, 100),
-            confidence: 1.0,
-            language: 'py',
-            containerId: getContainerId(node, filePath),
-            payload: {
-                kind: 'error_raise',
-                subtype: 'throw', // Python raise ≡ throw
-                errorType,
-            },
-        });
-    });
-}
-// ── error_handle ─────────────────────────────────────────────────────────
-function extractErrorHandle(root, source, filePath, nodes) {
-    // except clauses
-    walkNodes(root, 'except_clause', (node) => {
-        const block = node.children.find((c) => c.type === 'block');
-        const disposition = classifyPythonDisposition(block, source);
-        const errorVar = extractExceptVar(node);
-        nodes.push({
-            id: conceptId(filePath, 'error_handle', node.startIndex),
-            kind: 'error_handle',
-            primarySpan: nodeSpan(filePath, node),
-            evidence: nodeText(source, node, 150),
-            confidence: disposition.confidence,
-            language: 'py',
-            containerId: getContainerId(node, filePath),
-            payload: {
-                kind: 'error_handle',
-                disposition: disposition.type,
-                errorVariable: errorVar,
-            },
-        });
-    });
-}
-function classifyPythonDisposition(block, source) {
-    if (!block)
-        return { type: 'ignored', confidence: 1.0 };
-    const children = block.namedChildren;
-    // except: pass → ignored
-    if (children.length === 1 && children[0].type === 'pass_statement') {
-        return { type: 'ignored', confidence: 1.0 };
-    }
-    // except: ... (ellipsis) → ignored
-    if (children.length === 1 && children[0].type === 'expression_statement') {
-        const text = source.substring(children[0].startIndex, children[0].endIndex).trim();
-        if (text === '...')
-            return { type: 'ignored', confidence: 1.0 };
-    }
-    // Empty block
-    if (children.length === 0) {
-        return { type: 'ignored', confidence: 1.0 };
-    }
-    const bodyText = source.substring(block.startIndex, block.endIndex);
-    // raise → rethrown or wrapped
-    if (bodyText.includes('raise')) {
-        // bare `raise` → rethrown
-        if (/\braise\s*$|\braise\s*\n/m.test(bodyText)) {
-            return { type: 'rethrown', confidence: 0.95 };
-        }
-        return { type: 'wrapped', confidence: 0.9 };
-    }
-    // return → returned
-    if (bodyText.includes('return')) {
-        return { type: 'returned', confidence: 0.85 };
-    }
-    // logging
-    if (/\b(logging|logger|log|print)\b/.test(bodyText)) {
-        if (children.length === 1)
-            return { type: 'logged', confidence: 0.9 };
-        return { type: 'logged', confidence: 0.7 };
-    }
-    return { type: 'wrapped', confidence: 0.5 };
-}
-// ── effect ───────────────────────────────────────────────────────────────
-function extractEffects(root, source, filePath, nodes) {
-    walkNodes(root, 'call', (node) => {
-        const funcNode = node.childForFieldName('function');
-        if (!funcNode)
-            return;
-        const funcText = source.substring(funcNode.startIndex, funcNode.endIndex);
-        // Network: requests.get(), httpx.post(), etc.
-        if (funcNode.type === 'attribute') {
-            const obj = funcNode.childForFieldName('object');
-            const attr = funcNode.childForFieldName('attribute');
-            if (obj && attr) {
-                const objName = source.substring(obj.startIndex, obj.endIndex);
-                const methodName = source.substring(attr.startIndex, attr.endIndex);
-                if (NETWORK_MODULES.has(objName) && NETWORK_METHODS.has(methodName)) {
-                    nodes.push({
-                        id: conceptId(filePath, 'effect', node.startIndex),
-                        kind: 'effect',
-                        primarySpan: nodeSpan(filePath, node),
-                        evidence: nodeText(source, node, 120),
-                        confidence: 0.95,
-                        language: 'py',
-                        containerId: getContainerId(node, filePath),
-                        payload: { kind: 'effect', subtype: 'network', async: isInAsyncDef(node) },
-                    });
-                    return;
-                }
-                // DB: cursor.execute(), db.query(), etc.
-                if (DB_METHODS.has(methodName) &&
-                    (DB_MODULES.has(objName) || /cursor|conn|db|session|collection/i.test(objName))) {
-                    nodes.push({
-                        id: conceptId(filePath, 'effect', node.startIndex),
-                        kind: 'effect',
-                        primarySpan: nodeSpan(filePath, node),
-                        evidence: nodeText(source, node, 120),
-                        confidence: 0.85,
-                        language: 'py',
-                        containerId: getContainerId(node, filePath),
-                        payload: { kind: 'effect', subtype: 'db', async: isInAsyncDef(node) },
-                    });
-                    return;
-                }
-            }
-        }
-        // FS: open()
-        if (funcText === 'open') {
-            nodes.push({
-                id: conceptId(filePath, 'effect', node.startIndex),
-                kind: 'effect',
-                primarySpan: nodeSpan(filePath, node),
-                evidence: nodeText(source, node, 120),
-                confidence: 0.9,
-                language: 'py',
-                containerId: getContainerId(node, filePath),
-                payload: { kind: 'effect', subtype: 'fs', async: false },
-            });
-        }
-        // fetch() in async context (aiohttp pattern)
-        if (funcText === 'fetch' || funcText === 'aiohttp.request') {
-            nodes.push({
-                id: conceptId(filePath, 'effect', node.startIndex),
-                kind: 'effect',
-                primarySpan: nodeSpan(filePath, node),
-                evidence: nodeText(source, node, 120),
-                confidence: 0.8,
-                language: 'py',
-                containerId: getContainerId(node, filePath),
-                payload: { kind: 'effect', subtype: 'network', async: true },
-            });
-        }
-    });
-}
-// ── entrypoint ──────────────────────────────────────────────────────────
-function extractEntrypoints(root, source, filePath, nodes) {
-    const pydanticModels = collectPydanticModels(source);
-    // FastAPI / Flask route decorators.
-    //
-    // The route *path* (e.g. `/current`) is what cross-stack rules need to
-    // match against — not the Python function name. Prior to 2026-04-21 this
-    // emitted the function name, which `collectRoutes` then silently dropped
-    // (it filters on paths starting with `/`). The FastAPI router-prefix join
-    // in `cross-stack-utils.collectRoutes` also needs `routerName` so it can
-    // pair per-file routes with the `include_router(prefix=…)` call that
-    // mounts them.
-    walkNodes(root, 'decorated_definition', (node) => {
-        const fnDef = node.children.find((c) => c.type === 'function_definition');
-        if (!fnDef)
-            return;
-        for (const child of node.children) {
-            if (child.type !== 'decorator')
-                continue;
-            const decText = source.substring(child.startIndex, child.endIndex);
-            const routeMatch = decText.match(/@(\w+)\.(route|get|post|put|delete|patch)\s*\(/);
-            if (!routeMatch)
-                continue;
-            const routerName = routeMatch[1];
-            const method = routeMatch[2].toUpperCase();
-            const pathMatch = decText.match(/['"]([^'"]+)['"]/);
-            const routePath = pathMatch?.[1];
-            // Only surface the decorator as a route when we could extract a URL
-            // path literal. Mystery decorators with only kwargs (e.g. `@app.get`
-            // stub) are noise — skip them instead of filling `name` with the
-            // function name, which cross-stack routes treat as invalid.
-            if (!routePath?.startsWith('/'))
-                continue;
-            const responseModel = extractResponseModel(decText);
-            const routeContainerId = getSelfContainerId(fnDef, filePath);
-            const routeAnalysis = analyzePythonRoute(fnDef, source, method, routePath, responseModel, pydanticModels, decText);
-            nodes.push({
-                id: conceptId(filePath, 'entrypoint', child.startIndex),
-                kind: 'entrypoint',
-                primarySpan: nodeSpan(filePath, child),
-                evidence: nodeText(source, child, 100),
-                confidence: 1.0,
-                language: 'py',
-                containerId: routeContainerId,
-                payload: {
-                    kind: 'entrypoint',
-                    subtype: 'route',
-                    name: routePath,
-                    httpMethod: method === 'ROUTE' ? undefined : method,
-                    responseModel,
-                    isAsync: isAsyncFunction(fnDef),
-                    routerName,
-                    errorStatusCodes: routeAnalysis.errorStatusCodes,
-                    successStatusCodes: routeAnalysis.successStatusCodes,
-                    successStatusCodesResolved: routeAnalysis.successStatusCodesResolved,
-                    paginationStrategy: routeAnalysis.paginationStrategy,
-                    paginationStrategyResolved: routeAnalysis.paginationStrategyResolved,
-                    hasUnboundedCollectionQuery: routeAnalysis.hasUnboundedCollectionQuery,
-                    hasDbWrite: routeAnalysis.hasDbWrite,
-                    hasIdempotencyProtection: routeAnalysis.hasIdempotencyProtection,
-                    hasBodyValidation: routeAnalysis.hasBodyValidation,
-                    validatedBodyFields: routeAnalysis.validatedBodyFields,
-                    bodyValidationResolved: routeAnalysis.bodyValidationResolved,
-                    validatedBodyFieldTypes: routeAnalysis.validatedBodyFieldTypes,
-                },
-            });
-        }
-    });
-    // FastAPI `app.include_router(<module>.<router>, prefix="/api/x")`.
-    //
-    // Emitted as a route-mount concept so `collectRoutes` can join it with
-    // the per-file route nodes: a route declared on `router` in
-    // `app/api/nutrition_goals.py` and mounted in `main.py` with
-    // `app.include_router(nutrition_goals.router, prefix="/api/nutrition-goals")`
-    // should resolve to the full URL `/api/nutrition-goals/<path>`.
-    walkNodes(root, 'call', (node) => {
-        const fn = node.childForFieldName('function');
-        if (!fn)
-            return;
-        const fnText = source.substring(fn.startIndex, fn.endIndex);
-        if (!/\.include_router$/.test(fnText))
-            return;
-        const argsNode = node.childForFieldName('arguments');
-        if (!argsNode)
-            return;
-        const argsText = source.substring(argsNode.startIndex, argsNode.endIndex);
-        // First positional arg is the router. Common shapes:
-        //   include_router(router)                  — local identifier
-        //   include_router(nutrition_goals.router)  — imported-module attribute
-        //   include_router(auth_router)             — aliased local identifier
-        const posMatch = argsText.match(/^\(\s*([A-Za-z_][\w.]*)/);
-        if (!posMatch)
-            return;
-        const routerRef = posMatch[1];
-        const dot = routerRef.lastIndexOf('.');
-        const sourceModule = dot === -1 ? undefined : routerRef.slice(0, dot);
-        const routerName = dot === -1 ? routerRef : routerRef.slice(dot + 1);
-        const prefixMatch = argsText.match(/prefix\s*=\s*['"]([^'"]*)['"]/);
-        // Prefix defaults to '' when omitted — still valid (the route keeps its
-        // declared path as-is), so emit the mount either way.
-        const prefix = prefixMatch?.[1] ?? '';
-        nodes.push({
-            id: conceptId(filePath, 'entrypoint', node.startIndex),
-            kind: 'entrypoint',
-            primarySpan: nodeSpan(filePath, node),
-            evidence: nodeText(source, node, 120),
-            confidence: 0.95,
-            language: 'py',
-            payload: {
-                kind: 'entrypoint',
-                subtype: 'route-mount',
-                name: prefix,
-                routerName,
-                sourceModule,
-            },
-        });
-    });
-    // `if __name__ == '__main__':`
-    walkNodes(root, 'if_statement', (node) => {
-        const condition = node.childForFieldName('condition');
-        if (condition?.text.includes('__name__') && condition.text.includes('__main__')) {
-            nodes.push({
-                id: conceptId(filePath, 'entrypoint', node.startIndex),
-                kind: 'entrypoint',
-                primarySpan: nodeSpan(filePath, node),
-                evidence: nodeText(source, node, 100),
-                confidence: 1.0,
-                language: 'py',
-                payload: {
-                    kind: 'entrypoint',
-                    subtype: 'main',
-                    name: 'main',
-                },
-            });
-        }
-    });
-}
-// ── guard ───────────────────────────────────────────────────────────────
-function extractGuards(root, source, filePath, nodes) {
-    // 1. Auth decorators (tree-sitter: decorated_definition → decorator + function_definition)
-    walkNodes(root, 'decorated_definition', (node) => {
-        for (const child of node.children) {
-            if (child.type !== 'decorator')
-                continue;
-            const decText = source.substring(child.startIndex, child.endIndex);
-            if (/@(login_required|requires_auth|permission_required|auth_required|authenticated)/.test(decText)) {
-                nodes.push({
-                    id: conceptId(filePath, 'guard', child.startIndex),
-                    kind: 'guard',
-                    primarySpan: nodeSpan(filePath, child),
-                    evidence: nodeText(source, child, 100),
-                    confidence: 1.0,
-                    language: 'py',
-                    containerId: getContainerId(node, filePath),
-                    payload: {
-                        kind: 'guard',
-                        subtype: 'auth',
-                        name: decText.replace('@', '').split('(')[0].trim(),
-                    },
-                });
-            }
-        }
-    });
-    // 2. Pydantic validation: BaseModel.model_validate()
-    walkNodes(root, 'call', (node) => {
-        const func = node.childForFieldName('function');
-        if (func?.text.includes('model_validate')) {
-            nodes.push({
-                id: conceptId(filePath, 'guard', node.startIndex),
-                kind: 'guard',
-                primarySpan: nodeSpan(filePath, node),
-                evidence: nodeText(source, node, 100),
-                confidence: 0.9,
-                language: 'py',
-                containerId: getContainerId(node, filePath),
-                payload: { kind: 'guard', subtype: 'validation', name: 'pydantic' },
-            });
-        }
-    });
-    // 3. FastAPI `Depends(...)` injection — route handler parameter with a
-    //    `Depends` default is the idiomatic FastAPI auth/validation guard.
-    //    Example:
-    //      @router.get("/me")
-    //      def me(user: User = Depends(get_current_user)):
-    //    Classified by the dependency function name:
-    //      - `get_current_user` / `current_user` / `require_auth` / `*_user` → 'auth'
-    //      - `verify_*` / `validate_*` → 'validation'
-    //      - `rate_limit_*` / `check_rate_limit` → 'rate-limit'
-    //      - everything else → 'policy'
-    //    Feeds the `auth-drift` cross-stack rule.
-    walkNodes(root, 'default_parameter', (node) => {
-        const val = node.childForFieldName('value');
-        if (!val || val.type !== 'call')
-            return;
-        const func = val.childForFieldName('function');
-        if (!func || func.text !== 'Depends')
-            return;
-        const args = val.childForFieldName('arguments');
-        if (!args)
-            return;
-        const posArg = args.namedChildren.find((c) => c.type === 'identifier' || c.type === 'attribute');
-        const depName = posArg ? posArg.text : 'Depends';
-        const subtype = classifyDependency(depName);
-        nodes.push({
-            id: conceptId(filePath, 'guard', node.startIndex),
-            kind: 'guard',
-            primarySpan: nodeSpan(filePath, node),
-            evidence: nodeText(source, node, 120),
-            confidence: 0.85,
-            language: 'py',
-            containerId: getContainerId(node, filePath),
-            payload: { kind: 'guard', subtype, name: depName },
-        });
-    });
-    // 4. Early return/raise after auth check: if not request.user: raise/return
-    walkNodes(root, 'if_statement', (node) => {
-        const cond = node.childForFieldName('condition');
-        if (cond && /\b(user|auth|request\.user)\b/.test(cond.text)) {
-            const block = node.namedChildren.find((c) => c.type === 'block');
-            if (block) {
-                const firstStmt = block.namedChildren[0];
-                if (firstStmt && (firstStmt.type === 'return_statement' || firstStmt.type === 'raise_statement')) {
-                    nodes.push({
-                        id: conceptId(filePath, 'guard', node.startIndex),
-                        kind: 'guard',
-                        primarySpan: nodeSpan(filePath, node),
-                        evidence: nodeText(source, node, 100),
-                        confidence: 0.8,
-                        language: 'py',
-                        containerId: getContainerId(node, filePath),
-                        payload: { kind: 'guard', subtype: 'auth' },
-                    });
-                }
-            }
-        }
-    });
-}
-function classifyDependency(depName) {
-    // Strip module prefix (`auth.get_current_user` → `get_current_user`) so the
-    // heuristic looks at the final identifier where intent usually lives.
-    const tail = depName.split('.').pop() ?? depName;
-    if (/^(get_current_user|current_user|require_auth|authenticated|is_authenticated)$/i.test(tail))
-        return 'auth';
-    if (/_user$|^user$|auth/i.test(tail))
-        return 'auth';
-    if (/^(verify_|validate_)/i.test(tail))
-        return 'validation';
-    if (/rate_?limit/i.test(tail))
-        return 'rate-limit';
-    return 'policy';
-}
-function analyzePythonRoute(fnDef, source, method, routePath, responseModel, pydanticModels, decText) {
-    const text = source.substring(fnDef.startIndex, fnDef.endIndex);
-    const validation = extractFastApiBodyValidation(fnDef, source, pydanticModels);
-    const success = extractFastApiSuccessStatusCodes(decText, fnDef, source);
-    const pagination = extractFastApiPaginationStrategy(fnDef, source);
-    return {
-        errorStatusCodes: extractPythonHttpExceptionStatusCodes(text),
-        successStatusCodes: success.codes,
-        successStatusCodesResolved: success.resolved,
-        paginationStrategy: pagination.strategy,
-        paginationStrategyResolved: pagination.resolved,
-        hasUnboundedCollectionQuery: hasUnboundedPythonCollectionQuery(text, method, routePath, responseModel),
-        hasDbWrite: PY_DB_WRITE_RE.test(text),
-        hasIdempotencyProtection: PY_IDEMPOTENCY_RE.test(text),
-        hasBodyValidation: validation.has,
-        validatedBodyFields: validation.fields,
-        bodyValidationResolved: validation.resolved,
-        validatedBodyFieldTypes: validation.types,
-    };
-}
-// ── FastAPI success status codes ─────────────────────────────────────────
-// Phase 2 of cross-stack `status-code-drift`. Populates the
-// `successStatusCodes` / `successStatusCodesResolved` payload fields so the
-// rule can flag clients checking a 2xx the FastAPI server doesn't emit.
-//
-// Sources of evidence (per buddy plan-review consensus):
-//   1. Decorator `status_code=N` (literal) or `status_code=status.HTTP_NNN_*`.
-//   2. Body-side `Response(status_code=N)` / `JSONResponse(...)` returns.
-//   3. Body-side `<param>.status_code = N` mutations (FastAPI's documented
-//      pattern for routes that take a `Response` parameter).
-//   4. When the decorator omits status_code AND the body has no explicit
-//      Response / mutation, default to 200 — FastAPI's documented default
-//      regardless of HTTP method. Codex caught Gemini's POST→201 premise as
-//      wrong (FastAPI docs:
-//      https://fastapi.tiangolo.com/tutorial/response-status-code/).
-//
-// Marked unresolved when:
-//   - Decorator status_code is set to a non-literal/non-status-constant
-//     expression (variable, function call).
-//   - Any `Response(status_code=...)` / `<x>.status_code = ...` RHS is dynamic.
-function extractFastApiSuccessStatusCodes(decText, fnDef, source) {
-    let sawDynamic = false;
-    // 1. Decorator `status_code=N` — applies ONLY to plain `return data` paths.
-    //    For routes whose return paths all use explicit Response/JSONResponse,
-    //    the decorator code is dead (Codex impl-review #1).
-    const decStatusMatch = decText.match(/\bstatus_code\s*=\s*([^,)]+)/);
-    let decoratorCode;
-    if (decStatusMatch) {
-        const code = parseFastApiStatusValue(decStatusMatch[1].trim());
-        if (code === undefined)
-            sawDynamic = true;
-        else if (PY_API_SUCCESS_STATUS_CODES.has(code))
-            decoratorCode = code;
-    }
-    const body = fnDef.childForFieldName('body') ?? fnDef.namedChildren.find((c) => c.type === 'block');
-    const bodyText = body ? source.substring(body.startIndex, body.endIndex) : '';
-    // 2. Response(status_code=N) / JSONResponse(...) etc. — applies only to
-    //    that specific return path. Multiple Response codes contribute a
-    //    multi-2xx route.
-    const responseCodes = new Set();
-    const responseRe = /\b(?:Response|JSONResponse|HTMLResponse|PlainTextResponse|RedirectResponse|StreamingResponse|FileResponse|ORJSONResponse|UJSONResponse)\s*\([^)]*?\bstatus_code\s*=\s*([^,)\n]+)/g;
-    for (const match of bodyText.matchAll(responseRe)) {
-        const code = parseFastApiStatusValue(match[1].trim());
-        if (code === undefined)
-            sawDynamic = true;
-        else if (PY_API_SUCCESS_STATUS_CODES.has(code))
-            responseCodes.add(code);
-    }
-    // 3. `<paramName>.status_code = N` — mutation on the injected Response
-    //    parameter. The parameter name varies (`response`, `resp`, `r`, `out`,
-    //    custom names — Codex impl-review #2). Match any identifier prefix
-    //    rather than a name whitelist; the API_SUCCESS_STATUS_CODES filter
-    //    keeps the noise tax low.
-    const mutationCodes = new Set();
-    // `=(?!=)` distinguishes assignment from `==` comparison so
-    // `if response.status_code == 200:` doesn't masquerade as a dynamic
-    // mutation (forge round, Claude engine).
-    const mutateRe = /\b[A-Za-z_]\w*\.status_code\s*=(?!=)\s*([^\n;]+)/g;
-    for (const match of bodyText.matchAll(mutateRe)) {
-        const code = parseFastApiStatusValue(match[1].trim());
-        if (code === undefined)
-            sawDynamic = true;
-        else if (PY_API_SUCCESS_STATUS_CODES.has(code))
-            mutationCodes.add(code);
-    }
-    if (sawDynamic)
-        return { codes: undefined, resolved: false };
-    // Plain return paths inherit the route's "primary" success code, computed
-    // as: mutation > decorator > FastAPI default 200. When a mutation is
-    // present we treat it as the plain-return code (the conditional-mutation
-    // case is a documented v1 false-negative — would require control-flow
-    // analysis to disambiguate).
-    const plainReturnRe = /\breturn\b(?!\s+(?:Response|JSONResponse|HTMLResponse|PlainTextResponse|RedirectResponse|StreamingResponse|FileResponse|ORJSONResponse|UJSONResponse)\s*\()/;
-    const hasPlainReturn = plainReturnRe.test(bodyText);
-    const final = new Set();
-    if (hasPlainReturn) {
-        if (mutationCodes.size > 0) {
-            for (const c of mutationCodes)
-                final.add(c);
-        }
-        else if (decoratorCode !== undefined) {
-            final.add(decoratorCode);
-        }
-        else {
-            final.add(FASTAPI_DEFAULT_SUCCESS_STATUS);
-        }
-    }
-    else if (decoratorCode !== undefined && responseCodes.size === 0 && mutationCodes.size === 0) {
-        // Handler with no plain return, no Response, no mutation — likely an
-        // implicit-None-return stub or all-raise. Decorator is the only signal.
-        final.add(decoratorCode);
-    }
-    // Response and mutation codes ALWAYS contribute (they're explicit choices
-    // for their respective return paths).
-    for (const c of responseCodes)
-        final.add(c);
-    for (const c of mutationCodes)
-        final.add(c);
-    return {
-        codes: Array.from(final).sort((a, b) => a - b),
-        resolved: true,
-    };
-}
-function parseFastApiStatusValue(val) {
-    const trimmed = val.trim();
-    // Literal 3-digit int.
-    const litMatch = trimmed.match(/^(\d{3})$/);
-    if (litMatch)
-        return Number(litMatch[1]);
-    // status.HTTP_NNN_NAME / starlette.status.HTTP_NNN_NAME / fastapi.status.HTTP_NNN_NAME.
-    const httpMatch = trimmed.match(/HTTP_(\d{3})_/);
-    if (httpMatch)
-        return Number(httpMatch[1]);
-    return undefined;
-}
-// ── FastAPI pagination strategy ──────────────────────────────────────────
-// Iterates the route handler's parameters and classifies each by name (or
-// `Query(alias=...)` literal alias when present) against page/offset/cursor
-// anchor sets. Returns:
-//   - `none` / resolved=true  — handler reads no anchor params (and no opaque
-//     paths to query data).
-//   - `page` / `offset` / `cursor` / resolved=true — handler reads exactly
-//     one family.
-//   - `mixed` / resolved=true — handler reads multiple families.
-//   - `undefined` / resolved=false — handler has a `Request` parameter,
-//     `**kwargs`, or a `Query(alias=<dynamic>)` we can't statically resolve.
-function extractFastApiPaginationStrategy(fnDef, source) {
-    const paramsNode = fnDef.childForFieldName('parameters');
-    if (!paramsNode)
-        return { strategy: 'none', resolved: true };
-    const families = new Set();
-    let sawOpaque = false;
-    for (const child of paramsNode.namedChildren) {
-        // **kwargs — handler may read any query key dynamically; opaque.
-        if (child.type === 'dictionary_splat_pattern') {
-            sawOpaque = true;
-            continue;
-        }
-        // *args — positional spread, irrelevant for query keys but rare in
-        // FastAPI handlers; keep silent.
-        if (child.type === 'list_splat_pattern')
-            continue;
-        // Drop typing wrappers to find the param identifier.
-        const paramName = extractParamName(child);
-        if (!paramName)
-            continue;
-        // `request: Request` — handler may call `request.query_params.get(...)`
-        // arbitrarily; mark opaque.
-        const typeText = extractParamTypeText(child, source);
-        if (typeText && /\bRequest\b/.test(typeText)) {
-            sawOpaque = true;
-            continue;
-        }
-        // Default-value AND type expression both can carry a `Query(alias="...")`
-        // call. Modern FastAPI (≥0.95) puts the call inside the type annotation
-        // via `Annotated[int, Query(alias="page")]` (Gemini/OpenCode impl-review).
-        // Older / classic syntax puts it in the default: `Query(0, alias="page")`.
-        // Check both — default-value form takes precedence when both are present.
-        const defaultText = extractParamDefaultText(child, source);
-        const aliasFromDefault = extractQueryAlias(defaultText);
-        const aliasFromType = aliasFromDefault.alias === undefined ? extractQueryAlias(typeText) : aliasFromDefault;
-        let key = paramName;
-        if (aliasFromDefault.opaque || aliasFromType.opaque) {
-            sawOpaque = true;
-            continue;
-        }
-        if (aliasFromDefault.alias)
-            key = aliasFromDefault.alias;
-        else if (aliasFromType.alias)
-            key = aliasFromType.alias;
-        const family = classifyPyAnchor(key);
-        if (family)
-            families.add(family);
-    }
-    if (sawOpaque)
-        return { strategy: undefined, resolved: false };
-    if (families.size === 0)
-        return { strategy: 'none', resolved: true };
-    if (families.size === 1)
-        return { strategy: [...families][0], resolved: true };
-    return { strategy: 'mixed', resolved: true };
-}
-function extractParamName(node) {
-    if (node.type === 'identifier')
-        return node.text;
-    if (node.type === 'typed_parameter' || node.type === 'typed_default_parameter' || node.type === 'default_parameter') {
-        const nameChild = node.childForFieldName('name') ?? node.namedChildren.find((c) => c.type === 'identifier');
-        if (nameChild)
-            return nameChild.text;
-    }
-    return undefined;
-}
-function extractParamTypeText(node, source) {
-    if (node.type !== 'typed_parameter' && node.type !== 'typed_default_parameter')
-        return undefined;
-    const typeChild = node.childForFieldName('type');
-    if (typeChild)
-        return source.substring(typeChild.startIndex, typeChild.endIndex);
-    return undefined;
-}
-function extractParamDefaultText(node, source) {
-    if (node.type !== 'default_parameter' && node.type !== 'typed_default_parameter')
-        return undefined;
-    const valueChild = node.childForFieldName('value');
-    if (valueChild)
-        return source.substring(valueChild.startIndex, valueChild.endIndex);
-    return undefined;
-}
-function classifyPyAnchor(key) {
-    if (PY_PAGE_ANCHORS.has(key))
-        return 'page';
-    if (PY_OFFSET_ANCHORS.has(key))
-        return 'offset';
-    if (PY_CURSOR_ANCHORS.has(key))
-        return 'cursor';
-    return undefined;
-}
-/** Extract a `Query(..., alias="...")` literal alias from a parameter's
- *  default-value or type-annotation text. Used to support both classic
- *  (`x = Query(0, alias="p")`) and modern (`x: Annotated[int, Query(alias="p")]`)
- *  FastAPI patterns. Returns `{alias?, opaque}` where `opaque=true` indicates
- *  a `Query(alias=<non-literal>)` we cannot statically resolve. */
-function extractQueryAlias(text) {
-    if (!text)
-        return { opaque: false };
-    if (!/\bQuery\s*\(/.test(text))
-        return { opaque: false };
-    const aliasMatch = text.match(/\balias\s*=\s*['"]([^'"]+)['"]/);
-    if (aliasMatch)
-        return { alias: aliasMatch[1], opaque: false };
-    if (/\balias\s*=/.test(text))
-        return { opaque: true };
-    return { opaque: false };
-}
-function extractPythonHttpExceptionStatusCodes(text) {
-    const codes = new Set();
-    const keywordRe = /HTTPException\s*\([^)]*status_code\s*=\s*(\d{3})/g;
-    for (const match of text.matchAll(keywordRe)) {
-        const code = Number(match[1]);
-        if (PY_API_ERROR_STATUS_CODES.has(code))
-            codes.add(code);
-    }
-    const positionalRe = /HTTPException\s*\(\s*(\d{3})/g;
-    for (const match of text.matchAll(positionalRe)) {
-        const code = Number(match[1]);
-        if (PY_API_ERROR_STATUS_CODES.has(code))
-            codes.add(code);
-    }
-    return codes.size > 0 ? Array.from(codes).sort((a, b) => a - b) : undefined;
-}
-function hasUnboundedPythonCollectionQuery(text, method, routePath, responseModel) {
-    if (method !== 'GET')
-        return false;
-    if (/[{:]/.test(routePath))
-        return false;
-    if (PY_PAGINATION_RE.test(text))
-        return false;
-    const responseLooksList = responseModel ? /^(list|List|Sequence|Iterable)\s*\[/.test(responseModel) : false;
-    return (PY_DB_COLLECTION_RE.test(text) &&
-        (responseLooksList || /\breturn\b[\s\S]*(\.all\s*\(|\.find\s*\(|\.fetchall\s*\()/.test(text)));
-}
-function collectPydanticModels(source) {
-    const models = new Map();
-    const classRe = /^class\s+([A-Za-z_]\w*)\s*\([^)]*BaseModel[^)]*\)\s*:/gm;
-    for (const match of source.matchAll(classRe)) {
-        const name = match[1];
-        const start = (match.index ?? 0) + match[0].length;
-        const rest = source.slice(start);
-        const nextTopLevel = rest.search(/\n\S/);
-        const body = nextTopLevel === -1 ? rest : rest.slice(0, nextTopLevel);
-        const fields = [];
-        const types = {};
-        // Capture annotations alongside names. The annotation runs until either
-        // an `=` (default value) or end-of-line / inline comment. Multiline
-        // annotations (`x: Annotated[\n  str, Field(...)\n]`) are not handled —
-        // false-negative on the type tag, never false-positive.
-        const fieldRe = /^[ \t]+([A-Za-z_]\w*)[ \t]*:[ \t]*([^=#\n]+?)(?:[ \t]*=[^\n]*|[ \t]*#[^\n]*)?$/gm;
-        for (const fieldMatch of body.matchAll(fieldRe)) {
-            const field = fieldMatch[1];
-            if (field === 'model_config' || field === 'Config')
-                continue;
-            fields.push(field);
-            const annotation = fieldMatch[2].trim();
-            types[field] = coarsenPythonTypeAnnotation(annotation);
-        }
-        if (fields.length > 0) {
-            models.set(name, { fields: fields.sort(), types: Object.freeze({ ...types }) });
-        }
-    }
-    return models;
-}
-// Split a type-annotation string at top-level commas / pipes — respecting
-// nested `[...]` brackets — so `Union[A, B[C, D]]` splits into `[A, B[C, D]]`
-// not `[A, B[C, D]]`.
-function splitTopLevelTypeArgs(s, delim) {
-    const parts = [];
-    let depth = 0;
-    let cur = '';
-    for (let i = 0; i < s.length; i++) {
-        const c = s[i];
-        if (c === '[' || c === '(')
-            depth++;
-        else if (c === ']' || c === ')')
-            depth--;
-        else if (c === delim && depth === 0) {
-            parts.push(cur.trim());
-            cur = '';
-            continue;
-        }
-        cur += c;
-    }
-    if (cur.trim())
-        parts.push(cur.trim());
-    return parts;
-}
-// Coarsen a Pydantic field type annotation to the same FieldTypeTag union
-// the TS mapper uses, so cross-stack rules can compare client TS types
-// against server Pydantic types symmetrically. Handles the common shapes:
-//
-//   str / int / float / bool / None / Decimal / UUID / EmailStr
-//   Optional[T] / Annotated[T, ...]               → coarsen T (drop wrapper)
-//   Union[A, B] / `A | B` (PEP 604)               → only stable if all agree
-//   List[T] / list[T] / Sequence[T] / Tuple[...]  → 'array'
-//   Dict[K, V] / dict[K, V] / Mapping[K, V]       → 'object'
-//   Literal['admin'] / Literal[1] / Literal[True] → primitive of literal
-//   <CapitalIdent>                                → 'object' (BaseModel sub)
-//
-// Anything we don't recognise → 'unknown'. Conservative on purpose:
-// /type rules skip 'unknown' tags.
-function coarsenPythonTypeAnnotation(ann) {
-    const t = ann.trim();
-    if (t === '')
-        return 'unknown';
-    // Optional[T] / typing.Optional[T] — strip and recurse.
-    const optMatch = t.match(/^(?:typing\.)?Optional\[([\s\S]+)\]$/);
-    if (optMatch)
-        return coarsenPythonTypeAnnotation(optMatch[1]);
-    // Annotated[T, ...] — first arg is the underlying type.
-    const annoMatch = t.match(/^(?:typing\.)?Annotated\[([\s\S]+)\]$/);
-    if (annoMatch) {
-        const parts = splitTopLevelTypeArgs(annoMatch[1], ',');
-        if (parts.length >= 1)
-            return coarsenPythonTypeAnnotation(parts[0]);
-        return 'unknown';
-    }
-    // Union[A, B, ...] — only stable if every non-null branch agrees.
-    // ANY 'unknown' branch poisons the result.
-    const unionMatch = t.match(/^(?:typing\.)?Union\[([\s\S]+)\]$/);
-    if (unionMatch) {
-        return coarsenUnionParts(splitTopLevelTypeArgs(unionMatch[1], ','));
-    }
-    // PEP 604 `int | None | str`. Only treat `|` as a union separator when
-    // it appears OUTSIDE of any `[...]` — otherwise `Dict[str, int | None]`
-    // would be split incorrectly.
-    if (containsTopLevelChar(t, '|')) {
-        return coarsenUnionParts(splitTopLevelTypeArgs(t, '|'));
-    }
-    // Container types — coarsen to wire shape.
-    if (/^(?:typing\.)?(?:List|list|Sequence|Iterable|Tuple|tuple|Set|set|FrozenSet|frozenset)\[/.test(t))
-        return 'array';
-    if (/^(?:typing\.)?(?:Dict|dict|Mapping|MutableMapping)\[/.test(t))
-        return 'object';
-    // Literal[X, Y, ...] — coarsen every literal arg, return the shared tag
-    // ONLY when all literals agree. Mixed-primitive literals like
-    // `Literal['a', 1]` accept either string or number on the wire, so
-    // tagging it 'string' (first-only) would FP-flag a number client.
-    // OpenCode caught this in the v1 review.
-    const litMatch = t.match(/^(?:typing\.)?Literal\[([\s\S]+)\]$/);
-    if (litMatch) {
-        const parts = splitTopLevelTypeArgs(litMatch[1], ',');
-        if (parts.length === 0)
-            return 'unknown';
-        const tags = parts.map((p) => coarsenLiteralValue(p.trim()));
-        if (tags.includes('unknown'))
-            return 'unknown';
-        const set = new Set(tags);
-        return set.size === 1 ? [...set][0] : 'unknown';
-    }
-    // Plain primitives + common Pydantic-string newtypes. `bytes` intentionally
-    // stays 'unknown' — it's binary on the wire and not a JSON primitive.
-    switch (t) {
-        case 'str':
-        case 'EmailStr':
-        case 'HttpUrl':
-        case 'AnyUrl':
-        case 'AnyHttpUrl':
-        case 'UUID':
-        case 'UUID1':
-        case 'UUID3':
-        case 'UUID4':
-        case 'UUID5':
-        case 'SecretStr':
-            return 'string';
-        case 'int':
-        case 'float':
-        case 'Decimal':
-        case 'PositiveInt':
-        case 'NegativeInt':
-        case 'NonNegativeInt':
-        case 'NonPositiveInt':
-        case 'PositiveFloat':
-        case 'NegativeFloat':
-            return 'number';
-        case 'bool':
-        case 'StrictBool':
-            return 'boolean';
-        case 'None':
-        case 'NoneType':
-            return 'null';
-    }
-    // Capitalized bare identifier could be:
-    //   - A nested BaseModel ('object' on the wire)
-    //   - A `class Status(str, Enum)` ('string' on the wire)
-    //   - A `Status = Literal['a','b']` type alias ('string' on the wire)
-    //   - A custom newtype like StrictStr / IPvAnyAddress
-    // We can't disambiguate without symbol resolution. Tagging 'object'
-    // FP'd Enum/Literal aliases against string clients (Codex flag); tag
-    // 'unknown' instead — the rule will skip and we trade FN for FP.
-    if (/^[A-Z][\w]*$/.test(t))
-        return 'unknown';
-    return 'unknown';
-}
-// Coarsen a single literal-value source token (e.g. `'admin'`, `42`, `True`)
-// to its primitive tag. Anything we don't recognise as one of the four JSON
-// primitives → 'unknown'.
-function coarsenLiteralValue(v) {
-    if (/^['"]/.test(v))
-        return 'string';
-    if (/^-?\d/.test(v))
-        return 'number';
-    if (v === 'True' || v === 'False')
-        return 'boolean';
-    if (v === 'None')
-        return 'null';
-    return 'unknown';
-}
-function coarsenUnionParts(parts) {
-    const tags = parts.map(coarsenPythonTypeAnnotation);
-    if (tags.includes('unknown'))
-        return 'unknown';
-    const noNull = tags.filter((tag) => tag !== 'null');
-    if (noNull.length === 0)
-        return 'null';
-    const set = new Set(noNull);
-    return set.size === 1 ? [...set][0] : 'unknown';
-}
-function containsTopLevelChar(s, ch) {
-    let depth = 0;
-    for (let i = 0; i < s.length; i++) {
-        const c = s[i];
-        if (c === '[' || c === '(')
-            depth++;
-        else if (c === ']' || c === ')')
-            depth--;
-        else if (c === ch && depth === 0)
-            return true;
-    }
-    return false;
-}
-function extractFastApiBodyValidation(fnDef, source, pydanticModels) {
-    const body = fnDef.childForFieldName('body') ?? fnDef.namedChildren.find((child) => child.type === 'block');
-    const headerEnd = body ? body.startIndex : fnDef.endIndex;
-    const header = source.substring(fnDef.startIndex, headerEnd);
-    const fields = new Set();
-    const types = {};
-    let has = false;
-    const annotationRe = /([A-Za-z_]\w*)\s*:\s*([A-Za-z_]\w*)/g;
-    for (const match of header.matchAll(annotationRe)) {
-        const model = pydanticModels.get(match[2]);
-        if (!model)
-            continue;
-        has = true;
-        for (const field of model.fields)
-            fields.add(field);
-        for (const [name, tag] of Object.entries(model.types)) {
-            // Only record concrete tags. 'unknown' for a key would shadow a
-            // concrete tag from another model parameter on the same handler
-            // (rare, but multi-arg handlers do exist), so skip them.
-            if (tag !== 'unknown')
-                types[name] = tag;
-        }
-    }
-    return {
-        has,
-        fields: fields.size > 0 ? Array.from(fields).sort() : undefined,
-        resolved: fields.size > 0,
-        types: Object.keys(types).length > 0 ? Object.freeze({ ...types }) : undefined,
-    };
-}
-// ── state_mutation ───────────────────────────────────────────────────────
-function extractStateMutation(root, source, filePath, nodes) {
-    // Track global keyword usage
-    const globalVarsInFile = new Set();
-    walkNodes(root, 'global_statement', (node) => {
-        for (const child of node.namedChildren) {
-            if (child.type === 'identifier')
-                globalVarsInFile.add(child.text);
-        }
-    });
-    walkNodes(root, 'assignment', (node) => {
-        const left = node.childForFieldName('left');
-        if (!left)
-            return;
-        // self.x = ... → scope 'module' (as requested)
-        if (left.type === 'attribute') {
-            const obj = left.childForFieldName('object');
-            if (obj && obj.text === 'self') {
-                nodes.push({
-                    id: conceptId(filePath, 'state_mutation', node.startIndex),
-                    kind: 'state_mutation',
-                    primarySpan: nodeSpan(filePath, node),
-                    evidence: nodeText(source, node, 100),
-                    confidence: 0.9,
-                    language: 'py',
-                    containerId: getContainerId(node, filePath),
-                    payload: { kind: 'state_mutation', target: left.text, scope: 'module' },
-                });
-                return;
-            }
-        }
-        // Global or Module level assignment
-        if (left.type === 'identifier') {
-            const name = left.text;
-            const containerId = getContainerId(node, filePath);
-            if (globalVarsInFile.has(name)) {
-                nodes.push({
-                    id: conceptId(filePath, 'state_mutation', node.startIndex),
-                    kind: 'state_mutation',
-                    primarySpan: nodeSpan(filePath, node),
-                    evidence: nodeText(source, node, 100),
-                    confidence: 1.0,
-                    language: 'py',
-                    containerId,
-                    payload: { kind: 'state_mutation', target: name, scope: 'global' },
-                });
-            }
-            else if (!containerId) {
-                // Module level (top level)
-                nodes.push({
-                    id: conceptId(filePath, 'state_mutation', node.startIndex),
-                    kind: 'state_mutation',
-                    primarySpan: nodeSpan(filePath, node),
-                    evidence: nodeText(source, node, 100),
-                    confidence: 0.8,
-                    language: 'py',
-                    payload: { kind: 'state_mutation', target: name, scope: 'module' },
-                });
-            }
-        }
-    });
-}
-// ── dependency ──────────────────────────────────────────────────────────
-function extractDependencyEdges(root, source, filePath, edges) {
-    const addDependency = (node, specifier) => {
-        let subtype = 'external';
-        if (specifier.startsWith('.')) {
-            subtype = 'internal';
-        }
-        else {
-            const rootModule = specifier.split('.')[0];
-            if (STDLIB_MODULES.has(rootModule)) {
-                subtype = 'stdlib';
-            }
-        }
-        edges.push({
-            id: `${filePath}#dep@${node.startIndex}`,
-            kind: 'dependency',
-            sourceId: filePath,
-            targetId: specifier,
-            primarySpan: nodeSpan(filePath, node),
-            evidence: nodeText(source, node, 100),
-            confidence: 1.0,
-            language: 'py',
-            payload: { kind: 'dependency', subtype, specifier },
-        });
-    };
-    walkNodes(root, 'import_statement', (node) => {
-        // import x, y as z
-        for (const child of node.namedChildren) {
-            if (child.type === 'dotted_name') {
-                addDependency(node, child.text);
-            }
-            else if (child.type === 'aliased_import') {
-                const name = child.childForFieldName('name');
-                if (name)
-                    addDependency(node, name.text);
-            }
-        }
-    });
-    walkNodes(root, 'import_from_statement', (node) => {
-        // from x import y
-        const moduleNode = node.childForFieldName('module_name');
-        const relativeMatch = node.text.match(/^from\s+(\.+)/);
-        let specifier = moduleNode ? moduleNode.text : '';
-        if (relativeMatch) {
-            specifier = relativeMatch[1] + specifier;
-        }
-        if (specifier) {
-            addDependency(node, specifier);
-        }
-    });
-}
-// ── Tree-sitter Helpers ──────────────────────────────────────────────────
-function walkNodes(root, type, callback) {
-    const cursor = root.walk();
-    let reachedRoot = false;
-    while (true) {
-        if (cursor.nodeType === type) {
-            callback(cursor.currentNode);
-        }
-        if (cursor.gotoFirstChild())
-            continue;
-        if (cursor.gotoNextSibling())
-            continue;
-        while (true) {
-            if (!cursor.gotoParent()) {
-                reachedRoot = true;
-                break;
-            }
-            if (cursor.gotoNextSibling())
-                break;
-        }
-        if (reachedRoot)
-            break;
-    }
-}
-function nodeSpan(filePath, node) {
-    return conceptSpan(filePath, node.startPosition.row + 1, node.startPosition.column + 1, node.endPosition.row + 1, node.endPosition.column + 1);
-}
-function nodeText(source, node, maxLen) {
-    return source.substring(node.startIndex, Math.min(node.endIndex, node.startIndex + maxLen));
-}
-function getContainerId(node, filePath) {
-    let parent = node.parent;
-    while (parent) {
-        if (parent.type === 'function_definition' || parent.type === 'class_definition') {
-            const nameNode = parent.childForFieldName('name');
-            const name = nameNode ? nameNode.text : 'anonymous';
-            return `${filePath}#fn:${name}@${parent.startIndex}`;
-        }
-        parent = parent.parent;
-    }
-    return undefined;
-}
-function getSelfContainerId(node, filePath) {
-    if (node.type !== 'function_definition' && node.type !== 'class_definition')
-        return undefined;
-    const nameNode = node.childForFieldName('name');
-    const name = nameNode ? nameNode.text : 'anonymous';
-    return `${filePath}#fn:${name}@${node.startIndex}`;
-}
-function extractResponseModel(decoratorText) {
-    const match = decoratorText.match(/\bresponse_model\s*=/);
-    if (!match || match.index === undefined)
-        return undefined;
-    let index = match.index + match[0].length;
-    while (/\s/.test(decoratorText[index] ?? ''))
-        index++;
-    const start = index;
-    let squareDepth = 0;
-    let parenDepth = 0;
-    let braceDepth = 0;
-    let quote;
-    while (index < decoratorText.length) {
-        const char = decoratorText[index];
-        const prev = decoratorText[index - 1];
-        if (quote) {
-            if (char === quote && prev !== '\\')
-                quote = undefined;
-            index++;
-            continue;
-        }
-        if (char === '"' || char === "'") {
-            quote = char;
-            index++;
-            continue;
-        }
-        if (char === '[')
-            squareDepth++;
-        else if (char === ']')
-            squareDepth = Math.max(0, squareDepth - 1);
-        else if (char === '(')
-            parenDepth++;
-        else if (char === ')') {
-            if (squareDepth === 0 && parenDepth === 0 && braceDepth === 0)
-                break;
-            parenDepth = Math.max(0, parenDepth - 1);
-        }
-        else if (char === '{')
-            braceDepth++;
-        else if (char === '}')
-            braceDepth = Math.max(0, braceDepth - 1);
-        else if (char === ',' && squareDepth === 0 && parenDepth === 0 && braceDepth === 0) {
-            break;
-        }
-        index++;
-    }
-    const model = decoratorText.slice(start, index).trim();
-    if (!model || model === 'None')
-        return undefined;
-    return model;
-}
-function extractRaiseType(node) {
-    // raise ValueError("...") → "ValueError"
-    const callNode = node.namedChildren.find((c) => c.type === 'call');
-    if (callNode) {
-        const func = callNode.childForFieldName('function');
-        if (func)
-            return func.text;
-    }
-    // raise ValueError → just identifier
-    const ident = node.namedChildren.find((c) => c.type === 'identifier');
-    if (ident)
-        return ident.text;
-    return undefined;
-}
-function extractExceptVar(node) {
-    // except Exception as e → "e"
-    for (const child of node.children) {
-        if (child.type === 'as_pattern') {
-            const alias = child.childForFieldName('alias');
-            if (alias)
-                return alias.text;
-        }
-        // Also try direct identifier after 'as'
-        if (child.type === 'identifier' && child.previousSibling?.text === 'as') {
-            return child.text;
-        }
-    }
-    return undefined;
-}
-function isInAsyncDef(node) {
-    let parent = node.parent;
-    while (parent) {
-        if (parent.type === 'function_definition') {
-            return isAsyncFunction(parent);
-        }
-        parent = parent.parent;
-    }
-    return false;
-}
-function isAsyncFunction(node) {
-    return node.children.some((c) => c.type === 'async');
-}
+export { extractPythonConcepts } from './mapper/index.js';