ucn 4.2.2 → 5.0.1

package/core/project.js

@@ -8,10 +8,14 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { expandGlob, findProjectRoot, detectProjectPattern, isTestFile, parseGitignore, DEFAULT_IGNORES, compareNames } = require('./discovery');
-const { extractImports, extractExports } = require('./imports');
-const { parse, cleanHtmlScriptTags } = require('./parser');
-const { detectLanguage, getParser, getLanguageModule, safeParse, langTraits, PARSE_OPTIONS } = require('../languages');
+const {
+    expandGlob, findProjectRoot, detectProjectPattern, isTestFile,
+    parseGitignore, gitTrackedPaths, DEFAULT_IGNORES, compareNames, classifyUnsupportedSourceFile,
+} = require('./discovery');
+const { cleanHtmlScriptTags } = require('./parser');
+const { detectLanguage, getParser, getLanguageAdapter, safeParse, langTraits, PARSE_OPTIONS } = require('../languages');
+const { validateFileIR } = require('./ir');
+const { createFileEntryFromIR, populateFileEntryFromIR } = require('./index-ir');
 const { getTokenTypeAtPosition } = require('../languages/utils');
 const { escapeRegExp, NON_CALLABLE_TYPES, codeUnitCompare } = require('./shared');
 const stacktrace = require('./stacktrace');
@@ -29,6 +33,15 @@ const reportingModule = require('./reporting');
 // Lazy-initialized per-language keyword sets (populated on first isKeyword call)
 let LANGUAGE_KEYWORDS = null;
 
+// Query-time ASTs are immutable for the lifetime of an indexed file. Keep a
+// small cross-operation LRU so a sequence of agent queries does not reparse the
+// same large headers/modules for every conservation-account classification.
+// The source-byte budget is deliberately conservative because tree-sitter's
+// native tree is larger than its source. Evictions explicitly release native
+// memory instead of waiting for N-API finalizers.
+const PARSED_TREE_CACHE_MAX_ENTRIES = 128;
+const PARSED_TREE_CACHE_MAX_SOURCE_BYTES = 32 * 1024 * 1024;
+
 /**
  * ProjectIndex - Manages symbol table for a project
  */
@@ -47,15 +60,27 @@ class ProjectIndex {
         this.extendedByGraph = new Map(); // parentName -> [childInfo]
         this.config = this.loadConfig();
         this.buildTime = null;
+        // Build telemetry is intentionally transient (never cached). Release
+        // performance gates use it to prove the requested worker shape was
+        // actually exercised instead of inferring parallelism from host CPUs.
+        this.lastBuildWorkerCount = 1;
+        this.lastBuildParallelEligible = false;
+        this.lastBuildRequestedWorkers = null;
         this.callsCache = new Map();     // filePath -> { mtime, hash, calls, content }
         this.callsCacheDirty = false;    // set by getCachedCalls when entries are added or mutated
+        this.computedDispatchDirty = false; // persisted project-wide AST blind-spot inventory
         this.failedFiles = new Set();    // files that failed to index (e.g. large minified bundles)
+        this.unsupportedFiles = [];      // common source files skipped by the parser registry
+        this.discoveryIssues = [];       // explicit reasons the index may be partial
         this._opContentCache = null;     // per-operation file content cache (Map<filePath, string>)
         this._opUsagesCache = null;      // per-operation findUsagesInCode cache (Map<"file:name", usages[]>)
         this._opTreeCache = null;        // per-operation parsed-tree cache (Map<filePath, tree|null>, bounded FIFO)
+        this._opTransientTrees = null;   // evicted/errored trees kept alive until the active operation ends
         this._opLinesCache = null;       // per-operation split-lines cache (Map<filePath, string[]>, bounded FIFO)
         this._opInnerSymbolRangesCache = null; // per-operation sorted class-method ranges by file
         this._opFlowTypeOriginCache = null; // per-operation annotation type identity results
+        this._parsedTreeCache = new Map(); // cross-operation LRU: filePath -> immutable tree entry
+        this._parsedTreeCacheSourceBytes = 0;
         this.calleeIndex = null;         // name -> Set<filePath> — inverted call index (built lazily)
     }
 
@@ -84,6 +109,7 @@ class ProjectIndex {
             this._opUsageTotalsCache = new Map();
             this._opEnclosingFnCache = new Map();
             this._opTreeCache = new Map();
+            this._opTransientTrees = new Set();
             this._opLinesCache = new Map();
             // Query-time semantic derivations that depend only on one file's
             // immutable call records. Reachability may ask findCallees() for
@@ -109,6 +135,10 @@ class ProjectIndex {
             this._opUsageTotalsCache = null;
             this._opEnclosingFnCache = null;
             this._opTreeCache = null;
+            if (this._opTransientTrees) {
+                for (const tree of this._opTransientTrees) tree?.delete?.();
+            }
+            this._opTransientTrees = null;
             this._opLinesCache = null;
             this._opReturnTypeFlowCache = null;
             this._opCallsByLineCache = null;
@@ -124,11 +154,46 @@ class ProjectIndex {
         }
     }
 
+    /** Remove one persistent parsed tree, deferring disposal if an operation still uses it. */
+    _evictParsedTree(filePath) {
+        const entry = this._parsedTreeCache.get(filePath);
+        if (!entry) return;
+        this._parsedTreeCache.delete(filePath);
+        this._parsedTreeCacheSourceBytes -= entry.sourceBytes;
+        if (this._opTreeCache?.get(filePath) === entry.tree) {
+            this._opTransientTrees?.add(entry.tree);
+        } else {
+            entry.tree?.delete?.();
+        }
+    }
+
+    /** Dispose every cross-operation tree. Used when an index is replaced from cache. */
+    _clearParsedTreeCache() {
+        for (const filePath of [...this._parsedTreeCache.keys()]) {
+            this._evictParsedTree(filePath);
+        }
+        this._parsedTreeCacheSourceBytes = 0;
+    }
+
+    _cacheParsedTree(filePath, language, tree, sourceBytes) {
+        const fileHash = this.files.get(filePath)?.hash || null;
+        this._evictParsedTree(filePath);
+        this._parsedTreeCache.set(filePath, {
+            tree, language, fileHash, sourceBytes,
+        });
+        this._parsedTreeCacheSourceBytes += sourceBytes;
+        while (this._parsedTreeCache.size > PARSED_TREE_CACHE_MAX_ENTRIES ||
+            this._parsedTreeCacheSourceBytes > PARSED_TREE_CACHE_MAX_SOURCE_BYTES) {
+            this._evictParsedTree(this._parsedTreeCache.keys().next().value);
+        }
+    }
+
     /**
-     * Parse a file once per operation and reuse the tree across symbol names.
+     * Parse a file once and reuse the immutable tree across operations.
      * Multi-symbol commands (diff-impact, check) classify ground lines for MANY
      * names against the SAME files; without this, each (file, name) pair costs a
-     * full tree-sitter parse. Bounded FIFO (trees hold native memory).
+     * full tree-sitter parse. Both operation and persistent caches are bounded
+     * because trees hold native memory.
      * Returns null when parsing fails or no operation cache is active — callers
      * fall back to parsing themselves.
      */
@@ -136,6 +201,19 @@ class ProjectIndex {
         if (!this._opTreeCache) return null;
         const cached = this._opTreeCache.get(filePath);
         if (cached !== undefined) return cached;
+
+        const persistent = this._parsedTreeCache.get(filePath);
+        const currentHash = this.files.get(filePath)?.hash || null;
+        if (persistent && persistent.language === language &&
+            persistent.fileHash === currentHash) {
+            // LRU touch.
+            this._parsedTreeCache.delete(filePath);
+            this._parsedTreeCache.set(filePath, persistent);
+            this._opTreeCache.set(filePath, persistent.tree);
+            return persistent.tree;
+        }
+        if (persistent) this._evictParsedTree(filePath);
+
         let tree;
         try {
             const parser = getParser(language);
@@ -147,6 +225,9 @@ class ProjectIndex {
             this._opTreeCache.delete(this._opTreeCache.keys().next().value);
         }
         this._opTreeCache.set(filePath, tree);
+        if (tree) {
+            this._cacheParsedTree(filePath, language, tree, Buffer.byteLength(content));
+        }
         return tree;
     }
 
@@ -183,8 +264,13 @@ class ProjectIndex {
             if (cached !== undefined) return cached;
         }
 
-        const lang = detectLanguage(filePath);
-        const langModule = getLanguageModule(lang);
+        // Header language is resolved during indexing from compilation
+        // databases/include context. Re-detecting `.h` here can choose C for
+        // a C++ header and silently drop member/template usages from the raw
+        // inventory. The indexed language is the authoritative parse mode.
+        const lang = this.files.get(filePath)?.language ||
+            detectLanguage(filePath, this.root);
+        const langModule = getLanguageAdapter(lang);
         if (!langModule || typeof langModule.findUsagesInCode !== 'function') return null;
 
         try {
@@ -202,7 +288,8 @@ class ProjectIndex {
             if (!parser) return null;
             // Language modules that accept a pre-parsed tree (4th param) reuse
             // the per-operation tree cache; others (html) parse internally.
-            const tree = langModule.findUsagesInCode.length >= 4
+            const tree = langModule.findUsagesInCode.length >= 4 &&
+                !langModule.managesOwnParseTree
                 ? this._getParsedTree(filePath, content, lang)
                 : null;
             const usages = langModule.findUsagesInCode(content, name, parser, tree);
@@ -224,7 +311,7 @@ class ProjectIndex {
             try {
                 return JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
             } catch (e) {
-                // Config load failed, use defaults
+                this.configError = `.ucn.json could not be parsed: ${e.message}`;
             }
         }
         return {};
@@ -233,10 +320,10 @@ class ProjectIndex {
     /**
      * Build index for files matching pattern
      *
-     * @param {string} pattern - Glob pattern (e.g., "**\/*.js")
+     * @param {string|null} [pattern=null] - Glob pattern (e.g., "**\/*.js")
      * @param {object} options - { forceRebuild, maxFiles, quiet }
      */
-    build(pattern, options = {}) {
+    build(pattern = null, options = {}) {
         const startTime = Date.now();
         const quiet = options.quiet !== false;
 
@@ -252,6 +339,23 @@ class ProjectIndex {
 
         // Accept pre-expanded file array (glob mode) or a pattern string
         let files;
+        const implicitProjectDiscovery = !Array.isArray(pattern) && !pattern;
+        this.unsupportedFiles = [];
+        this.discoveryIssues = [];
+        const discoveryIssueKeys = new Set();
+        const recordDiscoveryIssue = (issue) => {
+            const rel = path.relative(this.root, issue.path || this.root) || '.';
+            const key = `${issue.reason}\0${rel}`;
+            if (discoveryIssueKeys.has(key)) return;
+            discoveryIssueKeys.add(key);
+            this.discoveryIssues.push({ ...issue, relativePath: rel, path: undefined });
+        };
+        if (this.configError) {
+            recordDiscoveryIssue({
+                path: path.join(this.root, '.ucn.json'),
+                kind: 'file', reason: 'invalid-config', detail: this.configError,
+            });
+        }
         if (Array.isArray(pattern)) {
             files = pattern;
         } else {
@@ -262,23 +366,44 @@ class ProjectIndex {
             const globOpts = {
                 root: this.root,
                 maxFiles: options.maxFiles || this.config.maxFiles || 50000,
+                maxDepth: options.maxDepth ?? this.config.maxDepth,
+                maxFileSize: options.maxFileSize ?? this.config.maxFileSize,
                 followSymlinks: options.followSymlinks
             };
 
             // Merge .gitignore and .ucn.json exclude into file discovery
             const gitignorePatterns = parseGitignore(this.root);
-            const configExclude = this.config.exclude || [];
-            if (gitignorePatterns.length > 0 || configExclude.length > 0) {
-                globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
+            globOpts.gitignorePatterns = gitignorePatterns;
+            globOpts.trackedPaths = gitTrackedPaths(this.root);
+            const configExclude = Array.isArray(this.config.exclude)
+                ? this.config.exclude
+                : (this.config.exclude ? [String(this.config.exclude)] : []);
+            if (configExclude.length > 0) {
+                globOpts.ignores = [...DEFAULT_IGNORES, ...configExclude];
+            }
+            globOpts.disclosureIgnores = configExclude;
+            globOpts.onDiscoveryIssue = recordDiscoveryIssue;
+
+            if (implicitProjectDiscovery) {
+                globOpts.onSkippedFile = (filePath) => {
+                    const kind = classifyUnsupportedSourceFile(filePath);
+                    if (!kind) return;
+                    this.unsupportedFiles.push({
+                        relativePath: path.relative(this.root, filePath),
+                        ...kind,
+                    });
+                };
             }
-
             files = expandGlob(pattern, globOpts);
+            this.unsupportedFiles.sort((a, b) => compareNames(a.relativePath, b.relativePath));
+            this.discoveryIssues.sort((a, b) => compareNames(a.relativePath, b.relativePath));
         }
 
         // Track if files were truncated by maxFiles limit
         const maxFiles = options.maxFiles || this.config.maxFiles || 50000;
-        if (!Array.isArray(pattern) && files.length >= maxFiles) {
-            this.truncated = { indexed: files.length, maxFiles };
+        const maxFileIssues = this.discoveryIssues.filter(issue => issue.reason === 'max-files');
+        if (!Array.isArray(pattern) && maxFileIssues.length > 0) {
+            this.truncated = { indexed: files.length, maxFiles, skipped: maxFileIssues.length };
         } else {
             this.truncated = null;
         }
@@ -318,6 +443,7 @@ class ProjectIndex {
         // Always invalidate caches on rebuild
         this._completenessCache = null;
         this._attrTypeCache = null;
+        this._computedDispatchBlindspots = null;
         // Endpoints cache (server routes / client requests / bridges) becomes
         // stale when files change; clear on every rebuild.
         this._endpointsCache = null;
@@ -330,13 +456,43 @@ class ProjectIndex {
         const workersSetting = options.workers;
         const envWorkers = parseInt(process.env.UCN_WORKERS, 10);
         const disableParallel = workersSetting === 0 || envWorkers === 0;
+        const explicitWorkerCount = workersSetting > 0 || envWorkers > 0;
+        const requestedWorkerCount = workersSetting > 0
+            ? workersSetting : (envWorkers > 0 ? envWorkers : null);
+        this.lastBuildWorkerCount = 1;
+        this.lastBuildRequestedWorkers = requestedWorkerCount;
         let usedParallel = false;
 
-        if (!disableParallel && files.length > 150) {
+        // C/C++ recovery performs materially heavier parser work per file
+        // (attribute normalization plus bounded preprocessor views). Medium
+        // native projects therefore benefit from workers well before the
+        // generic 150-file crossover; measured release repos cross over at
+        // roughly 25 C-family files.
+        const cFamilyFileCount = files.reduce((count, filePath) => {
+            const language = detectLanguage(filePath, this.root);
+            return count + (language === 'c' || language === 'cpp' ? 1 : 0);
+        }, 0);
+        // An explicit worker count is a request for a reproducible execution
+        // shape (not merely an upper bound). This is useful to users tuning a
+        // constrained host and lets the release gate compare like with like.
+        const parallelWorthwhile = explicitWorkerCount
+            ? files.length >= 2
+            : files.length > 150 || cFamilyFileCount >= 25;
+        this.lastBuildParallelEligible = !disableParallel && parallelWorthwhile;
+        if (!disableParallel && parallelWorthwhile) {
             try {
                 const { parallelBuild } = require('./parallel-build');
                 const result = parallelBuild(this, files, {
                     workerCount: workersSetting > 0 ? workersSetting : (envWorkers > 0 ? envWorkers : undefined),
+                    // After the recovery scorer stopped repeatedly walking
+                    // every candidate tree, real-repo sweeps put the native
+                    // throughput knee at 5-6 workers. Default to the lower
+                    // knee (five) for RSS headroom; explicit user settings
+                    // retain the ordinary eight-worker safety cap.
+                    maxWorkers: cFamilyFileCount >= 25 && !explicitWorkerCount
+                        ? 5 : 8,
+                    minFilesPerWorker: explicitWorkerCount
+                        ? 1 : (cFamilyFileCount >= 25 ? 10 : 100),
                     quiet,
                 });
                 if (result !== false) {
@@ -345,6 +501,7 @@ class ProjectIndex {
                     usedParallel = true;
                 }
             } catch (e) {
+                this.lastBuildWorkerCount = 1;
                 if (!quiet) {
                     console.error(`Parallel build failed, falling back to sequential: ${e.message}`);
                 }
@@ -384,9 +541,10 @@ class ProjectIndex {
         // avoiding the 2+ minute deferred cost when the first analysis command runs later.
         this.buildCalleeIndex();
 
-        // buildCalleeIndex re-parses changed files via getCachedCalls, which
-        // appends their entries at the callsCache TAIL — restore canonical
-        // key order so iteration-order consumers match a fresh build.
+        // Keep persisted iteration deterministic. Fresh and changed files
+        // already populated callsCache through the shared IR ingestion path;
+        // unchanged entries may have arrived from a sharded cache in a
+        // different order.
         this.callsCache = new Map([...this.callsCache.entries()].sort((a, b) => compareNames(a[0], b[0])));
 
         this.buildTime = Date.now() - startTime;
@@ -435,16 +593,16 @@ class ProjectIndex {
             this.removeFileSymbols(filePath);
         }
 
-        const language = detectLanguage(filePath);
+        const language = detectLanguage(filePath, this.root);
         if (!language) return;
 
-        // Parse content once — the tree-sitter cache in safeParse ensures the tree
-        // is shared across parse()/extractImports()/extractExports() (5→1 parse per file)
-        const parsed = parse(content, language);
-        parsed.filePath = filePath;
-        parsed.relativePath = filePath;
-        const { imports, dynamicCount, importAliases } = extractImports(content, language);
-        const { exports } = extractExports(content, language);
+        const adapter = getLanguageAdapter(language);
+        const parser = getParser(language);
+        const ir = adapter.analyze(content, parser, filePath);
+        const irFailures = validateFileIR(ir);
+        if (irFailures.length > 0) {
+            throw new Error(`Invalid ${language} IR: ${irFailures.join('; ')}`);
+        }
 
         // Detect bundled/minified files (webpack bundles, minified code)
         // These are build artifacts, not user-written source code
@@ -470,8 +628,12 @@ class ProjectIndex {
         const isBundled = (() => {
             // Webpack bundles contain __webpack_require__ or __webpack_modules__
             if (content.includes('__webpack_require__') || content.includes('__webpack_modules__')) return true;
-            // Minified files: very few lines but large content (avg > 500 chars/line)
-            if (lineCount > 0 && lineCount < 50 && content.length / lineCount > 500) return true;
+            // Minified files: large content with extreme bytes/line. Bundlers
+            // often insert 50-200 licence/chunk-separator lines, so an
+            // arbitrary <50 cap lets the same bytes flip classification when
+            // a banner is added. The size floor protects authored small files.
+            if (lineCount > 0 && content.length >= 100 * 1024 &&
+                content.length / lineCount > 500) return true;
             // Very long single lines (> 1000 chars) in most of the file suggest minification
             if (lineCount > 0 && longLineCount > 0 && longLineCount / lineCount > 0.3) return true;
             return false;
@@ -484,140 +646,26 @@ class ProjectIndex {
             content.slice(0, 500)
         );
 
-        const fileEntry = {
-            path: filePath,
+        const fileEntry = createFileEntryFromIR({
+            ir,
+            filePath,
             relativePath: path.relative(this.root, filePath),
-            language,
-            lines: lineCount,
             hash,
             mtime: stat.mtimeMs,
             size: stat.size,
-            imports: imports.map(i => i.module),
-            importNames: imports.flatMap(i => i.names || []),
-            // Paired name↔module bindings (fix #209): importNames flattens the
-            // pairing away, but name-level shadow detection needs to know WHICH
-            // module bound a name (`from urllib.parse import unquote` rebinds
-            // the bare name for the whole file).
-            importBindings: imports.flatMap(i => (i.names || [])
-                .filter(n => n && n !== '*' && n !== '_' && n !== '.')
-                .map(n => {
-                    // Rename pairing (fix #269): `{ validate: validateSchema }
-                    // = require('./validation')` — the record's local alias
-                    // pins to ITS module, not any module exporting the name.
-                    const rn = (i.renames || []).find(r => r.original === n);
-                    return { name: n, module: i.module, ...(rn && { alias: rn.local }) };
-                })),
-            exports: exports.map(e => e.name),
-            exportDetails: exports,
-            symbols: [],
-            bindings: [],
-            ...(parsed.parseRecovery && { parseRecovery: true }),
-            ...(importAliases && { importAliases }),
-            // Module-scope assignment targets (fix #217): names a module can
-            // expose WITHOUT a def/class/import binding (`render = impl`,
-            // `global name`). The import-binding name-chase treats these as
-            // undetermined — a dead-end verdict would be unsound.
-            ...(parsed.moduleAssignedNames && { moduleAssignedNames: parsed.moduleAssignedNames }),
-            ...(isBundled && { isBundled: true }),
-            ...(isGenerated && { isGenerated: true })
-        };
-        fileEntry.dynamicImports = dynamicCount || 0;
-
-        // Add symbols
-        const addSymbol = (item, type) => {
-            const symbol = {
-                name: item.name,
-                type,
-                file: filePath,
-                relativePath: fileEntry.relativePath,
-                startLine: item.startLine,
-                endLine: item.endLine,
-                params: item.params,
-                paramsStructured: item.paramsStructured,
-                returnType: item.returnType,
-                ...(item.returnedFunctionResult && { returnedFunctionResult: item.returnedFunctionResult }),
-                ...(item.isFunctionVariable && { isFunctionVariable: true }),
-                ...(item.paramTypes && { paramTypes: item.paramTypes }),
-                ...(item.isAsync && { isAsync: true }),
-                ...(item.isGenerator && { isGenerator: true }),
-                modifiers: item.modifiers,
-                docstring: item.docstring,
-                bindingId: `${fileEntry.relativePath}:${type}:${item.startLine}`,
-                ...(item.generics && { generics: item.generics }),
-                ...(item.extends && { extends: item.extends }),
-                ...(item.implements && { implements: item.implements }),
-                ...(item.indent !== undefined && { indent: item.indent }),
-                ...(item.isNested && { isNested: item.isNested }),
-                ...(item.isMethod && { isMethod: item.isMethod }),
-                ...(item.receiver && { receiver: item.receiver }),
-                ...(item.className && { className: item.className }),
-                ...(item.memberType && { memberType: item.memberType }),
-                ...(item.fieldType && { fieldType: item.fieldType }),
-                ...(item.aliasOf && { aliasOf: item.aliasOf }),
-                ...(item.decorators && item.decorators.length > 0 && { decorators: item.decorators }),
-                // Decorator/annotation/attribute argument capture for endpoints command:
-                // these fields hold the parsed first-string-arg of each route-style annotation.
-                // Only populated when at least one entry has a string-literal arg, keeping memory
-                // overhead minimal for non-route code.
-                ...(item.decoratorsWithArgs && item.decoratorsWithArgs.length > 0 && { decoratorsWithArgs: item.decoratorsWithArgs }),
-                ...(item.annotationsWithArgs && item.annotationsWithArgs.length > 0 && { annotationsWithArgs: item.annotationsWithArgs }),
-                ...(item.attributesWithArgs && item.attributesWithArgs.length > 0 && { attributesWithArgs: item.attributesWithArgs }),
-                ...(item.nameLine && { nameLine: item.nameLine }),
-                ...(item.traitImpl && { traitImpl: true }),
-                // Trait the impl block implements (rust `impl Trait for X`
-                // members) — external-contract detection needs the NAME, not
-                // just the traitImpl flag (fix #210).
-                ...(item.traitName && { traitName: item.traitName }),
-                ...(item.isSignature && { isSignature: true }),
-                ...(item.memberAssigned && { memberAssigned: true }),
-                ...(item.registryMember && { registryMember: true }),
-                ...(item.registryContainer && { registryContainer: item.registryContainer })
-            };
-            fileEntry.symbols.push(symbol);
-            // Property-assignment defs (fix #269: Reply.prototype.serialize
-            // = function) declare no lexical name — a bare reference in the
-            // file can never bind them, so they never enter the bindings
-            // table (the symbol stays indexed and method-reachable).
-            if (!item.memberAssigned) {
-                fileEntry.bindings.push({
-                    id: symbol.bindingId,
-                    name: symbol.name,
-                    type: symbol.type,
-                    startLine: symbol.startLine
-                });
-            }
-
-            if (!this.symbols.has(item.name)) {
-                this.symbols.set(item.name, []);
-            }
-            this.symbols.get(item.name).push(symbol);
-        };
-
-        for (const fn of parsed.functions) {
-            // Go/Rust methods: set className from receiver for consistent method resolution.
-            // Go/Rust methods are standalone functions with receiver, not class members,
-            // so className is never set by the class member loop below.
-            if (fn.receiver && !fn.className) {
-                fn.className = fn.receiver.replace(/^\*/, '');
-            }
-            addSymbol(fn, fn.isConstructor ? 'constructor' : 'function');
-        }
-
-        for (const cls of parsed.classes) {
-            addSymbol(cls, cls.type || 'class');
-            if (cls.members) {
-                for (const m of cls.members) {
-                    const memberType = m.memberType || 'method';
-                    addSymbol({ ...m, className: cls.name, ...(cls.traitName && { traitImpl: true, traitName: cls.traitName }) }, memberType);
-                }
-            }
-        }
-
-        for (const state of parsed.stateObjects) {
-            addSymbol(state, 'state');
-        }
+            lineCount,
+            isBundled,
+            isGenerated,
+        });
+        populateFileEntryFromIR(fileEntry, ir, this.symbols);
 
         this.files.set(filePath, fileEntry);
+        this.callsCache.set(filePath, {
+            mtime: stat.mtimeMs,
+            hash,
+            calls: ir.calls,
+        });
+        this.callsCacheDirty = true;
         return true;
     }
 
@@ -628,6 +676,8 @@ class ProjectIndex {
         const existing = this.files.get(filePath);
         if (!existing) return;
 
+        this._evictParsedTree(filePath);
+
         for (const symbol of existing.symbols) {
             const entries = this.symbols.get(symbol.name);
             if (entries) {
@@ -652,6 +702,8 @@ class ProjectIndex {
 
         // Invalidate lazy Java file index (will be rebuilt on next use)
         this._javaFileIndex = null;
+        // Computed-dispatch diagnostics are project-wide and read source text.
+        this._computedDispatchBlindspots = null;
         // Endpoints cache is project-wide; safest to clear on any file removal.
         this._endpointsCache = null;
     }
@@ -748,6 +800,17 @@ class ProjectIndex {
                     }
                 }
             }
+            // A compiler-recognized type qualifier is also a semantic use of
+            // the receiver type: `JValue.Compare(...)` references both
+            // JValue and Compare. Index the receiver so class/type queries do
+            // not fall back to a full project scan or leave the occurrence as
+            // an unexplained call-not-resolved line.
+            if (call.receiverIsTypeQualified && call.receiver) {
+                if (!this.calleeIndex.has(call.receiver)) {
+                    this.calleeIndex.set(call.receiver, new Set());
+                }
+                this.calleeIndex.get(call.receiver).add(filePath);
+            }
         }
     }
 
@@ -772,6 +835,9 @@ class ProjectIndex {
                     if (rn !== call.name) removeName(rn);
                 }
             }
+            if (call.receiverIsTypeQualified && call.receiver) {
+                removeName(call.receiver);
+            }
         }
     }
 
@@ -828,6 +894,10 @@ class ProjectIndex {
         return graphBuildModule._resolveJavaPackageImport(this, importModule, javaFileIndex);
     }
 
+    _resolveCSharpUsing(importModule) {
+        return graphBuildModule._resolveCSharpUsing(this, importModule);
+    }
+
     /**
      * Build import/export relationship graphs
      */
@@ -1038,9 +1108,11 @@ class ProjectIndex {
 
         // Filter by file if specified
         if (options.file) {
-            const filtered = definitions.filter(d =>
-                d.relativePath && d.relativePath.includes(options.file)
-            );
+            const resolvedFile = this.resolveFilePathForQuery(options.file);
+            const filtered = typeof resolvedFile === 'string'
+                ? definitions.filter(d => d.file === resolvedFile)
+                : definitions.filter(d =>
+                    d.relativePath && d.relativePath.includes(options.file));
             if (filtered.length > 0) {
                 definitions = filtered;
             }
@@ -1048,15 +1120,23 @@ class ProjectIndex {
 
         // Filter by exact startLine when a handle was supplied. This pins
         // the resolution to one specific definition — no ambiguity allowed.
-        if (options.line && Number.isFinite(options.line)) {
-            const filtered = definitions.filter(d => d.startLine === options.line);
-            if (filtered.length > 0) {
-                definitions = filtered;
+        if (options.line != null && options.line !== '') {
+            const exactLine = Number(options.line);
+            if (Number.isFinite(exactLine)) {
+                // A line is an exact identity pin, never a ranking hint.
+                // An unsatisfied pin must not fall back to another definition.
+                definitions = definitions.filter(d =>
+                    d.startLine === exactLine || d.nameLine === exactLine);
             }
         }
+        if (definitions.length === 0) {
+            return { def: null, definitions: [], warnings: [] };
+        }
 
         // Score each definition for selection
-        const typeOrder = new Set(['class', 'struct', 'interface', 'type', 'impl']);
+        const typeOrder = new Set([
+            'class', 'struct', 'interface', 'type', 'impl', 'enum', 'record',
+        ]);
         const { isTestPath } = require('./shared');
         const scored = definitions.map(d => {
             let score = 0;
@@ -1303,7 +1383,15 @@ class ProjectIndex {
             }
 
             const total = calls + definitions + imports;
-            const result = { total, calls, definitions, imports, references: 0 };
+            const result = {
+                total,
+                calls,
+                definitions,
+                imports,
+                references: 0,
+                complete: false,
+                countKind: 'fast-disambiguation-excludes-references',
+            };
             if (memoKey) this._opUsageTotalsCache.set(memoKey, result);
             return result;
         }
@@ -1412,7 +1500,9 @@ class ProjectIndex {
             calls,
             definitions,
             imports,
-            references
+            references,
+            complete: true,
+            countKind: 'detailed-ast-usages',
         };
     }
 
@@ -1434,11 +1524,53 @@ class ProjectIndex {
      * @param {string} typeName - The class/struct/interface name
      * @returns {Array} Methods belonging to this type
      */
-    findMethodsForType(typeName) {
+    findMethodsForType(typeName, definition = null) {
         const methods = [];
         // Match both "TypeName" and "*TypeName" receivers (for Go/Rust pointer receivers)
         const baseTypeName = typeName.replace(/^\*/, '');
 
+        const targetLanguage = definition?.file
+            ? this.files.get(definition.file)?.language : null;
+        const targetNamespace = definition?.namespace || null;
+        const targetDir = definition?.file ? path.dirname(definition.file) : null;
+        const sameCompilerType = symbol => {
+            if (!definition || !targetLanguage) return true;
+            const language = this.files.get(symbol.file)?.language;
+            if (language !== targetLanguage) return false;
+            if (['javascript', 'typescript', 'tsx', 'python', 'html']
+                .includes(targetLanguage)) return symbol.file === definition.file;
+            if (targetLanguage === 'go') return path.dirname(symbol.file) === targetDir;
+            if (targetLanguage === 'java' || targetLanguage === 'csharp') {
+                return (symbol.namespace || null) === targetNamespace;
+            }
+            if (targetLanguage === 'c' || targetLanguage === 'cpp') {
+                if (symbol.file === definition.file) return true;
+                const reachable = (from, to) => {
+                    const queue = [from];
+                    const seen = new Set(queue);
+                    for (let depth = 0; queue.length > 0 && depth < 16; depth++) {
+                        const current = queue.shift();
+                        for (const imported of this.importGraph.get(current) || []) {
+                            if (imported === to) return true;
+                            if (!seen.has(imported)) {
+                                seen.add(imported);
+                                queue.push(imported);
+                            }
+                        }
+                    }
+                    return false;
+                };
+                return reachable(symbol.file, definition.file) ||
+                    reachable(definition.file, symbol.file);
+            }
+            if (targetLanguage === 'rust') {
+                const typeDefs = (this.symbols.get(baseTypeName) || []).filter(candidate =>
+                    ['struct', 'enum', 'trait', 'type'].includes(candidate.type));
+                return typeDefs.length === 1 || symbol.file === definition.file;
+            }
+            return symbol.file === definition.file;
+        };
+
         for (const [, symbols] of this.symbols) {
             for (const symbol of symbols) {
                 // Skip non-method types (fields, properties, etc.)
@@ -1450,7 +1582,7 @@ class ProjectIndex {
                 // Also matches Rust associated functions (have receiver but isMethod=false)
                 if (symbol.receiver) {
                     const receiverBase = symbol.receiver.replace(/^\*/, '');
-                    if (receiverBase === baseTypeName) {
+                    if (receiverBase === baseTypeName && sameCompilerType(symbol)) {
                         methods.push(symbol);
                         continue;
                     }
@@ -1459,7 +1591,8 @@ class ProjectIndex {
                 // Check Python/Java/JS-style className (class members)
                 // Must be a method type, not just any symbol with className
                 if (symbol.className === baseTypeName &&
-                    (symbol.isMethod || symbol.type === 'method' || symbol.type === 'constructor')) {
+                    (symbol.isMethod || symbol.type === 'method' || symbol.type === 'constructor') &&
+                    sameCompilerType(symbol)) {
                     methods.push(symbol);
                     continue;
                 }
@@ -1496,7 +1629,7 @@ class ProjectIndex {
      * @returns {boolean} true if ALL occurrences of name are inside strings
      */
     isInsideStringAST(content, lineNum, line, name, filePath) {
-        const language = detectLanguage(filePath);
+        const language = detectLanguage(filePath, this.root);
         if (!language) {
             return false; // Unsupported language - assume not inside string
         }
@@ -1617,6 +1750,18 @@ class ProjectIndex {
             parts.push(def.modifiers.join(' '));
         }
         parts.push(def.name);
+        const dataMember = def.type === 'field' || def.type === 'state' ||
+            def.memberType === 'field' || def.memberType === 'property';
+        if (dataMember) {
+            const declaredType = def.fieldType || def.returnType;
+            if (declaredType) {
+                parts.push(`: ${String(declaredType).replace(/\s+/g, ' ').trim()}`);
+            }
+            return parts.join(' ');
+        }
+        if (def.type === 'macro' && def.functionLike === false) {
+            return parts.join(' ');
+        }
         if (def.params !== undefined) {
             // Prefer typed rendering when paramTypes/paramsStructured carry annotations
             const { renderTypedParams } = require('./output/shared');
@@ -1641,12 +1786,12 @@ class ProjectIndex {
      * @returns {string} 'call', 'import', 'definition', or 'reference'
      */
     classifyUsageAST(content, lineNum, name, filePath) {
-        const language = detectLanguage(filePath);
+        const language = detectLanguage(filePath, this.root);
         if (!language) {
             return null; // Signal to use fallback
         }
 
-        const langModule = getLanguageModule(language);
+        const langModule = getLanguageAdapter(language);
         if (!langModule || typeof langModule.findUsagesInCode !== 'function') {
             return null;
         }
@@ -1680,7 +1825,7 @@ class ProjectIndex {
      * @returns {boolean}
      */
     isCommentOrStringAtPosition(content, lineNum, column, filePath) {
-        const language = detectLanguage(filePath);
+        const language = detectLanguage(filePath, this.root);
         if (!language) {
             return false; // Can't determine, assume code
         }
@@ -1844,6 +1989,62 @@ class ProjectIndex {
                     'FunctionalInterface', 'SafeVarargs',
                     'Iterable', 'Comparable', 'AutoCloseable', 'Cloneable',
                     'Enum', 'Record', 'Void'
+                ]),
+                c: new Set([
+                    'auto', 'break', 'case', 'char', 'const', 'continue',
+                    'default', 'do', 'double', 'else', 'enum', 'extern',
+                    'float', 'for', 'goto', 'if', 'inline', 'int', 'long',
+                    'register', 'restrict', 'return', 'short', 'signed',
+                    'sizeof', 'static', 'struct', 'switch', 'typedef', 'union',
+                    'unsigned', 'void', 'volatile', 'while', '_Bool',
+                    '_Complex', '_Atomic', '_Generic', '_Noreturn',
+                    'NULL', 'true', 'false', 'size_t', 'ptrdiff_t',
+                    'printf', 'fprintf', 'sprintf', 'snprintf', 'scanf',
+                    'malloc', 'calloc', 'realloc', 'free', 'memcpy', 'memmove',
+                    'memset', 'strlen', 'strcmp', 'strcpy', 'strncpy',
+                    'fopen', 'fclose', 'fread', 'fwrite', 'exit', 'abort',
+                ]),
+                cpp: new Set([
+                    'alignas', 'alignof', 'and', 'and_eq', 'asm', 'auto',
+                    'bitand', 'bitor', 'bool', 'break', 'case', 'catch',
+                    'char', 'char8_t', 'char16_t', 'char32_t', 'class',
+                    'compl', 'concept', 'const', 'consteval', 'constexpr',
+                    'constinit', 'const_cast', 'continue', 'co_await',
+                    'co_return', 'co_yield', 'decltype', 'default', 'delete',
+                    'do', 'double', 'dynamic_cast', 'else', 'enum', 'explicit',
+                    'export', 'extern', 'false', 'float', 'for', 'friend',
+                    'goto', 'if', 'inline', 'int', 'long', 'mutable',
+                    'namespace', 'new', 'noexcept', 'not', 'nullptr',
+                    'operator', 'or', 'private', 'protected', 'public',
+                    'register', 'reinterpret_cast', 'requires', 'return',
+                    'short', 'signed', 'sizeof', 'static', 'static_assert',
+                    'static_cast', 'struct', 'switch', 'template', 'this',
+                    'thread_local', 'throw', 'true', 'try', 'typedef',
+                    'typeid', 'typename', 'union', 'unsigned', 'using',
+                    'virtual', 'void', 'volatile', 'wchar_t', 'while',
+                    'std', 'string', 'vector', 'map', 'unordered_map', 'set',
+                    'unique_ptr', 'shared_ptr', 'weak_ptr', 'optional',
+                    'variant', 'tuple', 'move', 'forward', 'make_shared',
+                    'make_unique', 'cout', 'cerr', 'cin', 'endl',
+                ]),
+                csharp: new Set([
+                    'abstract', 'as', 'base', 'bool', 'break', 'byte', 'case',
+                    'catch', 'char', 'checked', 'class', 'const', 'continue',
+                    'decimal', 'default', 'delegate', 'do', 'double', 'else',
+                    'enum', 'event', 'explicit', 'extern', 'false', 'finally',
+                    'fixed', 'float', 'for', 'foreach', 'goto', 'if',
+                    'implicit', 'in', 'int', 'interface', 'internal', 'is',
+                    'lock', 'long', 'namespace', 'new', 'null', 'object',
+                    'operator', 'out', 'override', 'params', 'private',
+                    'protected', 'public', 'readonly', 'record', 'ref',
+                    'return', 'sbyte', 'sealed', 'short', 'sizeof',
+                    'stackalloc', 'static', 'string', 'struct', 'switch',
+                    'this', 'throw', 'true', 'try', 'typeof', 'uint', 'ulong',
+                    'unchecked', 'unsafe', 'ushort', 'using', 'virtual',
+                    'void', 'volatile', 'while', 'async', 'await', 'var',
+                    'dynamic', 'yield', 'Console', 'Math', 'String', 'Object',
+                    'Task', 'ValueTask', 'List', 'Dictionary', 'HashSet',
+                    'IEnumerable', 'IDisposable', 'Exception',
                 ])
             };
             // TypeScript/TSX share JavaScript keywords
@@ -2181,6 +2382,12 @@ class ProjectIndex {
     /** Load index from cache file */
     loadCache(cachePath) { return indexCache.loadCache(this, cachePath); }
 
+    /** Return this project's default per-user cache file path. */
+    getCachePath() { return indexCache.getProjectCachePath(this.root); }
+
+    /** Remove this project's per-user cache and any legacy project-local cache. */
+    clearCache() { return indexCache.clearProjectCache(this.root); }
+
     /** Load callsCache from separate file on demand (called by findCallers/findCallees) */
     loadCallsCache() { return indexCache.loadCallsCache(this); }