@kernlang/review-python 3.4.6-canary.46.1.19dcfc19 → 3.4.6-canary.53.1.ca3b242b

package/dist/mapper/extractors/background-tasks.d.ts

@@ -0,0 +1,3 @@
+import type { ConceptNode } from '@kernlang/core';
+import type Parser from 'tree-sitter';
+export declare function extractBackgroundTasks(root: Parser.SyntaxNode, source: string, filePath: string, nodes: ConceptNode[]): void;

package/dist/mapper/extractors/background-tasks.js

@@ -0,0 +1,103 @@
+import { conceptId } from '@kernlang/core';
+import { getContainerId, isInAsyncDef, nodeSpan, nodeText, walkNodes } from '../helpers/ast.js';
+// FastAPI BackgroundTasks dispatch.
+//
+//   from fastapi import BackgroundTasks
+//
+//   @app.post("/email")
+//   async def send_email(background_tasks: BackgroundTasks, body: EmailIn):
+//       background_tasks.add_task(send_email_func, body.to)
+//                       ^^^^^^^^^ → effect[background-task]
+//
+// We emit one effect concept per `<param>.add_task(...)` call inside a
+// function whose signature declares a `BackgroundTasks` parameter. The
+// `target` carries the dispatched function name when it can be read from
+// the first positional arg.
+export function extractBackgroundTasks(root, source, filePath, nodes) {
+    walkNodes(root, 'function_definition', (fnDef) => {
+        const paramNames = collectBackgroundTasksParams(fnDef, source);
+        if (paramNames.size === 0)
+            return;
+        const body = fnDef.childForFieldName('body');
+        if (!body)
+            return;
+        walkNodes(body, 'call', (callNode) => {
+            const fnNode = callNode.childForFieldName('function');
+            if (!fnNode || fnNode.type !== 'attribute')
+                return;
+            const obj = fnNode.childForFieldName('object');
+            const attr = fnNode.childForFieldName('attribute');
+            if (!obj || !attr)
+                return;
+            if (attr.text !== 'add_task')
+                return;
+            if (!paramNames.has(obj.text))
+                return;
+            const target = readTargetName(callNode, source);
+            nodes.push({
+                id: conceptId(filePath, 'effect', callNode.startIndex),
+                kind: 'effect',
+                primarySpan: nodeSpan(filePath, callNode),
+                evidence: nodeText(source, callNode, 120),
+                confidence: 0.95,
+                language: 'py',
+                containerId: getContainerId(callNode, filePath),
+                payload: {
+                    kind: 'effect',
+                    subtype: 'background-task',
+                    async: isInAsyncDef(callNode),
+                    target,
+                },
+            });
+        });
+    });
+}
+function collectBackgroundTasksParams(fnDef, source) {
+    const names = new Set();
+    const params = fnDef.childForFieldName('parameters');
+    if (!params)
+        return names;
+    for (const child of params.namedChildren) {
+        if (child.type !== 'typed_parameter' && child.type !== 'typed_default_parameter')
+            continue;
+        const typeNode = child.childForFieldName('type');
+        if (!typeNode)
+            continue;
+        const typeText = source.substring(typeNode.startIndex, typeNode.endIndex).trim();
+        if (typeText !== 'BackgroundTasks' && typeText !== 'fastapi.BackgroundTasks')
+            continue;
+        // typed_parameter has the name as its first child identifier;
+        // typed_default_parameter exposes it via the `name` field.
+        const nameField = child.childForFieldName('name');
+        if (nameField) {
+            names.add(nameField.text);
+            continue;
+        }
+        const ident = child.namedChildren.find((c) => c.type === 'identifier');
+        if (ident)
+            names.add(ident.text);
+    }
+    return names;
+}
+function readTargetName(callNode, source) {
+    const args = callNode.childForFieldName('arguments');
+    if (!args)
+        return undefined;
+    // The scheduled callable can be passed positionally or as `func=...`
+    // (BackgroundTasks.add_task signature: `add_task(func, *args, **kwargs)`).
+    // Take the first positional arg if present; otherwise look for `func=`.
+    let funcKeywordValue;
+    for (const child of args.namedChildren) {
+        if (child.type === 'keyword_argument') {
+            const nameNode = child.childForFieldName('name');
+            if (nameNode && nameNode.text === 'func') {
+                const valueNode = child.childForFieldName('value');
+                if (valueNode)
+                    funcKeywordValue = source.substring(valueNode.startIndex, valueNode.endIndex).trim();
+            }
+            continue;
+        }
+        return source.substring(child.startIndex, child.endIndex).trim();
+    }
+    return funcKeywordValue;
+}

package/dist/mapper/index.js

@@ -6,6 +6,7 @@
  */
 import Parser from 'tree-sitter';
 import Python from 'tree-sitter-python';
+import { extractBackgroundTasks } from './extractors/background-tasks.js';
 import { extractDependencyEdges } from './extractors/dependency.js';
 import { extractEffects } from './extractors/effect.js';
 import { extractEntrypoints } from './extractors/entrypoint.js';
@@ -28,6 +29,7 @@ export function extractPythonConcepts(source, filePath) {
     extractErrorRaise(tree.rootNode, source, filePath, nodes);
     extractErrorHandle(tree.rootNode, source, filePath, nodes);
     extractEffects(tree.rootNode, source, filePath, nodes);
+    extractBackgroundTasks(tree.rootNode, source, filePath, nodes);
     extractEntrypoints(tree.rootNode, source, filePath, nodes);
     extractGuards(tree.rootNode, source, filePath, nodes);
     extractStateMutation(tree.rootNode, source, filePath, nodes);

package/dist/mapper/signatures.d.ts

@@ -3,7 +3,6 @@ export declare const NETWORK_MODULES: Set<string>;
 export declare const NETWORK_METHODS: Set<string>;
 export declare const DB_MODULES: Set<string>;
 export declare const DB_METHODS: Set<string>;
-export declare const _FS_FUNCTIONS: Set<string>;
 export declare const PY_API_ERROR_STATUS_CODES: Set<number>;
 export declare const PY_API_SUCCESS_STATUS_CODES: Set<number>;
 export declare const FASTAPI_DEFAULT_SUCCESS_STATUS = 200;

package/dist/mapper/signatures.js

@@ -26,7 +26,6 @@ export const DB_METHODS = new Set([
     'update_one',
     'delete_one',
 ]);
-export const _FS_FUNCTIONS = new Set(['open', 'read', 'write', 'readlines', 'writelines']);
 export const PY_API_ERROR_STATUS_CODES = new Set([401, 403, 404, 422, 500]);
 export 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernlang/review-python",
-  "version": "3.4.6-canary.46.1.19dcfc19",
+  "version": "3.4.6-canary.53.1.ca3b242b",
   "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/core": "3.4.6-canary.46.1.19dcfc19",
-    "@kernlang/review": "3.4.6-canary.46.1.19dcfc19"
+    "@kernlang/core": "3.4.6-canary.53.1.ca3b242b",
+    "@kernlang/review": "3.4.6-canary.53.1.ca3b242b"
   },
   "devDependencies": {
     "ts-morph": "^28.0.0",

package/src/mapper/extractors/background-tasks.ts

@@ -0,0 +1,107 @@
+import type { ConceptNode } from '@kernlang/core';
+import { conceptId } from '@kernlang/core';
+import type Parser from 'tree-sitter';
+import { getContainerId, isInAsyncDef, nodeSpan, nodeText, walkNodes } from '../helpers/ast.js';
+
+// FastAPI BackgroundTasks dispatch.
+//
+//   from fastapi import BackgroundTasks
+//
+//   @app.post("/email")
+//   async def send_email(background_tasks: BackgroundTasks, body: EmailIn):
+//       background_tasks.add_task(send_email_func, body.to)
+//                       ^^^^^^^^^ → effect[background-task]
+//
+// We emit one effect concept per `<param>.add_task(...)` call inside a
+// function whose signature declares a `BackgroundTasks` parameter. The
+// `target` carries the dispatched function name when it can be read from
+// the first positional arg.
+export function extractBackgroundTasks(
+  root: Parser.SyntaxNode,
+  source: string,
+  filePath: string,
+  nodes: ConceptNode[],
+): void {
+  walkNodes(root, 'function_definition', (fnDef) => {
+    const paramNames = collectBackgroundTasksParams(fnDef, source);
+    if (paramNames.size === 0) return;
+
+    const body = fnDef.childForFieldName('body');
+    if (!body) return;
+
+    walkNodes(body, 'call', (callNode) => {
+      const fnNode = callNode.childForFieldName('function');
+      if (!fnNode || fnNode.type !== 'attribute') return;
+
+      const obj = fnNode.childForFieldName('object');
+      const attr = fnNode.childForFieldName('attribute');
+      if (!obj || !attr) return;
+      if (attr.text !== 'add_task') return;
+      if (!paramNames.has(obj.text)) return;
+
+      const target = readTargetName(callNode, source);
+      nodes.push({
+        id: conceptId(filePath, 'effect', callNode.startIndex),
+        kind: 'effect',
+        primarySpan: nodeSpan(filePath, callNode),
+        evidence: nodeText(source, callNode, 120),
+        confidence: 0.95,
+        language: 'py',
+        containerId: getContainerId(callNode, filePath),
+        payload: {
+          kind: 'effect',
+          subtype: 'background-task',
+          async: isInAsyncDef(callNode),
+          target,
+        },
+      });
+    });
+  });
+}
+
+function collectBackgroundTasksParams(fnDef: Parser.SyntaxNode, source: string): Set<string> {
+  const names = new Set<string>();
+  const params = fnDef.childForFieldName('parameters');
+  if (!params) return names;
+
+  for (const child of params.namedChildren) {
+    if (child.type !== 'typed_parameter' && child.type !== 'typed_default_parameter') continue;
+    const typeNode = child.childForFieldName('type');
+    if (!typeNode) continue;
+    const typeText = source.substring(typeNode.startIndex, typeNode.endIndex).trim();
+    if (typeText !== 'BackgroundTasks' && typeText !== 'fastapi.BackgroundTasks') continue;
+
+    // typed_parameter has the name as its first child identifier;
+    // typed_default_parameter exposes it via the `name` field.
+    const nameField = child.childForFieldName('name');
+    if (nameField) {
+      names.add(nameField.text);
+      continue;
+    }
+    const ident = child.namedChildren.find((c) => c.type === 'identifier');
+    if (ident) names.add(ident.text);
+  }
+  return names;
+}
+
+function readTargetName(callNode: Parser.SyntaxNode, source: string): string | undefined {
+  const args = callNode.childForFieldName('arguments');
+  if (!args) return undefined;
+
+  // The scheduled callable can be passed positionally or as `func=...`
+  // (BackgroundTasks.add_task signature: `add_task(func, *args, **kwargs)`).
+  // Take the first positional arg if present; otherwise look for `func=`.
+  let funcKeywordValue: string | undefined;
+  for (const child of args.namedChildren) {
+    if (child.type === 'keyword_argument') {
+      const nameNode = child.childForFieldName('name');
+      if (nameNode && nameNode.text === 'func') {
+        const valueNode = child.childForFieldName('value');
+        if (valueNode) funcKeywordValue = source.substring(valueNode.startIndex, valueNode.endIndex).trim();
+      }
+      continue;
+    }
+    return source.substring(child.startIndex, child.endIndex).trim();
+  }
+  return funcKeywordValue;
+}

package/src/mapper/index.ts

@@ -8,6 +8,7 @@
 import type { ConceptEdge, ConceptMap, ConceptNode } from '@kernlang/core';
 import Parser from 'tree-sitter';
 import Python from 'tree-sitter-python';
+import { extractBackgroundTasks } from './extractors/background-tasks.js';
 import { extractDependencyEdges } from './extractors/dependency.js';
 import { extractEffects } from './extractors/effect.js';
 import { extractEntrypoints } from './extractors/entrypoint.js';
@@ -34,6 +35,7 @@ export function extractPythonConcepts(source: string, filePath: string): Concept
   extractErrorRaise(tree.rootNode, source, filePath, nodes);
   extractErrorHandle(tree.rootNode, source, filePath, nodes);
   extractEffects(tree.rootNode, source, filePath, nodes);
+  extractBackgroundTasks(tree.rootNode, source, filePath, nodes);
 
   extractEntrypoints(tree.rootNode, source, filePath, nodes);
   extractGuards(tree.rootNode, source, filePath, nodes);

package/src/mapper/signatures.ts

@@ -29,8 +29,6 @@ export const DB_METHODS = new Set([
   'delete_one',
 ]);
 
-export const _FS_FUNCTIONS = new Set(['open', 'read', 'write', 'readlines', 'writelines']);
-
 export const PY_API_ERROR_STATUS_CODES = new Set([401, 403, 404, 422, 500]);
 export 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

package/tests/background-tasks.test.ts

@@ -0,0 +1,87 @@
+/// <reference types="jest" />
+import type { ConceptNode, EffectPayload } from '@kernlang/core';
+import { extractPythonConcepts } from '../src/mapper.js';
+
+function isEffectNode(node: ConceptNode): node is ConceptNode & { payload: EffectPayload } {
+  return node.kind === 'effect' && node.payload.kind === 'effect';
+}
+
+function backgroundTasks(source: string) {
+  return extractPythonConcepts(source, 'app/api/email.py')
+    .nodes.filter(isEffectNode)
+    .filter((node) => node.payload.subtype === 'background-task');
+}
+
+describe('FastAPI BackgroundTasks extraction', () => {
+  it('emits one background-task effect per add_task call', () => {
+    const effects = backgroundTasks(`
+from fastapi import BackgroundTasks
+
+@app.post("/email")
+async def send_email(background_tasks: BackgroundTasks, body: dict):
+    background_tasks.add_task(send_email_func, body["to"])
+    background_tasks.add_task(log_email, body["to"])
+    return {"ok": True}
+`);
+
+    expect(effects).toHaveLength(2);
+    expect(effects[0].payload.subtype).toBe('background-task');
+    expect(effects[0].payload.target).toBe('send_email_func');
+    expect(effects[0].payload.async).toBe(true);
+    expect(effects[1].payload.target).toBe('log_email');
+  });
+
+  it('only fires when the param is typed BackgroundTasks', () => {
+    const effects = backgroundTasks(`
+@app.post("/email")
+async def send_email(other: SomeOther):
+    other.add_task(send_email_func)
+    return {"ok": True}
+`);
+
+    expect(effects).toHaveLength(0);
+  });
+
+  it('matches against the param name, not arbitrary identifiers', () => {
+    const effects = backgroundTasks(`
+from fastapi import BackgroundTasks
+
+@app.post("/email")
+async def send_email(bg: BackgroundTasks):
+    bg.add_task(send_email_func)
+    other.add_task(should_not_match)
+    return {"ok": True}
+`);
+
+    expect(effects).toHaveLength(1);
+    expect(effects[0].payload.target).toBe('send_email_func');
+  });
+
+  it('handles add_task(func=...) keyword form', () => {
+    const effects = backgroundTasks(`
+from fastapi import BackgroundTasks
+
+@app.post("/email")
+async def send_email(background_tasks: BackgroundTasks):
+    background_tasks.add_task(func=send_email_func, to="x@y")
+    return {"ok": True}
+`);
+
+    expect(effects).toHaveLength(1);
+    expect(effects[0].payload.target).toBe('send_email_func');
+  });
+
+  it('records async=false for sync route handlers', () => {
+    const effects = backgroundTasks(`
+from fastapi import BackgroundTasks
+
+@app.post("/email")
+def send_email(background_tasks: BackgroundTasks):
+    background_tasks.add_task(send_email_func)
+    return {"ok": True}
+`);
+
+    expect(effects).toHaveLength(1);
+    expect(effects[0].payload.async).toBe(false);
+  });
+});

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/index.ts","./src/mapper.ts","./src/mapper/index.ts","./src/mapper/signatures.ts","./src/mapper/extractors/dependency.ts","./src/mapper/extractors/effect.ts","./src/mapper/extractors/entrypoint.ts","./src/mapper/extractors/error.ts","./src/mapper/extractors/fastapi-pagination.ts","./src/mapper/extractors/fastapi-status.ts","./src/mapper/extractors/guard.ts","./src/mapper/extractors/pydantic.ts","./src/mapper/extractors/state-mutation.ts","./src/mapper/helpers/ast.ts","./src/mapper/helpers/types.ts"],"version":"6.0.3"}
+{"root":["./src/index.ts","./src/mapper.ts","./src/mapper/index.ts","./src/mapper/signatures.ts","./src/mapper/extractors/background-tasks.ts","./src/mapper/extractors/dependency.ts","./src/mapper/extractors/effect.ts","./src/mapper/extractors/entrypoint.ts","./src/mapper/extractors/error.ts","./src/mapper/extractors/fastapi-pagination.ts","./src/mapper/extractors/fastapi-status.ts","./src/mapper/extractors/guard.ts","./src/mapper/extractors/pydantic.ts","./src/mapper/extractors/state-mutation.ts","./src/mapper/helpers/ast.ts","./src/mapper/helpers/types.ts"],"version":"6.0.3"}