@zuvia-software-solutions/code-mapper 1.4.0

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

@@ -0,0 +1,175 @@
+// code-mapper/src/core/ingestion/type-extractors/python.ts
+/** @file python.ts
+ *  @description Type extraction for Python (PEP 484/526 annotations and constructor inference) */
+import { extractSimpleTypeName, extractVarName } from './shared.js';
+const DECLARATION_NODE_TYPES = new Set([
+    'assignment',
+    'named_expression',
+    'expression_statement',
+]);
+// Python: x: Foo = ... (PEP 484 annotated assignment) or x: Foo (standalone annotation)
+//
+// tree-sitter-python grammar produces two distinct shapes:
+//   1. Annotated assignment with value: `name: str = ""`
+//      Node type: assignment, Fields: left=identifier, type=identifier/type, right=value
+//   2. Standalone annotation (no value): `name: str`
+//      Node type: expression_statement, Child: type { name=identifier, type=identifier/type }
+// Both appear at file scope and inside class bodies (PEP 526 class variable annotations)
+const extractDeclaration = (node, env) => {
+    if (node.type === 'expression_statement') {
+        // Standalone annotation: expression_statement > type { name: identifier, type: identifier }
+        const typeChild = node.firstNamedChild;
+        if (!typeChild || typeChild.type !== 'type')
+            return;
+        const nameNode = typeChild.childForFieldName('name');
+        const typeNode = typeChild.childForFieldName('type');
+        if (!nameNode || !typeNode)
+            return;
+        const varName = extractVarName(nameNode);
+        const inner = typeNode.type === 'type' ? (typeNode.firstNamedChild ?? typeNode) : typeNode;
+        const typeName = extractSimpleTypeName(inner) ?? inner.text;
+        if (varName && typeName)
+            env.set(varName, typeName);
+        return;
+    }
+    // Annotated assignment: left : type = value
+    const left = node.childForFieldName('left');
+    const typeNode = node.childForFieldName('type');
+    if (!left || !typeNode)
+        return;
+    const varName = extractVarName(left);
+    // extractSimpleTypeName handles identifiers and qualified names
+    // Python 3.10+ union syntax `User | None` is parsed as binary_operator,
+    // which extractSimpleTypeName doesn't handle -- fall back to raw text so
+    // stripNullable can process it at lookup time (e.g. "User | None" -> "User")
+    const inner = typeNode.type === 'type' ? (typeNode.firstNamedChild ?? typeNode) : typeNode;
+    const typeName = extractSimpleTypeName(inner) ?? inner.text;
+    if (varName && typeName)
+        env.set(varName, typeName);
+};
+// Python: parameter with type annotation
+const extractParameter = (node, env) => {
+    let nameNode = null;
+    let typeNode = null;
+    if (node.type === 'parameter') {
+        nameNode = node.childForFieldName('name');
+        typeNode = node.childForFieldName('type');
+    }
+    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);
+};
+// Python: user = User("alice") -- infer type from call when callee is a known class
+// Python constructors are syntactically identical to function calls, so we verify
+// against classNames (which may include cross-file SymbolTable lookups)
+// Also handles walrus operator: if (user := User("alice")):
+const extractInitializer = (node, env, classNames) => {
+    let left;
+    let right;
+    if (node.type === 'named_expression') {
+        // Walrus operator: (user := User("alice"))
+        // tree-sitter-python: named_expression has 'name' and 'value' fields
+        left = node.childForFieldName('name');
+        right = node.childForFieldName('value');
+    }
+    else if (node.type === 'assignment') {
+        left = node.childForFieldName('left');
+        right = node.childForFieldName('right');
+        // Skip if already has type annotation -- extractDeclaration handled it
+        if (node.childForFieldName('type'))
+            return;
+    }
+    else {
+        return;
+    }
+    if (!left || !right)
+        return;
+    const varName = extractVarName(left);
+    if (!varName || env.has(varName))
+        return;
+    if (right.type !== 'call')
+        return;
+    const func = right.childForFieldName('function');
+    if (!func)
+        return;
+    // Support both direct calls (User()) and qualified calls (models.User())
+    // tree-sitter-python: direct -> identifier, qualified -> attribute
+    const calleeName = extractSimpleTypeName(func);
+    if (!calleeName)
+        return;
+    if (classNames.has(calleeName)) {
+        env.set(varName, calleeName);
+    }
+};
+// Python: user = User("alice") -- scan assignment/walrus for constructor-like calls
+// Returns {varName, calleeName} without checking classNames (caller validates)
+const scanConstructorBinding = (node) => {
+    let left;
+    let right;
+    if (node.type === 'named_expression') {
+        left = node.childForFieldName('name');
+        right = node.childForFieldName('value');
+    }
+    else if (node.type === 'assignment') {
+        left = node.childForFieldName('left');
+        right = node.childForFieldName('right');
+        if (node.childForFieldName('type'))
+            return undefined;
+    }
+    else {
+        return undefined;
+    }
+    if (!left || !right)
+        return undefined;
+    if (left.type !== 'identifier')
+        return undefined;
+    if (right.type !== 'call')
+        return undefined;
+    const func = right.childForFieldName('function');
+    if (!func)
+        return undefined;
+    const calleeName = extractSimpleTypeName(func);
+    if (!calleeName)
+        return undefined;
+    return { varName: left.text, calleeName };
+};
+// Python: alias = u -> assignment with left/right fields
+// Also handles walrus operator: alias := u -> named_expression with name/value fields
+const extractPendingAssignment = (node, scopeEnv) => {
+    let left;
+    let right;
+    if (node.type === 'assignment') {
+        left = node.childForFieldName('left');
+        right = node.childForFieldName('right');
+    }
+    else if (node.type === 'named_expression') {
+        left = node.childForFieldName('name');
+        right = node.childForFieldName('value');
+    }
+    else {
+        return undefined;
+    }
+    if (!left || !right)
+        return undefined;
+    const lhs = left.type === 'identifier' ? left.text : undefined;
+    if (!lhs || scopeEnv.has(lhs))
+        return undefined;
+    if (right.type === 'identifier')
+        return { lhs, rhs: right.text };
+    return undefined;
+};
+export const typeConfig = {
+    declarationNodeTypes: DECLARATION_NODE_TYPES,
+    extractDeclaration,
+    extractParameter,
+    extractInitializer,
+    scanConstructorBinding,
+    extractPendingAssignment,
+};

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

@@ -0,0 +1,12 @@
+/** @file ruby.ts
+ *  @description Type extraction for Ruby via YARD annotation parsing and constructor inference
+ *
+ *  Ruby has no static type system, but YARD provides de facto type annotations via comments:
+ *    `# @param name [String]`, `# @return [User]`
+ *
+ *  Resolution tiers:
+ *  - Tier 0: YARD @param annotations (extractDeclaration pre-populates env)
+ *  - Tier 1: Constructor inference via `user = User.new` (scanConstructorBinding)
+ */
+import type { LanguageTypeConfig } from './types.js';
+export declare const typeConfig: LanguageTypeConfig;

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

@@ -0,0 +1,218 @@
+// code-mapper/src/core/ingestion/type-extractors/ruby.ts
+/** @file ruby.ts
+ *  @description Type extraction for Ruby via YARD annotation parsing and constructor inference
+ *
+ *  Ruby has no static type system, but YARD provides de facto type annotations via comments:
+ *    `# @param name [String]`, `# @return [User]`
+ *
+ *  Resolution tiers:
+ *  - Tier 0: YARD @param annotations (extractDeclaration pre-populates env)
+ *  - Tier 1: Constructor inference via `user = User.new` (scanConstructorBinding)
+ */
+import { extractRubyConstructorAssignment, extractSimpleTypeName } from './shared.js';
+// Regex to extract @param annotations: `@param name [Type]`
+const YARD_PARAM_RE = /@param\s+(\w+)\s+\[([^\]]+)\]/g;
+// Alternate YARD order: `@param [Type] name`
+const YARD_PARAM_ALT_RE = /@param\s+\[([^\]]+)\]\s+(\w+)/g;
+// Regex to extract @return annotations: `@return [Type]`
+const YARD_RETURN_RE = /@return\s+\[([^\]]+)\]/;
+/**
+ * Extract the simple type name from a YARD type string
+ *
+ * Handles simple types ("String"), qualified ("Models::User" -> "User"),
+ * generic ("Array<User>" -> "Array"), nullable ("String, nil" -> "String"),
+ * and rejects ambiguous unions ("String, Integer" -> undefined)
+ */
+const extractYardTypeName = (yardType) => {
+    const trimmed = yardType.trim();
+    // Handle nullable: "Type, nil" or "nil, Type"
+    // Use bracket-balanced split to avoid breaking on commas inside generics (e.g. Hash<Symbol, User>)
+    const parts = [];
+    let depth = 0, start = 0;
+    for (let i = 0; i < trimmed.length; i++) {
+        if (trimmed[i] === '<')
+            depth++;
+        else if (trimmed[i] === '>')
+            depth--;
+        else if (trimmed[i] === ',' && depth === 0) {
+            parts.push(trimmed.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    parts.push(trimmed.slice(start).trim());
+    const filtered = parts.filter(p => p !== '' && p !== 'nil');
+    if (filtered.length !== 1)
+        return undefined; // ambiguous union
+    const typePart = filtered[0];
+    // Handle qualified: "Models::User" -> "User"
+    const segments = typePart.split('::');
+    const last = segments[segments.length - 1];
+    // Handle generic: "Array<User>" -> "Array"
+    const genericMatch = last.match(/^(\w+)\s*[<{(]/);
+    if (genericMatch)
+        return genericMatch[1];
+    // Simple identifier check
+    if (/^\w+$/.test(last))
+        return last;
+    return undefined;
+};
+/**
+ * Collect YARD @param annotations from comment nodes preceding a method definition
+ *
+ * In tree-sitter-ruby, comments are sibling nodes before the method node
+ * Walks backwards through preceding siblings collecting consecutive comment nodes
+ * @returns Map of paramName -> typeName
+ */
+const collectYardParams = (methodNode) => {
+    const params = new Map();
+    // In tree-sitter-ruby, YARD comments preceding a method inside a class body are
+    // placed as children of the `class` node, NOT as siblings of the `method` inside
+    // `body_statement`. For top-level methods, comments ARE direct siblings
+    // We handle both: if method has no preceding comment siblings, check parent
+    // (body_statement) siblings instead
+    const commentTexts = [];
+    const collectComments = (startNode) => {
+        let sibling = startNode.previousSibling;
+        while (sibling) {
+            if (sibling.type === 'comment') {
+                commentTexts.unshift(sibling.text);
+            }
+            else if (sibling.isNamed) {
+                break;
+            }
+            sibling = sibling.previousSibling;
+        }
+    };
+    // Try method's own siblings first (top-level methods)
+    collectComments(methodNode);
+    // If no comments found and parent is body_statement, check parent's siblings
+    if (commentTexts.length === 0 && methodNode.parent?.type === 'body_statement') {
+        collectComments(methodNode.parent);
+    }
+    // Parse all comment lines for @param annotations
+    const commentBlock = commentTexts.join('\n');
+    let match;
+    // Reset regex state
+    YARD_PARAM_RE.lastIndex = 0;
+    while ((match = YARD_PARAM_RE.exec(commentBlock)) !== null) {
+        const paramName = match[1];
+        const rawType = match[2];
+        const typeName = extractYardTypeName(rawType);
+        if (typeName) {
+            params.set(paramName, typeName);
+        }
+    }
+    // Also check alternate YARD order: @param [Type] name
+    YARD_PARAM_ALT_RE.lastIndex = 0;
+    while ((match = YARD_PARAM_ALT_RE.exec(commentBlock)) !== null) {
+        const rawType = match[1];
+        const paramName = match[2];
+        if (params.has(paramName))
+            continue; // standard format takes priority
+        const typeName = extractYardTypeName(rawType);
+        if (typeName) {
+            params.set(paramName, typeName);
+        }
+    }
+    return params;
+};
+// Ruby node types that may carry type bindings:
+// - method/singleton_method: YARD @param annotations (via extractDeclaration)
+// - assignment: Constructor inference like `user = User.new` (via extractInitializer)
+const DECLARATION_NODE_TYPES = new Set([
+    'method',
+    'singleton_method',
+    'assignment',
+]);
+// Extract YARD annotations from method definitions
+// Pre-populates the scope env with parameter types before the standard parameter walk
+const extractDeclaration = (node, env) => {
+    if (node.type !== 'method' && node.type !== 'singleton_method')
+        return;
+    const yardParams = collectYardParams(node);
+    if (yardParams.size === 0)
+        return;
+    // Pre-populate env with YARD type bindings for each parameter
+    for (const [paramName, typeName] of yardParams) {
+        env.set(paramName, typeName);
+    }
+};
+// Ruby parameters have no inline type annotations -- YARD types are already populated
+// by extractDeclaration. No-op to satisfy the LanguageTypeConfig contract
+const extractParameter = (_node, _env) => {
+    // no-op: YARD types are pre-populated by extractDeclaration
+};
+// Ruby constructor inference: user = User.new or service = Models::User.new
+// Uses the shared extractRubyConstructorAssignment helper, then resolves against known class names
+const extractInitializer = (node, env, classNames) => {
+    const result = extractRubyConstructorAssignment(node);
+    if (!result)
+        return;
+    if (env.has(result.varName))
+        return;
+    if (classNames.has(result.calleeName)) {
+        env.set(result.varName, result.calleeName);
+    }
+};
+// Extract return type from YARD `@return [Type]` annotation preceding a method
+// Same comment-walking strategy as collectYardParams: try direct siblings first,
+// fall back to parent (body_statement) siblings for class methods
+const extractReturnType = (node) => {
+    const search = (startNode) => {
+        let sibling = startNode.previousSibling;
+        while (sibling) {
+            if (sibling.type === 'comment') {
+                const match = YARD_RETURN_RE.exec(sibling.text);
+                if (match)
+                    return extractYardTypeName(match[1]);
+            }
+            else if (sibling.isNamed) {
+                break;
+            }
+            sibling = sibling.previousSibling;
+        }
+        return undefined;
+    };
+    const result = search(node);
+    if (result)
+        return result;
+    if (node.parent?.type === 'body_statement') {
+        return search(node.parent);
+    }
+    return undefined;
+};
+// Ruby constructor binding scanner: captures both `user = User.new` and plain call
+// assignments like `user = get_user()`. The `.new` pattern returns the class name
+// directly; plain calls return the callee name for return-type inference
+const scanConstructorBinding = (node) => {
+    // Try the .new pattern first (returns class name directly)
+    const newResult = extractRubyConstructorAssignment(node);
+    if (newResult)
+        return newResult;
+    // Plain call assignment: user = get_user() / user = Models.create()
+    if (node.type !== 'assignment')
+        return undefined;
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    if (!left || !right)
+        return undefined;
+    if (left.type !== 'identifier' && left.type !== 'constant')
+        return undefined;
+    if (right.type !== 'call')
+        return undefined;
+    const method = right.childForFieldName('method');
+    if (!method)
+        return undefined;
+    const calleeName = extractSimpleTypeName(method);
+    if (!calleeName)
+        return undefined;
+    return { varName: left.text, calleeName };
+};
+export const typeConfig = {
+    declarationNodeTypes: DECLARATION_NODE_TYPES,
+    extractDeclaration,
+    extractParameter,
+    extractInitializer,
+    scanConstructorBinding,
+    extractReturnType,
+};

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

@@ -0,0 +1,4 @@
+/** @file rust.ts
+ *  @description Type extraction for Rust (let bindings, pattern matching, struct literals) */
+import type { LanguageTypeConfig } from './types.js';
+export declare const typeConfig: LanguageTypeConfig;