@kernlang/review-python 3.4.6-canary.45.1.130ca3d2 → 3.4.6-canary.46.1.19dcfc19

package/src/mapper/extractors/fastapi-pagination.ts

@@ -0,0 +1,117 @@
+import type Parser from 'tree-sitter';
+import { PY_CURSOR_ANCHORS, PY_OFFSET_ANCHORS, PY_PAGE_ANCHORS } from '../signatures.js';
+
+// 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.
+export function extractFastApiPaginationStrategy(
+  fnDef: Parser.SyntaxNode,
+  source: string,
+): {
+  strategy: 'page' | 'offset' | 'cursor' | 'mixed' | 'none' | undefined;
+  resolved: boolean;
+} {
+  const paramsNode = fnDef.childForFieldName('parameters');
+  if (!paramsNode) return { strategy: 'none', resolved: true };
+
+  const families = new Set<'page' | 'offset' | 'cursor'>();
+  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: Parser.SyntaxNode): string | undefined {
+  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: Parser.SyntaxNode, source: string): string | undefined {
+  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: Parser.SyntaxNode, source: string): string | undefined {
+  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: string): 'page' | 'offset' | 'cursor' | undefined {
+  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: string | undefined): { alias?: string; opaque: boolean } {
+  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 };
+}

package/src/mapper/extractors/fastapi-status.ts

@@ -0,0 +1,119 @@
+import type Parser from 'tree-sitter';
+import { FASTAPI_DEFAULT_SUCCESS_STATUS, PY_API_SUCCESS_STATUS_CODES } from '../signatures.js';
+
+// 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.
+export function extractFastApiSuccessStatusCodes(
+  decText: string,
+  fnDef: Parser.SyntaxNode,
+  source: string,
+): { codes: readonly number[] | undefined; resolved: boolean } {
+  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: number | undefined;
+  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<number>();
+  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<number>();
+  // `=(?!=)` 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<number>();
+
+  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,
+  };
+}
+
+export function parseFastApiStatusValue(val: string): number | undefined {
+  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;
+}

package/src/mapper/extractors/guard.ts

@@ -0,0 +1,114 @@
+import type { ConceptNode } from '@kernlang/core';
+import { conceptId } from '@kernlang/core';
+import type Parser from 'tree-sitter';
+import { getContainerId, nodeSpan, nodeText, walkNodes } from '../helpers/ast.js';
+
+export function extractGuards(root: Parser.SyntaxNode, source: string, filePath: string, nodes: ConceptNode[]): void {
+  // 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: 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';
+}

package/src/mapper/extractors/pydantic.ts

@@ -0,0 +1,74 @@
+import type Parser from 'tree-sitter';
+import { coarsenPythonTypeAnnotation, type FieldTypeMap, type FieldTypeTag } from '../helpers/types.js';
+
+export interface PydanticModel {
+  fields: readonly string[];
+  types: FieldTypeMap;
+}
+
+export function collectPydanticModels(source: string): Map<string, PydanticModel> {
+  const models = new Map<string, PydanticModel>();
+  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: string[] = [];
+    const types: Record<string, FieldTypeTag> = {};
+    // 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;
+}
+
+export function extractFastApiBodyValidation(
+  fnDef: Parser.SyntaxNode,
+  source: string,
+  pydanticModels: ReadonlyMap<string, PydanticModel>,
+): {
+  has: boolean;
+  fields: readonly string[] | undefined;
+  resolved: boolean;
+  types: FieldTypeMap | undefined;
+} {
+  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<string>();
+  const types: Record<string, FieldTypeTag> = {};
+  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,
+  };
+}

package/src/mapper/extractors/state-mutation.ts

@@ -0,0 +1,72 @@
+import type { ConceptNode } from '@kernlang/core';
+import { conceptId } from '@kernlang/core';
+import type Parser from 'tree-sitter';
+import { getContainerId, nodeSpan, nodeText, walkNodes } from '../helpers/ast.js';
+
+export function extractStateMutation(
+  root: Parser.SyntaxNode,
+  source: string,
+  filePath: string,
+  nodes: ConceptNode[],
+): void {
+  // Track global keyword usage
+  const globalVarsInFile = new Set<string>();
+  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' },
+        });
+      }
+    }
+  });
+}

package/src/mapper/helpers/ast.ts

@@ -0,0 +1,72 @@
+import type { ConceptSpan } from '@kernlang/core';
+import { conceptSpan } from '@kernlang/core';
+import type Parser from 'tree-sitter';
+
+export function walkNodes(root: Parser.SyntaxNode, type: string, callback: (node: Parser.SyntaxNode) => void): void {
+  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;
+  }
+}
+
+export function nodeSpan(filePath: string, node: Parser.SyntaxNode): ConceptSpan {
+  return conceptSpan(
+    filePath,
+    node.startPosition.row + 1,
+    node.startPosition.column + 1,
+    node.endPosition.row + 1,
+    node.endPosition.column + 1,
+  );
+}
+
+export function nodeText(source: string, node: Parser.SyntaxNode, maxLen: number): string {
+  return source.substring(node.startIndex, Math.min(node.endIndex, node.startIndex + maxLen));
+}
+
+export function getContainerId(node: Parser.SyntaxNode, filePath: string): string | undefined {
+  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;
+}
+
+export 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}`;
+}
+
+export function isInAsyncDef(node: Parser.SyntaxNode): boolean {
+  let parent = node.parent;
+  while (parent) {
+    if (parent.type === 'function_definition') {
+      return isAsyncFunction(parent);
+    }
+    parent = parent.parent;
+  }
+  return false;
+}
+
+export function isAsyncFunction(node: Parser.SyntaxNode): boolean {
+  return node.children.some((c) => c.type === 'async');
+}