gitnexus 1.4.6 → 1.4.8

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

@@ -3,11 +3,146 @@ 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 { getLanguageFromFilename, isVerboseIngestionEnabled, yieldToEventLoop, FUNCTION_NODE_TYPES, extractFunctionName, isBuiltInOrNoise, countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, findEnclosingClassId, extractMixedChain, } from './utils.js';
+import { buildTypeEnv, isSubclassOf } from './type-env.js';
 import { getTreeSitterBufferSize } from './constants.js';
 import { callRouters } from './call-routing.js';
-import { extractReturnTypeName } from './type-extractors/shared.js';
+import { extractReturnTypeName, stripNullable } from './type-extractors/shared.js';
+import { typeConfigs } from './type-extractors/index.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.env.get('');
+    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.
+const TYPE_PRESERVING_METHODS = new Set([
+    'unwrap', 'expect', 'unwrap_or', 'unwrap_or_default', 'unwrap_or_else', // Rust Option/Result
+    'clone', 'to_owned', 'as_ref', 'as_mut', 'borrow', 'borrow_mut', // Rust clone/borrow
+    'get', // Kotlin/Java Optional.get()
+    'orElseThrow', // Java Optional
+]);
 /**
  * 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).
@@ -78,9 +213,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++) {
@@ -123,15 +272,103 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
             continue;
         }
         const lang = getLanguageFromFilename(file.path);
-        const typeEnv = lang ? buildTypeEnv(tree, lang, ctx.symbols) : null;
+        // 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 = lang ? buildTypeEnv(tree, lang, { symbolTable: ctx.symbols, parentMap, importedBindings, importedReturnTypes, importedRawReturnTypes }) : null;
+        if (typeEnv && exportedTypeMap) {
+            const fileExports = collectExportedBindings(typeEnv, file.path, ctx.symbols, graph);
+            if (fileExports)
+                exportedTypeMap.set(file.path, fileExports);
+        }
         const callRouter = callRouters[language];
         const verifiedReceivers = typeEnv && typeEnv.constructorBindings.length > 0
             ? verifyConstructorBindings(typeEnv.constructorBindings, file.path, ctx)
             : new Map();
+        const receiverIndex = buildReceiverTypeIndex(verifiedReceivers);
         ctx.enableCache(file.path);
         matches.forEach(match => {
             const captureMap = {};
             match.captures.forEach(c => captureMap[c.name] = c.node);
+            // ── Write access: emit ACCESSES {reason: 'write'} for assignments to member fields ──
+            if (captureMap['assignment'] && captureMap['assignment.receiver'] && captureMap['assignment.property']) {
+                const receiverNode = captureMap['assignment.receiver'];
+                const propertyName = captureMap['assignment.property'].text;
+                // Resolve receiver type: simple identifier → TypeEnv lookup or class resolution
+                let receiverTypeName;
+                const receiverText = receiverNode.text;
+                if (receiverText && typeEnv) {
+                    receiverTypeName = typeEnv.lookup(receiverText, captureMap['assignment']);
+                }
+                // 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 funcName = enclosing ? extractFuncNameFromSourceId(enclosing) : '';
+                    receiverTypeName = lookupReceiverType(receiverIndex, funcName, receiverText);
+                }
+                if (!receiverTypeName && receiverText) {
+                    const resolved = ctx.resolve(receiverText, file.path);
+                    if (resolved?.candidates.some(d => d.type === 'Class' || d.type === 'Struct' || d.type === 'Interface'
+                        || d.type === 'Enum' || d.type === 'Record' || d.type === 'Impl')) {
+                        receiverTypeName = receiverText;
+                    }
+                }
+                if (receiverTypeName) {
+                    const enclosing = findEnclosingFunction(captureMap['assignment'], file.path, ctx);
+                    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
+                    // been processed yet. Collect now, resolve after all files are done.
+                    pendingWrites.push({ receiverTypeName, propertyName, filePath: file.path, srcId });
+                }
+                // Assignment-only capture (no @call sibling): skip the rest of this
+                // forEach iteration — this acts as a `continue` in the match loop.
+                if (!captureMap['call'])
+                    return;
+            }
             if (!captureMap['call'])
                 return;
             const nameNode = captureMap['call.name'];
@@ -169,7 +406,10 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
                                     description: item.accessorType,
                                 },
                             });
-                            ctx.symbols.add(file.path, item.propName, nodeId, 'Property', propEnclosingClassId ? { ownerId: propEnclosingClassId } : undefined);
+                            ctx.symbols.add(file.path, item.propName, nodeId, 'Property', {
+                                ...(propEnclosingClassId ? { ownerId: propEnclosingClassId } : {}),
+                                ...(item.declaredType ? { declaredType: item.declaredType } : {}),
+                            });
                             const relId = generateId('DEFINES', `${fileId}->${nodeId}`);
                             graph.addRelationship({
                                 id: relId, sourceId: fileId, targetId: nodeId,
@@ -177,9 +417,9 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
                             });
                             if (propEnclosingClassId) {
                                 graph.addRelationship({
-                                    id: generateId('HAS_METHOD', `${propEnclosingClassId}->${nodeId}`),
+                                    id: generateId('HAS_PROPERTY', `${propEnclosingClassId}->${nodeId}`),
                                     sourceId: propEnclosingClassId, targetId: nodeId,
-                                    type: 'HAS_METHOD', confidence: 1.0, reason: '',
+                                    type: 'HAS_PROPERTY', confidence: 1.0, reason: '',
                                 });
                             }
                         }
@@ -195,11 +435,49 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
             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 && verifiedReceivers.size > 0) {
+            if (!receiverTypeName && receiverName && receiverIndex.size > 0) {
                 const enclosingFunc = findEnclosingFunction(callNode, file.path, ctx);
                 const funcName = enclosingFunc ? extractFuncNameFromSourceId(enclosingFunc) : '';
-                receiverTypeName = lookupReceiverType(verifiedReceivers, funcName, receiverName);
+                receiverTypeName = lookupReceiverType(receiverIndex, funcName, receiverName);
             }
             // Fall back to class-as-receiver for static method calls (e.g. UserService.find_user()).
             // When the receiver name is not a variable in TypeEnv but resolves to a Class/Struct/Interface
@@ -210,43 +488,51 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
                     receiverTypeName = receiverName;
                 }
             }
-            // Fall back to chained call resolution when the receiver is a call expression
-            // (e.g. svc.getUser().save() — receiver of save() is getUser(), not a simple identifier).
+            // Hoist sourceId so it's available for ACCESSES edge emission during chain walk.
+            const enclosingFuncId = findEnclosingFunction(callNode, file.path, ctx);
+            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
+            // svc.getUser().address.save()). Handles all cases with a single unified walk.
             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 if possible
-                        let baseType = extracted.baseReceiverName && typeEnv
+                if (receiverNode) {
+                    const extracted = extractMixedChain(receiverNode);
+                    if (extracted && extracted.chain.length > 0) {
+                        let currentType = 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);
+                        if (!currentType && extracted.baseReceiverName && receiverIndex.size > 0) {
+                            const funcName = enclosingFuncId ? extractFuncNameFromSourceId(enclosingFuncId) : '';
+                            currentType = lookupReceiverType(receiverIndex, funcName, extracted.baseReceiverName);
                         }
-                        // Class-as-receiver for chain base (e.g. UserService.find_user().save())
-                        if (!baseType && extracted.baseReceiverName) {
+                        if (!currentType && 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;
+                                currentType = extracted.baseReceiverName;
                             }
                         }
-                        receiverTypeName = resolveChainedReceiver(extracted.chain, baseType, file.path, ctx);
+                        if (currentType) {
+                            receiverTypeName = walkMixedChain(extracted.chain, currentType, file.path, ctx, makeAccessEmitter(graph, sourceId));
+                        }
                     }
                 }
             }
+            // 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 = lang ? typeConfigs[lang] : undefined;
+            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);
             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}`);
             graph.addRelationship({
                 id: relId,
@@ -259,6 +545,21 @@ export const processCalls = async (graph, files, astCache, ctx, onProgress) => {
         });
         ctx.clearCache();
     }
+    // ── Resolve deferred write-access edges ──
+    // All properties (including Ruby attr_accessor) are now registered.
+    for (const pw of pendingWrites) {
+        const fieldOwner = resolveFieldOwnership(pw.receiverTypeName, pw.propertyName, pw.filePath, ctx);
+        if (fieldOwner) {
+            graph.addRelationship({
+                id: generateId('ACCESSES', `${pw.srcId}:${fieldOwner.nodeId}:write`),
+                sourceId: pw.srcId,
+                targetId: fieldOwner.nodeId,
+                type: 'ACCESSES',
+                confidence: 1.0,
+                reason: 'write',
+            });
+        }
+    }
     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.`);
@@ -296,58 +597,139 @@ 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,
     confidence: TIER_CONFIDENCE[tier],
     reason: tier === 'same-file' ? 'same-file' : tier === 'import-scoped' ? 'import-resolved' : 'global',
+    returnType: definition.returnType,
 });
 /**
- * Resolve a chain of intermediate method calls to find the receiver type for a
- * final member call.  Called when the receiver of a call is itself a call
- * expression (e.g. `svc.getUser().save()`).
+ * 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.
  *
- * @param chainNames  Ordered list of method names from outermost to innermost
- *                    intermediate call (e.g. ['getUser'] for `svc.getUser().save()`).
- * @param baseReceiverTypeName  The already-resolved type of the base receiver
- *                              (e.g. 'UserService' for `svc`), or undefined.
- * @param currentFile  The file path for resolution context.
- * @param ctx  The resolution context for symbol lookup.
- * @returns The type name of the final intermediate call's return type, or undefined
- *          if resolution fails at any step.
+ * Only applied to single-word identifiers that look like a JVM primitive alias;
+ * multi-word or qualified names are left untouched.
  */
-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;
+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');
+        }
     }
-    return currentType;
-}
+    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;
+};
 /**
  * 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
+ * E. Apply overload disambiguation via argument literal types (when available)
  *
  * If filtering still leaves multiple candidates, refuse to emit a CALLS edge.
  */
-const resolveCallTarget = (call, currentFile, ctx) => {
+const resolveCallTarget = (call, currentFile, ctx, overloadHints) => {
     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);
+    // 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()` — when both models.py and
+    // auth.py export User, receiverName='auth' selects auth.py via moduleAliasMap.
+    // Runs when multiple candidates survive filtering and the receiver is a known module alias.
+    if (filteredCandidates.length > 1 && 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;
+            }
+        }
+    }
     // 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
@@ -379,10 +761,25 @@ 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;
         }
     }
+    // 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)
         return null;
     return toResolveResult(filteredCandidates[0], tiered.tier);
@@ -411,44 +808,159 @@ const extractFuncNameFromSourceId = (sourceId) => {
  */
 const receiverKey = (scope, varName) => `${scope}\0${varName}`;
 /**
- * Look up a receiver type from a verified receiver map.
- * The map is keyed by `scope\0varName` (full scope with @startIndex).
- * Since the lookup side only has `funcName` (no startIndex), we scan for
- * all entries whose key starts with `funcName@` and has the matching varName.
- * If exactly one unique type is found, return it. If multiple distinct types
- * exist (true overload collision), return undefined (refuse to guess).
- * Falls back to the file-level scope key `\0varName` (empty funcName).
+ * Build a two-level secondary index from the verified receiver map.
+ * The verified map is keyed by `scope\0varName` where scope is either
+ * "funcName@startIndex" (inside a function) or "" (file level).
+ * Index structure: Map<funcName, Map<varName, ReceiverTypeEntry>>
  */
-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 the key is exactly "funcName@<digits>\0varName" with no extra chars.
-            // The part between prefix and suffix should be the startIndex (digits only),
-            // but we accept any non-empty segment to be forward-compatible.
-            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;
+const buildReceiverTypeIndex = (map) => {
+    const index = new Map();
+    for (const [key, typeName] of map) {
+        const nul = key.indexOf('\0');
+        if (nul < 0)
+            continue;
+        const scope = key.slice(0, nul);
+        const varName = key.slice(nul + 1);
+        if (!varName)
+            continue;
+        if (scope !== '' && !scope.includes('@'))
+            continue;
+        const funcName = scope === '' ? '' : scope.slice(0, scope.indexOf('@'));
+        let varMap = index.get(funcName);
+        if (!varMap) {
+            varMap = new Map();
+            index.set(funcName, varMap);
+        }
+        const existing = varMap.get(varName);
+        if (existing === undefined) {
+            varMap.set(varName, { kind: 'resolved', value: typeName });
+        }
+        else if (existing.kind === 'resolved' && existing.value !== typeName) {
+            varMap.set(varName, { kind: 'ambiguous' });
+        }
+    }
+    return index;
+};
+/**
+ * O(1) receiver type lookup using the pre-built secondary index.
+ * Returns the unique type name if unambiguous. Falls back to file-level scope.
+ */
+const lookupReceiverType = (index, funcName, varName) => {
+    const funcBucket = index.get(funcName);
+    if (funcBucket) {
+        const entry = funcBucket.get(varName);
+        if (entry?.kind === 'resolved')
+            return entry.value;
+        if (entry?.kind === 'ambiguous') {
+            // Ambiguous in this function scope — try file-level fallback
+            const fileEntry = index.get('')?.get(varName);
+            return fileEntry?.kind === 'resolved' ? fileEntry.value : undefined;
+        }
+    }
+    // Fallback: file-level scope (funcName "")
+    if (funcName !== '') {
+        const fileEntry = index.get('')?.get(varName);
+        if (fileEntry?.kind === 'resolved')
+            return fileEntry.value;
+    }
+    return undefined;
+};
+/**
+ * Resolve the type that results from accessing `receiverName.fieldName`.
+ * Requires declaredType on the Property node (needed for chain walking continuation).
+ */
+const resolveFieldAccessType = (receiverName, fieldName, filePath, ctx) => {
+    const fieldDef = resolveFieldOwnership(receiverName, fieldName, filePath, ctx);
+    if (!fieldDef?.declaredType)
+        return undefined;
+    // Use stripNullable (not extractReturnTypeName) — field types like List<User>
+    // should be preserved as-is, not unwrapped to User. Only strip nullable wrappers.
+    return {
+        typeName: stripNullable(fieldDef.declaredType),
+        fieldNodeId: fieldDef.nodeId,
+    };
+};
+/**
+ * Resolve a field's Property node given a receiver type name and field name.
+ * Does NOT require declaredType — used by write-access tracking where only the
+ * fieldNodeId is needed (no chain continuation).
+ */
+const resolveFieldOwnership = (receiverName, fieldName, filePath, ctx) => {
+    const typeResolved = ctx.resolve(receiverName, filePath);
+    if (!typeResolved)
+        return undefined;
+    const classDef = typeResolved.candidates.find(d => d.type === 'Class' || d.type === 'Struct' || d.type === 'Interface'
+        || d.type === 'Enum' || d.type === 'Record' || d.type === 'Impl');
+    if (!classDef)
+        return undefined;
+    return ctx.symbols.lookupFieldByOwner(classDef.nodeId, fieldName) ?? undefined;
+};
+/**
+ * Create a deduplicated ACCESSES edge emitter for a single source node.
+ * Each (sourceId, fieldNodeId) pair is emitted at most once per source.
+ */
+const makeAccessEmitter = (graph, sourceId) => {
+    const emitted = new Set();
+    return (fieldNodeId) => {
+        const key = `${sourceId}\0${fieldNodeId}`;
+        if (emitted.has(key))
+            return;
+        emitted.add(key);
+        graph.addRelationship({
+            id: generateId('ACCESSES', `${sourceId}:${fieldNodeId}:read`),
+            sourceId,
+            targetId: fieldNodeId,
+            type: 'ACCESSES',
+            confidence: 1.0,
+            reason: 'read',
+        });
+    };
+};
+const walkMixedChain = (chain, startType, filePath, ctx, onFieldResolved) => {
+    let currentType = startType;
+    for (const step of chain) {
+        if (!currentType)
+            break;
+        if (step.kind === 'field') {
+            const resolved = resolveFieldAccessType(currentType, step.name, filePath, ctx);
+            if (!resolved) {
+                currentType = undefined;
                 break;
             }
+            onFieldResolved?.(resolved.fieldNodeId);
+            currentType = resolved.typeName;
+        }
+        else {
+            // Ruby/Python: property access is syntactically identical to method calls.
+            // Try field resolution first — if the name is a known property with declaredType,
+            // use that type directly. Otherwise fall back to method call resolution.
+            const fieldResolved = resolveFieldAccessType(currentType, step.name, filePath, ctx);
+            if (fieldResolved) {
+                onFieldResolved?.(fieldResolved.fieldNodeId);
+                currentType = fieldResolved.typeName;
+                continue;
+            }
+            const resolved = resolveCallTarget({ calledName: step.name, callForm: 'member', receiverTypeName: currentType }, filePath, ctx);
+            if (!resolved) {
+                // Stdlib passthrough: unwrap(), clone(), etc. preserve the receiver type
+                if (TYPE_PRESERVING_METHODS.has(step.name))
+                    continue;
+                currentType = undefined;
+                break;
+            }
+            if (!resolved.returnType) {
+                currentType = undefined;
+                break;
+            }
+            const retType = extractReturnTypeName(resolved.returnType);
+            if (!retType) {
+                currentType = undefined;
+                break;
+            }
+            currentType = retType;
         }
     }
-    if (!ambiguous && found !== undefined)
-        return found;
-    // Fallback: file-level scope (bindings outside any function)
-    return map.get(fileLevelKey);
+    return currentType;
 };
 /**
  * Fast path: resolve pre-extracted call sites from workers.
@@ -463,7 +975,7 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
         for (const { filePath, bindings } of constructorBindings) {
             const verified = verifyConstructorBindings(bindings, filePath, ctx, graph);
             if (verified.size > 0) {
-                fileReceiverTypes.set(filePath, verified);
+                fileReceiverTypes.set(filePath, buildReceiverTypeIndex(verified));
             }
         }
     }
@@ -503,24 +1015,27 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
                     effectiveCall = { ...effectiveCall, receiverTypeName: effectiveCall.receiverName };
                 }
             }
-            // Step 2: if the call has a receiver call chain (e.g. svc.getUser().save()),
-            // resolve the chain to determine the final receiver type.
-            // This runs whenever receiverCallChain is present — even when Step 1 set a
-            // receiverTypeName, that type is the BASE receiver (e.g. UserService for svc),
-            // and the chain must be walked to produce the FINAL receiver (e.g. User from
-            // getUser() : User).
-            if (effectiveCall.receiverCallChain?.length) {
-                // Step 1 may have resolved the base receiver type (e.g. svc → UserService).
-                // Use it as the 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) {
+            // Step 1c: mixed chain resolution (field, call, or interleaved — e.g. svc.getUser().address.save()).
+            // Runs whenever receiverMixedChain is present. Steps 1/1b may have resolved the base receiver
+            // type already; that type is used as the chain's starting point.
+            if (effectiveCall.receiverMixedChain?.length) {
+                // Use the already-resolved base type (from Steps 1/1b) or look it up now.
+                let currentType = effectiveCall.receiverTypeName;
+                if (!currentType && effectiveCall.receiverName && receiverMap) {
                     const callFuncName = extractFuncNameFromSourceId(effectiveCall.sourceId);
-                    baseType = lookupReceiverType(receiverMap, callFuncName, effectiveCall.receiverName);
+                    currentType = lookupReceiverType(receiverMap, callFuncName, effectiveCall.receiverName);
+                }
+                if (!currentType && effectiveCall.receiverName) {
+                    const typeResolved = ctx.resolve(effectiveCall.receiverName, effectiveCall.filePath);
+                    if (typeResolved?.candidates.some(d => d.type === 'Class' || d.type === 'Interface' || d.type === 'Struct' || d.type === 'Enum')) {
+                        currentType = effectiveCall.receiverName;
+                    }
                 }
-                const chainedType = resolveChainedReceiver(effectiveCall.receiverCallChain, baseType, effectiveCall.filePath, ctx);
-                if (chainedType) {
-                    effectiveCall = { ...effectiveCall, receiverTypeName: chainedType };
+                if (currentType) {
+                    const walkedType = walkMixedChain(effectiveCall.receiverMixedChain, currentType, effectiveCall.filePath, ctx, makeAccessEmitter(graph, effectiveCall.sourceId));
+                    if (walkedType) {
+                        effectiveCall = { ...effectiveCall, receiverTypeName: walkedType };
+                    }
                 }
             }
             const resolved = resolveCallTarget(effectiveCall, effectiveCall.filePath, ctx);
@@ -540,6 +1055,56 @@ export const processCallsFromExtracted = async (graph, extractedCalls, ctx, onPr
     }
     onProgress?.(totalFiles, totalFiles);
 };
+/**
+ * Resolve pre-extracted field write assignments to ACCESSES {reason: 'write'} edges.
+ * Accepts optional constructorBindings for return-type-aware receiver inference,
+ * mirroring processCallsFromExtracted's verified binding lookup.
+ */
+export const processAssignmentsFromExtracted = (graph, assignments, ctx, constructorBindings) => {
+    // Build per-file receiver type indexes from verified constructor bindings
+    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, buildReceiverTypeIndex(verified));
+            }
+        }
+    }
+    for (const asn of assignments) {
+        // Resolve the receiver type
+        let receiverTypeName = asn.receiverTypeName;
+        // Tier 2: verified constructor bindings (return-type inference)
+        if (!receiverTypeName && fileReceiverTypes.size > 0) {
+            const receiverMap = fileReceiverTypes.get(asn.filePath);
+            if (receiverMap) {
+                const funcName = extractFuncNameFromSourceId(asn.sourceId);
+                receiverTypeName = lookupReceiverType(receiverMap, funcName, asn.receiverText);
+            }
+        }
+        // Tier 3: static class-as-receiver fallback
+        if (!receiverTypeName) {
+            const resolved = ctx.resolve(asn.receiverText, asn.filePath);
+            if (resolved?.candidates.some(d => d.type === 'Class' || d.type === 'Struct' || d.type === 'Interface'
+                || d.type === 'Enum' || d.type === 'Record' || d.type === 'Impl')) {
+                receiverTypeName = asn.receiverText;
+            }
+        }
+        if (!receiverTypeName)
+            continue;
+        const fieldOwner = resolveFieldOwnership(receiverTypeName, asn.propertyName, asn.filePath, ctx);
+        if (!fieldOwner)
+            continue;
+        graph.addRelationship({
+            id: generateId('ACCESSES', `${asn.sourceId}:${fieldOwner.nodeId}:write`),
+            sourceId: asn.sourceId,
+            targetId: fieldOwner.nodeId,
+            type: 'ACCESSES',
+            confidence: 1.0,
+            reason: 'write',
+        });
+    }
+};
 /**
  * Resolve pre-extracted Laravel routes to CALLS edges from route files to controller methods.
  */