@kernlang/review-python 3.3.8 → 3.4.0

package/dist/mapper.js

@@ -27,6 +27,11 @@ const DB_METHODS = new Set([
     '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_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',
@@ -253,6 +258,7 @@ function extractEffects(root, source, filePath, nodes) {
 }
 // ── 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
@@ -285,6 +291,7 @@ function extractEntrypoints(root, source, filePath, nodes) {
                 continue;
             const responseModel = extractResponseModel(decText);
             const routeContainerId = getSelfContainerId(fnDef, filePath);
+            const routeAnalysis = analyzePythonRoute(fnDef, source, method, routePath, responseModel, pydanticModels);
             nodes.push({
                 id: conceptId(filePath, 'entrypoint', child.startIndex),
                 kind: 'entrypoint',
@@ -301,6 +308,13 @@ function extractEntrypoints(root, source, filePath, nodes) {
                     responseModel,
                     isAsync: isAsyncFunction(fnDef),
                     routerName,
+                    errorStatusCodes: routeAnalysis.errorStatusCodes,
+                    hasUnboundedCollectionQuery: routeAnalysis.hasUnboundedCollectionQuery,
+                    hasDbWrite: routeAnalysis.hasDbWrite,
+                    hasIdempotencyProtection: routeAnalysis.hasIdempotencyProtection,
+                    hasBodyValidation: routeAnalysis.hasBodyValidation,
+                    validatedBodyFields: routeAnalysis.validatedBodyFields,
+                    bodyValidationResolved: routeAnalysis.bodyValidationResolved,
                 },
             });
         }
@@ -488,6 +502,89 @@ function classifyDependency(depName) {
         return 'rate-limit';
     return 'policy';
 }
+function analyzePythonRoute(fnDef, source, method, routePath, responseModel, pydanticModels) {
+    const text = source.substring(fnDef.startIndex, fnDef.endIndex);
+    const validation = extractFastApiBodyValidation(fnDef, source, pydanticModels);
+    return {
+        errorStatusCodes: extractPythonHttpExceptionStatusCodes(text),
+        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,
+    };
+}
+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 fieldRe = /^\s+([A-Za-z_]\w*)\s*:/gm;
+        for (const fieldMatch of body.matchAll(fieldRe)) {
+            const field = fieldMatch[1];
+            if (field === 'model_config' || field === 'Config')
+                continue;
+            fields.push(field);
+        }
+        if (fields.length > 0)
+            models.set(name, fields.sort());
+    }
+    return models;
+}
+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();
+    let has = false;
+    const annotationRe = /([A-Za-z_]\w*)\s*:\s*([A-Za-z_]\w*)/g;
+    for (const match of header.matchAll(annotationRe)) {
+        const modelFields = pydanticModels.get(match[2]);
+        if (!modelFields)
+            continue;
+        has = true;
+        for (const field of modelFields)
+            fields.add(field);
+    }
+    return {
+        has,
+        fields: fields.size > 0 ? Array.from(fields).sort() : undefined,
+        resolved: fields.size > 0,
+    };
+}
 // ── state_mutation ───────────────────────────────────────────────────────
 function extractStateMutation(root, source, filePath, nodes) {
     // Track global keyword usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernlang/review-python",
-  "version": "3.3.8",
+  "version": "3.4.0",
   "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.3.8",
-    "@kernlang/review": "3.3.8"
+    "@kernlang/review": "3.4.0",
+    "@kernlang/core": "3.4.0"
   },
   "devDependencies": {
     "ts-morph": "^28.0.0",

package/src/mapper.ts

@@ -35,6 +35,24 @@ const DB_METHODS = new Set([
 
 const _FS_FUNCTIONS = new Set(['open', 'read', 'write', 'readlines', 'writelines']);
 
+interface PythonRouteAnalysis {
+  errorStatusCodes?: readonly number[];
+  hasUnboundedCollectionQuery?: boolean;
+  hasDbWrite?: boolean;
+  hasIdempotencyProtection?: boolean;
+  hasBodyValidation?: boolean;
+  validatedBodyFields?: readonly string[];
+  bodyValidationResolved?: boolean;
+}
+
+const PY_API_ERROR_STATUS_CODES = new Set([401, 403, 404, 422, 500]);
+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',
@@ -295,6 +313,8 @@ function extractEffects(root: Parser.SyntaxNode, source: string, filePath: strin
 // ── entrypoint ──────────────────────────────────────────────────────────
 
 function extractEntrypoints(root: Parser.SyntaxNode, source: string, filePath: string, nodes: ConceptNode[]): void {
+  const pydanticModels = collectPydanticModels(source);
+
   // FastAPI / Flask route decorators.
   //
   // The route *path* (e.g. `/current`) is what cross-stack rules need to
@@ -327,6 +347,7 @@ function extractEntrypoints(root: Parser.SyntaxNode, source: string, filePath: s
 
       const responseModel = extractResponseModel(decText);
       const routeContainerId = getSelfContainerId(fnDef, filePath);
+      const routeAnalysis = analyzePythonRoute(fnDef, source, method, routePath, responseModel, pydanticModels);
 
       nodes.push({
         id: conceptId(filePath, 'entrypoint', child.startIndex),
@@ -344,6 +365,13 @@ function extractEntrypoints(root: Parser.SyntaxNode, source: string, filePath: s
           responseModel,
           isAsync: isAsyncFunction(fnDef),
           routerName,
+          errorStatusCodes: routeAnalysis.errorStatusCodes,
+          hasUnboundedCollectionQuery: routeAnalysis.hasUnboundedCollectionQuery,
+          hasDbWrite: routeAnalysis.hasDbWrite,
+          hasIdempotencyProtection: routeAnalysis.hasIdempotencyProtection,
+          hasBodyValidation: routeAnalysis.hasBodyValidation,
+          validatedBodyFields: routeAnalysis.validatedBodyFields,
+          bodyValidationResolved: routeAnalysis.bodyValidationResolved,
         },
       });
     }
@@ -531,6 +559,103 @@ function classifyDependency(depName: string): 'auth' | 'validation' | 'rate-limi
   return 'policy';
 }
 
+function analyzePythonRoute(
+  fnDef: Parser.SyntaxNode,
+  source: string,
+  method: string,
+  routePath: string,
+  responseModel: string | undefined,
+  pydanticModels: ReadonlyMap<string, readonly string[]>,
+): PythonRouteAnalysis {
+  const text = source.substring(fnDef.startIndex, fnDef.endIndex);
+  const validation = extractFastApiBodyValidation(fnDef, source, pydanticModels);
+  return {
+    errorStatusCodes: extractPythonHttpExceptionStatusCodes(text),
+    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,
+  };
+}
+
+function extractPythonHttpExceptionStatusCodes(text: string): readonly number[] | undefined {
+  const codes = new Set<number>();
+  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: string,
+  method: string,
+  routePath: string,
+  responseModel: string | undefined,
+): boolean {
+  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: string): Map<string, readonly string[]> {
+  const models = new Map<string, readonly string[]>();
+  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 fieldRe = /^\s+([A-Za-z_]\w*)\s*:/gm;
+    for (const fieldMatch of body.matchAll(fieldRe)) {
+      const field = fieldMatch[1];
+      if (field === 'model_config' || field === 'Config') continue;
+      fields.push(field);
+    }
+    if (fields.length > 0) models.set(name, fields.sort());
+  }
+  return models;
+}
+
+function extractFastApiBodyValidation(
+  fnDef: Parser.SyntaxNode,
+  source: string,
+  pydanticModels: ReadonlyMap<string, readonly string[]>,
+): { has: boolean; fields: readonly string[] | undefined; resolved: boolean } {
+  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>();
+  let has = false;
+  const annotationRe = /([A-Za-z_]\w*)\s*:\s*([A-Za-z_]\w*)/g;
+  for (const match of header.matchAll(annotationRe)) {
+    const modelFields = pydanticModels.get(match[2]);
+    if (!modelFields) continue;
+    has = true;
+    for (const field of modelFields) fields.add(field);
+  }
+  return {
+    has,
+    fields: fields.size > 0 ? Array.from(fields).sort() : undefined,
+    resolved: fields.size > 0,
+  };
+}
+
 // ── state_mutation ───────────────────────────────────────────────────────
 
 function extractStateMutation(root: Parser.SyntaxNode, source: string, filePath: string, nodes: ConceptNode[]): void {

package/tests/route-entrypoints.test.ts

@@ -96,4 +96,23 @@ def list_users():
     expect(route?.containerId).toBeDefined();
     expect(route?.containerId).toBe(effect?.containerId);
   });
+
+  it('extracts Pydantic request model fields from annotated route parameters', () => {
+    const routes = routePayloads(`
+from pydantic import BaseModel
+
+class UserCreate(BaseModel):
+    email: str
+    name: str
+
+@router.post("/users")
+def create_user(payload: UserCreate):
+    return payload
+`);
+
+    expect(routes).toHaveLength(1);
+    expect(routes[0].payload.hasBodyValidation).toBe(true);
+    expect(routes[0].payload.bodyValidationResolved).toBe(true);
+    expect(routes[0].payload.validatedBodyFields).toEqual(['email', 'name']);
+  });
 });