@zuvia-software-solutions/code-mapper 1.4.0

package/dist/core/ingestion/call-processor.js

@@ -0,0 +1,937 @@
+// code-mapper/src/core/ingestion/call-processor.ts
+/** @file call-processor.ts @description Resolves function/method call sites to target symbol nodes, supporting sequential AST-based and pre-extracted worker-based paths */
+import Parser from 'tree-sitter';
+import { TIER_CONFIDENCE } from './resolution-context.js';
+import { isLanguageAvailable, loadParser, loadLanguage } from '../tree-sitter/parser-loader.js';
+import { LANGUAGE_QUERIES } from './tree-sitter-queries.js';
+import { generateId } from '../../lib/utils.js';
+import { getLanguageFromFilename, isVerboseIngestionEnabled, yieldToEventLoop, FUNCTION_NODE_TYPES, extractFunctionName, isBuiltInOrNoise, countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, findEnclosingClassId, CALL_EXPRESSION_TYPES, extractCallChain, } from './utils.js';
+import { buildTypeEnv } from './type-env.js';
+import { getTreeSitterBufferSize } from './constants.js';
+import { callRouters } from './call-routing.js';
+/** Walk up the AST to find the enclosing function/method, or null for top-level code */
+const findEnclosingFunction = (node, filePath, ctx) => {
+    let current = node.parent;
+    while (current) {
+        if (FUNCTION_NODE_TYPES.has(current.type)) {
+            const { funcName, label } = extractFunctionName(current);
+            if (funcName) {
+                const resolved = ctx.resolve(funcName, filePath);
+                if (resolved?.tier === 'same-file' && resolved.candidates.length > 0) {
+                    return resolved.candidates[0].nodeId;
+                }
+                return generateId(label, `${filePath}:${funcName}`);
+            }
+        }
+        current = current.parent;
+    }
+    return null;
+};
+/** Verify constructor bindings against SymbolTable and infer receiver types */
+const verifyConstructorBindings = (bindings, filePath, ctx, graph) => {
+    const verified = new Map();
+    for (const { scope, varName, calleeName, receiverClassName } of bindings) {
+        const tiered = ctx.resolve(calleeName, filePath);
+        const isClass = tiered?.candidates.some(def => def.type === 'Class') ?? false;
+        if (isClass) {
+            verified.set(receiverKey(scope, varName), calleeName);
+        }
+        else {
+            let callableDefs = tiered?.candidates.filter(d => d.type === 'Function' || d.type === 'Method');
+            // When receiver class is known (e.g. $this->method() in PHP), narrow
+            // candidates to methods owned by that class
+            if (callableDefs && callableDefs.length > 1 && receiverClassName) {
+                if (graph) {
+                    // Worker path: use graph.getNode
+                    const narrowed = callableDefs.filter(d => {
+                        if (!d.ownerId)
+                            return false;
+                        const owner = graph.getNode(d.ownerId);
+                        return owner?.properties.name === receiverClassName;
+                    });
+                    if (narrowed.length > 0)
+                        callableDefs = narrowed;
+                }
+                else {
+                    // Sequential path: use ctx.resolve
+                    const classResolved = ctx.resolve(receiverClassName, filePath);
+                    if (classResolved && classResolved.candidates.length > 0) {
+                        const classNodeIds = new Set(classResolved.candidates.map(c => c.nodeId));
+                        const narrowed = callableDefs.filter(d => d.ownerId && classNodeIds.has(d.ownerId));
+                        if (narrowed.length > 0)
+                            callableDefs = narrowed;
+                    }
+                }
+            }
+            if (callableDefs && callableDefs.length === 1 && callableDefs[0].returnType) {
+                const typeName = extractReturnTypeName(callableDefs[0].returnType);
+                if (typeName) {
+                    verified.set(receiverKey(scope, varName), typeName);
+                }
+            }
+        }
+    }
+    return verified;
+};
+/** Check if a node is inside a catch clause */
+const isInsideCatch = (node) => {
+    let current = node.parent;
+    while (current) {
+        if (current.type === 'catch_clause')
+            return true;
+        // Stop at function boundary
+        if (FUNCTION_NODE_TYPES.has(current.type))
+            return false;
+        current = current.parent;
+    }
+    return false;
+};
+/** Check if a node is inside an if-statement body (conditional call) */
+const isInsideConditional = (node) => {
+    let current = node.parent;
+    while (current) {
+        if (current.type === 'if_statement' || current.type === 'conditional_expression' || current.type === 'ternary_expression')
+            return true;
+        if (FUNCTION_NODE_TYPES.has(current.type))
+            return false;
+        current = current.parent;
+    }
+    return false;
+};
+export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
+    const parser = await loadParser();
+    const collectedHeritage = [];
+    const logSkipped = isVerboseIngestionEnabled();
+    const skippedByLang = logSkipped ? new Map() : null;
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
+        onProgress?.(i + 1, files.length);
+        if (i % 20 === 0)
+            await yieldToEventLoop();
+        const language = getLanguageFromFilename(file.path);
+        if (!language)
+            continue;
+        if (!isLanguageAvailable(language)) {
+            if (skippedByLang) {
+                skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);
+            }
+            continue;
+        }
+        const queryStr = LANGUAGE_QUERIES[language];
+        if (!queryStr)
+            continue;
+        await loadLanguage(language, file.path);
+        let tree = astCache.get(file.path);
+        if (!tree) {
+            try {
+                tree = parser.parse(file.content, undefined, { bufferSize: getTreeSitterBufferSize(file.content.length) });
+            }
+            catch (parseError) {
+                continue;
+            }
+            astCache.set(file.path, tree);
+        }
+        let query;
+        let matches;
+        try {
+            const language = parser.getLanguage();
+            query = new Parser.Query(language, queryStr);
+            matches = query.matches(tree.rootNode);
+        }
+        catch (queryError) {
+            console.warn(`Query error for ${file.path}:`, queryError);
+            continue;
+        }
+        const lang = getLanguageFromFilename(file.path);
+        const typeEnv = lang ? buildTypeEnv(tree, lang, ctx.symbols) : null;
+        const callRouter = callRouters[language];
+        const verifiedReceivers = typeEnv && typeEnv.constructorBindings.length > 0
+            ? verifyConstructorBindings(typeEnv.constructorBindings, file.path, ctx)
+            : new Map();
+        ctx.enableCache(file.path);
+        matches.forEach(match => {
+            const captureMap = {};
+            match.captures.forEach(c => captureMap[c.name] = c.node);
+            if (!captureMap['call'])
+                return;
+            const nameNode = captureMap['call.name'];
+            if (!nameNode)
+                return;
+            const calledName = nameNode.text;
+            const routed = callRouter(calledName, captureMap['call']);
+            if (routed) {
+                switch (routed.kind) {
+                    case 'skip':
+                    case 'import':
+                        return;
+                    case 'heritage':
+                        for (const item of routed.items) {
+                            collectedHeritage.push({
+                                filePath: file.path,
+                                className: item.enclosingClass,
+                                parentName: item.mixinName,
+                                kind: item.heritageKind,
+                            });
+                        }
+                        return;
+                    case 'properties': {
+                        const fileId = generateId('File', file.path);
+                        const propEnclosingClassId = findEnclosingClassId(captureMap['call'], file.path);
+                        for (const item of routed.items) {
+                            const nodeId = generateId('Property', `${file.path}:${item.propName}`);
+                            graph.addNode({
+                                id: nodeId,
+                                label: 'Property', // TODO: add 'Property' to graph node label union
+                                properties: {
+                                    name: item.propName, filePath: file.path,
+                                    startLine: item.startLine, endLine: item.endLine,
+                                    language, isExported: true,
+                                    description: item.accessorType,
+                                },
+                            });
+                            ctx.symbols.add(file.path, item.propName, nodeId, 'Property', propEnclosingClassId ? { ownerId: propEnclosingClassId } : undefined);
+                            const relId = generateId('DEFINES', `${fileId}->${nodeId}`);
+                            graph.addRelationship({
+                                id: relId, sourceId: fileId, targetId: nodeId,
+                                type: 'DEFINES', confidence: 1.0, reason: '',
+                            });
+                            if (propEnclosingClassId) {
+                                graph.addRelationship({
+                                    id: generateId('HAS_METHOD', `${propEnclosingClassId}->${nodeId}`),
+                                    sourceId: propEnclosingClassId, targetId: nodeId,
+                                    type: 'HAS_METHOD', confidence: 1.0, reason: '',
+                                });
+                            }
+                        }
+                        return;
+                    }
+                    case 'call':
+                        break;
+                }
+            }
+            // B3: Handle dynamic imports — `const { foo } = await import('./module.js')`
+            // Extract destructured names and create CALLS edges to the resolved module's exports
+            if (calledName === 'import') {
+                const callNode = captureMap['call'];
+                // Get the import path from the argument
+                let importPath = null;
+                for (const arg of (callNode?.children || [])) {
+                    if (arg.type === 'arguments') {
+                        const strArg = arg.children?.find((c) => c.type === 'string' || c.type === 'template_string');
+                        if (strArg) {
+                            importPath = strArg.text?.replace(/['"``]/g, '') || null;
+                        }
+                    }
+                }
+                if (importPath) {
+                    // Find the variable_declarator parent to get destructured names
+                    let parent = callNode.parent;
+                    while (parent && parent.type !== 'variable_declarator' && parent.type !== 'lexical_declaration') {
+                        parent = parent.parent;
+                    }
+                    if (parent?.type === 'variable_declarator' || parent?.type === 'lexical_declaration') {
+                        const declarator = parent.type === 'variable_declarator' ? parent : parent.children?.find((c) => c.type === 'variable_declarator');
+                        const pattern = declarator?.childForFieldName?.('name') || declarator?.children?.find((c) => c.type === 'object_pattern');
+                        if (pattern?.type === 'object_pattern') {
+                            // Extract destructured names: { rerank, mergeWithRRF }
+                            for (const child of (pattern.children || [])) {
+                                if (child.type === 'shorthand_property_identifier_pattern' || child.type === 'shorthand_property_identifier') {
+                                    const importedName = child.text;
+                                    if (importedName && !isBuiltInOrNoise(importedName)) {
+                                        const enclosingFuncId = findEnclosingFunction(callNode, file.path, ctx);
+                                        const sourceId = enclosingFuncId || generateId('File', file.path);
+                                        // Try module-scoped resolution first: extract the target filename
+                                        // from the import path and look up the name in that file
+                                        let targetId = null;
+                                        let confidence = 0.5;
+                                        let reason = 'global';
+                                        // Extract filename hint from import path (e.g. '../../core/search/hybrid-search.js' → 'hybrid-search')
+                                        const pathBase = importPath.split('/').pop()?.replace(/\.\w+$/, '');
+                                        if (pathBase) {
+                                            // Try exact lookup in files whose path contains the base name
+                                            const candidates = ctx.symbols.lookupFuzzy(importedName);
+                                            const moduleMatch = candidates.find(c => c.filePath.includes(pathBase) && (c.type === 'Function' || c.type === 'Class' || c.type === 'Interface' || c.type === 'Method'));
+                                            if (moduleMatch) {
+                                                targetId = moduleMatch.nodeId;
+                                                confidence = 0.9;
+                                                reason = 'dynamic-import-resolved';
+                                            }
+                                        }
+                                        // Fall back to general resolution
+                                        if (!targetId) {
+                                            const resolved = ctx.resolve(importedName, file.path);
+                                            if (resolved && resolved.candidates.length > 0) {
+                                                targetId = resolved.candidates[0].nodeId;
+                                                confidence = Math.max(TIER_CONFIDENCE[resolved.tier] ?? 0.5, 0.8);
+                                                reason = `dynamic-import:${resolved.tier}`;
+                                            }
+                                        }
+                                        if (targetId) {
+                                            graph.addRelationship({
+                                                id: generateId('CALLS', `${sourceId}:dyn_import:${importedName}->${targetId}`),
+                                                sourceId,
+                                                targetId,
+                                                type: 'CALLS',
+                                                confidence,
+                                                reason,
+                                            });
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                return; // don't process 'import' as a regular call
+            }
+            if (isBuiltInOrNoise(calledName))
+                return;
+            const callNode = captureMap['call'];
+            const callForm = inferCallForm(callNode, nameNode);
+            const receiverName = callForm === 'member' ? extractReceiverName(nameNode) : undefined;
+            let receiverTypeName = receiverName && typeEnv ? typeEnv.lookup(receiverName, callNode) : undefined;
+            // Fall back to verified constructor bindings
+            if (!receiverTypeName && receiverName && verifiedReceivers.size > 0) {
+                const enclosingFunc = findEnclosingFunction(callNode, file.path, ctx);
+                const funcName = enclosingFunc ? extractFuncNameFromSourceId(enclosingFunc) : '';
+                receiverTypeName = lookupReceiverType(verifiedReceivers, funcName, receiverName);
+            }
+            // Fall back to class-as-receiver for static method calls (e.g. UserService.find_user())
+            // when receiver name resolves to a Class/Struct/Interface via tiered resolution
+            if (!receiverTypeName && receiverName && callForm === 'member') {
+                const typeResolved = ctx.resolve(receiverName, file.path);
+                if (typeResolved && typeResolved.candidates.some(d => d.type === 'Class' || d.type === 'Interface' || d.type === 'Struct' || d.type === 'Enum')) {
+                    receiverTypeName = receiverName;
+                }
+            }
+            // Fall back to chained call resolution when receiver is a call expression
+            // (e.g. svc.getUser().save() -- receiver of save() is getUser())
+            if (callForm === 'member' && !receiverTypeName && !receiverName) {
+                const receiverNode = extractReceiverNode(nameNode);
+                if (receiverNode && CALL_EXPRESSION_TYPES.has(receiverNode.type)) {
+                    const extracted = extractCallChain(receiverNode);
+                    if (extracted) {
+                        // Resolve the base receiver type
+                        let baseType = extracted.baseReceiverName && typeEnv
+                            ? typeEnv.lookup(extracted.baseReceiverName, callNode)
+                            : undefined;
+                        if (!baseType && extracted.baseReceiverName && verifiedReceivers.size > 0) {
+                            const enclosingFunc = findEnclosingFunction(callNode, file.path, ctx);
+                            const funcName = enclosingFunc ? extractFuncNameFromSourceId(enclosingFunc) : '';
+                            baseType = lookupReceiverType(verifiedReceivers, funcName, extracted.baseReceiverName);
+                        }
+                        // Class-as-receiver for chain base
+                        if (!baseType && extracted.baseReceiverName) {
+                            const cr = ctx.resolve(extracted.baseReceiverName, file.path);
+                            if (cr?.candidates.some(d => d.type === 'Class' || d.type === 'Interface' || d.type === 'Struct' || d.type === 'Enum')) {
+                                baseType = extracted.baseReceiverName;
+                            }
+                        }
+                        receiverTypeName = resolveChainedReceiver(extracted.chain, baseType, file.path, ctx);
+                    }
+                }
+            }
+            // Fix 2: Skip generic method names (has, get, set, etc.) when called on unknown receiver
+            // These almost always resolve to wrong targets (Map.has -> type-env.has) with low confidence
+            const GENERIC_MEMBER_METHODS = new Set(['has', 'get', 'set', 'add', 'remove', 'delete', 'close', 'stop', 'clear', 'reset', 'toString', 'valueOf', 'push', 'pop', 'entries', 'keys', 'values']);
+            if (callForm === 'member' && !receiverTypeName && GENERIC_MEMBER_METHODS.has(calledName))
+                return;
+            const resolved = resolveCallTarget({
+                calledName,
+                argCount: countCallArguments(callNode),
+                callForm,
+                receiverTypeName,
+            }, file.path, ctx);
+            if (!resolved)
+                return;
+            const enclosingFuncId = findEnclosingFunction(callNode, file.path, ctx);
+            const sourceId = enclosingFuncId || generateId('File', file.path);
+            const relId = generateId('CALLS', `${sourceId}:${calledName}->${resolved.nodeId}`);
+            const callContext = isInsideCatch(callNode) ? 'error-handler' : isInsideConditional(callNode) ? 'conditional' : '';
+            graph.addRelationship({
+                id: relId,
+                sourceId,
+                targetId: resolved.nodeId,
+                type: 'CALLS',
+                confidence: resolved.confidence,
+                reason: callContext || resolved.reason,
+                callLine: callNode.startPosition?.row != null ? callNode.startPosition.row + 1 : undefined,
+            });
+        });
+        // Fix 9: Scan for dynamic imports that tree-sitter queries can't capture
+        // Pattern: const { foo, bar } = await import('./module.js')
+        // The tree-sitter query `(call_expression function: (import) @call.name) @call`
+        // doesn't reliably capture import() because (import) has no text as an identifier.
+        // This post-processing walks the AST directly to find these patterns.
+        try {
+            const visitNode = (node) => {
+                if (node.type === 'call_expression') {
+                    const funcChild = node.childForFieldName?.('function');
+                    if (funcChild?.type === 'import') {
+                        // Found a dynamic import
+                        const args = node.childForFieldName?.('arguments');
+                        const strArg = args?.children?.find((c) => c.type === 'string' || c.type === 'template_string');
+                        const importPath = strArg?.text?.replace(/['"``]/g, '') || null;
+                        if (importPath) {
+                            // Walk up to find variable_declarator with object_pattern
+                            let parent = node.parent;
+                            // Skip await_expression wrapper
+                            if (parent?.type === 'await_expression')
+                                parent = parent.parent;
+                            // Should be in a variable_declarator
+                            if (parent?.type === 'variable_declarator') {
+                                const pattern = parent.childForFieldName?.('name');
+                                if (pattern?.type === 'object_pattern') {
+                                    for (const child of (pattern.children || [])) {
+                                        if (child.type === 'shorthand_property_identifier_pattern' || child.type === 'shorthand_property_identifier') {
+                                            const importedName = child.text;
+                                            if (importedName && !isBuiltInOrNoise(importedName)) {
+                                                const enclosingFuncId = findEnclosingFunction(node, file.path, ctx);
+                                                const sourceId = enclosingFuncId || generateId('File', file.path);
+                                                const resolved = ctx.resolve(importedName, file.path);
+                                                if (resolved && resolved.candidates.length > 0) {
+                                                    graph.addRelationship({
+                                                        id: generateId('CALLS', `${sourceId}:dyn:${importedName}->${resolved.candidates[0].nodeId}`),
+                                                        sourceId,
+                                                        targetId: resolved.candidates[0].nodeId,
+                                                        type: 'CALLS',
+                                                        confidence: 0.85,
+                                                        reason: 'dynamic-import',
+                                                    });
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                // Recurse into children
+                for (let i = 0; i < node.childCount; i++) {
+                    visitNode(node.child(i));
+                }
+            };
+            visitNode(tree.rootNode);
+        }
+        catch (e) {
+            // Non-fatal — dynamic import scanning is best-effort
+        }
+        ctx.clearCache();
+    }
+    if (skippedByLang && skippedByLang.size > 0) {
+        for (const [lang, count] of skippedByLang.entries()) {
+            console.warn(`[ingestion] Skipped ${count} ${lang} file(s) in call processing — ${lang} parser not available.`);
+        }
+    }
+    return collectedHeritage;
+};
+const CALLABLE_SYMBOL_TYPES = new Set([
+    'Function',
+    'Method',
+    'Constructor',
+    'Macro',
+    'Delegate',
+]);
+const CONSTRUCTOR_TARGET_TYPES = new Set(['Constructor', 'Class', 'Struct', 'Record']);
+const filterCallableCandidates = (candidates, argCount, callForm) => {
+    let kindFiltered;
+    if (callForm === 'constructor') {
+        const constructors = candidates.filter(c => c.type === 'Constructor');
+        if (constructors.length > 0) {
+            kindFiltered = constructors;
+        }
+        else {
+            const types = candidates.filter(c => CONSTRUCTOR_TARGET_TYPES.has(c.type));
+            kindFiltered = types.length > 0 ? types : candidates.filter(c => CALLABLE_SYMBOL_TYPES.has(c.type));
+        }
+    }
+    else {
+        kindFiltered = candidates.filter(c => CALLABLE_SYMBOL_TYPES.has(c.type));
+    }
+    if (kindFiltered.length === 0)
+        return [];
+    if (argCount === undefined)
+        return kindFiltered;
+    const hasParameterMetadata = kindFiltered.some(candidate => candidate.parameterCount !== undefined);
+    if (!hasParameterMetadata)
+        return kindFiltered;
+    return kindFiltered.filter(candidate => candidate.parameterCount === undefined || candidate.parameterCount === argCount);
+};
+const toResolveResult = (definition, tier) => ({
+    nodeId: definition.nodeId,
+    confidence: TIER_CONFIDENCE[tier],
+    reason: tier === 'same-file' ? 'same-file' : tier === 'import-scoped' ? 'import-resolved' : 'global',
+});
+/**
+ * Resolve a chain of intermediate method calls to find the receiver type
+ * for a final member call (e.g. svc.getUser().save())
+ *
+ * @param chainNames - Ordered method names from outermost to innermost
+ * @param baseReceiverTypeName - Already-resolved type of the base receiver, or undefined
+ * @param currentFile - File path for resolution context
+ * @param ctx - Resolution context for symbol lookup
+ * @returns Final intermediate call's return type name, or undefined if resolution fails
+ */
+function resolveChainedReceiver(chainNames, baseReceiverTypeName, currentFile, ctx) {
+    let currentType = baseReceiverTypeName;
+    for (const name of chainNames) {
+        const resolved = resolveCallTarget({ calledName: name, callForm: 'member', receiverTypeName: currentType }, currentFile, ctx);
+        if (!resolved)
+            return undefined;
+        const candidates = ctx.symbols.lookupFuzzy(name);
+        const symDef = candidates.find(c => c.nodeId === resolved.nodeId);
+        if (!symDef?.returnType)
+            return undefined;
+        const returnTypeName = extractReturnTypeName(symDef.returnType);
+        if (!returnTypeName)
+            return undefined;
+        currentType = returnTypeName;
+    }
+    return currentType;
+}
+/**
+ * Resolve a function call to its target node ID
+ *
+ * Strategy: A) narrow by scope tier, B) filter callable kinds, C) arity filter,
+ * D) receiver-type filter. Refuses to emit CALLS edge if multiple candidates remain
+ */
+const resolveCallTarget = (call, currentFile, ctx) => {
+    const tiered = ctx.resolve(call.calledName, currentFile);
+    if (!tiered)
+        return null;
+    const filteredCandidates = filterCallableCandidates(tiered.candidates, call.argCount, call.callForm);
+    // D. Receiver-type filtering: resolve type via tiered imports, filter method
+    // candidates to the type's defining file. Applied regardless of candidate count
+    // since the sole same-file candidate may belong to the wrong class
+    if (call.callForm === 'member' && call.receiverTypeName) {
+        // D1. Resolve receiver type
+        const typeResolved = ctx.resolve(call.receiverTypeName, currentFile);
+        if (typeResolved && typeResolved.candidates.length > 0) {
+            const typeNodeIds = new Set(typeResolved.candidates.map(d => d.nodeId));
+            const typeFiles = new Set(typeResolved.candidates.map(d => d.filePath));
+            // D2. Widen candidates: same-file tier may miss parent's method in another file
+            const methodPool = filteredCandidates.length <= 1
+                ? filterCallableCandidates(ctx.symbols.lookupFuzzy(call.calledName), call.argCount, call.callForm)
+                : filteredCandidates;
+            // D3. File-based: prefer candidates in the resolved type's file
+            const fileFiltered = methodPool.filter(c => typeFiles.has(c.filePath));
+            if (fileFiltered.length === 1) {
+                return toResolveResult(fileFiltered[0], tiered.tier);
+            }
+            // D4. ownerId fallback: narrow by ownerId matching type's nodeId
+            const pool = fileFiltered.length > 0 ? fileFiltered : methodPool;
+            const ownerFiltered = pool.filter(c => c.ownerId && typeNodeIds.has(c.ownerId));
+            if (ownerFiltered.length === 1) {
+                return toResolveResult(ownerFiltered[0], tiered.tier);
+            }
+            if (fileFiltered.length > 1 || ownerFiltered.length > 1)
+                return null;
+        }
+    }
+    if (filteredCandidates.length === 0)
+        return null;
+    // Deduplicate by nodeId — the same symbol can appear multiple times from different resolution paths
+    if (filteredCandidates.length > 1) {
+        const uniqueById = new Map(filteredCandidates.map(c => [c.nodeId, c]));
+        if (uniqueById.size === 1) {
+            return toResolveResult(filteredCandidates[0], tiered.tier);
+        }
+        // Multiple distinct candidates — ambiguous, skip
+        return null;
+    }
+    return toResolveResult(filteredCandidates[0], tiered.tier);
+};
+// Return type text helpers
+// Operates on raw return-type text in SymbolDefinition (e.g. "User", "Promise<User>",
+// "User | null", "*User") to extract the base user-defined type name
+// Primitive/built-in types that should NOT produce a receiver binding
+const PRIMITIVE_TYPES = new Set([
+    'string', 'number', 'boolean', 'void', 'int', 'float', 'double', 'long',
+    'short', 'byte', 'char', 'bool', 'str', 'i8', 'i16', 'i32', 'i64',
+    'u8', 'u16', 'u32', 'u64', 'f32', 'f64', 'usize', 'isize',
+    'undefined', 'null', 'None', 'nil',
+]);
+/**
+ * Extract a simple type name from raw return-type text
+ *
+ * Handles: "User", "Promise<User>", "Option<User>", "Result<User, Error>",
+ * "User | null", "User?", "*User" (Go pointer), "&User" (Rust reference)
+ *
+ * @returns The base type name, or undefined for complex types or primitives
+ */
+// Wrapper generics that get unwrapped to their inner type argument
+// Containers (List, Vec, Set, etc.) are excluded -- methods are called on the container
+const WRAPPER_GENERICS = new Set([
+    'Promise', 'Observable', 'Future', 'CompletableFuture', 'Task', 'ValueTask',
+    'Option', 'Some', 'Optional', 'Maybe',
+    'Result', 'Either',
+    'Rc', 'Arc', 'Weak',
+    'MutexGuard', 'RwLockReadGuard', 'RwLockWriteGuard',
+    'Ref', 'RefMut',
+    'Cow',
+]);
+/** Extract the first type argument from a generic string, respecting nested angle brackets */
+function extractFirstGenericArg(args) {
+    let depth = 0;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '<')
+            depth++;
+        else if (args[i] === '>')
+            depth--;
+        else if (args[i] === ',' && depth === 0)
+            return args.slice(0, i).trim();
+    }
+    return args.trim();
+}
+/** Extract the first non-lifetime type argument, skipping Rust lifetime params ('a, '_) */
+function extractFirstTypeArg(args) {
+    let remaining = args;
+    while (remaining) {
+        const first = extractFirstGenericArg(remaining);
+        if (!first.startsWith("'"))
+            return first;
+        // Skip past this lifetime arg + comma separator
+        const commaIdx = remaining.indexOf(',', first.length);
+        if (commaIdx < 0)
+            return first; // only lifetimes, fall through
+        remaining = remaining.slice(commaIdx + 1).trim();
+    }
+    return args.trim();
+}
+export const extractReturnTypeName = (raw, depth = 0) => {
+    if (depth > 10)
+        return undefined;
+    let text = raw.trim();
+    if (!text)
+        return undefined;
+    // Strip pointer/reference prefixes (*User, &User, &mut User)
+    text = text.replace(/^[&*]+\s*(mut\s+)?/, '');
+    // Strip nullable suffix (User?)
+    text = text.replace(/\?$/, '');
+    // Handle union types ("User | null" -> "User")
+    if (text.includes('|')) {
+        const parts = text.split('|').map(p => p.trim()).filter(p => p !== 'null' && p !== 'undefined' && p !== 'void' && p !== 'None' && p !== 'nil');
+        if (parts.length === 1)
+            text = parts[0];
+        else
+            return undefined; // genuine union, too complex
+    }
+    // Handle generics (Promise<User> -> unwrap if wrapper, else take base)
+    const genericMatch = text.match(/^(\w+)\s*<(.+)>$/);
+    if (genericMatch) {
+        const [, base, args] = genericMatch;
+        if (WRAPPER_GENERICS.has(base)) {
+            // Take the first non-lifetime type argument using bracket-balanced splitting
+            const firstArg = extractFirstTypeArg(args);
+            return extractReturnTypeName(firstArg, depth + 1);
+        }
+        // Non-wrapper generic: return the base type (e.g. Map<K,V> -> Map)
+        return PRIMITIVE_TYPES.has(base.toLowerCase()) ? undefined : base;
+    }
+    // Bare wrapper type without generic argument is meaningless
+    if (WRAPPER_GENERICS.has(text))
+        return undefined;
+    // Handle qualified names (models.User -> User, Models::User -> User)
+    if (text.includes('::') || text.includes('.') || text.includes('\\')) {
+        text = text.split(/::|[.\\]/).pop();
+    }
+    // Skip primitives
+    if (PRIMITIVE_TYPES.has(text) || PRIMITIVE_TYPES.has(text.toLowerCase()))
+        return undefined;
+    // Must start with uppercase (class/type convention)
+    if (!/^[A-Z_]\w*$/.test(text))
+        return undefined;
+    return text;
+};
+// Scope key helpers
+// Scope keys: "funcName@startIndex" (type-env.ts)
+// Source IDs: "Label:filepath:funcName" (parse-worker.ts)
+// NUL (\0) separates composite keys to prevent ambiguous concatenation
+// receiverKey uses full scope to distinguish overloaded methods (e.g. User.save@100 vs Repo.save@200)
+/** Extract function name from a scope key ("funcName@startIndex" -> "funcName") */
+const extractFuncNameFromScope = (scope) => scope.slice(0, scope.indexOf('@'));
+/** Extract trailing function name from a sourceId ("Function:filepath:funcName" -> "funcName") */
+const extractFuncNameFromSourceId = (sourceId) => {
+    const lastColon = sourceId.lastIndexOf(':');
+    return lastColon >= 0 ? sourceId.slice(lastColon + 1) : '';
+};
+/** Build a composite key for receiver type storage using full scope string */
+const receiverKey = (scope, varName) => `${scope}\0${varName}`;
+/**
+ * Look up receiver type from a verified receiver map keyed by scope\0varName
+ *
+ * Scans entries matching funcName@ prefix with matching varName. Returns the
+ * type if exactly one unique match exists, undefined if ambiguous. Falls back
+ * to file-level scope (\0varName)
+ */
+const lookupReceiverType = (map, funcName, varName) => {
+    // Fast path: file-level scope (empty funcName, used as fallback)
+    const fileLevelKey = receiverKey('', varName);
+    const prefix = `${funcName}@`;
+    const suffix = `\0${varName}`;
+    let found;
+    let ambiguous = false;
+    for (const [key, value] of map) {
+        if (key === fileLevelKey)
+            continue; // handled separately below
+        if (key.startsWith(prefix) && key.endsWith(suffix)) {
+            // Verify key is "funcName@<startIndex>\0varName" with non-empty middle segment
+            const middle = key.slice(prefix.length, key.length - suffix.length);
+            if (middle.length === 0)
+                continue; // malformed key, skip
+            if (found === undefined) {
+                found = value;
+            }
+            else if (found !== value) {
+                ambiguous = true;
+                break;
+            }
+        }
+    }
+    if (!ambiguous && found !== undefined)
+        return found;
+    // Fallback: file-level scope
+    return map.get(fileLevelKey);
+};
+/** Resolve pre-extracted call sites from workers (no AST parsing needed) */
+export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onProgress, constructorBindings) => {
+    // Scope-aware receiver types keyed by filePath -> scope\0varName -> typeName
+    const fileReceiverTypes = new Map();
+    if (constructorBindings) {
+        for (const { filePath, bindings } of constructorBindings) {
+            const verified = verifyConstructorBindings(bindings, filePath, ctx, graph);
+            if (verified.size > 0) {
+                fileReceiverTypes.set(filePath, verified);
+            }
+        }
+    }
+    const byFile = new Map();
+    for (const call of extractedCalls) {
+        let list = byFile.get(call.filePath);
+        if (!list) {
+            list = [];
+            byFile.set(call.filePath, list);
+        }
+        list.push(call);
+    }
+    const totalFiles = byFile.size;
+    let filesProcessed = 0;
+    for (const [filePath, calls] of byFile) {
+        filesProcessed++;
+        if (filesProcessed % 100 === 0) {
+            onProgress?.(filesProcessed, totalFiles);
+            await yieldToEventLoop();
+        }
+        ctx.enableCache(filePath);
+        const receiverMap = fileReceiverTypes.get(filePath);
+        for (const call of calls) {
+            let effectiveCall = call;
+            // Step 1: resolve receiver type from constructor bindings
+            if (!call.receiverTypeName && call.receiverName && receiverMap) {
+                const callFuncName = extractFuncNameFromSourceId(call.sourceId);
+                const resolvedType = lookupReceiverType(receiverMap, callFuncName, call.receiverName);
+                if (resolvedType) {
+                    effectiveCall = { ...call, receiverTypeName: resolvedType };
+                }
+            }
+            // Step 1b: class-as-receiver for static method calls
+            if (!effectiveCall.receiverTypeName && effectiveCall.receiverName && effectiveCall.callForm === 'member') {
+                const typeResolved = ctx.resolve(effectiveCall.receiverName, effectiveCall.filePath);
+                if (typeResolved && typeResolved.candidates.some(d => d.type === 'Class' || d.type === 'Interface' || d.type === 'Struct' || d.type === 'Enum')) {
+                    effectiveCall = { ...effectiveCall, receiverTypeName: effectiveCall.receiverName };
+                }
+            }
+            // Step 2: resolve receiver call chain (e.g. svc.getUser().save())
+            // Runs even when Step 1 set a receiverTypeName -- that's the BASE receiver,
+            // the chain resolves the FINAL receiver type
+            if (effectiveCall.receiverCallChain?.length) {
+                // Use Step 1's base receiver type as starting point for chain resolution
+                let baseType = effectiveCall.receiverTypeName;
+                // If Step 1 didn't resolve it, try the receiver map directly
+                if (!baseType && effectiveCall.receiverName && receiverMap) {
+                    const callFuncName = extractFuncNameFromSourceId(effectiveCall.sourceId);
+                    baseType = lookupReceiverType(receiverMap, callFuncName, effectiveCall.receiverName);
+                }
+                const chainedType = resolveChainedReceiver(effectiveCall.receiverCallChain, baseType, effectiveCall.filePath, ctx);
+                if (chainedType) {
+                    effectiveCall = { ...effectiveCall, receiverTypeName: chainedType };
+                }
+            }
+            const resolved = resolveCallTarget(effectiveCall, effectiveCall.filePath, ctx);
+            if (!resolved)
+                continue;
+            const relId = generateId('CALLS', `${effectiveCall.sourceId}:${effectiveCall.calledName}->${resolved.nodeId}`);
+            graph.addRelationship({
+                id: relId,
+                sourceId: effectiveCall.sourceId,
+                targetId: resolved.nodeId,
+                type: 'CALLS',
+                confidence: resolved.confidence,
+                reason: resolved.reason,
+                callLine: effectiveCall.callLine,
+            });
+        }
+        ctx.clearCache();
+    }
+    onProgress?.(totalFiles, totalFiles);
+};
+/** Resolve pre-extracted Laravel routes to CALLS edges from route files to controller methods */
+export const processRoutesFromExtracted = async (graph, extractedRoutes, ctx, onProgress) => {
+    for (let i = 0; i < extractedRoutes.length; i++) {
+        const route = extractedRoutes[i];
+        if (i % 50 === 0) {
+            onProgress?.(i, extractedRoutes.length);
+            await yieldToEventLoop();
+        }
+        if (!route.controllerName || !route.methodName)
+            continue;
+        const controllerResolved = ctx.resolve(route.controllerName, route.filePath);
+        if (!controllerResolved || controllerResolved.candidates.length === 0)
+            continue;
+        if (controllerResolved.tier === 'global' && controllerResolved.candidates.length > 1)
+            continue;
+        const controllerDef = controllerResolved.candidates[0];
+        const confidence = TIER_CONFIDENCE[controllerResolved.tier];
+        const methodResolved = ctx.resolve(route.methodName, controllerDef.filePath);
+        const methodId = methodResolved?.tier === 'same-file' ? methodResolved.candidates[0]?.nodeId : undefined;
+        const sourceId = generateId('File', route.filePath);
+        if (!methodId) {
+            const guessedId = generateId('Method', `${controllerDef.filePath}:${route.methodName}`);
+            const relId = generateId('CALLS', `${sourceId}:route->${guessedId}`);
+            graph.addRelationship({
+                id: relId,
+                sourceId,
+                targetId: guessedId,
+                type: 'CALLS',
+                confidence: confidence * 0.8,
+                reason: 'laravel-route',
+            });
+            continue;
+        }
+        const relId = generateId('CALLS', `${sourceId}:route->${methodId}`);
+        graph.addRelationship({
+            id: relId,
+            sourceId,
+            targetId: methodId,
+            type: 'CALLS',
+            confidence,
+            reason: 'laravel-route',
+        });
+    }
+    onProgress?.(extractedRoutes.length, extractedRoutes.length);
+};
+// ── DI Awareness: DEPENDS_ON + PROVIDES edge creation ───────────────────
+/** Symbol types that represent injectable dependencies */
+const INJECTABLE_TYPES = new Set(['Class', 'Interface', 'Trait', 'Struct']);
+/** Method names that act as constructors across languages */
+const CONSTRUCTOR_METHOD_NAMES = new Set(['__init__', 'initialize', 'constructor']);
+/**
+ * Create DEPENDS_ON edges from constructor parameter types.
+ *
+ * For each Constructor (or constructor-like method like Python __init__),
+ * resolves its parameterTypes and creates DEPENDS_ON edges from the owning
+ * class to each resolved Class/Interface/Trait/Struct parameter type.
+ *
+ * This bridges DI: BookingService(IPaymentGateway) → DEPENDS_ON → IPaymentGateway
+ */
+export const createDependsOnEdges = async (graph, ctx) => {
+    let edgesCreated = 0;
+    const seen = new Set(); // deduplicate: "ownerClassId->targetId"
+    // Collect Constructor nodes + constructor-like methods (__init__, initialize)
+    const candidates = [];
+    graph.forEachNode(n => {
+        if (n.label === 'Constructor') {
+            candidates.push({ nodeId: n.id, filePath: n.properties.filePath, name: n.properties.name });
+        }
+        else if ((n.label === 'Method' || n.label === 'Function') && CONSTRUCTOR_METHOD_NAMES.has(n.properties.name)) {
+            candidates.push({ nodeId: n.id, filePath: n.properties.filePath, name: n.properties.name });
+        }
+    });
+    for (const ctor of candidates) {
+        const symDef = ctx.symbols.lookupExactFull(ctor.filePath, ctor.name);
+        if (!symDef?.parameterTypes?.length || !symDef.ownerId)
+            continue;
+        for (const paramType of symDef.parameterTypes) {
+            const resolved = ctx.resolve(paramType, ctor.filePath);
+            if (!resolved || resolved.candidates.length === 0)
+                continue;
+            // Find first injectable candidate
+            const target = resolved.candidates.find(c => INJECTABLE_TYPES.has(c.type));
+            if (!target)
+                continue;
+            // Skip self-referential edges
+            if (target.nodeId === symDef.ownerId)
+                continue;
+            const edgeKey = `${symDef.ownerId}->${target.nodeId}`;
+            if (seen.has(edgeKey))
+                continue;
+            seen.add(edgeKey);
+            graph.addRelationship({
+                id: generateId('DEPENDS_ON', edgeKey),
+                sourceId: symDef.ownerId,
+                targetId: target.nodeId,
+                type: 'DEPENDS_ON',
+                confidence: TIER_CONFIDENCE[resolved.tier],
+                reason: 'constructor-injection',
+            });
+            edgesCreated++;
+        }
+    }
+    return edgesCreated;
+};
+/**
+ * Create PROVIDES edges from factory method return types.
+ *
+ * For methods/functions whose return type resolves to an Interface or Trait,
+ * creates a PROVIDES edge from the method to the interface. Heuristic filter:
+ * only short methods (< 20 lines) OR methods with DI-related framework annotations.
+ *
+ * This captures @Bean factories, provider methods, and factory functions.
+ */
+export const createProvidesEdges = async (graph, ctx) => {
+    const PROVIDER_TYPES = new Set(['Interface', 'Trait']);
+    let edgesCreated = 0;
+    const candidates = [];
+    graph.forEachNode(n => {
+        if ((n.label === 'Method' || n.label === 'Function') && n.properties.returnType) {
+            candidates.push({
+                id: n.id,
+                filePath: n.properties.filePath,
+                returnType: n.properties.returnType,
+                startLine: n.properties.startLine ?? 0,
+                endLine: n.properties.endLine ?? 0,
+                frameworkReason: n.properties.astFrameworkReason,
+            });
+        }
+    });
+    for (const node of candidates) {
+        const returnTypeName = extractReturnTypeName(node.returnType);
+        if (!returnTypeName)
+            continue;
+        const resolved = ctx.resolve(returnTypeName, node.filePath);
+        if (!resolved || resolved.candidates.length === 0)
+            continue;
+        const interfaceTarget = resolved.candidates.find(c => PROVIDER_TYPES.has(c.type));
+        if (!interfaceTarget)
+            continue;
+        // Heuristic: only short methods (likely factories) or DI-annotated methods
+        const bodyLength = node.endLine - node.startLine;
+        const isDIAnnotated = node.frameworkReason && (node.frameworkReason.includes('bean') ||
+            node.frameworkReason.includes('provider') ||
+            node.frameworkReason.includes('provides') ||
+            node.frameworkReason.includes('di'));
+        if (bodyLength > 20 && !isDIAnnotated)
+            continue;
+        graph.addRelationship({
+            id: generateId('PROVIDES', `${node.id}->${interfaceTarget.nodeId}`),
+            sourceId: node.id,
+            targetId: interfaceTarget.nodeId,
+            type: 'PROVIDES',
+            confidence: TIER_CONFIDENCE[resolved.tier] * 0.9,
+            reason: 'factory-return-type',
+        });
+        edgesCreated++;
+    }
+    return edgesCreated;
+};