@zuvia-software-solutions/code-mapper 1.4.0

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

@@ -0,0 +1,227 @@
+// code-mapper/src/core/ingestion/type-extractors/typescript.ts
+/** @file typescript.ts
+ *  @description Type extraction for TypeScript and JavaScript (including JSDoc annotations) */
+import { extractSimpleTypeName, extractVarName, hasTypeAnnotation, unwrapAwait, extractCalleeName } from './shared.js';
+const DECLARATION_NODE_TYPES = new Set([
+    'lexical_declaration',
+    'variable_declaration',
+    'function_declaration', // JSDoc @param on function declarations
+    'method_definition', // JSDoc @param on class methods
+]);
+// Normalize a JSDoc type to a simple identifier, stripping prefixes/unions/generics
+const normalizeJsDocType = (raw) => {
+    let type = raw.trim();
+    // Strip JSDoc nullable/non-nullable prefixes: ?User -> User, !User -> User
+    if (type.startsWith('?') || type.startsWith('!'))
+        type = type.slice(1);
+    // Strip union with null/undefined/void: User|null -> User
+    const parts = type.split('|').map(p => p.trim()).filter(p => p !== 'null' && p !== 'undefined' && p !== 'void');
+    if (parts.length !== 1)
+        return undefined; // ambiguous union
+    type = parts[0];
+    // Strip module: prefix -- module:models.User -> models.User
+    if (type.startsWith('module:'))
+        type = type.slice(7);
+    // Take last segment of dotted path: models.User -> User
+    const segments = type.split('.');
+    type = segments[segments.length - 1];
+    // Strip generic wrapper: Promise<User> -> Promise (base type, not inner)
+    const genericMatch = type.match(/^(\w+)\s*</);
+    if (genericMatch)
+        type = genericMatch[1];
+    // Simple identifier check
+    if (/^\w+$/.test(type))
+        return type;
+    return undefined;
+};
+// Regex to extract JSDoc @param annotations: `@param {Type} name`
+const JSDOC_PARAM_RE = /@param\s*\{([^}]+)\}\s+\[?(\w+)[\]=]?[^\s]*/g;
+/**
+ * Collect JSDoc @param type bindings from comment nodes preceding a function/method
+ * @returns Map of paramName -> typeName
+ */
+const collectJsDocParams = (funcNode) => {
+    const commentTexts = [];
+    let sibling = funcNode.previousSibling;
+    while (sibling) {
+        if (sibling.type === 'comment') {
+            commentTexts.unshift(sibling.text);
+        }
+        else if (sibling.isNamed && sibling.type !== 'decorator') {
+            break;
+        }
+        sibling = sibling.previousSibling;
+    }
+    if (commentTexts.length === 0)
+        return new Map();
+    const params = new Map();
+    const commentBlock = commentTexts.join('\n');
+    JSDOC_PARAM_RE.lastIndex = 0;
+    let match;
+    while ((match = JSDOC_PARAM_RE.exec(commentBlock)) !== null) {
+        const typeName = normalizeJsDocType(match[1]);
+        const paramName = match[2];
+        if (typeName) {
+            params.set(paramName, typeName);
+        }
+    }
+    return params;
+};
+// TS: const x: Foo = ..., let x: Foo
+// Also: JSDoc @param annotations on function/method definitions (for .js files)
+const extractDeclaration = (node, env) => {
+    // JSDoc @param on functions/methods -- pre-populate env with param types
+    if (node.type === 'function_declaration' || node.type === 'method_definition') {
+        const jsDocParams = collectJsDocParams(node);
+        for (const [paramName, typeName] of jsDocParams) {
+            if (!env.has(paramName))
+                env.set(paramName, typeName);
+        }
+        return;
+    }
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const declarator = node.namedChild(i);
+        if (declarator?.type !== 'variable_declarator')
+            continue;
+        const nameNode = declarator.childForFieldName('name');
+        const typeAnnotation = declarator.childForFieldName('type');
+        if (!nameNode || !typeAnnotation)
+            continue;
+        const varName = extractVarName(nameNode);
+        const typeName = extractSimpleTypeName(typeAnnotation);
+        if (varName && typeName)
+            env.set(varName, typeName);
+    }
+};
+// TS: required_parameter / optional_parameter -> name: type
+const extractParameter = (node, env) => {
+    let nameNode = null;
+    let typeNode = null;
+    if (node.type === 'required_parameter' || node.type === 'optional_parameter') {
+        nameNode = node.childForFieldName('pattern') ?? node.childForFieldName('name');
+        typeNode = node.childForFieldName('type');
+    }
+    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);
+};
+// TS: const x = new User() -- infer type from new_expression
+const extractInitializer = (node, env, _classNames) => {
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const declarator = node.namedChild(i);
+        if (declarator?.type !== 'variable_declarator')
+            continue;
+        // Only activate when there is no explicit type annotation -- extractDeclaration already
+        // handles the annotated case and this function is called as a fallback
+        if (declarator.childForFieldName('type') !== null)
+            continue;
+        let valueNode = declarator.childForFieldName('value');
+        // Unwrap `new User() as T`, `new User()!`, and double-cast `new User() as unknown as T`
+        while (valueNode?.type === 'as_expression' || valueNode?.type === 'non_null_expression') {
+            valueNode = valueNode.firstNamedChild;
+        }
+        if (valueNode?.type !== 'new_expression')
+            continue;
+        const constructorNode = valueNode.childForFieldName('constructor');
+        if (!constructorNode)
+            continue;
+        const nameNode = declarator.childForFieldName('name');
+        if (!nameNode)
+            continue;
+        const varName = extractVarName(nameNode);
+        const typeName = extractSimpleTypeName(constructorNode);
+        if (varName && typeName)
+            env.set(varName, typeName);
+    }
+};
+// TS/JS: const user = getUser() -- variable_declarator with call_expression value
+// Only matches unannotated declarators; annotated ones are handled by extractDeclaration
+// await is unwrapped: const user = await fetchUser() -> callee = 'fetchUser'
+const scanConstructorBinding = (node) => {
+    if (node.type !== 'variable_declarator')
+        return undefined;
+    if (hasTypeAnnotation(node))
+        return undefined;
+    const nameNode = node.childForFieldName('name');
+    if (!nameNode || nameNode.type !== 'identifier')
+        return undefined;
+    const value = unwrapAwait(node.childForFieldName('value'));
+    if (!value || value.type !== 'call_expression')
+        return undefined;
+    const calleeName = extractCalleeName(value);
+    if (!calleeName)
+        return undefined;
+    return { varName: nameNode.text, calleeName };
+};
+// Regex to extract @returns or @return from JSDoc comments: `@returns {Type}`
+const JSDOC_RETURN_RE = /@returns?\s*\{([^}]+)\}/;
+// Minimal sanitization for JSDoc return types -- preserves generic wrappers
+// (e.g. `Promise<User>`) so extractReturnTypeName in call-processor can apply
+// WRAPPER_GENERICS unwrapping. Unlike normalizeJsDocType (which strips generics),
+// this only strips JSDoc-specific syntax markers
+const sanitizeReturnType = (raw) => {
+    let type = raw.trim();
+    // Strip JSDoc nullable/non-nullable prefixes: ?User -> User, !User -> User
+    if (type.startsWith('?') || type.startsWith('!'))
+        type = type.slice(1);
+    // Strip module: prefix -- module:models.User -> models.User
+    if (type.startsWith('module:'))
+        type = type.slice(7);
+    // Reject unions (ambiguous)
+    if (type.includes('|'))
+        return undefined;
+    if (!type)
+        return undefined;
+    return type;
+};
+// Extract return type from JSDoc `@returns {Type}` or `@return {Type}` annotation
+// preceding a function/method definition
+const extractReturnType = (node) => {
+    let sibling = node.previousSibling;
+    while (sibling) {
+        if (sibling.type === 'comment') {
+            const match = JSDOC_RETURN_RE.exec(sibling.text);
+            if (match)
+                return sanitizeReturnType(match[1]);
+        }
+        else if (sibling.isNamed && sibling.type !== 'decorator')
+            break;
+        sibling = sibling.previousSibling;
+    }
+    return undefined;
+};
+// TS/JS: const alias = u -> variable_declarator with name/value fields
+const extractPendingAssignment = (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')
+            return { lhs, rhs: valueNode.text };
+    }
+    return undefined;
+};
+export const typeConfig = {
+    declarationNodeTypes: DECLARATION_NODE_TYPES,
+    extractDeclaration,
+    extractParameter,
+    extractInitializer,
+    scanConstructorBinding,
+    extractReturnType,
+    extractPendingAssignment,
+};

package/dist/core/ingestion/utils.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file Shared AST utilities for code ingestion
+ * @description Tree-sitter node helpers, built-in name filtering, function/class extraction,
+ *   call-form discrimination, and receiver resolution used across all ingestion modules
+ */
+import type Parser from 'tree-sitter';
+import { SupportedLanguages } from '../../config/supported-languages.js';
+export type SyntaxNode = Parser.SyntaxNode;
+/** Ordered definition capture keys for tree-sitter query matches */
+export declare const DEFINITION_CAPTURE_KEYS: readonly ["definition.function", "definition.class", "definition.interface", "definition.method", "definition.struct", "definition.enum", "definition.namespace", "definition.module", "definition.trait", "definition.impl", "definition.type", "definition.const", "definition.static", "definition.typedef", "definition.macro", "definition.union", "definition.property", "definition.record", "definition.delegate", "definition.annotation", "definition.constructor", "definition.template"];
+/** Extract the definition node from a tree-sitter query capture map */
+export declare const getDefinitionNodeFromCaptures: (captureMap: Record<string, any>) => any | null;
+/** Node types representing function/method definitions across languages */
+export declare const FUNCTION_NODE_TYPES: Set<string>;
+/** Node types for standard function declarations that need C/C++ declarator handling */
+export declare const FUNCTION_DECLARATION_TYPES: Set<string>;
+/** Built-in function/method names that should not be tracked as call targets */
+export declare const BUILT_IN_NAMES: Set<string>;
+/** Check if a name is a built-in or common noise that should be filtered out */
+export declare const isBuiltInOrNoise: (name: string) => boolean;
+/** AST node types representing class-like containers (for HAS_METHOD edges) */
+export declare const CLASS_CONTAINER_TYPES: Set<string>;
+export declare const CONTAINER_TYPE_TO_LABEL: Record<string, string>;
+/** Walk up AST to find enclosing class/struct/impl and return its generateId (handles Go receivers) */
+export declare const findEnclosingClassId: (node: any, filePath: string) => string | null;
+/** Extract function name and label from a function/method AST node (handles C/C++ qualified_identifier) */
+export declare const extractFunctionName: (node: any) => {
+    funcName: string | null;
+    label: string;
+};
+/** Yield control to the event loop to prevent UI freezes in hot loops */
+export declare const yieldToEventLoop: () => Promise<void>;
+/** Find a child of `childType` within a sibling node of `siblingType` (used for Kotlin AST) */
+export declare const findSiblingChild: (parent: any, siblingType: string, childType: string) => any | null;
+/** Map file extension to SupportedLanguage enum */
+export declare const getLanguageFromFilename: (filename: string) => SupportedLanguages | null;
+export interface MethodSignature {
+    parameterCount: number | undefined;
+    returnType: string | undefined;
+    parameterTypes?: string[];
+}
+/** Extract parameter count and return type from an AST function/method node */
+export declare const extractMethodSignature: (node: SyntaxNode | null | undefined) => MethodSignature;
+/** Count direct arguments for a call expression across common tree-sitter grammars */
+export declare const countCallArguments: (callNode: SyntaxNode | null | undefined) => number | undefined;
+type CallForm = 'free' | 'member' | 'constructor';
+/**
+ * Infer whether a captured call site is a free call, member call, or constructor
+ *
+ * Inspects the AST structure between callNode (@call) and nameNode (@call.name)
+ */
+export declare const inferCallForm: (callNode: SyntaxNode, nameNode: SyntaxNode) => CallForm | undefined;
+/** Extract the receiver identifier for member calls (simple identifiers only) */
+export declare const extractReceiverName: (nameNode: SyntaxNode) => string | undefined;
+/**
+ * Extract the raw receiver AST node for a member call (including chained calls)
+ *
+ * Unlike extractReceiverName, returns the receiver node regardless of its type
+ */
+export declare const extractReceiverNode: (nameNode: SyntaxNode) => SyntaxNode | undefined;
+export declare const isVerboseIngestionEnabled: () => boolean;
+export declare const CALL_EXPRESSION_TYPES: Set<string>;
+export declare const MAX_CHAIN_DEPTH = 3;
+/**
+ * Walk a receiver call expression to accumulate a chain of intermediate method names
+ *
+ * For `svc.getUser().save()`: { chain: ['getUser'], baseReceiverName: 'svc' }
+ */
+export declare function extractCallChain(receiverCallNode: SyntaxNode): {
+    chain: string[];
+    baseReceiverName: string | undefined;
+} | undefined;
+export {};