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

package/dist/mapper/extractors/fastapi-status.js

@@ -0,0 +1,115 @@
+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, 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,
+    };
+}
+export 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;
+}

package/dist/mapper/extractors/guard.d.ts

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

package/dist/mapper/extractors/guard.js

@@ -0,0 +1,115 @@
+import { conceptId } from '@kernlang/core';
+import { getContainerId, nodeSpan, nodeText, walkNodes } from '../helpers/ast.js';
+export 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';
+}

package/dist/mapper/extractors/pydantic.d.ts

@@ -0,0 +1,13 @@
+import type Parser from 'tree-sitter';
+import { type FieldTypeMap } from '../helpers/types.js';
+export interface PydanticModel {
+    fields: readonly string[];
+    types: FieldTypeMap;
+}
+export declare function collectPydanticModels(source: string): Map<string, PydanticModel>;
+export declare function extractFastApiBodyValidation(fnDef: Parser.SyntaxNode, source: string, pydanticModels: ReadonlyMap<string, PydanticModel>): {
+    has: boolean;
+    fields: readonly string[] | undefined;
+    resolved: boolean;
+    types: FieldTypeMap | undefined;
+};

package/dist/mapper/extractors/pydantic.js

@@ -0,0 +1,61 @@
+import { coarsenPythonTypeAnnotation } from '../helpers/types.js';
+export 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;
+}
+export 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,
+    };
+}

package/dist/mapper/extractors/state-mutation.d.ts

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

package/dist/mapper/extractors/state-mutation.js

@@ -0,0 +1,63 @@
+import { conceptId } from '@kernlang/core';
+import { getContainerId, nodeSpan, nodeText, walkNodes } from '../helpers/ast.js';
+export 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' },
+                });
+            }
+        }
+    });
+}

package/dist/mapper/helpers/ast.d.ts

@@ -0,0 +1,9 @@
+import type { ConceptSpan } from '@kernlang/core';
+import type Parser from 'tree-sitter';
+export declare function walkNodes(root: Parser.SyntaxNode, type: string, callback: (node: Parser.SyntaxNode) => void): void;
+export declare function nodeSpan(filePath: string, node: Parser.SyntaxNode): ConceptSpan;
+export declare function nodeText(source: string, node: Parser.SyntaxNode, maxLen: number): string;
+export declare function getContainerId(node: Parser.SyntaxNode, filePath: string): string | undefined;
+export declare function getSelfContainerId(node: Parser.SyntaxNode, filePath: string): string | undefined;
+export declare function isInAsyncDef(node: Parser.SyntaxNode): boolean;
+export declare function isAsyncFunction(node: Parser.SyntaxNode): boolean;

package/dist/mapper/helpers/ast.js

@@ -0,0 +1,62 @@
+import { conceptSpan } from '@kernlang/core';
+export 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;
+    }
+}
+export function nodeSpan(filePath, node) {
+    return conceptSpan(filePath, node.startPosition.row + 1, node.startPosition.column + 1, node.endPosition.row + 1, node.endPosition.column + 1);
+}
+export function nodeText(source, node, maxLen) {
+    return source.substring(node.startIndex, Math.min(node.endIndex, node.startIndex + maxLen));
+}
+export 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;
+}
+export 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}`;
+}
+export function isInAsyncDef(node) {
+    let parent = node.parent;
+    while (parent) {
+        if (parent.type === 'function_definition') {
+            return isAsyncFunction(parent);
+        }
+        parent = parent.parent;
+    }
+    return false;
+}
+export function isAsyncFunction(node) {
+    return node.children.some((c) => c.type === 'async');
+}

package/dist/mapper/helpers/types.d.ts

@@ -0,0 +1,7 @@
+export type FieldTypeTag = 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array' | 'unknown';
+export type FieldTypeMap = Readonly<Record<string, FieldTypeTag>>;
+export declare function coarsenPythonTypeAnnotation(ann: string): FieldTypeTag;
+export declare function coarsenLiteralValue(v: string): FieldTypeTag;
+export declare function coarsenUnionParts(parts: readonly string[]): FieldTypeTag;
+export declare function splitTopLevelTypeArgs(s: string, delim: ',' | '|'): string[];
+export declare function containsTopLevelChar(s: string, ch: string): boolean;

package/dist/mapper/helpers/types.js

@@ -0,0 +1,168 @@
+// 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.
+export 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'.
+export 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';
+}
+export 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';
+}
+// 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]]`.
+export 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;
+}
+export 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;
+}

package/dist/mapper/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Python Concept Mapper — tree-sitter based.
+ *
+ * Maps Python syntax → universal KERN concepts.
+ * Phase 1: error_raise, error_handle, effect
+ */
+import type { ConceptMap } from '@kernlang/core';
+export declare function extractPythonConcepts(source: string, filePath: string): ConceptMap;