ucn 3.8.21 → 3.8.23

package/core/project.js

@@ -23,6 +23,7 @@ const tracingModule = require('./tracing');
 const searchModule = require('./search');
 const analysisModule = require('./analysis');
 const graphModule = require('./graph');
+const graphBuildModule = require('./graph-build');
 const reportingModule = require('./reporting');
 
 // Lazy-initialized per-language keyword sets (populated on first isKeyword call)
@@ -76,6 +77,7 @@ class ProjectIndex {
             this._opContentCache = new Map();
             this._opUsagesCache = new Map();
             this._opCallsCountCache = new Map();
+            this._opEnclosingFnCache = new Map();
             this._opDepth = 0;
         }
         this._opDepth++;
@@ -83,10 +85,17 @@ class ProjectIndex {
 
     /** End a per-operation content cache scope (only clears when outermost scope ends) */
     _endOp() {
+        if (!this._opContentCache) return; // Mismatched call — no active operation
         if (--this._opDepth <= 0) {
             this._opContentCache = null;
             this._opUsagesCache = null;
             this._opCallsCountCache = null;
+            this._opEnclosingFnCache = null;
+            // Free cached file content from callsCache entries (retained during
+            // operation for _readFile caching, not needed between operations)
+            for (const entry of this.callsCache.values()) {
+                if (entry.content !== undefined) entry.content = undefined;
+            }
             this._opDepth = 0;
         }
     }
@@ -473,30 +482,78 @@ class ProjectIndex {
             }
         }
 
-        // Invalidate cached call data for this file
+        // Incrementally update callee index before deleting cached calls
+        const oldCached = this.callsCache.get(filePath);
+        if (oldCached) {
+            this._removeFromCalleeIndex(filePath, oldCached.calls);
+        }
         this.callsCache.delete(filePath);
 
-        // Invalidate callee index (will be rebuilt lazily)
-        this.calleeIndex = null;
-
         // Invalidate attribute type cache for this file
         if (this._attrTypeCache) this._attrTypeCache.delete(filePath);
+
+        // Invalidate lazy Java file index (will be rebuilt on next use)
+        this._javaFileIndex = null;
     }
 
     /**
      * Build directory→files index for O(1) same-package lookups.
      * Replaces O(N) full-index scans in findCallers and countSymbolUsages.
      */
-    _buildDirIndex() {
-        this.dirToFiles = new Map();
-        for (const filePath of this.files.keys()) {
-            const dir = path.dirname(filePath);
-            let list = this.dirToFiles.get(dir);
-            if (!list) {
-                list = [];
-                this.dirToFiles.set(dir, list);
+    _buildDirIndex() { graphBuildModule.buildDirIndex(this); }
+
+    /**
+     * Add a file's calls to the callee index (name → Set<filePath>).
+     * Used by buildCalleeIndex (full build) and getCachedCalls (incremental update).
+     */
+    _addToCalleeIndex(filePath, calls) {
+        if (!this.calleeIndex || !calls) return;
+        for (const call of calls) {
+            const name = call.name;
+            if (!this.calleeIndex.has(name)) {
+                this.calleeIndex.set(name, new Set());
+            }
+            this.calleeIndex.get(name).add(filePath);
+            if (call.resolvedName && call.resolvedName !== name) {
+                if (!this.calleeIndex.has(call.resolvedName)) {
+                    this.calleeIndex.set(call.resolvedName, new Set());
+                }
+                this.calleeIndex.get(call.resolvedName).add(filePath);
+            }
+            if (call.resolvedNames) {
+                for (const rn of call.resolvedNames) {
+                    if (rn !== name) {
+                        if (!this.calleeIndex.has(rn)) {
+                            this.calleeIndex.set(rn, new Set());
+                        }
+                        this.calleeIndex.get(rn).add(filePath);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Remove a file's calls from the callee index.
+     * Used by removeFileSymbols for incremental updates instead of full invalidation.
+     */
+    _removeFromCalleeIndex(filePath, calls) {
+        if (!this.calleeIndex || !calls) return;
+        for (const call of calls) {
+            const removeName = (n) => {
+                const fileSet = this.calleeIndex.get(n);
+                if (fileSet) {
+                    fileSet.delete(filePath);
+                    if (fileSet.size === 0) this.calleeIndex.delete(n);
+                }
+            };
+            removeName(call.name);
+            if (call.resolvedName && call.resolvedName !== call.name) removeName(call.resolvedName);
+            if (call.resolvedNames) {
+                for (const rn of call.resolvedNames) {
+                    if (rn !== call.name) removeName(rn);
+                }
             }
-            list.push(filePath);
         }
     }
 
@@ -507,37 +564,15 @@ class ProjectIndex {
      */
     buildCalleeIndex() {
         const { getCachedCalls } = require('./callers');
+        const { ensureCallsCacheLoaded } = require('./cache');
+        ensureCallsCacheLoaded(this);
         this.calleeIndex = new Map();
 
         for (const [filePath] of this.files) {
             // Fast path: use pre-populated callsCache (avoids stat per file)
             const cached = this.callsCache.get(filePath);
             const calls = cached ? cached.calls : getCachedCalls(this, filePath);
-            if (!calls) continue;
-            for (const call of calls) {
-                const name = call.name;
-                if (!this.calleeIndex.has(name)) {
-                    this.calleeIndex.set(name, new Set());
-                }
-                this.calleeIndex.get(name).add(filePath);
-                // Also index resolvedName and resolvedNames for alias resolution
-                if (call.resolvedName && call.resolvedName !== name) {
-                    if (!this.calleeIndex.has(call.resolvedName)) {
-                        this.calleeIndex.set(call.resolvedName, new Set());
-                    }
-                    this.calleeIndex.get(call.resolvedName).add(filePath);
-                }
-                if (call.resolvedNames) {
-                    for (const rn of call.resolvedNames) {
-                        if (rn !== name) {
-                            if (!this.calleeIndex.has(rn)) {
-                                this.calleeIndex.set(rn, new Set());
-                            }
-                            this.calleeIndex.get(rn).add(filePath);
-                        }
-                    }
-                }
-            }
+            this._addToCalleeIndex(filePath, calls);
         }
     }
 
@@ -558,194 +593,32 @@ class ProjectIndex {
      * Progressively strips trailing segments to find the class file.
      */
     _resolveJavaPackageImport(importModule, javaFileIndex) {
-        const isWildcard = importModule.endsWith('.*');
-        // Strip wildcard suffix (e.g., "com.pkg.Class.*" -> "com.pkg.Class")
-        const mod = isWildcard ? importModule.slice(0, -2) : importModule;
-        const segments = mod.split('.');
-
-        // Try progressively shorter paths: full path, then strip last segment, etc.
-        // This handles static imports where path includes member name after class
-        if (javaFileIndex) {
-            // Fast path: use pre-built filename→files index (O(candidates) vs O(all files))
-            for (let i = segments.length; i > 0; i--) {
-                const className = segments[i - 1];
-                const candidates = javaFileIndex.get(className);
-                if (candidates) {
-                    const fileSuffix = '/' + segments.slice(0, i).join('/') + '.java';
-                    for (const absPath of candidates) {
-                        if (absPath.endsWith(fileSuffix)) {
-                            return absPath;
-                        }
-                    }
-                }
-            }
-        } else {
-            // Fallback: scan all files (used by imports() method outside buildImportGraph)
-            for (let i = segments.length; i > 0; i--) {
-                const fileSuffix = '/' + segments.slice(0, i).join('/') + '.java';
-                for (const absPath of this.files.keys()) {
-                    if (absPath.endsWith(fileSuffix)) {
-                        return absPath;
+        if (!javaFileIndex) {
+            // Lazy-build index to avoid O(N) fallback scan of all files
+            if (!this._javaFileIndex) {
+                this._javaFileIndex = new Map();
+                for (const [fp, fe] of this.files) {
+                    if (fe.language === 'java') {
+                        const name = path.basename(fp, '.java');
+                        if (!this._javaFileIndex.has(name)) this._javaFileIndex.set(name, []);
+                        this._javaFileIndex.get(name).push(fp);
                     }
                 }
             }
+            javaFileIndex = this._javaFileIndex;
         }
-
-        // For wildcard imports (com.pkg.model.*), the package may be a directory
-        // containing .java files. Check if any file lives under this package path.
-        if (isWildcard) {
-            const dirSuffix = '/' + segments.join('/') + '/';
-            for (const absPath of this.files.keys()) {
-                if (absPath.includes(dirSuffix)) {
-                    return absPath;
-                }
-            }
-        }
-
-        return null;
+        return graphBuildModule._resolveJavaPackageImport(this, importModule, javaFileIndex);
     }
 
     /**
      * Build import/export relationship graphs
      */
-    buildImportGraph() {
-        this.importGraph.clear();
-        this.exportGraph.clear();
-
-        // Pre-build directory→files map for Go package linking (O(1) lookup vs O(n) scan)
-        const dirToGoFiles = new Map();
-        // Pre-build filename→files map for Java import resolution (O(1) vs O(n) scan)
-        const javaFileIndex = new Map();
-        for (const [fp, fe] of this.files) {
-            if (langTraits(fe.language)?.packageScope === 'directory') {
-                const dir = path.dirname(fp);
-                if (!dirToGoFiles.has(dir)) dirToGoFiles.set(dir, []);
-                dirToGoFiles.get(dir).push(fp);
-            } else if (fe.language === 'java') {
-                const name = path.basename(fp, '.java');
-                if (!javaFileIndex.has(name)) javaFileIndex.set(name, []);
-                javaFileIndex.get(name).push(fp);
-            }
-        }
-
-        for (const [filePath, fileEntry] of this.files) {
-            const importedFiles = [];
-            const seenModules = new Set();
-
-            for (const importModule of fileEntry.imports) {
-                // Skip null modules (e.g., dynamic include! macros in Rust)
-                if (!importModule) continue;
-
-                // Deduplicate: same module imported multiple times in one file
-                // (e.g., lazy imports inside different functions)
-                if (seenModules.has(importModule)) continue;
-                seenModules.add(importModule);
-
-                let resolved = resolveImport(importModule, filePath, {
-                    aliases: this.config.aliases,
-                    language: fileEntry.language,
-                    root: this.root
-                });
-
-                // Java package imports: resolve by progressive suffix matching
-                // Handles regular, static (com.pkg.Class.method), and wildcard (com.pkg.Class.*) imports
-                if (!resolved && fileEntry.language === 'java' && !importModule.startsWith('.')) {
-                    resolved = this._resolveJavaPackageImport(importModule, javaFileIndex);
-                }
-
-                if (resolved && this.files.has(resolved)) {
-                    // For Go, a package import means all files in that directory are dependencies
-                    // (Go packages span multiple files in the same directory)
-                    const filesToLink = [resolved];
-                    if (langTraits(fileEntry.language)?.packageScope === 'directory') {
-                        const pkgDir = path.dirname(resolved);
-                        const dirFiles = dirToGoFiles.get(pkgDir) || [];
-                        const importerIsTest = filePath.endsWith('_test.go');
-                        for (const fp of dirFiles) {
-                            if (fp !== resolved) {
-                                if (!importerIsTest && fp.endsWith('_test.go')) continue;
-                                filesToLink.push(fp);
-                            }
-                        }
-                    }
-
-                    for (const linkedFile of filesToLink) {
-                        importedFiles.push(linkedFile);
-                        if (!this.exportGraph.has(linkedFile)) {
-                            this.exportGraph.set(linkedFile, []);
-                        }
-                        this.exportGraph.get(linkedFile).push(filePath);
-                    }
-                }
-            }
-
-            this.importGraph.set(filePath, importedFiles);
-        }
-    }
+    buildImportGraph() { graphBuildModule.buildImportGraph(this); }
 
     /**
      * Build inheritance relationship graphs
      */
-    buildInheritanceGraph() {
-        this.extendsGraph.clear();
-        this.extendedByGraph.clear();
-
-        // Collect all class/interface/struct names for alias resolution
-        const classNames = new Set();
-        for (const [, fileEntry] of this.files) {
-            for (const symbol of fileEntry.symbols) {
-                if (['class', 'interface', 'struct', 'trait', 'record'].includes(symbol.type)) {
-                    classNames.add(symbol.name);
-                }
-            }
-        }
-
-        for (const [filePath, fileEntry] of this.files) {
-            for (const symbol of fileEntry.symbols) {
-                if (!['class', 'interface', 'struct', 'trait', 'record'].includes(symbol.type)) {
-                    continue;
-                }
-
-                if (symbol.extends) {
-                    // Parse comma-separated parents (Python MRO: "Flyable, Swimmable")
-                    const parents = symbol.extends.split(',').map(s => s.trim()).filter(Boolean);
-
-                    // Resolve aliased parent names via import aliases
-                    // e.g., const { BaseHandler: Handler } = require('./base')
-                    //        class Child extends Handler → resolve Handler to BaseHandler
-                    const resolvedParents = parents.map(parent => {
-                        if (classNames.has(parent)) return parent;
-                        if (fileEntry.importAliases) {
-                            const alias = fileEntry.importAliases.find(a => a.local === parent);
-                            if (alias && classNames.has(alias.original)) return alias.original;
-                        }
-                        return parent;
-                    });
-
-                    // Store with file scope to avoid collisions when same class name
-                    // appears in multiple files (F-002 fix)
-                    if (!this.extendsGraph.has(symbol.name)) {
-                        this.extendsGraph.set(symbol.name, []);
-                    }
-                    this.extendsGraph.get(symbol.name).push({
-                        file: filePath,
-                        parents: resolvedParents
-                    });
-
-                    for (const parent of resolvedParents) {
-                        if (!this.extendedByGraph.has(parent)) {
-                            this.extendedByGraph.set(parent, []);
-                        }
-                        this.extendedByGraph.get(parent).push({
-                            name: symbol.name,
-                            type: symbol.type,
-                            file: filePath
-                        });
-                    }
-                }
-            }
-        }
-    }
+    buildInheritanceGraph() { graphBuildModule.buildInheritanceGraph(this); }
 
     /**
      * Get inheritance parents for a class, scoped by file to handle
@@ -768,7 +641,7 @@ class ProjectIndex {
             if (contextFile) {
                 const imports = this.importGraph.get(contextFile);
                 if (imports) {
-                    const imported = entries.find(e => imports.includes(e.file));
+                    const imported = entries.find(e => imports.has(e.file));
                     if (imported) return imported.parents;
                 }
             }
@@ -800,7 +673,7 @@ class ProjectIndex {
         if (contextFile) {
             const imports = this.importGraph.get(contextFile);
             if (imports) {
-                const imported = classSymbols.find(s => imports.includes(s.file));
+                const imported = classSymbols.find(s => imports.has(s.file));
                 if (imported) return imported.file;
             }
         }
@@ -1010,7 +883,7 @@ class ProjectIndex {
             for (const candidate of tiedCandidates) {
                 let importerCount = 0;
                 for (const [, importedFiles] of this.importGraph) {
-                    if (importedFiles.includes(candidate.def.file)) {
+                    if (importedFiles.has(candidate.def.file)) {
                         importerCount++;
                     }
                 }
@@ -1085,8 +958,7 @@ class ProjectIndex {
             const hasFilters = options.exclude && options.exclude.length > 0;
 
             // Pre-compute which files can reference THIS specific definition
-            const importers = this.exportGraph.get(defFile) || [];
-            const importersSet = new Set(importers);
+            const importersSet = this.exportGraph.get(defFile) || new Set();
             const defEntry = this.files.get(defFile);
             const isDirectoryScope = langTraits(defEntry?.language)?.packageScope === 'directory';
             const defDir = isDirectoryScope ? path.dirname(defFile) : null;
@@ -1149,7 +1021,7 @@ class ProjectIndex {
 
             // Count imports from import graph (files that import from defFile and use this name)
             let imports = 0;
-            for (const importer of importers) {
+            for (const importer of importersSet) {
                 const fe = this.files.get(importer);
                 if (!fe) continue;
                 if (hasFilters && !this.matchesFilters(fe.relativePath, { exclude: options.exclude })) continue;
@@ -1208,7 +1080,7 @@ class ProjectIndex {
 
         while (queue.length > 0) {
             const file = queue.pop();
-            const importersArr = this.exportGraph.get(file) || [];
+            const importersArr = this.exportGraph.get(file) || new Set();
             for (const importer of importersArr) {
                 if (!relevantFiles.has(importer)) {
                     relevantFiles.add(importer);
@@ -1734,6 +1606,15 @@ class ProjectIndex {
         const fileEntry = this.files.get(filePath);
         if (!fileEntry) return null;
 
+        // Per-operation cache: avoid rescanning symbols for same (file, line)
+        const cacheKey = filePath + '\0' + lineNum;
+        if (this._opEnclosingFnCache) {
+            const cached = this._opEnclosingFnCache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached === null ? null : (returnSymbol ? cached : cached.name);
+            }
+        }
+
         let best = null;
         for (const symbol of fileEntry.symbols) {
             if (!NON_CALLABLE_TYPES.has(symbol.type) &&
@@ -1744,8 +1625,11 @@ class ProjectIndex {
                 }
             }
         }
-        if (!best) return null;
-        return returnSymbol ? best : best.name;
+
+        if (this._opEnclosingFnCache) {
+            this._opEnclosingFnCache.set(cacheKey, best);
+        }
+        return best ? (returnSymbol ? best : best.name) : null;
     }
 
     /** Get instance attribute types for a class in a file */

package/core/registry.js

@@ -143,6 +143,10 @@ const BROAD_COMMANDS = new Set([
     'deadcode', 'usages', 'reverseTrace', 'circularDeps',
 ]);
 
+// Commands that can operate on a single file without a project index.
+// Used by CLI to decide whether to build a file-local or project-wide index.
+const FILE_LOCAL_COMMANDS = new Set(['toc', 'fn', 'class', 'find', 'usages', 'search', 'lines', 'typedef', 'api']);
+
 // ============================================================================
 // HELPERS
 // ============================================================================
@@ -263,6 +267,7 @@ module.exports = {
     REVERSE_PARAM_MAP,
     FLAG_APPLICABILITY,
     BROAD_COMMANDS,
+    FILE_LOCAL_COMMANDS,
     resolveCommand,
     normalizeParams,
     getCliCommandSet,

package/core/search.js

@@ -221,11 +221,15 @@ function usages(index, name, options = {}) {
                 let _importedHasDef = null;
                 const importedFileHasDef = () => {
                     if (_importedHasDef !== null) return _importedHasDef;
-                    const importedFiles = index.importGraph.get(filePath) || [];
-                    _importedHasDef = importedFiles.some(imp => {
+                    const importedFiles = index.importGraph.get(filePath);
+                    _importedHasDef = false;
+                    if (importedFiles) for (const imp of importedFiles) {
                         const impEntry = index.files.get(imp);
-                        return impEntry?.symbols?.some(s => s.name === name);
-                    });
+                        if (impEntry?.symbols?.some(s => s.name === name)) {
+                            _importedHasDef = true;
+                            break;
+                        }
+                    }
                     return _importedHasDef;
                 };
 
@@ -1008,7 +1012,7 @@ function _buildSourceFileImporters(index, defs) {
 
     while (queue.length > 0) {
         const current = queue.shift();
-        const directImporters = index.exportGraph?.get(current) || [];
+        const directImporters = index.exportGraph?.get(current) || new Set();
         for (const imp of directImporters) {
             importers.add(imp);
             // Check if this importer re-exports the symbol (barrel pattern).

package/core/tracing.js

@@ -435,13 +435,22 @@ function reverseTrace(index, name, options = {}) {
                 if (callerEntries.length > maxChildren) {
                     node.truncatedChildren = callerEntries.length - maxChildren;
                     // Count entry points in truncated branches so summary is accurate
+                    // Use callerCache to avoid redundant findCallers calls
                     for (const { def: cDef } of callerEntries.slice(maxChildren)) {
-                        const key = `${cDef.file}:${cDef.startLine}`;
-                        if (!visited.has(key)) {
-                            const cCallers = index.findCallers(cDef.name, {
-                                includeMethods, includeUncertain,
-                                targetDefinitions: cDef.bindingId ? [cDef] : undefined,
-                            });
+                        const cKey = `${cDef.file}:${cDef.startLine}`;
+                        if (!visited.has(cKey)) {
+                            const cCacheKey = cDef.bindingId
+                                ? `${cDef.name}:${cDef.bindingId}`
+                                : `${cDef.name}:${cKey}`;
+                            let cCallers = callerCache.get(cCacheKey);
+                            if (!cCallers) {
+                                cCallers = index.findCallers(cDef.name, {
+                                    includeMethods, includeUncertain,
+                                    targetDefinitions: cDef.bindingId ? [cDef] : undefined,
+                                    maxResults: 1, // Only need to know if any exist
+                                });
+                                callerCache.set(cCacheKey, cCallers);
+                            }
                             if (cCallers.length === 0) {
                                 entryPoints.push({ name: cDef.name, file: cDef.relativePath || path.relative(index.root, cDef.file), line: cDef.startLine });
                             }

package/languages/go.js

@@ -45,14 +45,14 @@ function extractGoParams(paramsNode) {
  */
 function extractReceiver(receiverNode) {
     if (!receiverNode) return null;
-    const text = receiverNode.text;
-    // Match named receiver: (r *Router) or (r Router[T])
-    const namedMatch = text.match(/\(\s*\w+\s+(\*?\w+(?:\[[\w,\s]+\])?)\s*\)/);
-    if (namedMatch) return namedMatch[1];
-    // Match unnamed receiver: (Router) or (*Router) or (Router[T])
-    const unnamedMatch = text.match(/\(\s*(\*?\w+(?:\[[\w,\s]+\])?)\s*\)/);
-    if (unnamedMatch) return unnamedMatch[1];
-    return text.replace(/^\(|\)$/g, '').trim();
+    // receiverNode is a parameter_list: (r *Router)
+    // Find the parameter_declaration child
+    const param = receiverNode.namedChildren.find(c => c.type === 'parameter_declaration');
+    if (!param) return receiverNode.text.replace(/^\(|\)$/g, '').trim();
+    // The type is the last named child (name is first for named receivers)
+    const typeNode = param.namedChildren[param.namedChildren.length - 1];
+    if (!typeNode) return null;
+    return typeNode.text;
 }
 
 // --- Single-pass helpers: extracted from find* callbacks ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.8.21",
+  "version": "3.8.23",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Code intelligence toolkit for AI agents — extract functions, trace call chains, find callers, detect dead code without reading entire files. Works as MCP server, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java.",
   "main": "index.js",
@@ -9,7 +9,7 @@
     "ucn-mcp": "mcp/server.js"
   },
   "scripts": {
-    "test": "node --test test/parser-unit.test.js test/integration.test.js test/cache.test.js test/formatter.test.js test/interactive.test.js test/feature.test.js test/regression-js.test.js test/regression-py.test.js test/regression-go.test.js test/regression-java.test.js test/regression-rust.test.js test/regression-cross.test.js test/regression-mcp.test.js test/regression-parser.test.js test/regression-commands.test.js test/regression-fixes.test.js test/regression-bugfixes.test.js test/cross-language.test.js test/accuracy.test.js test/command-coverage.test.js test/systematic-test.js test/mcp-edge-cases.js test/parity-test.js",
+    "test": "node --test test/parser-unit.test.js test/integration.test.js test/cache.test.js test/formatter.test.js test/interactive.test.js test/feature.test.js test/regression-js.test.js test/regression-py.test.js test/regression-go.test.js test/regression-java.test.js test/regression-rust.test.js test/regression-cross.test.js test/regression-mcp.test.js test/regression-parser.test.js test/regression-commands.test.js test/regression-fixes.test.js test/regression-bugfixes.test.js test/cross-language.test.js test/accuracy.test.js test/command-coverage.test.js test/perf-optimizations.test.js test/systematic-test.js test/mcp-edge-cases.js test/parity-test.js",
     "benchmark:agent": "node test/agent-understanding-benchmark.js",
     "lint": "eslint core/ cli/ mcp/ languages/"
   },