gitnexus 1.4.7 → 1.4.9

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

@@ -1,13 +1,142 @@
 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 { getProvider } from './languages/index.js';
 import { generateId } from '../../lib/utils.js';
-import { getLanguageFromFilename, isVerboseIngestionEnabled, yieldToEventLoop, FUNCTION_NODE_TYPES, extractFunctionName, isBuiltInOrNoise, countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, findEnclosingClassId, extractMixedChain, } from './utils.js';
-import { buildTypeEnv } from './type-env.js';
+import { getLanguageFromFilename } from './utils/language-detection.js';
+import { isVerboseIngestionEnabled } from './utils/verbose.js';
+import { yieldToEventLoop } from './utils/event-loop.js';
+import { FUNCTION_NODE_TYPES, extractFunctionName, findEnclosingClassId } from './utils/ast-helpers.js';
+import { countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, extractMixedChain, } from './utils/call-analysis.js';
+import { buildTypeEnv, isSubclassOf } from './type-env.js';
 import { getTreeSitterBufferSize } from './constants.js';
-import { callRouters } from './call-routing.js';
+import { normalizeFetchURL, routeMatches } from './route-extractors/nextjs.js';
 import { extractReturnTypeName, stripNullable } from './type-extractors/shared.js';
+const MAX_EXPORTS_PER_FILE = 500;
+const MAX_TYPE_NAME_LENGTH = 256;
+/** Build a map of imported callee names → return types for cross-file call-result binding.
+ *  Consulted ONLY when SymbolTable has no unambiguous local match (local-first principle). */
+export function buildImportedReturnTypes(filePath, namedImportMap, symbolTable) {
+    const result = new Map();
+    const fileImports = namedImportMap.get(filePath);
+    if (!fileImports)
+        return result;
+    for (const [localName, binding] of fileImports) {
+        const def = symbolTable.lookupExactFull(binding.sourcePath, binding.exportedName);
+        if (!def?.returnType)
+            continue;
+        const simpleReturn = extractReturnTypeName(def.returnType);
+        if (simpleReturn)
+            result.set(localName, simpleReturn);
+    }
+    return result;
+}
+/** Build cross-file RAW return types for imported callables.
+ *  Unlike buildImportedReturnTypes (which stores extractReturnTypeName output),
+ *  this stores the raw declared return type string (e.g., 'User[]', 'List<User>').
+ *  Used by lookupRawReturnType for for-loop element extraction via extractElementTypeFromString. */
+export function buildImportedRawReturnTypes(filePath, namedImportMap, symbolTable) {
+    const result = new Map();
+    const fileImports = namedImportMap.get(filePath);
+    if (!fileImports)
+        return result;
+    for (const [localName, binding] of fileImports) {
+        const def = symbolTable.lookupExactFull(binding.sourcePath, binding.exportedName);
+        if (!def?.returnType)
+            continue;
+        result.set(localName, def.returnType);
+    }
+    return result;
+}
+/** Collect resolved type bindings for exported file-scope symbols.
+ *  Uses graph node isExported flag — does NOT require isExported on SymbolDefinition. */
+function collectExportedBindings(typeEnv, filePath, symbolTable, graph) {
+    const fileScope = typeEnv.fileScope();
+    if (!fileScope || fileScope.size === 0)
+        return null;
+    const exported = new Map();
+    for (const [varName, typeName] of fileScope) {
+        if (exported.size >= MAX_EXPORTS_PER_FILE)
+            break;
+        if (!typeName || typeName.length > MAX_TYPE_NAME_LENGTH)
+            continue;
+        const nodeId = symbolTable.lookupExact(filePath, varName);
+        if (!nodeId)
+            continue;
+        const node = graph.getNode(nodeId);
+        if (node?.properties?.isExported) {
+            exported.set(varName, typeName);
+        }
+    }
+    return exported.size > 0 ? exported : null;
+}
+/** Build ExportedTypeMap from graph nodes — used for worker path where TypeEnv
+ *  is not available in the main thread. Collects returnType/declaredType from
+ *  exported symbols that have callables with known return types. */
+export function buildExportedTypeMapFromGraph(graph, symbolTable) {
+    const result = new Map();
+    graph.forEachNode(node => {
+        if (!node.properties?.isExported)
+            return;
+        if (!node.properties?.filePath || !node.properties?.name)
+            return;
+        const filePath = node.properties.filePath;
+        const name = node.properties.name;
+        if (!name || name.length > MAX_TYPE_NAME_LENGTH)
+            return;
+        // For callable symbols, use returnType; for properties/variables, use declaredType
+        const def = symbolTable.lookupExactFull(filePath, name);
+        if (!def)
+            return;
+        const typeName = def.returnType ?? def.declaredType;
+        if (!typeName || typeName.length > MAX_TYPE_NAME_LENGTH)
+            return;
+        // Extract simple type name (strip Promise<>, etc.) — reuse shared utility
+        const simpleType = extractReturnTypeName(typeName) ?? typeName;
+        if (!simpleType)
+            return;
+        let fileExports = result.get(filePath);
+        if (!fileExports) {
+            fileExports = new Map();
+            result.set(filePath, fileExports);
+        }
+        if (fileExports.size < MAX_EXPORTS_PER_FILE) {
+            fileExports.set(name, simpleType);
+        }
+    });
+    return result;
+}
+/** Seed cross-file receiver types into pre-extracted call records.
+ *  Fills missing receiverTypeName for single-hop imported variables
+ *  using ExportedTypeMap + namedImportMap — zero disk I/O, zero AST re-parsing.
+ *  Mutates calls in-place. Runs BEFORE processCallsFromExtracted. */
+export function seedCrossFileReceiverTypes(calls, namedImportMap, exportedTypeMap) {
+    if (namedImportMap.size === 0 || exportedTypeMap.size === 0) {
+        return { enrichedCount: 0 };
+    }
+    let enrichedCount = 0;
+    for (const call of calls) {
+        if (call.receiverTypeName || !call.receiverName)
+            continue;
+        if (call.callForm !== 'member')
+            continue;
+        const fileImports = namedImportMap.get(call.filePath);
+        if (!fileImports)
+            continue;
+        const binding = fileImports.get(call.receiverName);
+        if (!binding)
+            continue;
+        const upstream = exportedTypeMap.get(binding.sourcePath);
+        if (!upstream)
+            continue;
+        const type = upstream.get(binding.exportedName);
+        if (type) {
+            call.receiverTypeName = type;
+            enrichedCount++;
+        }
+    }
+    return { enrichedCount };
+}
 // Stdlib methods that preserve the receiver's type identity. When TypeEnv already
 // strips nullable wrappers (Option<User> → User), these chain steps are no-ops
 // for type resolution — the current type passes through unchanged.
@@ -21,7 +150,7 @@ const TYPE_PRESERVING_METHODS = new Set([
  * Walk up the AST from a node to find the enclosing function/method.
  * Returns null if the call is at module/file level (top-level code).
  */
-const findEnclosingFunction = (node, filePath, ctx) => {
+const findEnclosingFunction = (node, filePath, ctx, provider) => {
     let current = node.parent;
     while (current) {
         if (FUNCTION_NODE_TYPES.has(current.type)) {
@@ -31,7 +160,33 @@ const findEnclosingFunction = (node, filePath, ctx) => {
                 if (resolved?.tier === 'same-file' && resolved.candidates.length > 0) {
                     return resolved.candidates[0].nodeId;
                 }
-                return generateId(label, `${filePath}:${funcName}`);
+                // Apply labelOverride so label matches the definition phase (single source of truth).
+                let finalLabel = label;
+                if (provider.labelOverride) {
+                    const override = provider.labelOverride(current, label);
+                    if (override !== null)
+                        finalLabel = override;
+                }
+                return generateId(finalLabel, `${filePath}:${funcName}`);
+            }
+        }
+        // Language-specific enclosing function resolution (e.g., Dart where
+        // function_body is a sibling of function_signature, not a child).
+        if (provider.enclosingFunctionFinder) {
+            const customResult = provider.enclosingFunctionFinder(current);
+            if (customResult) {
+                // Try SymbolTable first (same pattern as the FUNCTION_NODE_TYPES branch above).
+                const resolved = ctx.resolve(customResult.funcName, filePath);
+                if (resolved?.tier === 'same-file' && resolved.candidates.length > 0) {
+                    return resolved.candidates[0].nodeId;
+                }
+                let finalLabel = customResult.label;
+                if (provider.labelOverride) {
+                    const override = provider.labelOverride(current.previousSibling, finalLabel);
+                    if (override !== null)
+                        finalLabel = override;
+                }
+                return generateId(finalLabel, `${filePath}:${customResult.funcName}`);
             }
         }
         current = current.parent;
@@ -87,10 +242,23 @@ const verifyConstructorBindings = (bindings, filePath, ctx, graph) => {
     }
     return verified;
 };
-export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
+export const processCalls = async (graph, files, astCache, ctx, onProgress, exportedTypeMap, 
+/** Phase 14: pre-resolved cross-file bindings to seed into buildTypeEnv. Keyed by filePath → Map<localName, typeName>. */
+importedBindingsMap, 
+/** Phase 14 E3: cross-file return types for imported callables. Keyed by filePath → Map<calleeName, returnType>.
+ *  Consulted ONLY when SymbolTable has no unambiguous match (local-first principle). */
+importedReturnTypesMap, 
+/** Phase 14 E3: cross-file RAW return types for for-loop element extraction. Keyed by filePath → Map<calleeName, rawReturnType>. */
+importedRawReturnTypesMap) => {
     const parser = await loadParser();
     const collectedHeritage = [];
     const pendingWrites = [];
+    // Phase P cross-file: accumulate heritage across files for cross-file isSubclassOf.
+    // Used as a secondary check when per-file parentMap lacks the relationship — helps
+    // when the heritage-declaring file is processed before the call site file.
+    // For remaining cases (reverse file order), the SymbolTable class-type fallback applies.
+    const globalParentMap = new Map();
+    const globalParentSeen = new Map();
     const logSkipped = isVerboseIngestionEnabled();
     const skippedByLang = logSkipped ? new Map() : null;
     for (let i = 0; i < files.length; i++) {
@@ -107,7 +275,8 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
             }
             continue;
         }
-        const queryStr = LANGUAGE_QUERIES[language];
+        const provider = getProvider(language);
+        const queryStr = provider.treeSitterQueries;
         if (!queryStr)
             continue;
         await loadLanguage(language, file.path);
@@ -132,14 +301,65 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
             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
+        // Pre-pass: extract heritage from query matches to build parentMap for buildTypeEnv.
+        // Heritage-processor runs in PARALLEL, so graph edges don't exist when buildTypeEnv runs.
+        const fileParentMap = new Map();
+        for (const match of matches) {
+            const captureMap = {};
+            match.captures.forEach(c => captureMap[c.name] = c.node);
+            if (captureMap['heritage.class'] && captureMap['heritage.extends']) {
+                const className = captureMap['heritage.class'].text;
+                const parentName = captureMap['heritage.extends'].text;
+                const extendsNode = captureMap['heritage.extends'];
+                const fieldDecl = extendsNode.parent;
+                if (fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name'))
+                    continue;
+                let parents = fileParentMap.get(className);
+                if (!parents) {
+                    parents = [];
+                    fileParentMap.set(className, parents);
+                }
+                if (!parents.includes(parentName))
+                    parents.push(parentName);
+            }
+        }
+        const parentMap = fileParentMap;
+        // Merge per-file heritage into globalParentMap for cross-file isSubclassOf lookups.
+        // Uses a parallel Set (globalParentSeen) for O(1) deduplication instead of O(n) includes().
+        for (const [cls, parents] of fileParentMap) {
+            let global = globalParentMap.get(cls);
+            let seen = globalParentSeen.get(cls);
+            if (!global) {
+                global = [];
+                globalParentMap.set(cls, global);
+            }
+            if (!seen) {
+                seen = new Set();
+                globalParentSeen.set(cls, seen);
+            }
+            for (const p of parents) {
+                if (!seen.has(p)) {
+                    seen.add(p);
+                    global.push(p);
+                }
+            }
+        }
+        const importedBindings = importedBindingsMap?.get(file.path);
+        const importedReturnTypes = importedReturnTypesMap?.get(file.path);
+        const importedRawReturnTypes = importedRawReturnTypesMap?.get(file.path);
+        const typeEnv = buildTypeEnv(tree, language, { symbolTable: ctx.symbols, parentMap, importedBindings, importedReturnTypes, importedRawReturnTypes, enclosingFunctionFinder: provider?.enclosingFunctionFinder });
+        if (typeEnv && exportedTypeMap) {
+            const fileExports = collectExportedBindings(typeEnv, file.path, ctx.symbols, graph);
+            if (fileExports)
+                exportedTypeMap.set(file.path, fileExports);
+        }
+        const callRouter = provider.callRouter;
+        const verifiedReceivers = typeEnv.constructorBindings.length > 0
             ? verifyConstructorBindings(typeEnv.constructorBindings, file.path, ctx)
             : new Map();
         const receiverIndex = buildReceiverTypeIndex(verifiedReceivers);
         ctx.enableCache(file.path);
+        const widenCache = new Map();
         matches.forEach(match => {
             const captureMap = {};
             match.captures.forEach(c => captureMap[c.name] = c.node);
@@ -155,7 +375,7 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
                 }
                 // Fall back to verified constructor bindings (mirrors CALLS resolution tier 2)
                 if (!receiverTypeName && receiverText && receiverIndex.size > 0) {
-                    const enclosing = findEnclosingFunction(captureMap['assignment'], file.path, ctx);
+                    const enclosing = findEnclosingFunction(captureMap['assignment'], file.path, ctx, provider);
                     const funcName = enclosing ? extractFuncNameFromSourceId(enclosing) : '';
                     receiverTypeName = lookupReceiverType(receiverIndex, funcName, receiverText);
                 }
@@ -167,7 +387,7 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
                     }
                 }
                 if (receiverTypeName) {
-                    const enclosing = findEnclosingFunction(captureMap['assignment'], file.path, ctx);
+                    const enclosing = findEnclosingFunction(captureMap['assignment'], file.path, ctx, provider);
                     const srcId = enclosing || generateId('File', file.path);
                     // Defer resolution: Ruby attr_accessor properties are registered during
                     // this same loop, so cross-file lookups fail if the declaring file hasn't
@@ -185,7 +405,7 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
             if (!nameNode)
                 return;
             const calledName = nameNode.text;
-            const routed = callRouter(calledName, captureMap['call']);
+            const routed = callRouter?.(calledName, captureMap['call']);
             if (routed) {
                 switch (routed.kind) {
                     case 'skip':
@@ -239,15 +459,53 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
                         break;
                 }
             }
-            if (isBuiltInOrNoise(calledName))
+            if (provider.isBuiltInName(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;
+            // Phase P: virtual dispatch override — when the declared type is a base class but
+            // the constructor created a known subclass, prefer the more specific type.
+            // Checks per-file parentMap first, then falls back to globalParentMap for
+            // cross-file heritage (e.g. Dog extends Animal declared in a different file).
+            // Reconstructs the exact scope key (funcName@startIndex\0varName) from the
+            // enclosing function AST node for a correct, O(1) map lookup.
+            if (receiverTypeName && receiverName && typeEnv && typeEnv.constructorTypeMap.size > 0) {
+                // Reconstruct scope key to match constructorTypeMap's scope\0varName format
+                let scope = '';
+                let p = callNode.parent;
+                while (p) {
+                    if (FUNCTION_NODE_TYPES.has(p.type)) {
+                        const { funcName } = extractFunctionName(p);
+                        if (funcName) {
+                            scope = `${funcName}@${p.startIndex}`;
+                            break;
+                        }
+                    }
+                    p = p.parent;
+                }
+                const ctorType = typeEnv.constructorTypeMap.get(`${scope}\0${receiverName}`);
+                if (ctorType && ctorType !== receiverTypeName) {
+                    // Verify subclass relationship: per-file parentMap first, then cross-file
+                    // globalParentMap, then fall back to SymbolTable class verification.
+                    // The SymbolTable fallback handles cross-file cases where heritage is declared
+                    // in a file not yet processed (e.g. Dog extends Animal in models/Dog.kt when
+                    // processing services/App.kt). Since constructorTypeMap only records entries
+                    // when a type annotation AND constructor are both present (val x: Base = Sub()),
+                    // confirming both are class-like types is sufficient — the original code would
+                    // not compile if Sub didn't extend Base.
+                    if (isSubclassOf(ctorType, receiverTypeName, parentMap)
+                        || isSubclassOf(ctorType, receiverTypeName, globalParentMap)
+                        || (ctx.symbols.lookupFuzzy(ctorType).some(d => d.type === 'Class' || d.type === 'Struct')
+                            && ctx.symbols.lookupFuzzy(receiverTypeName).some(d => d.type === 'Class' || d.type === 'Struct' || d.type === 'Interface'))) {
+                        receiverTypeName = ctorType;
+                    }
+                }
+            }
             // Fall back to verified constructor bindings for return type inference
             if (!receiverTypeName && receiverName && receiverIndex.size > 0) {
-                const enclosingFunc = findEnclosingFunction(callNode, file.path, ctx);
+                const enclosingFunc = findEnclosingFunction(callNode, file.path, ctx, provider);
                 const funcName = enclosingFunc ? extractFuncNameFromSourceId(enclosingFunc) : '';
                 receiverTypeName = lookupReceiverType(receiverIndex, funcName, receiverName);
             }
@@ -261,7 +519,7 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
                 }
             }
             // Hoist sourceId so it's available for ACCESSES edge emission during chain walk.
-            const enclosingFuncId = findEnclosingFunction(callNode, file.path, ctx);
+            const enclosingFuncId = findEnclosingFunction(callNode, file.path, ctx, provider);
             const sourceId = enclosingFuncId || generateId('File', file.path);
             // Fall back to mixed chain resolution when the receiver is a complex expression
             // (field chain, call chain, or interleaved — e.g. user.address.city.save() or
@@ -290,12 +548,19 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
                     }
                 }
             }
+            // Build overload hints for languages with inferLiteralType (Java/Kotlin/C#/C++).
+            // Only used when multiple candidates survive arity filtering — ~1-3% of calls.
+            const langConfig = provider.typeConfig;
+            const hints = langConfig?.inferLiteralType
+                ? { callNode, inferLiteralType: langConfig.inferLiteralType }
+                : undefined;
             const resolved = resolveCallTarget({
                 calledName,
                 argCount: countCallArguments(callNode),
                 callForm,
                 receiverTypeName,
-            }, file.path, ctx);
+                receiverName,
+            }, file.path, ctx, hints, widenCache);
             if (!resolved)
                 return;
             const relId = generateId('CALLS', `${sourceId}:${calledName}->${resolved.nodeId}`);
@@ -362,7 +627,9 @@ const filterCallableCandidates = (candidates, argCount, callForm) => {
     const hasParameterMetadata = kindFiltered.some(candidate => candidate.parameterCount !== undefined);
     if (!hasParameterMetadata)
         return kindFiltered;
-    return kindFiltered.filter(candidate => candidate.parameterCount === undefined || candidate.parameterCount === argCount);
+    return kindFiltered.filter(candidate => candidate.parameterCount === undefined
+        || (argCount >= (candidate.requiredParameterCount ?? candidate.parameterCount)
+            && argCount <= candidate.parameterCount));
 };
 const toResolveResult = (definition, tier) => ({
     nodeId: definition.nodeId,
@@ -371,19 +638,145 @@ const toResolveResult = (definition, tier) => ({
     returnType: definition.returnType,
 });
 /**
- * Resolve a function call to its target node ID using priority strategy:
- * A. Narrow candidates by scope tier via ctx.resolve()
- * B. Filter to callable symbol kinds (constructor-aware when callForm is set)
- * C. Apply arity filtering when parameter metadata is available
- * D. Apply receiver-type filtering for member calls with typed receivers
+ * Kotlin (and JVM in general) uses boxed type names in parameter declarations
+ * (e.g. `Int`, `Long`, `Boolean`) while inferJvmLiteralType returns unboxed
+ * primitives (`int`, `long`, `boolean`). Normalise both sides to lowercase so
+ * that the comparison `'Int' === 'int'` does not fail.
  *
- * If filtering still leaves multiple candidates, refuse to emit a CALLS edge.
+ * Only applied to single-word identifiers that look like a JVM primitive alias;
+ * multi-word or qualified names are left untouched.
  */
-const resolveCallTarget = (call, currentFile, ctx) => {
+const KOTLIN_BOXED_TO_PRIMITIVE = {
+    Int: 'int',
+    Long: 'long',
+    Short: 'short',
+    Byte: 'byte',
+    Float: 'float',
+    Double: 'double',
+    Boolean: 'boolean',
+    Char: 'char',
+};
+const normalizeJvmTypeName = (name) => KOTLIN_BOXED_TO_PRIMITIVE[name] ?? name;
+/**
+ * Try to disambiguate overloaded candidates using argument literal types.
+ * Only invoked when filteredCandidates.length > 1 and at least one has parameterTypes.
+ * Returns the single matching candidate, or null if ambiguous/inconclusive.
+ */
+const tryOverloadDisambiguation = (candidates, hints) => {
+    if (!candidates.some(c => c.parameterTypes))
+        return null;
+    // Find the argument list node in the call expression.
+    // Kotlin wraps value_arguments inside a call_suffix child, so we must also
+    // search one level deeper when a direct match is not found.
+    let argList = hints.callNode.childForFieldName?.('arguments')
+        ?? hints.callNode.children.find((c) => c.type === 'arguments' || c.type === 'argument_list' || c.type === 'value_arguments');
+    if (!argList) {
+        // Kotlin: call_expression → call_suffix → value_arguments
+        const callSuffix = hints.callNode.children.find((c) => c.type === 'call_suffix');
+        if (callSuffix) {
+            argList = callSuffix.children.find((c) => c.type === 'value_arguments');
+        }
+    }
+    if (!argList)
+        return null;
+    const argTypes = [];
+    for (const arg of argList.namedChildren) {
+        if (arg.type === 'comment')
+            continue;
+        // Unwrap argument wrapper nodes before passing to inferLiteralType:
+        //   - Kotlin value_argument: has 'value' field containing the literal
+        //   - C# argument: has 'expression' field (handles named args like `name: "alice"`
+        //     where firstNamedChild would return name_colon instead of the value)
+        //   - Java/others: arg IS the literal directly (no unwrapping needed)
+        const valueNode = arg.childForFieldName?.('value')
+            ?? arg.childForFieldName?.('expression')
+            ?? (arg.type === 'argument' || arg.type === 'value_argument'
+                ? arg.firstNamedChild ?? arg
+                : arg);
+        argTypes.push(hints.inferLiteralType(valueNode));
+    }
+    // If no literal types could be inferred, can't disambiguate
+    if (argTypes.every(t => t === undefined))
+        return null;
+    const matched = candidates.filter(c => {
+        // Keep candidates without type info — conservative: partially-annotated codebases
+        // (e.g. C++ with some missing declarations) may have mixed typed/untyped overloads.
+        // If one typed and one untyped both survive, matched.length > 1 → returns null (no edge).
+        if (!c.parameterTypes)
+            return true;
+        return c.parameterTypes.every((pType, i) => {
+            if (i >= argTypes.length || !argTypes[i])
+                return true;
+            // Normalise Kotlin boxed type names (Int→int, Boolean→boolean, etc.) so
+            // that the stored declaration type matches the inferred literal type.
+            return normalizeJvmTypeName(pType) === argTypes[i];
+        });
+    });
+    if (matched.length === 1)
+        return matched[0];
+    // Multiple survivors may share the same nodeId (e.g. TypeScript overload signatures +
+    // implementation body all collide via generateId). Deduplicate by nodeId — if all
+    // matched candidates resolve to the same graph node, disambiguation succeeded.
+    if (matched.length > 1) {
+        const uniqueIds = new Set(matched.map(c => c.nodeId));
+        if (uniqueIds.size === 1)
+            return matched[0];
+    }
+    return null;
+};
+const resolveCallTarget = (call, currentFile, ctx, overloadHints, widenCache) => {
     const tiered = ctx.resolve(call.calledName, currentFile);
     if (!tiered)
         return null;
-    const filteredCandidates = filterCallableCandidates(tiered.candidates, call.argCount, call.callForm);
+    let filteredCandidates = filterCallableCandidates(tiered.candidates, call.argCount, call.callForm);
+    // Swift/Kotlin: constructor calls look like free function calls (no `new` keyword).
+    // If free-form filtering found no callable candidates but the symbol resolves to a
+    // Class/Struct, retry with constructor form so CONSTRUCTOR_TARGET_TYPES applies.
+    if (filteredCandidates.length === 0 && call.callForm === 'free') {
+        const hasTypeTarget = tiered.candidates.some(c => c.type === 'Class' || c.type === 'Struct' || c.type === 'Enum');
+        if (hasTypeTarget) {
+            filteredCandidates = filterCallableCandidates(tiered.candidates, call.argCount, 'constructor');
+        }
+    }
+    // Module-qualified constructor pattern: e.g. Python `import models; models.User()`.
+    // The attribute access gives callForm='member', but the callee may be a Class — a valid
+    // constructor target. Re-try with constructor-form filtering so that `module.ClassName()`
+    // emits a CALLS edge to the class node.
+    if (filteredCandidates.length === 0 && call.callForm === 'member') {
+        filteredCandidates = filterCallableCandidates(tiered.candidates, call.argCount, 'constructor');
+    }
+    // Module-alias disambiguation: Python `import auth; auth.User()` — receiverName='auth'
+    // selects auth.py via moduleAliasMap. Runs for ALL member calls with a known module alias,
+    // not just ambiguous ones — same-file tier may shadow the correct cross-module target when
+    // the caller defines a function with the same name as the callee (Issue #417).
+    if (call.callForm === 'member' && call.receiverName) {
+        const aliasMap = ctx.moduleAliasMap?.get(currentFile);
+        if (aliasMap) {
+            const moduleFile = aliasMap.get(call.receiverName);
+            if (moduleFile) {
+                const aliasFiltered = filteredCandidates.filter(c => c.filePath === moduleFile);
+                if (aliasFiltered.length > 0) {
+                    filteredCandidates = aliasFiltered;
+                }
+                else {
+                    // Same-file tier returned a local match, but the alias points elsewhere.
+                    // Widen to global candidates and filter to the aliased module's file.
+                    // Use per-file widenCache to avoid repeated lookupFuzzy for the same
+                    // calledName+moduleFile from multiple call sites in the same file.
+                    const cacheKey = `${call.calledName}\0${moduleFile}`;
+                    let fuzzyDefs = widenCache?.get(cacheKey);
+                    if (!fuzzyDefs) {
+                        fuzzyDefs = ctx.symbols.lookupFuzzy(call.calledName);
+                        widenCache?.set(cacheKey, fuzzyDefs);
+                    }
+                    const widened = filterCallableCandidates(fuzzyDefs, call.argCount, call.callForm)
+                        .filter(c => c.filePath === moduleFile);
+                    if (widened.length > 0)
+                        filteredCandidates = widened;
+                }
+            }
+        }
+    }
     // D. Receiver-type filtering: for member calls with a known receiver type,
     // resolve the type through the same tiered import infrastructure, then
     // filter method candidates to the type's defining file. Fall back to
@@ -415,12 +808,39 @@ const resolveCallTarget = (call, currentFile, ctx) => {
             if (ownerFiltered.length === 1) {
                 return toResolveResult(ownerFiltered[0], tiered.tier);
             }
+            // E. Try overload disambiguation on the narrowed pool
+            if ((fileFiltered.length > 1 || ownerFiltered.length > 1) && overloadHints) {
+                const overloadPool = ownerFiltered.length > 1 ? ownerFiltered : fileFiltered;
+                const disambiguated = tryOverloadDisambiguation(overloadPool, overloadHints);
+                if (disambiguated)
+                    return toResolveResult(disambiguated, tiered.tier);
+            }
             if (fileFiltered.length > 1 || ownerFiltered.length > 1)
                 return null;
         }
     }
-    if (filteredCandidates.length !== 1)
+    // E. Overload disambiguation: when multiple candidates survive arity + receiver filtering,
+    // try matching argument literal types against parameter types (Phase P).
+    // Only available on sequential path (has AST); worker path falls through gracefully.
+    if (filteredCandidates.length > 1 && overloadHints) {
+        const disambiguated = tryOverloadDisambiguation(filteredCandidates, overloadHints);
+        if (disambiguated)
+            return toResolveResult(disambiguated, tiered.tier);
+    }
+    if (filteredCandidates.length !== 1) {
+        // Deduplicate: Swift extensions create multiple Class nodes with the same name.
+        // When all candidates share the same type and differ only by file (extension vs
+        // primary definition), they represent the same symbol. Prefer the primary
+        // definition (shortest file path: Product.swift over ProductExtension.swift).
+        if (filteredCandidates.length > 1) {
+            const allSameType = filteredCandidates.every(c => c.type === filteredCandidates[0].type);
+            if (allSameType && (filteredCandidates[0].type === 'Class' || filteredCandidates[0].type === 'Struct')) {
+                const sorted = [...filteredCandidates].sort((a, b) => a.filePath.length - b.filePath.length);
+                return toResolveResult(sorted[0], tiered.tier);
+            }
+        }
         return null;
+    }
     return toResolveResult(filteredCandidates[0], tiered.tier);
 };
 // ── Scope key helpers ────────────────────────────────────────────────────
@@ -636,6 +1056,7 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
             await yieldToEventLoop();
         }
         ctx.enableCache(filePath);
+        const widenCache = new Map();
         const receiverMap = fileReceiverTypes.get(filePath);
         for (const call of calls) {
             let effectiveCall = call;
@@ -677,7 +1098,7 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
                     }
                 }
             }
-            const resolved = resolveCallTarget(effectiveCall, effectiveCall.filePath, ctx);
+            const resolved = resolveCallTarget(effectiveCall, effectiveCall.filePath, ctx, undefined, widenCache);
             if (!resolved)
                 continue;
             const relId = generateId('CALLS', `${effectiveCall.sourceId}:${effectiveCall.calledName}->${resolved.nodeId}`);
@@ -791,3 +1212,202 @@ export const processRoutesFromExtracted = async (graph, extractedRoutes, ctx, on
     }
     onProgress?.(extractedRoutes.length, extractedRoutes.length);
 };
+/**
+ * Extract property access keys from a consumer file's source code near fetch calls.
+ *
+ * Looks for three patterns after a fetch/response variable assignment:
+ * 1. Destructuring: `const { data, pagination } = await res.json()`
+ * 2. Property access: `response.data`, `result.items`
+ * 3. Optional chaining: `data?.key1?.key2`
+ *
+ * Returns deduplicated top-level property names accessed on the response.
+ *
+ * NOTE: This scans the entire file content, not just code near a specific fetch call.
+ * If a file has multiple fetch calls to different routes, all accessed keys are
+ * attributed to each fetch. This is an acceptable tradeoff for regex-based extraction.
+ */
+/** Common method names on response/data objects that are NOT property accesses */
+// Properties/methods to ignore when extracting consumer accessed keys from `data.X` patterns.
+// Avoids false positives from Fetch API, Array, Object, Promise, and DOM access on variables
+// that happen to share names with response variables (data, result, response, etc.).
+const RESPONSE_ACCESS_BLOCKLIST = new Set([
+    // Fetch/Response API
+    'json', 'text', 'blob', 'arrayBuffer', 'formData', 'ok', 'status', 'headers', 'clone',
+    // Promise
+    'then', 'catch', 'finally',
+    // Array
+    'map', 'filter', 'forEach', 'reduce', 'find', 'some', 'every',
+    'push', 'pop', 'shift', 'unshift', 'splice', 'slice', 'concat', 'join',
+    'sort', 'reverse', 'includes', 'indexOf',
+    // Object
+    'length', 'toString', 'valueOf', 'keys', 'values', 'entries',
+    // DOM methods — file-download patterns often reuse `data`/`response` variable names
+    'appendChild', 'removeChild', 'insertBefore', 'replaceChild', 'replaceChildren',
+    'createElement', 'getElementById', 'querySelector', 'querySelectorAll',
+    'setAttribute', 'getAttribute', 'removeAttribute', 'hasAttribute',
+    'addEventListener', 'removeEventListener', 'dispatchEvent',
+    'classList', 'className',
+    'parentNode', 'parentElement', 'childNodes', 'children',
+    'nextSibling', 'previousSibling', 'firstChild', 'lastChild',
+    'click', 'focus', 'blur', 'submit', 'reset',
+    'innerHTML', 'outerHTML', 'textContent', 'innerText',
+]);
+export const extractConsumerAccessedKeys = (content) => {
+    const keys = new Set();
+    // Pattern 1: Destructuring from .json() — const { key1, key2 } = await res.json()
+    // Also matches: const { key1, key2 } = await (await fetch(...)).json()
+    const destructurePattern = /(?:const|let|var)\s+\{([^}]+)\}\s*=\s*(?:await\s+)?(?:\w+\.json\s*\(\)|(?:await\s+)?(?:fetch|axios|got)\s*\([^)]*\)(?:\.then\s*\([^)]*\))?(?:\.json\s*\(\))?)/g;
+    let match;
+    while ((match = destructurePattern.exec(content)) !== null) {
+        const destructuredBody = match[1];
+        // Extract identifiers from destructuring, handling renamed bindings (key: alias)
+        const keyPattern = /(\w+)\s*(?::\s*\w+)?/g;
+        let keyMatch;
+        while ((keyMatch = keyPattern.exec(destructuredBody)) !== null) {
+            keys.add(keyMatch[1]);
+        }
+    }
+    // Pattern 2: Destructuring from a data/result/response/json variable
+    // e.g., const { items, total } = data; or const { error } = result;
+    const dataVarDestructure = /(?:const|let|var)\s+\{([^}]+)\}\s*=\s*(?:data|result|response|json|body|res)\b/g;
+    while ((match = dataVarDestructure.exec(content)) !== null) {
+        const destructuredBody = match[1];
+        const keyPattern = /(\w+)\s*(?::\s*\w+)?/g;
+        let keyMatch;
+        while ((keyMatch = keyPattern.exec(destructuredBody)) !== null) {
+            keys.add(keyMatch[1]);
+        }
+    }
+    // Pattern 3: Property access on common response variable names
+    // Matches: data.key, response.key, result.key, json.key, body.key
+    // Also matches optional chaining: data?.key
+    const propAccessPattern = /\b(?:data|response|result|json|body|res)\s*(?:\?\.|\.)(\w+)/g;
+    while ((match = propAccessPattern.exec(content)) !== null) {
+        const key = match[1];
+        // Skip common method calls that aren't property accesses
+        if (!RESPONSE_ACCESS_BLOCKLIST.has(key)) {
+            keys.add(key);
+        }
+    }
+    return [...keys];
+};
+/**
+ * Create FETCHES edges from extracted fetch() calls to matching Route nodes.
+ * When consumerContents is provided, extracts property access patterns from
+ * consumer files and encodes them in the edge reason field.
+ */
+export const processNextjsFetchRoutes = (graph, fetchCalls, routeRegistry, // routeURL → handlerFilePath
+consumerContents) => {
+    // Pre-count how many routes each consumer file matches (for confidence attribution)
+    const routeCountByFile = new Map();
+    for (const call of fetchCalls) {
+        const normalized = normalizeFetchURL(call.fetchURL);
+        if (!normalized)
+            continue;
+        for (const [routeURL] of routeRegistry) {
+            if (routeMatches(normalized, routeURL)) {
+                routeCountByFile.set(call.filePath, (routeCountByFile.get(call.filePath) ?? 0) + 1);
+                break;
+            }
+        }
+    }
+    for (const call of fetchCalls) {
+        const normalized = normalizeFetchURL(call.fetchURL);
+        if (!normalized)
+            continue;
+        for (const [routeURL] of routeRegistry) {
+            if (routeMatches(normalized, routeURL)) {
+                const sourceId = generateId('File', call.filePath);
+                const routeNodeId = generateId('Route', routeURL);
+                // Extract consumer accessed keys if file content is available
+                let reason = 'fetch-url-match';
+                if (consumerContents) {
+                    const content = consumerContents.get(call.filePath);
+                    if (content) {
+                        const accessedKeys = extractConsumerAccessedKeys(content);
+                        if (accessedKeys.length > 0) {
+                            reason = `fetch-url-match|keys:${accessedKeys.join(',')}`;
+                        }
+                    }
+                }
+                // Encode multi-fetch count so downstream can set confidence
+                const fetchCount = routeCountByFile.get(call.filePath) ?? 1;
+                if (fetchCount > 1) {
+                    reason = `${reason}|fetches:${fetchCount}`;
+                }
+                graph.addRelationship({
+                    id: generateId('FETCHES', `${sourceId}->${routeNodeId}`),
+                    sourceId,
+                    targetId: routeNodeId,
+                    type: 'FETCHES',
+                    confidence: 0.9,
+                    reason,
+                });
+                break;
+            }
+        }
+    }
+};
+/**
+ * Extract fetch() calls from source files (sequential path).
+ * Workers handle this via tree-sitter captures in parse-worker; this function
+ * provides the same extraction for the sequential fallback path.
+ */
+export const extractFetchCallsFromFiles = async (files, astCache) => {
+    const parser = await loadParser();
+    const result = [];
+    for (const file of files) {
+        const language = getLanguageFromFilename(file.path);
+        if (!language)
+            continue;
+        if (!isLanguageAvailable(language))
+            continue;
+        const provider = getProvider(language);
+        const queryStr = provider.treeSitterQueries;
+        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 {
+                continue;
+            }
+            astCache.set(file.path, tree);
+        }
+        let matches;
+        try {
+            const lang = parser.getLanguage();
+            const query = new Parser.Query(lang, queryStr);
+            matches = query.matches(tree.rootNode);
+        }
+        catch {
+            continue;
+        }
+        for (const match of matches) {
+            const captureMap = {};
+            match.captures.forEach(c => captureMap[c.name] = c.node);
+            if (captureMap['route.fetch']) {
+                const urlNode = captureMap['route.url'] ?? captureMap['route.template_url'];
+                if (urlNode) {
+                    result.push({
+                        filePath: file.path,
+                        fetchURL: urlNode.text,
+                        lineNumber: captureMap['route.fetch'].startPosition.row,
+                    });
+                }
+            }
+            else if (captureMap['http_client'] && captureMap['http_client.url']) {
+                const method = captureMap['http_client.method']?.text;
+                const url = captureMap['http_client.url'].text;
+                const HTTP_CLIENT_ONLY = new Set(['head', 'options', 'request', 'ajax']);
+                if (method && HTTP_CLIENT_ONLY.has(method) && url.startsWith('/')) {
+                    result.push({ filePath: file.path, fetchURL: url, lineNumber: captureMap['http_client'].startPosition.row });
+                }
+            }
+        }
+    }
+    return result;
+};