ucn 3.7.36 → 3.7.37

package/core/callers.js

@@ -140,7 +140,12 @@ function findCallers(index, name, options = {}) {
                 // Resolve binding within this file (without mutating cached call objects)
                 let bindingId = call.bindingId;
                 let isUncertain = call.uncertain;
-                if (!bindingId) {
+                // Skip binding resolution for method calls with non-self/this/cls receivers:
+                // e.g., analyzer.analyze_instrument() should NOT resolve to a local
+                // standalone function def `analyze_instrument` — they're different symbols.
+                const selfReceivers = new Set(['self', 'cls', 'this', 'super']);
+                const skipLocalBinding = call.isMethod && call.receiver && !selfReceivers.has(call.receiver);
+                if (!bindingId && !skipLocalBinding) {
                     let bindings = (fileEntry.bindings || []).filter(b => b.name === call.name);
                     // For Go, also check sibling files in same directory (same package scope)
                     if (bindings.length === 0 && fileEntry.language === 'go') {
@@ -615,7 +620,8 @@ function findCallees(index, def, options = {}) {
         }
 
         // Second pass: resolve Python self.attr.method() calls
-        if (selfAttrCalls && def.className) {
+        // Respect includeMethods=false — skip self/this method resolution entirely
+        if (selfAttrCalls && def.className && options.includeMethods !== false) {
             const attrTypes = getInstanceAttributeTypes(index, def.file, def.className);
             if (attrTypes) {
                 for (const call of selfAttrCalls) {
@@ -646,7 +652,8 @@ function findCallees(index, def, options = {}) {
 
         // Third pass: resolve self/this/super.method() calls to same-class or parent methods
         // Falls back to walking the inheritance chain if not found in same class
-        if (selfMethodCalls && def.className) {
+        // Respect includeMethods=false — skip self/this method resolution entirely
+        if (selfMethodCalls && def.className && options.includeMethods !== false) {
             for (const call of selfMethodCalls) {
                 const symbols = index.symbols.get(call.name);
                 if (!symbols) continue;

package/core/deadcode.js

@@ -52,6 +52,44 @@ function buildUsageIndex(index) {
                     node.type === 'shorthand_property_identifier' ||
                     node.type === 'shorthand_property_identifier_pattern' ||
                     node.type === 'field_identifier') {
+                    // Skip property_identifier/field_identifier when they're:
+                    // 1. The property part of a member expression (e.g., obj.Separator)
+                    // 2. An object literal key (e.g., { Separator: value })
+                    // These are NOT references to standalone symbols.
+                    // Shorthand properties ({ Separator }) use shorthand_property_identifier instead.
+                    if ((node.type === 'property_identifier' || node.type === 'field_identifier') && node.parent) {
+                        const parentType = node.parent.type;
+                        // Object literal key: { Separator: 'value' } — not a reference
+                        if (parentType === 'pair' || parentType === 'key_value_pair' ||
+                            parentType === 'dictionary_entry' || parentType === 'field_declaration') {
+                            // Check if this is the key (first child) of the pair
+                            const firstChild = node.parent.child(0);
+                            if (firstChild === node) {
+                                for (let i = 0; i < node.childCount; i++) {
+                                    traverse(node.child(i));
+                                }
+                                return;
+                            }
+                        }
+                        // Member expression property: obj.Separator — not a standalone reference
+                        if (parentType === 'member_expression' ||
+                            parentType === 'field_expression' ||
+                            parentType === 'member_access_expression' ||
+                            parentType === 'selector_expression' ||       // Go
+                            parentType === 'field_access_expression' ||   // Rust
+                            parentType === 'scoped_identifier') {         // Rust
+                            // Check if this is the property (right side) of the member expression
+                            // by checking if it's NOT the object (left side)
+                            const firstChild = node.parent.child(0);
+                            if (firstChild !== node) {
+                                // This is the property part — skip it for deadcode counting
+                                for (let i = 0; i < node.childCount; i++) {
+                                    traverse(node.child(i));
+                                }
+                                return;
+                            }
+                        }
+                    }
                     const name = node.text;
                     if (!usageIndex.has(name)) {
                         usageIndex.set(name, []);

package/core/execute.js

@@ -306,6 +306,7 @@ const HANDLERS = {
             exclude,
             in: p.in,
             regex: p.regex,
+            top: num(p.top, undefined),
         });
         return { ok: true, result };
     },

package/core/output.js

@@ -2048,6 +2048,10 @@ function formatSearch(results, term) {
         }
     }
 
+    if (meta && meta.truncatedMatches > 0) {
+        lines.push(`\n${results.reduce((s, r) => s + r.matches.length, 0)} shown of ${meta.totalMatches} total matches. Use top= to see more.`);
+    }
+
     return lines.join('\n');
 }
 

package/core/project.js

@@ -1737,20 +1737,19 @@ class ProjectIndex {
         // 2. From the class the method belongs to
         if (def.className) addIfType(def.className);
 
-        // 3. From function body — scan for project-defined type references
+        // 3. From function body — always scan for project-defined type references
         //    (constructors, type annotations, isinstance checks)
-        if (types.size === 0) {
-            const code = this.extractCode(def);
-            if (code) {
-                // Find capitalized identifiers that match project types
-                const bodyMatches = code.match(/\b([A-Z][A-Za-z0-9_]*)\b/g);
-                if (bodyMatches) {
-                    const seen = new Set();
-                    for (const m of bodyMatches) {
-                        if (!seen.has(m)) {
-                            seen.add(m);
-                            addIfType(m);
-                        }
+        //    Not just a fallback — methods may reference types beyond their own class
+        const code = this.extractCode(def);
+        if (code) {
+            // Find capitalized identifiers that match project types
+            const bodyMatches = code.match(/\b([A-Z][A-Za-z0-9_]*)\b/g);
+            if (bodyMatches) {
+                const seen = new Set();
+                for (const m of bodyMatches) {
+                    if (!seen.has(m)) {
+                        seen.add(m);
+                        addIfType(m);
                     }
                 }
             }
@@ -2643,11 +2642,17 @@ class ProjectIndex {
             }
         }
 
-        // Add smart hint when resolved function has zero callees and alternatives exist
-        if (tree && tree.children && tree.children.length === 0 && definitions.length > 1 && !options.file) {
-            warnings.push({
-                message: `Resolved to ${def.relativePath}:${def.startLine} which has no callees. ${definitions.length - 1} other definition(s) exist — specify a file to pick a different one.`
-            });
+        // Add smart hint when resolved function has zero callees
+        if (tree && tree.children && tree.children.length === 0) {
+            if (maxDepth === 0) {
+                warnings.push({
+                    message: `depth=0: showing root function only. Increase depth to see callees.`
+                });
+            } else if (definitions.length > 1 && !options.file) {
+                warnings.push({
+                    message: `Resolved to ${def.relativePath}:${def.startLine} which has no callees. ${definitions.length - 1} other definition(s) exist — specify a file to pick a different one.`
+                });
+            }
         }
 
         return {
@@ -2680,58 +2685,140 @@ class ProjectIndex {
         if (!def) {
             return null;
         }
-        const usages = this.usages(name, { codeOnly: true });
-        const targetBindingId = def.bindingId;
-        const calls = usages.filter(u => {
-            if (u.usageType !== 'call' || u.isDefinition) return false;
-            const fileEntry = this.files.get(u.file);
-            if (fileEntry) {
-                // Filter by binding: skip calls from files that define their own version of this function
-                // For Go, also check sibling files in same directory (same package scope)
-                if (targetBindingId) {
-                    let localBindings = (fileEntry.bindings || []).filter(b => b.name === name);
-                    if (localBindings.length === 0 && fileEntry.language === 'go') {
-                        const dir = path.dirname(u.file);
-                        for (const [fp, fe] of this.files) {
-                            if (fp !== u.file && path.dirname(fp) === dir) {
-                                const sibling = (fe.bindings || []).filter(b => b.name === name);
-                                localBindings = localBindings.concat(sibling);
+        const defIsMethod = def.isMethod || def.type === 'method' || def.className;
+
+        // Use findCallers for className-scoped or method queries (sophisticated binding resolution)
+        // Fall back to usages-based approach for simple function queries (backward compatible)
+        let callSites;
+        if (options.className || defIsMethod) {
+            // findCallers has proper method call resolution (self/this, binding IDs, receiver checks)
+            let callerResults = this.findCallers(name, {
+                includeMethods: true,
+                includeUncertain: false,
+                targetDefinitions: [def],
+            });
+
+            // When className is explicitly provided, filter out method calls whose
+            // receiver clearly belongs to a different type. This helps with common
+            // method names like .close(), .get() etc. where many objects have the same method.
+            if (options.className && def.className) {
+                const targetClassName = def.className;
+                callerResults = callerResults.filter(c => {
+                    // Keep non-method calls and self/this/cls calls (already resolved by findCallers)
+                    if (!c.isMethod) return true;
+                    const r = c.receiver;
+                    if (!r || ['self', 'cls', 'this', 'super'].includes(r)) return true;
+                    // Check if receiver matches the target class name (case-insensitive camelCase convention)
+                    if (r.toLowerCase().includes(targetClassName.toLowerCase())) return true;
+                    // Check if receiver is an instance of the target class using local variable type inference
+                    if (c.callerFile) {
+                        const callerDef = c.callerStartLine ? { file: c.callerFile, startLine: c.callerStartLine, endLine: c.callerEndLine } : null;
+                        if (callerDef) {
+                            const callerCalls = this.getCachedCalls(c.callerFile);
+                            if (callerCalls && Array.isArray(callerCalls)) {
+                                const localTypes = new Map();
+                                for (const call of callerCalls) {
+                                    if (call.line >= callerDef.startLine && call.line <= callerDef.endLine) {
+                                        if (!call.isMethod && !call.receiver) {
+                                            const syms = this.symbols.get(call.name);
+                                            if (syms && syms.some(s => s.type === 'class')) {
+                                                // Found a constructor call — check for assignment pattern
+                                                const fileEntry = this.files.get(c.callerFile);
+                                                if (fileEntry) {
+                                                    const content = this._readFile(c.callerFile);
+                                                    const lines = content.split('\n');
+                                                    const line = lines[call.line - 1] || '';
+                                                    // Match "var = ClassName(...)"
+                                                    const m = line.match(/^\s*(\w+)\s*=\s*(?:await\s+)?(\w+)\s*\(/);
+                                                    if (m && m[2] === call.name) {
+                                                        localTypes.set(m[1], call.name);
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                                const receiverType = localTypes.get(r);
+                                if (receiverType) {
+                                    return receiverType === targetClassName;
+                                }
                             }
                         }
                     }
-                    if (localBindings.length > 0 && !localBindings.some(b => b.id === targetBindingId)) {
-                        return false; // This file/package has its own definition — call is to that, not our target
-                    }
-                }
-                // Cross-reference with findCallsInCode to filter local closures and built-ins
-                // (findCallsInCode has scope-aware filtering that findUsagesInCode lacks)
-                const parsedCalls = this.getCachedCalls(u.file);
-                if (parsedCalls && Array.isArray(parsedCalls)) {
-                    const hasCall = parsedCalls.some(c => c.name === name && c.line === u.line);
-                    if (!hasCall) return false;
-                }
+                    // When className is explicitly set and we can't determine the receiver type,
+                    // still include the call (conservative: prefer false positives over false negatives)
+                    return true;
+                });
             }
-            return true;
-        });
 
-        // Analyze each call site, filtering out method calls for non-method definitions
-        const defIsMethod = def.isMethod || def.type === 'method' || def.className;
-        const callSites = [];
-        for (const call of calls) {
-            const analysis = this.analyzeCallSite(call, name);
-            // Skip method calls (obj.parse()) when target is a standalone function (parse())
-            if (analysis.isMethodCall && !defIsMethod) {
-                continue;
+            callSites = [];
+            for (const c of callerResults) {
+                const analysis = this.analyzeCallSite(
+                    { file: c.file, relativePath: c.relativePath, line: c.line, content: c.content },
+                    name
+                );
+                callSites.push({
+                    file: c.relativePath,
+                    line: c.line,
+                    expression: c.content.trim(),
+                    callerName: c.callerName,
+                    ...analysis
+                });
             }
-            callSites.push({
-                file: call.relativePath,
-                line: call.line,
-                expression: call.content.trim(),
-                callerName: this.findEnclosingFunction(call.file, call.line),
-                ...analysis
+            this._clearTreeCache();
+        } else {
+            const usages = this.usages(name, { codeOnly: true });
+            const targetBindingId = def.bindingId;
+            const calls = usages.filter(u => {
+                if (u.usageType !== 'call' || u.isDefinition) return false;
+                const fileEntry = this.files.get(u.file);
+                if (fileEntry) {
+                    // Filter by binding: skip calls from files that define their own version of this function
+                    // For Go, also check sibling files in same directory (same package scope)
+                    if (targetBindingId) {
+                        let localBindings = (fileEntry.bindings || []).filter(b => b.name === name);
+                        if (localBindings.length === 0 && fileEntry.language === 'go') {
+                            const dir = path.dirname(u.file);
+                            for (const [fp, fe] of this.files) {
+                                if (fp !== u.file && path.dirname(fp) === dir) {
+                                    const sibling = (fe.bindings || []).filter(b => b.name === name);
+                                    localBindings = localBindings.concat(sibling);
+                                }
+                            }
+                        }
+                        if (localBindings.length > 0 && !localBindings.some(b => b.id === targetBindingId)) {
+                            return false; // This file/package has its own definition — call is to that, not our target
+                        }
+                    }
+                    // Cross-reference with findCallsInCode to filter local closures and built-ins
+                    // (findCallsInCode has scope-aware filtering that findUsagesInCode lacks)
+                    const parsedCalls = this.getCachedCalls(u.file);
+                    if (parsedCalls && Array.isArray(parsedCalls)) {
+                        const hasCall = parsedCalls.some(c => c.name === name && c.line === u.line);
+                        if (!hasCall) return false;
+                    }
+                }
+                return true;
             });
+
+            // Analyze each call site, filtering out method calls for non-method definitions
+            callSites = [];
+            for (const call of calls) {
+                const analysis = this.analyzeCallSite(call, name);
+                // Skip method calls (obj.parse()) when target is a standalone function (parse())
+                if (analysis.isMethodCall && !defIsMethod) {
+                    continue;
+                }
+                callSites.push({
+                    file: call.relativePath,
+                    line: call.line,
+                    expression: call.content.trim(),
+                    callerName: this.findEnclosingFunction(call.file, call.line),
+                    ...analysis
+                });
+            }
+            this._clearTreeCache();
         }
-        this._clearTreeCache();
 
         // Apply exclude filter
         let filteredSites = callSites;
@@ -2846,7 +2933,6 @@ class ProjectIndex {
         try {
         const maxCallers = options.all ? Infinity : (options.maxCallers || 10);
         const maxCallees = options.all ? Infinity : (options.maxCallees || 10);
-        const includeMethods = options.includeMethods ?? false;
 
         // Find symbol definition(s) — skip counts since about() computes its own via usages()
         const definitions = this.find(name, { exact: true, file: options.file, className: options.className, skipCounts: true });
@@ -2879,6 +2965,11 @@ class ProjectIndex {
         // Use the actual symbol name (may differ from query if fuzzy matched)
         const symbolName = primary.name;
 
+        // Default includeMethods: true when target is a class method (method calls are the primary way
+        // class methods are invoked), false for standalone functions (reduces noise from unrelated obj.fn() calls)
+        const isMethod = !!(primary.isMethod || primary.type === 'method' || primary.className);
+        const includeMethods = options.includeMethods ?? isMethod;
+
         // Get usage counts by type
         const usages = this.usages(symbolName, { codeOnly: true });
         const usagesByType = {
@@ -3141,7 +3232,28 @@ class ProjectIndex {
             }
         }
 
-        results.meta = { filesScanned, filesSkipped, totalFiles: this.files.size, regexFallback };
+        // Apply top limit (limits total matches across all files)
+        const totalMatches = results.reduce((sum, r) => sum + r.matches.length, 0);
+        let truncatedMatches = 0;
+        if (options.top && options.top > 0 && totalMatches > options.top) {
+            let remaining = options.top;
+            const truncated = [];
+            for (const r of results) {
+                if (remaining <= 0) break;
+                if (r.matches.length <= remaining) {
+                    truncated.push(r);
+                    remaining -= r.matches.length;
+                } else {
+                    truncated.push({ ...r, matches: r.matches.slice(0, remaining) });
+                    remaining = 0;
+                }
+            }
+            truncatedMatches = totalMatches - options.top;
+            results.length = 0;
+            results.push(...truncated);
+        }
+
+        results.meta = { filesScanned, filesSkipped, totalFiles: this.files.size, regexFallback, totalMatches, truncatedMatches };
         return results;
         } finally { this._endOp(); }
     }

package/core/stacktrace.js

@@ -189,7 +189,9 @@ function createStackFrame(index, filePath, lineNum, funcName, col, rawLine) {
                 frame.context = contextLines;
             }
 
-            // Try to find function info (verify it contains the line)
+            // Try to find function info — always use AST to find enclosing function at this line,
+            // then verify against the parsed function name from the stack trace
+            const enclosing = index.findEnclosingFunction(resolvedPath, lineNum, true);
             if (funcName) {
                 const symbols = index.symbols.get(funcName);
                 if (symbols) {
@@ -205,9 +207,21 @@ function createStackFrame(index, filePath, lineNum, funcName, col, rawLine) {
                             params: funcMatch.params
                         };
                         frame.confidence = 1.0; // High confidence when function verified
+                    } else if (enclosing) {
+                        // Stack trace function name doesn't match — use AST-resolved function
+                        // (source may have changed, or the name was from a transpiled/minified trace)
+                        frame.functionInfo = {
+                            name: enclosing.name,
+                            startLine: enclosing.startLine,
+                            endLine: enclosing.endLine,
+                            params: enclosing.params,
+                            inferred: true,
+                            traceName: funcName  // preserve original name from stack trace
+                        };
+                        frame.confidence = Math.min(frame.confidence, 0.7);
                     } else {
-                        // Function exists but line doesn't match - lower confidence
-                        const anyMatch = symbols.find(s => s.file === resolvedPath);
+                        // Function name doesn't match AND no enclosing function found
+                        const anyMatch = symbols?.find(s => s.file === resolvedPath);
                         if (anyMatch) {
                             frame.functionInfo = {
                                 name: anyMatch.name,
@@ -219,19 +233,27 @@ function createStackFrame(index, filePath, lineNum, funcName, col, rawLine) {
                             frame.confidence = Math.min(frame.confidence, 0.5);
                         }
                     }
-                }
-            } else {
-                // No function name in stack - find enclosing function
-                const enclosing = index.findEnclosingFunction(resolvedPath, lineNum, true);
-                if (enclosing) {
+                } else if (enclosing) {
+                    // funcName not in symbol table — use AST enclosing function
                     frame.functionInfo = {
                         name: enclosing.name,
                         startLine: enclosing.startLine,
                         endLine: enclosing.endLine,
                         params: enclosing.params,
-                        inferred: true
+                        inferred: true,
+                        traceName: funcName
                     };
+                    frame.confidence = Math.min(frame.confidence, 0.6);
                 }
+            } else if (enclosing) {
+                // No function name in stack - find enclosing function
+                frame.functionInfo = {
+                    name: enclosing.name,
+                    startLine: enclosing.startLine,
+                    endLine: enclosing.endLine,
+                    params: enclosing.params,
+                    inferred: true
+                };
             }
         } catch (e) {
             frame.error = e.message;

package/core/verify.js

@@ -5,8 +5,10 @@
  * as the first argument instead of using `this`.
  */
 
+const path = require('path');
 const { detectLanguage, getParser, getLanguageModule, safeParse } = require('../languages');
 const { escapeRegExp } = require('./shared');
+const { extractImports } = require('./imports');
 
 /**
  * Find a call expression node at the target line matching funcName
@@ -199,24 +201,73 @@ function verify(index, name, options = {}) {
     const optionalCount = nonRestParams.filter(p => p.optional || p.default !== undefined).length;
     const minArgs = expectedParamCount - optionalCount;
 
-    // Get all call sites
-    const usages = index.usages(name, { codeOnly: true });
-    const calls = usages.filter(u => u.usageType === 'call' && !u.isDefinition);
+    // Get all call sites using findCallers for accurate resolution
+    // (usages-based approach misses calls when className is set or local names collide)
+    const callerResults = index.findCallers(name, {
+        includeMethods: true,
+        includeUncertain: false,
+        targetDefinitions: [def],
+    });
+    // Convert caller results to usage-like objects for analyzeCallSite
+    const calls = callerResults.map(c => ({
+        file: c.file,
+        relativePath: c.relativePath,
+        line: c.line,
+        content: c.content,
+        usageType: 'call',
+        receiver: c.receiver,
+    }));
 
     const valid = [];
     const mismatches = [];
     const uncertain = [];
 
     // If the definition is NOT a method, filter out method calls (e.g., dict.get() vs get())
-    // This prevents false positives where a standalone function name matches method calls
-    const defIsMethod = def.isMethod || def.type === 'method' || def.className;
+    // This prevents false positives where a standalone function name matches method calls.
+    // Exception: module-level calls (module.func()) are kept when the receiver matches the
+    // target module's name and is an imported name (e.g., jobs.submit() where jobs is imported
+    // and the function lives in jobs.py).
+    const defIsMethod = !!(def.isMethod || def.type === 'method' || def.className);
+    const targetBasename = path.basename(def.file, path.extname(def.file));
+
+    // Build import-name lookup for receiver checking (module.func() vs dict.get())
+    const importNameCache = new Map();
+    function getImportedNames(filePath) {
+        if (importNameCache.has(filePath)) return importNameCache.get(filePath);
+        const names = new Set();
+        const fe = index.files.get(filePath);
+        if (!fe) { importNameCache.set(filePath, names); return names; }
+        try {
+            const content = index._readFile(filePath);
+            const { imports: rawImports, importAliases } = extractImports(content, fe.language);
+            for (const imp of rawImports) {
+                if (imp.names) for (const n of imp.names) names.add(n);
+            }
+            if (importAliases) {
+                for (const alias of importAliases) names.add(alias.local);
+            }
+        } catch (e) { /* skip */ }
+        importNameCache.set(filePath, names);
+        return names;
+    }
 
     for (const call of calls) {
         const analysis = analyzeCallSite(index, call, name);
 
-        // Skip method calls when verifying a non-method definition
+        // Skip method calls when verifying a non-method definition.
+        // This prevents false positives (e.g., dict.get() vs standalone get()).
+        // Allow module-level calls only when:
+        // 1. Receiver matches target file's basename (e.g., jobs == jobs for jobs.py)
+        // 2. Receiver is an imported name (not a local variable)
         if (analysis.isMethodCall && !defIsMethod) {
-            continue;
+            const callReceiver = call.receiver;
+            if (callReceiver && callReceiver === targetBasename) {
+                const importedNames = getImportedNames(call.file);
+                if (!importedNames.has(callReceiver)) continue;
+                // Receiver matches target module and is imported — keep it
+            } else {
+                continue;
+            }
         }
 
         if (analysis.args === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.36",
+  "version": "3.7.37",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Universal Code Navigator — AST-based call graph analysis for AI agents. Find callers, trace impact, detect dead code across JS/TS, Python, Go, Rust, Java, and HTML. CLI, MCP server, and agent skill.",
   "main": "index.js",