ucn 3.8.20 → 3.8.22

package/cli/index.js

@@ -14,7 +14,7 @@ const { detectLanguage } = require('../core/parser');
 const { ProjectIndex } = require('../core/project');
 const { expandGlob, findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
-const { getCliCommandSet, resolveCommand, FLAG_APPLICABILITY, toCliName } = require('../core/registry');
+const { getCliCommandSet, resolveCommand, FLAG_APPLICABILITY, toCliName, FILE_LOCAL_COMMANDS } = require('../core/registry');
 const { execute } = require('../core/execute');
 const { ExpandCache } = require('../core/expand-cache');
 
@@ -322,7 +322,7 @@ function runFileCommand(filePath, command, arg) {
     const canonical = resolveCommand(command, 'cli') || command;
 
     // Commands that need full project index — auto-route to project mode
-    const fileLocalCommands = new Set(['toc', 'fn', 'class', 'find', 'usages', 'search', 'lines', 'typedef', 'api']);
+    const fileLocalCommands = FILE_LOCAL_COMMANDS;
 
     if (!fileLocalCommands.has(canonical)) {
         // Auto-detect project root and route to project mode

package/core/callers.js

@@ -109,7 +109,14 @@ function getCachedCalls(index, filePath, options = {}) {
 }
 
 /**
- * Find all callers of a function using AST-based detection
+ * Find all call sites that invoke the named symbol.
+ *
+ * ReceiverType filtering (nominal vs structural):
+ * - Nominal languages (Go/Java/Rust): uses call.receiverType (from parser-inferred
+ *   method receivers, constructors, composite literals) to filter false positives.
+ * - Structural languages (JS/TS/Python): checks receiver binding evidence from imports
+ *   instead of receiverType, since structural typing makes receiver types ambiguous.
+ *
  * @param {object} index - ProjectIndex instance
  * @param {string} name - Function name to find callers for
  * @param {object} [options] - Options
@@ -652,7 +659,15 @@ function findCallers(index, name, options = {}) {
 }
 
 /**
- * Find all functions called by a function using AST-based detection
+ * Find all symbols called from within a function definition.
+ *
+ * Method resolution uses receiverType when available:
+ * - Go: receiverType from method receiver params + _buildTypedLocalTypeMap (New*() patterns)
+ * - Java: receiverType from `new Foo()` constructors + typed parameter declarations
+ * - Rust: receiverType from impl block context + _buildTypedLocalTypeMap
+ * - JS/TS: receiverType from constructor calls + import binding evidence
+ * - Python: receiverType from __init__ attribute type inference (getInstanceAttributeTypes)
+ *
  * @param {object} index - ProjectIndex instance
  * @param {object} def - Symbol definition with file, name, startLine, endLine
  * @param {object} [options] - Options
@@ -1395,6 +1410,11 @@ function _buildLocalTypeMap(index, def, calls) {
  * @param {object} index - ProjectIndex instance
  * @param {object} def - Function definition with file, startLine, endLine
  * @param {Array} calls - Cached call sites for the file
+ *
+ * Sources: parser-inferred receiverType from method receivers, constructor calls,
+ * composite literals. Used by Go, Java, Rust (nominal languages) to infer local
+ * variable types for method resolution. Not used by JS/TS/Python -- structural
+ * languages use import evidence via _buildLocalTypeMap instead.
  */
 function _buildTypedLocalTypeMap(index, def, calls) {
     const localTypes = new Map();
@@ -1437,7 +1457,10 @@ function _buildTypedLocalTypeMap(index, def, calls) {
 }
 
 /**
- * Check if a function is used as a callback anywhere in the codebase
+ * Find higher-order function usages where `name` is passed as a callback argument.
+ * Handles patterns like .map(fn), setTimeout(fn), promise.then(handler).
+ * Delegates to per-language findCallbackUsages implementations.
+ *
  * @param {object} index - ProjectIndex instance
  * @param {string} name - Function name
  * @returns {Array} Callback usages

package/core/graph-build.js

@@ -0,0 +1,224 @@
+/**
+ * core/graph-build.js - Import/export and inheritance graph construction
+ *
+ * Extracted from project.js. All functions take an `index` (ProjectIndex)
+ * as the first argument instead of using `this`.
+ */
+
+const path = require('path');
+const { resolveImport } = require('./imports');
+const { langTraits } = require('../languages');
+
+/**
+ * Build directory→files index for O(1) same-package lookups.
+ * Replaces O(N) full-index scans in findCallers and countSymbolUsages.
+ */
+function buildDirIndex(index) {
+    index.dirToFiles = new Map();
+    for (const filePath of index.files.keys()) {
+        const dir = path.dirname(filePath);
+        let list = index.dirToFiles.get(dir);
+        if (!list) {
+            list = [];
+            index.dirToFiles.set(dir, list);
+        }
+        list.push(filePath);
+    }
+}
+
+/**
+ * Resolve a Java package import to a project file.
+ * Handles regular imports, static imports (strips member name), and wildcards (strips .*).
+ * Progressively strips trailing segments to find the class file.
+ */
+function _resolveJavaPackageImport(index, 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 index.files.keys()) {
+                if (absPath.endsWith(fileSuffix)) {
+                    return absPath;
+                }
+            }
+        }
+    }
+
+    // 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 index.files.keys()) {
+            if (absPath.includes(dirSuffix)) {
+                return absPath;
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Build import/export relationship graphs
+ */
+function buildImportGraph(index) {
+    index.importGraph.clear();
+    index.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 index.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 index.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: index.config.aliases,
+                language: fileEntry.language,
+                root: index.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 = _resolveJavaPackageImport(index, importModule, javaFileIndex);
+            }
+
+            if (resolved && index.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 (!index.exportGraph.has(linkedFile)) {
+                        index.exportGraph.set(linkedFile, []);
+                    }
+                    index.exportGraph.get(linkedFile).push(filePath);
+                }
+            }
+        }
+
+        index.importGraph.set(filePath, importedFiles);
+    }
+}
+
+/**
+ * Build inheritance relationship graphs
+ */
+function buildInheritanceGraph(index) {
+    index.extendsGraph.clear();
+    index.extendedByGraph.clear();
+
+    // Collect all class/interface/struct names for alias resolution
+    const classNames = new Set();
+    for (const [, fileEntry] of index.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 index.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 (!index.extendsGraph.has(symbol.name)) {
+                    index.extendsGraph.set(symbol.name, []);
+                }
+                index.extendsGraph.get(symbol.name).push({
+                    file: filePath,
+                    parents: resolvedParents
+                });
+
+                for (const parent of resolvedParents) {
+                    if (!index.extendedByGraph.has(parent)) {
+                        index.extendedByGraph.set(parent, []);
+                    }
+                    index.extendedByGraph.get(parent).push({
+                        name: symbol.name,
+                        type: symbol.type,
+                        file: filePath
+                    });
+                }
+            }
+        }
+    }
+}
+
+module.exports = { buildDirIndex, buildImportGraph, buildInheritanceGraph, _resolveJavaPackageImport };

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)
@@ -487,18 +488,7 @@ class ProjectIndex {
      * 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);
-            }
-            list.push(filePath);
-        }
-    }
+    _buildDirIndex() { graphBuildModule.buildDirIndex(this); }
 
     /**
      * Build inverted call index: callee name -> Set<filePath>.
@@ -558,194 +548,18 @@ 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;
-                    }
-                }
-            }
-        }
-
-        // 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

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/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.20",
+  "version": "3.8.22",
   "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",