@kernlang/review-python 3.3.4 → 3.3.6

package/dist/mapper.js

@@ -253,8 +253,15 @@ function extractEffects(root, source, filePath, nodes) {
 }
 // ── entrypoint ──────────────────────────────────────────────────────────
 function extractEntrypoints(root, source, filePath, nodes) {
-    // 1. Route decorators: @app.route, @app.get, @router.post, etc.
-    // tree-sitter Python wraps decorated functions in 'decorated_definition'
+    // 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)
@@ -263,31 +270,91 @@ function extractEntrypoints(root, source, filePath, nodes) {
             if (child.type !== 'decorator')
                 continue;
             const decText = source.substring(child.startIndex, child.endIndex);
-            const routeMatch = decText.match(/@(app|router|bp)\.(route|get|post|put|delete|patch)\s*\(/);
-            if (routeMatch) {
-                const method = routeMatch[2].toUpperCase();
-                const nameNode = fnDef.childForFieldName('name');
-                // Try to extract path from decorator args
-                const pathMatch = decText.match(/['"]([^'"]+)['"]/);
-                nodes.push({
-                    id: conceptId(filePath, 'entrypoint', child.startIndex),
+            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);
+            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',
-                    primarySpan: nodeSpan(filePath, child),
-                    evidence: nodeText(source, child, 100),
-                    confidence: 1.0,
-                    language: 'py',
-                    containerId: getContainerId(node, filePath),
-                    payload: {
-                        kind: 'entrypoint',
-                        subtype: 'route',
-                        name: nameNode ? nameNode.text : pathMatch?.[1] || 'anonymous',
-                        httpMethod: method === 'ROUTE' ? undefined : method,
-                    },
-                });
-            }
+                    subtype: 'route',
+                    name: routePath,
+                    httpMethod: method === 'ROUTE' ? undefined : method,
+                    responseModel,
+                    isAsync: isAsyncFunction(fnDef),
+                    routerName,
+                },
+            });
         }
     });
-    // 2. if __name__ == '__main__':
+    // 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__')) {
@@ -349,7 +416,42 @@ function extractGuards(root, source, filePath, nodes) {
             });
         }
     });
-    // 3. Early return/raise after auth check: if not request.user: raise/return
+    // 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)) {
@@ -372,6 +474,20 @@ function extractGuards(root, source, filePath, nodes) {
         }
     });
 }
+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';
+}
 // ── state_mutation ───────────────────────────────────────────────────────
 function extractStateMutation(root, source, filePath, nodes) {
     // Track global keyword usage
@@ -527,6 +643,64 @@ function getContainerId(node, filePath) {
     }
     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');
@@ -560,10 +734,12 @@ function isInAsyncDef(node) {
     let parent = node.parent;
     while (parent) {
         if (parent.type === 'function_definition') {
-            // Check for 'async' keyword before 'def'
-            return parent.children.some((c) => c.type === 'async');
+            return isAsyncFunction(parent);
         }
         parent = parent.parent;
     }
     return false;
 }
+function isAsyncFunction(node) {
+    return node.children.some((c) => c.type === 'async');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernlang/review-python",
-  "version": "3.3.4",
+  "version": "3.3.6",
   "description": "Python concept mapper for kern review — tree-sitter based",
   "type": "module",
   "main": "dist/index.js",
@@ -8,8 +8,8 @@
   "dependencies": {
     "tree-sitter": "^0.25.0",
     "tree-sitter-python": "^0.25.0",
-    "@kernlang/review": "3.3.4",
-    "@kernlang/core": "3.3.4"
+    "@kernlang/review": "3.3.6",
+    "@kernlang/core": "3.3.6"
   },
   "devDependencies": {
     "ts-morph": "^28.0.0",

package/src/mapper.ts

@@ -295,8 +295,15 @@ function extractEffects(root: Parser.SyntaxNode, source: string, filePath: strin
 // ── entrypoint ──────────────────────────────────────────────────────────
 
 function extractEntrypoints(root: Parser.SyntaxNode, source: string, filePath: string, nodes: ConceptNode[]): void {
-  // 1. Route decorators: @app.route, @app.get, @router.post, etc.
-  // tree-sitter Python wraps decorated functions in 'decorated_definition'
+  // 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;
@@ -305,33 +312,93 @@ function extractEntrypoints(root: Parser.SyntaxNode, source: string, filePath: s
       if (child.type !== 'decorator') continue;
       const decText = source.substring(child.startIndex, child.endIndex);
 
-      const routeMatch = decText.match(/@(app|router|bp)\.(route|get|post|put|delete|patch)\s*\(/);
-      if (routeMatch) {
-        const method = routeMatch[2].toUpperCase();
-        const nameNode = fnDef.childForFieldName('name');
-        // Try to extract path from decorator args
-        const pathMatch = decText.match(/['"]([^'"]+)['"]/);
+      const routeMatch = decText.match(/@(\w+)\.(route|get|post|put|delete|patch)\s*\(/);
+      if (!routeMatch) continue;
 
-        nodes.push({
-          id: conceptId(filePath, 'entrypoint', child.startIndex),
+      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);
+
+      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',
-          primarySpan: nodeSpan(filePath, child),
-          evidence: nodeText(source, child, 100),
-          confidence: 1.0,
-          language: 'py',
-          containerId: getContainerId(node, filePath),
-          payload: {
-            kind: 'entrypoint',
-            subtype: 'route',
-            name: nameNode ? nameNode.text : pathMatch?.[1] || 'anonymous',
-            httpMethod: method === 'ROUTE' ? undefined : method,
-          },
-        });
-      }
+          subtype: 'route',
+          name: routePath,
+          httpMethod: method === 'ROUTE' ? undefined : method,
+          responseModel,
+          isAsync: isAsyncFunction(fnDef),
+          routerName,
+        },
+      });
     }
   });
 
-  // 2. if __name__ == '__main__':
+  // 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__')) {
@@ -396,7 +463,40 @@ function extractGuards(root: Parser.SyntaxNode, source: string, filePath: string
     }
   });
 
-  // 3. Early return/raise after auth check: if not request.user: raise/return
+  // 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)) {
@@ -420,6 +520,17 @@ function extractGuards(root: Parser.SyntaxNode, source: string, filePath: string
   });
 }
 
+function classifyDependency(depName: string): 'auth' | 'validation' | 'rate-limit' | 'policy' {
+  // 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';
+}
+
 // ── state_mutation ───────────────────────────────────────────────────────
 
 function extractStateMutation(root: Parser.SyntaxNode, source: string, filePath: string, nodes: ConceptNode[]): void {
@@ -587,6 +698,62 @@ function getContainerId(node: Parser.SyntaxNode, filePath: string): string | und
   return undefined;
 }
 
+function getSelfContainerId(node: Parser.SyntaxNode, filePath: string): string | undefined {
+  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: string): string | undefined {
+  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: string | undefined;
+
+  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: Parser.SyntaxNode): string | undefined {
   // raise ValueError("...") → "ValueError"
   const callNode = node.namedChildren.find((c) => c.type === 'call');
@@ -619,10 +786,13 @@ function isInAsyncDef(node: Parser.SyntaxNode): boolean {
   let parent = node.parent;
   while (parent) {
     if (parent.type === 'function_definition') {
-      // Check for 'async' keyword before 'def'
-      return parent.children.some((c) => c.type === 'async');
+      return isAsyncFunction(parent);
     }
     parent = parent.parent;
   }
   return false;
 }
+
+function isAsyncFunction(node: Parser.SyntaxNode): boolean {
+  return node.children.some((c) => c.type === 'async');
+}

package/tests/route-entrypoints.test.ts

@@ -0,0 +1,99 @@
+/// <reference types="jest" />
+import type { ConceptNode, EntrypointPayload } from '@kernlang/core';
+import { extractPythonConcepts } from '../src/mapper.js';
+
+function isEntrypointNode(node: ConceptNode): node is ConceptNode & { payload: EntrypointPayload } {
+  return node.kind === 'entrypoint' && node.payload.kind === 'entrypoint';
+}
+
+function routePayloads(source: string) {
+  return extractPythonConcepts(source, 'app/api/users.py')
+    .nodes.filter(isEntrypointNode)
+    .map((node) => ({ node, payload: node.payload }));
+}
+
+describe('Python route entrypoint payloads', () => {
+  it('extracts FastAPI response_model from route decorator kwargs', () => {
+    const routes = routePayloads(`
+from fastapi import APIRouter
+router = APIRouter()
+
+@router.get("/users", response_model=UserOut)
+def list_users():
+    return []
+`);
+
+    expect(routes).toHaveLength(1);
+    expect(routes[0].payload.responseModel).toBe('UserOut');
+  });
+
+  it('extracts bracketed response_model expressions', () => {
+    const routes = routePayloads(`
+@router.get("/users", response_model=list[schemas.UserOut])
+def list_users():
+    return []
+`);
+
+    expect(routes[0].payload.responseModel).toBe('list[schemas.UserOut]');
+  });
+
+  it('extracts nested response_model generic expressions', () => {
+    const routes = routePayloads(`
+@router.get("/users", response_model=dict[str, list[schemas.UserOut]], status_code=200)
+def list_users():
+    return {}
+`);
+
+    expect(routes[0].payload.responseModel).toBe('dict[str, list[schemas.UserOut]]');
+  });
+
+  it('leaves responseModel undefined when response_model is absent or None', () => {
+    const routes = routePayloads(`
+@router.get("/healthz")
+def healthz():
+    return {"ok": True}
+
+@router.get("/raw", response_model=None)
+def raw():
+    return {"ok": True}
+`);
+
+    expect(routes.map((route) => route.payload.responseModel)).toEqual([undefined, undefined]);
+  });
+
+  it('marks async def route handlers as async', () => {
+    const routes = routePayloads(`
+@router.get("/users", response_model=UserOut)
+async def list_users():
+    return []
+`);
+
+    expect(routes[0].payload.isAsync).toBe(true);
+  });
+
+  it('marks sync def route handlers as not async', () => {
+    const routes = routePayloads(`
+@router.get("/users", response_model=UserOut)
+def list_users():
+    return []
+`);
+
+    expect(routes[0].payload.isAsync).toBe(false);
+  });
+
+  it('sets the route containerId to the decorated function container', () => {
+    const concepts = extractPythonConcepts(
+      `
+@router.get("/users")
+def list_users():
+    requests.get("https://example.com")
+`,
+      'app/api/users.py',
+    );
+
+    const route = concepts.nodes.find((node) => node.kind === 'entrypoint');
+    const effect = concepts.nodes.find((node) => node.kind === 'effect');
+    expect(route?.containerId).toBeDefined();
+    expect(route?.containerId).toBe(effect?.containerId);
+  });
+});

package/tsconfig.json

@@ -9,6 +9,7 @@
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
+    "types": ["node", "jest"],
     "resolveJsonModule": true
   },
   "include": ["src"],