@zuvia-software-solutions/code-mapper 1.4.0

package/dist/core/ingestion/type-extractors/jvm.js

@@ -0,0 +1,386 @@
+// code-mapper/src/core/ingestion/type-extractors/jvm.ts
+/** @file jvm.ts
+ *  @description Type extraction for Java and Kotlin */
+import { extractSimpleTypeName, extractVarName, findChildByType } from './shared.js';
+const JAVA_DECLARATION_NODE_TYPES = new Set([
+    'local_variable_declaration',
+    'field_declaration',
+]);
+// Java: Type x = ...; Type x;
+const extractJavaDeclaration = (node, env) => {
+    const typeNode = node.childForFieldName('type');
+    if (!typeNode)
+        return;
+    const typeName = extractSimpleTypeName(typeNode);
+    if (!typeName || typeName === 'var')
+        return; // skip Java 10 var -- handled by extractInitializer
+    // Find variable_declarator children
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child?.type !== 'variable_declarator')
+            continue;
+        const nameNode = child.childForFieldName('name');
+        if (nameNode) {
+            const varName = extractVarName(nameNode);
+            if (varName)
+                env.set(varName, typeName);
+        }
+    }
+};
+// Java 10+: var x = new User() -- infer type from object_creation_expression
+const extractJavaInitializer = (node, env, _classNames) => {
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child?.type !== 'variable_declarator')
+            continue;
+        const nameNode = child.childForFieldName('name');
+        const valueNode = child.childForFieldName('value');
+        if (!nameNode || !valueNode)
+            continue;
+        // Skip declarators that already have a binding from extractDeclaration
+        const varName = extractVarName(nameNode);
+        if (!varName || env.has(varName))
+            continue;
+        if (valueNode.type !== 'object_creation_expression')
+            continue;
+        const ctorType = valueNode.childForFieldName('type');
+        if (!ctorType)
+            continue;
+        const typeName = extractSimpleTypeName(ctorType);
+        if (typeName)
+            env.set(varName, typeName);
+    }
+};
+// Java: formal_parameter -> type name
+const extractJavaParameter = (node, env) => {
+    let nameNode = null;
+    let typeNode = null;
+    if (node.type === 'formal_parameter') {
+        typeNode = node.childForFieldName('type');
+        nameNode = node.childForFieldName('name');
+    }
+    else {
+        // Generic fallback
+        nameNode = node.childForFieldName('name') ?? node.childForFieldName('pattern');
+        typeNode = node.childForFieldName('type');
+    }
+    if (!nameNode || !typeNode)
+        return;
+    const varName = extractVarName(nameNode);
+    const typeName = extractSimpleTypeName(typeNode);
+    if (varName && typeName)
+        env.set(varName, typeName);
+};
+// Java: var x = SomeFactory.create() -- constructor binding for `var` with method_invocation
+const scanJavaConstructorBinding = (node) => {
+    if (node.type !== 'local_variable_declaration')
+        return undefined;
+    const typeNode = node.childForFieldName('type');
+    if (!typeNode)
+        return undefined;
+    if (typeNode.text !== 'var')
+        return undefined;
+    const declarator = findChildByType(node, 'variable_declarator');
+    if (!declarator)
+        return undefined;
+    const nameNode = declarator.childForFieldName('name');
+    const value = declarator.childForFieldName('value');
+    if (!nameNode || !value)
+        return undefined;
+    if (value.type === 'object_creation_expression')
+        return undefined;
+    if (value.type !== 'method_invocation')
+        return undefined;
+    const methodName = value.childForFieldName('name');
+    if (!methodName)
+        return undefined;
+    return { varName: nameNode.text, calleeName: methodName.text };
+};
+const JAVA_FOR_LOOP_NODE_TYPES = new Set([
+    'enhanced_for_statement',
+]);
+// Java: for (User user : users) -- extract loop variable binding
+const extractJavaForLoopBinding = (node, scopeEnv) => {
+    const typeNode = node.childForFieldName('type');
+    const nameNode = node.childForFieldName('name');
+    if (!typeNode || !nameNode)
+        return;
+    const typeName = extractSimpleTypeName(typeNode);
+    const varName = extractVarName(nameNode);
+    if (typeName && varName)
+        scopeEnv.set(varName, typeName);
+};
+// Java: var alias = u -> local_variable_declaration > variable_declarator with name/value
+const extractJavaPendingAssignment = (node, scopeEnv) => {
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (!child || child.type !== 'variable_declarator')
+            continue;
+        const nameNode = child.childForFieldName('name');
+        const valueNode = child.childForFieldName('value');
+        if (!nameNode || !valueNode)
+            continue;
+        const lhs = nameNode.text;
+        if (scopeEnv.has(lhs))
+            continue;
+        if (valueNode.type === 'identifier' || valueNode.type === 'simple_identifier')
+            return { lhs, rhs: valueNode.text };
+    }
+    return undefined;
+};
+// Java 16+ `instanceof` pattern variable: `x instanceof User user`
+// AST: instanceof_expression { left, instanceof, right: type, name: identifier (Java 16+) }
+// Conservative: returns undefined when name field is absent (plain instanceof) or
+// type cannot be extracted. Source variable's type is NOT used -- the pattern
+// explicitly declares the new type, so no scopeEnv lookup is needed
+const extractJavaPatternBinding = (node) => {
+    if (node.type !== 'instanceof_expression')
+        return undefined;
+    const nameNode = node.childForFieldName('name');
+    if (!nameNode)
+        return undefined;
+    const typeNode = node.childForFieldName('right');
+    if (!typeNode)
+        return undefined;
+    const typeName = extractSimpleTypeName(typeNode);
+    const varName = extractVarName(nameNode);
+    if (!typeName || !varName)
+        return undefined;
+    return { varName, typeName };
+};
+export const javaTypeConfig = {
+    declarationNodeTypes: JAVA_DECLARATION_NODE_TYPES,
+    extractDeclaration: extractJavaDeclaration,
+    extractParameter: extractJavaParameter,
+    extractInitializer: extractJavaInitializer,
+    scanConstructorBinding: scanJavaConstructorBinding,
+    forLoopNodeTypes: JAVA_FOR_LOOP_NODE_TYPES,
+    extractForLoopBinding: extractJavaForLoopBinding,
+    extractPendingAssignment: extractJavaPendingAssignment,
+    extractPatternBinding: extractJavaPatternBinding,
+};
+// Kotlin
+const KOTLIN_DECLARATION_NODE_TYPES = new Set([
+    'property_declaration',
+    'variable_declaration',
+]);
+// Kotlin: val x: Foo = ...
+const extractKotlinDeclaration = (node, env) => {
+    if (node.type === 'property_declaration') {
+        // Kotlin property_declaration: name/type are inside a variable_declaration child
+        const varDecl = findChildByType(node, 'variable_declaration');
+        if (varDecl) {
+            const nameNode = findChildByType(varDecl, 'simple_identifier');
+            const typeNode = findChildByType(varDecl, 'user_type');
+            if (!nameNode || !typeNode)
+                return;
+            const varName = extractVarName(nameNode);
+            const typeName = extractSimpleTypeName(typeNode);
+            if (varName && typeName)
+                env.set(varName, typeName);
+            return;
+        }
+        // Fallback: try direct fields
+        const nameNode = node.childForFieldName('name')
+            ?? findChildByType(node, 'simple_identifier');
+        const typeNode = node.childForFieldName('type')
+            ?? findChildByType(node, 'user_type');
+        if (!nameNode || !typeNode)
+            return;
+        const varName = extractVarName(nameNode);
+        const typeName = extractSimpleTypeName(typeNode);
+        if (varName && typeName)
+            env.set(varName, typeName);
+    }
+    else if (node.type === 'variable_declaration') {
+        // variable_declaration directly inside functions
+        const nameNode = findChildByType(node, 'simple_identifier');
+        const typeNode = findChildByType(node, 'user_type');
+        if (nameNode && typeNode) {
+            const varName = extractVarName(nameNode);
+            const typeName = extractSimpleTypeName(typeNode);
+            if (varName && typeName)
+                env.set(varName, typeName);
+        }
+    }
+};
+// Kotlin: formal_parameter -> type name
+const extractKotlinParameter = (node, env) => {
+    let nameNode = null;
+    let typeNode = null;
+    if (node.type === 'formal_parameter') {
+        typeNode = node.childForFieldName('type');
+        nameNode = node.childForFieldName('name');
+    }
+    else {
+        nameNode = node.childForFieldName('name') ?? node.childForFieldName('pattern');
+        typeNode = node.childForFieldName('type');
+    }
+    if (!nameNode || !typeNode)
+        return;
+    const varName = extractVarName(nameNode);
+    const typeName = extractSimpleTypeName(typeNode);
+    if (varName && typeName)
+        env.set(varName, typeName);
+};
+// Kotlin: val user = User() -- infer type from call_expression when callee is a known class
+// Kotlin constructors are syntactically identical to function calls, so we verify
+// against classNames (which may include cross-file SymbolTable lookups)
+const extractKotlinInitializer = (node, env, classNames) => {
+    if (node.type !== 'property_declaration')
+        return;
+    // Skip if there's an explicit type annotation -- Tier 0 already handled it
+    const varDecl = findChildByType(node, 'variable_declaration');
+    if (varDecl && findChildByType(varDecl, 'user_type'))
+        return;
+    // Get the initializer value -- the call_expression after '='
+    const value = node.childForFieldName('value')
+        ?? findChildByType(node, 'call_expression');
+    if (!value || value.type !== 'call_expression')
+        return;
+    // The callee is the first child of call_expression (simple_identifier for direct calls)
+    const callee = value.firstNamedChild;
+    if (!callee || callee.type !== 'simple_identifier')
+        return;
+    const calleeName = callee.text;
+    if (!calleeName || !classNames.has(calleeName))
+        return;
+    // Extract the variable name from the variable_declaration inside property_declaration
+    const nameNode = varDecl
+        ? findChildByType(varDecl, 'simple_identifier')
+        : findChildByType(node, 'simple_identifier');
+    if (!nameNode)
+        return;
+    const varName = extractVarName(nameNode);
+    if (varName)
+        env.set(varName, calleeName);
+};
+// Kotlin: val x = User(...) -- constructor binding for property_declaration with call_expression
+const scanKotlinConstructorBinding = (node) => {
+    if (node.type !== 'property_declaration')
+        return undefined;
+    const varDecl = findChildByType(node, 'variable_declaration');
+    if (!varDecl)
+        return undefined;
+    if (findChildByType(varDecl, 'user_type'))
+        return undefined;
+    const callExpr = findChildByType(node, 'call_expression');
+    if (!callExpr)
+        return undefined;
+    const callee = callExpr.firstNamedChild;
+    if (!callee)
+        return undefined;
+    let calleeName;
+    if (callee.type === 'simple_identifier') {
+        calleeName = callee.text;
+    }
+    else if (callee.type === 'navigation_expression') {
+        // Extract method name from qualified call: service.getUser() -> getUser
+        const suffix = callee.lastNamedChild;
+        if (suffix?.type === 'navigation_suffix') {
+            const methodName = suffix.lastNamedChild;
+            if (methodName?.type === 'simple_identifier') {
+                calleeName = methodName.text;
+            }
+        }
+    }
+    if (!calleeName)
+        return undefined;
+    const nameNode = findChildByType(varDecl, 'simple_identifier');
+    if (!nameNode)
+        return undefined;
+    return { varName: nameNode.text, calleeName };
+};
+const KOTLIN_FOR_LOOP_NODE_TYPES = new Set([
+    'for_statement',
+]);
+// Kotlin: for (user: User in users) -- extract loop variable binding with explicit type annotation
+const extractKotlinForLoopBinding = (node, scopeEnv) => {
+    // Kotlin loop variable: variable_declaration child with optional user_type annotation
+    const varDecl = findChildByType(node, 'variable_declaration');
+    if (!varDecl)
+        return;
+    // Only extract when there is an explicit type annotation (user_type node)
+    const typeNode = findChildByType(varDecl, 'user_type');
+    if (!typeNode)
+        return;
+    const nameNode = findChildByType(varDecl, 'simple_identifier');
+    if (!nameNode)
+        return;
+    const typeName = extractSimpleTypeName(typeNode);
+    const varName = extractVarName(nameNode);
+    if (typeName && varName)
+        scopeEnv.set(varName, typeName);
+};
+// Kotlin: val alias = u -> property_declaration or variable_declaration
+// property_declaration has: binding_pattern_kind("val"), variable_declaration("alias"),
+// "=", and the RHS value (simple_identifier "u")
+// variable_declaration appears directly inside functions and has simple_identifier children
+const extractKotlinPendingAssignment = (node, scopeEnv) => {
+    if (node.type === 'property_declaration') {
+        // Find the variable name from variable_declaration child
+        const varDecl = findChildByType(node, 'variable_declaration');
+        if (!varDecl)
+            return undefined;
+        const nameNode = varDecl.firstNamedChild;
+        if (!nameNode || nameNode.type !== 'simple_identifier')
+            return undefined;
+        const lhs = nameNode.text;
+        if (scopeEnv.has(lhs))
+            return undefined;
+        // Find the RHS: a simple_identifier sibling after the "=" token
+        let foundEq = false;
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (!child)
+                continue;
+            if (child.type === '=') {
+                foundEq = true;
+                continue;
+            }
+            if (foundEq && child.type === 'simple_identifier') {
+                return { lhs, rhs: child.text };
+            }
+        }
+        return undefined;
+    }
+    if (node.type === 'variable_declaration') {
+        // variable_declaration directly inside functions: simple_identifier children
+        const nameNode = findChildByType(node, 'simple_identifier');
+        if (!nameNode)
+            return undefined;
+        const lhs = nameNode.text;
+        if (scopeEnv.has(lhs))
+            return undefined;
+        // Look for RHS simple_identifier after "=" in the parent (property_declaration)
+        // variable_declaration itself doesn't contain "=" -- it's in the parent
+        const parent = node.parent;
+        if (!parent)
+            return undefined;
+        let foundEq = false;
+        for (let i = 0; i < parent.childCount; i++) {
+            const child = parent.child(i);
+            if (!child)
+                continue;
+            if (child.type === '=') {
+                foundEq = true;
+                continue;
+            }
+            if (foundEq && child.type === 'simple_identifier') {
+                return { lhs, rhs: child.text };
+            }
+        }
+        return undefined;
+    }
+    return undefined;
+};
+export const kotlinTypeConfig = {
+    declarationNodeTypes: KOTLIN_DECLARATION_NODE_TYPES,
+    forLoopNodeTypes: KOTLIN_FOR_LOOP_NODE_TYPES,
+    extractDeclaration: extractKotlinDeclaration,
+    extractParameter: extractKotlinParameter,
+    extractInitializer: extractKotlinInitializer,
+    scanConstructorBinding: scanKotlinConstructorBinding,
+    extractForLoopBinding: extractKotlinForLoopBinding,
+    extractPendingAssignment: extractKotlinPendingAssignment,
+};

package/dist/core/ingestion/type-extractors/php.d.ts

@@ -0,0 +1,4 @@
+/** @file php.ts
+ *  @description Type extraction for PHP (typed properties, PHPDoc annotations, constructor inference) */
+import type { LanguageTypeConfig } from './types.js';
+export declare const typeConfig: LanguageTypeConfig;

package/dist/core/ingestion/type-extractors/php.js

@@ -0,0 +1,280 @@
+// code-mapper/src/core/ingestion/type-extractors/php.ts
+/** @file php.ts
+ *  @description Type extraction for PHP (typed properties, PHPDoc annotations, constructor inference) */
+import { extractSimpleTypeName, extractVarName, extractCalleeName } from './shared.js';
+const DECLARATION_NODE_TYPES = new Set([
+    'assignment_expression', // For constructor inference: $x = new User()
+    'property_declaration', // PHP 7.4+ typed properties: private UserRepo $repo;
+    'method_declaration', // PHPDoc @param on class methods
+    'function_definition', // PHPDoc @param on top-level functions
+]);
+// Walk up the AST to find the enclosing class declaration
+const findEnclosingClass = (node) => {
+    let current = node.parent;
+    while (current) {
+        if (current.type === 'class_declaration')
+            return current;
+        current = current.parent;
+    }
+    return null;
+};
+// Resolve PHP self/static/parent to the actual class name
+// self/static -> enclosing class name, parent -> superclass from base_clause
+const resolvePhpKeyword = (keyword, node) => {
+    if (keyword === 'self' || keyword === 'static') {
+        const cls = findEnclosingClass(node);
+        if (!cls)
+            return undefined;
+        const nameNode = cls.childForFieldName('name');
+        return nameNode?.text;
+    }
+    if (keyword === 'parent') {
+        const cls = findEnclosingClass(node);
+        if (!cls)
+            return undefined;
+        // base_clause contains the parent class name
+        for (let i = 0; i < cls.namedChildCount; i++) {
+            const child = cls.namedChild(i);
+            if (child?.type === 'base_clause') {
+                const parentName = child.firstNamedChild;
+                if (parentName)
+                    return extractSimpleTypeName(parentName);
+            }
+        }
+        return undefined;
+    }
+    return undefined;
+};
+// Normalize a PHP type string to a simple class name identifier
+const normalizePhpType = (raw) => {
+    // Strip nullable prefix: ?User -> User
+    let type = raw.startsWith('?') ? raw.slice(1) : raw;
+    // Strip array suffix: User[] -> User
+    type = type.replace(/\[\]$/, '');
+    // Strip union with null/false/void: User|null -> User
+    const parts = type.split('|').filter(p => p !== 'null' && p !== 'false' && p !== 'void' && p !== 'mixed');
+    if (parts.length !== 1)
+        return undefined;
+    type = parts[0];
+    // Strip namespace: \App\Models\User -> User
+    const segments = type.split('\\');
+    type = segments[segments.length - 1];
+    // Skip uninformative types
+    if (type === 'mixed' || type === 'void' || type === 'self' || type === 'static' || type === 'object')
+        return undefined;
+    if (/^\w+$/.test(type))
+        return type;
+    return undefined;
+};
+// Node types to skip when walking backwards to find doc-comments
+// PHP 8+ attributes (#[Route(...)]) appear as named siblings between PHPDoc and method
+const SKIP_NODE_TYPES = new Set(['attribute_list', 'attribute']);
+// Regex to extract PHPDoc @param annotations: `@param Type $name` (standard order)
+const PHPDOC_PARAM_RE = /@param\s+(\S+)\s+\$(\w+)/g;
+// Alternate PHPDoc order: `@param $name Type` (name first)
+const PHPDOC_PARAM_ALT_RE = /@param\s+\$(\w+)\s+(\S+)/g;
+/**
+ * Collect PHPDoc @param type bindings from comment nodes preceding a method/function
+ * @returns Map of paramName -> typeName (without $ prefix)
+ */
+const collectPhpDocParams = (methodNode) => {
+    const commentTexts = [];
+    let sibling = methodNode.previousSibling;
+    while (sibling) {
+        if (sibling.type === 'comment') {
+            commentTexts.unshift(sibling.text);
+        }
+        else if (sibling.isNamed && !SKIP_NODE_TYPES.has(sibling.type)) {
+            break;
+        }
+        sibling = sibling.previousSibling;
+    }
+    if (commentTexts.length === 0)
+        return new Map();
+    const params = new Map();
+    const commentBlock = commentTexts.join('\n');
+    PHPDOC_PARAM_RE.lastIndex = 0;
+    let match;
+    while ((match = PHPDOC_PARAM_RE.exec(commentBlock)) !== null) {
+        const typeName = normalizePhpType(match[1]);
+        const paramName = match[2]; // without $ prefix
+        if (typeName) {
+            // Store with $ prefix to match how PHP variables appear in the env
+            params.set('$' + paramName, typeName);
+        }
+    }
+    // Also check alternate PHPDoc order: @param $name Type
+    PHPDOC_PARAM_ALT_RE.lastIndex = 0;
+    while ((match = PHPDOC_PARAM_ALT_RE.exec(commentBlock)) !== null) {
+        const paramName = match[1];
+        if (params.has('$' + paramName))
+            continue; // standard format takes priority
+        const typeName = normalizePhpType(match[2]);
+        if (typeName) {
+            params.set('$' + paramName, typeName);
+        }
+    }
+    return params;
+};
+// PHP: typed class properties (PHP 7.4+): private UserRepo $repo;
+// Also: PHPDoc @param annotations on method/function definitions
+const extractDeclaration = (node, env) => {
+    // PHPDoc @param on methods/functions -- pre-populate env with param types
+    if (node.type === 'method_declaration' || node.type === 'function_definition') {
+        const phpDocParams = collectPhpDocParams(node);
+        for (const [paramName, typeName] of phpDocParams) {
+            if (!env.has(paramName))
+                env.set(paramName, typeName);
+        }
+        return;
+    }
+    if (node.type !== 'property_declaration')
+        return;
+    const typeNode = node.childForFieldName('type');
+    if (!typeNode)
+        return;
+    const typeName = extractSimpleTypeName(typeNode);
+    if (!typeName)
+        return;
+    // The variable name is inside property_element > variable_name
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child?.type === 'property_element') {
+            const varNameNode = child.firstNamedChild; // variable_name
+            if (varNameNode) {
+                const varName = extractVarName(varNameNode);
+                if (varName)
+                    env.set(varName, typeName);
+            }
+            break;
+        }
+    }
+};
+// PHP: $x = new User() -- infer type from object_creation_expression
+const extractInitializer = (node, env, _classNames) => {
+    if (node.type !== 'assignment_expression')
+        return;
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    if (!left || !right)
+        return;
+    if (right.type !== 'object_creation_expression')
+        return;
+    // The class name is the first named child of object_creation_expression
+    // (tree-sitter-php uses 'name' or 'qualified_name' nodes here)
+    const ctorType = right.firstNamedChild;
+    if (!ctorType)
+        return;
+    const typeName = extractSimpleTypeName(ctorType);
+    if (!typeName)
+        return;
+    // Resolve PHP self/static/parent to actual class names
+    const resolvedType = (typeName === 'self' || typeName === 'static' || typeName === 'parent')
+        ? resolvePhpKeyword(typeName, node)
+        : typeName;
+    if (!resolvedType)
+        return;
+    const varName = extractVarName(left);
+    if (varName)
+        env.set(varName, resolvedType);
+};
+// PHP: simple_parameter -> type $name
+const extractParameter = (node, env) => {
+    let nameNode = null;
+    let typeNode = null;
+    if (node.type === 'simple_parameter') {
+        typeNode = node.childForFieldName('type');
+        nameNode = node.childForFieldName('name');
+    }
+    else {
+        nameNode = node.childForFieldName('name') ?? node.childForFieldName('pattern');
+        typeNode = node.childForFieldName('type');
+    }
+    if (!nameNode || !typeNode)
+        return;
+    const varName = extractVarName(nameNode);
+    const typeName = extractSimpleTypeName(typeNode);
+    if (varName && typeName)
+        env.set(varName, typeName);
+};
+// PHP: $x = SomeFactory() or $x = $this->getUser() -- bind variable to call return type
+const scanConstructorBinding = (node) => {
+    if (node.type !== 'assignment_expression')
+        return undefined;
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    if (!left || !right)
+        return undefined;
+    if (left.type !== 'variable_name')
+        return undefined;
+    // Skip object_creation_expression (new User()) -- handled by extractInitializer
+    if (right.type === 'object_creation_expression')
+        return undefined;
+    // Handle both standalone function calls and method calls ($this->getUser())
+    if (right.type === 'function_call_expression') {
+        const calleeName = extractCalleeName(right);
+        if (!calleeName)
+            return undefined;
+        return { varName: left.text, calleeName };
+    }
+    if (right.type === 'member_call_expression') {
+        const methodName = right.childForFieldName('name');
+        if (!methodName)
+            return undefined;
+        // When receiver is $this/self/static, qualify with enclosing class for disambiguation
+        const receiver = right.childForFieldName('object');
+        const receiverText = receiver?.text;
+        let receiverClassName;
+        if (receiverText === '$this' || receiverText === 'self' || receiverText === 'static') {
+            const cls = findEnclosingClass(node);
+            const clsName = cls?.childForFieldName('name');
+            if (clsName)
+                receiverClassName = clsName.text;
+        }
+        return { varName: left.text, calleeName: methodName.text, receiverClassName };
+    }
+    return undefined;
+};
+// Regex to extract PHPDoc @return annotations: `@return User`
+const PHPDOC_RETURN_RE = /@return\s+(\S+)/;
+// Extract return type from PHPDoc `@return Type` annotation preceding a method
+const extractReturnType = (node) => {
+    let sibling = node.previousSibling;
+    while (sibling) {
+        if (sibling.type === 'comment') {
+            const match = PHPDOC_RETURN_RE.exec(sibling.text);
+            if (match)
+                return normalizePhpType(match[1]);
+        }
+        else if (sibling.isNamed && !SKIP_NODE_TYPES.has(sibling.type))
+            break;
+        sibling = sibling.previousSibling;
+    }
+    return undefined;
+};
+// PHP: $alias = $user -> assignment_expression with variable_name left/right
+// PHP TypeEnv stores variables WITH $ prefix ($user -> User), so we keep $ in lhs/rhs
+const extractPendingAssignment = (node, scopeEnv) => {
+    if (node.type !== 'assignment_expression')
+        return undefined;
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    if (!left || !right)
+        return undefined;
+    if (left.type !== 'variable_name' || right.type !== 'variable_name')
+        return undefined;
+    const lhs = left.text;
+    const rhs = right.text;
+    if (!lhs || !rhs || scopeEnv.has(lhs))
+        return undefined;
+    return { lhs, rhs };
+};
+export const typeConfig = {
+    declarationNodeTypes: DECLARATION_NODE_TYPES,
+    extractDeclaration,
+    extractParameter,
+    extractInitializer,
+    scanConstructorBinding,
+    extractReturnType,
+    extractPendingAssignment,
+};

package/dist/core/ingestion/type-extractors/python.d.ts

@@ -0,0 +1,4 @@
+/** @file python.ts
+ *  @description Type extraction for Python (PEP 484/526 annotations and constructor inference) */
+import type { LanguageTypeConfig } from './types.js';
+export declare const typeConfig: LanguageTypeConfig;