ucn 3.7.30 → 3.7.31

package/cli/index.js

@@ -306,8 +306,9 @@ function runFileCommand(filePath, command, arg) {
         api:     { file: relativePath },
     };
 
-    const { ok, result, error } = execute(index, canonical, paramsByCommand[canonical]);
+    const { ok, result, error, note } = execute(index, canonical, paramsByCommand[canonical]);
     if (!ok) fail(error);
+    if (note) console.error(note);
 
     // Format output using same formatters as project mode
     switch (canonical) {
@@ -416,8 +417,9 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'find': {
-            const { ok, result, error } = execute(index, 'find', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'find', { name: arg, ...flags });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 r => output.formatSymbolJson(r, arg),
                 r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all })
@@ -1257,8 +1259,9 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         }
 
         case 'find': {
-            const { ok, result, error } = execute(index, 'find', { name: arg, ...iflags });
+            const { ok, result, error, note } = execute(index, 'find', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
+            if (note) console.log(note);
             console.log(output.formatFindDetailed(result, arg, { depth: iflags.depth, top: iflags.top, all: iflags.all }));
             break;
         }

package/core/callers.js

@@ -758,6 +758,33 @@ function findCallees(index, def, options = {}) {
                             if (nonTest) callee = nonTest;
                         }
                     }
+                    // Priority 6: Usage-based tiebreaker for cross-language/cross-directory ambiguity
+                    // Matches resolveSymbol() scoring logic in project.js
+                    if (!bindingId && callee === symbols[0] && symbols.length > 1) {
+                        const typeOrder = new Set(['class', 'struct', 'interface', 'type', 'impl']);
+                        const scored = symbols.map(s => {
+                            let score = 0;
+                            const fe = index.files.get(s.file);
+                            const rp = fe ? fe.relativePath : (s.relativePath || '');
+                            if (typeOrder.has(s.type)) score += 1000;
+                            if (isTestFile(rp, detectLanguage(s.file))) score -= 500;
+                            if (/^(examples?|docs?|vendor|third[_-]?party|benchmarks?|samples?)\//i.test(rp)) score -= 300;
+                            if (/^(lib|src|core|internal|pkg|crates)\//i.test(rp)) score += 200;
+                            return { symbol: s, score };
+                        });
+                        scored.sort((a, b) => b.score - a.score);
+                        if (scored.length > 1 && scored[0].score === scored[1].score) {
+                            const tiedScore = scored[0].score;
+                            const tiedCandidates = scored.filter(s => s.score === tiedScore);
+                            for (const c of tiedCandidates) {
+                                c.usageCount = index.countSymbolUsages(c.symbol).total;
+                            }
+                            tiedCandidates.sort((a, b) => b.usageCount - a.usageCount);
+                            callee = tiedCandidates[0].symbol;
+                        } else {
+                            callee = scored[0].symbol;
+                        }
+                    }
                 }
 
                 // Skip test-file callees when caller is production code and

package/core/execute.js

@@ -41,6 +41,38 @@ function requireTerm(term) {
     return null;
 }
 
+/**
+ * Split Class.method syntax into className and methodName.
+ * Returns { className, methodName } or null if not applicable.
+ * Handles: "Class.method" → { className: "Class", methodName: "method" }
+ * Skips: ".method", "a.b.c" (multi-dot), names without dots
+ */
+function splitClassMethod(name) {
+    if (!name || typeof name !== 'string') return null;
+    const dotIndex = name.indexOf('.');
+    if (dotIndex <= 0 || dotIndex === name.length - 1) return null;
+    // Only split on first dot, and only if there's exactly one dot
+    if (name.indexOf('.', dotIndex + 1) !== -1) return null;
+    return {
+        className: name.substring(0, dotIndex),
+        methodName: name.substring(dotIndex + 1)
+    };
+}
+
+/**
+ * Apply Class.method syntax to params object.
+ * If name contains ".", splits it and sets p.name and p.className.
+ * Only applies if p.className is not already set.
+ */
+function applyClassMethodSyntax(p) {
+    if (p.className) return; // already set explicitly
+    const split = splitClassMethod(p.name);
+    if (split) {
+        p.name = split.methodName;
+        p.className = split.className;
+    }
+}
+
 /** Normalize exclude to an array (accepts string CSV, array, or falsy). */
 function toExcludeArray(exclude) {
     if (!exclude) return [];
@@ -93,9 +125,11 @@ const HANDLERS = {
     about: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         const result = index.about(p.name, {
             withTypes: p.withTypes || false,
             file: p.file,
+            className: p.className,
             all: p.all,
             includeMethods: p.includeMethods,
             includeUncertain: p.includeUncertain || false,
@@ -103,17 +137,36 @@ const HANDLERS = {
             maxCallers: num(p.top, undefined),
             maxCallees: num(p.top, undefined),
         });
-        if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
+        if (!result) {
+            // Give better error if file/className filter is the problem
+            if (p.file || p.className) {
+                const unfiltered = index.about(p.name, {
+                    withTypes: p.withTypes || false,
+                    all: false,
+                    includeMethods: p.includeMethods,
+                    includeUncertain: p.includeUncertain || false,
+                    exclude: toExcludeArray(p.exclude),
+                });
+                if (unfiltered && unfiltered.found !== false && unfiltered.symbol) {
+                    const loc = `${unfiltered.symbol.file}:${unfiltered.symbol.startLine}`;
+                    const filterDesc = p.className ? `class "${p.className}"` : `file "${p.file}"`;
+                    return { ok: false, error: `Symbol "${p.name}" not found in ${filterDesc}. Found in: ${loc}. Use the correct --file or Class.method syntax.` };
+                }
+            }
+            return { ok: false, error: `Symbol "${p.name}" not found.` };
+        }
         return { ok: true, result };
     },
 
     context: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         const result = index.context(p.name, {
             includeMethods: p.includeMethods,
             includeUncertain: p.includeUncertain || false,
             file: p.file,
+            className: p.className,
             exclude: toExcludeArray(p.exclude),
         });
         if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
@@ -123,8 +176,10 @@ const HANDLERS = {
     impact: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         const result = index.impact(p.name, {
             file: p.file,
+            className: p.className,
             exclude: toExcludeArray(p.exclude),
             top: num(p.top, undefined),
         });
@@ -135,8 +190,10 @@ const HANDLERS = {
     smart: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         const result = index.smart(p.name, {
             file: p.file,
+            className: p.className,
             withTypes: p.withTypes || false,
             includeMethods: p.includeMethods,
             includeUncertain: p.includeUncertain || false,
@@ -148,10 +205,12 @@ const HANDLERS = {
     trace: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         const depthVal = num(p.depth, undefined);
         const result = index.trace(p.name, {
             depth: depthVal ?? 3,
             file: p.file,
+            className: p.className,
             all: p.all || depthVal !== undefined,
             includeMethods: p.includeMethods,
             includeUncertain: p.includeUncertain || false,
@@ -163,7 +222,8 @@ const HANDLERS = {
     example: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
-        const result = index.example(p.name);
+        applyClassMethodSyntax(p);
+        const result = index.example(p.name, { file: p.file, className: p.className });
         if (!result) return { ok: false, error: `No examples found for "${p.name}".` };
         return { ok: true, result };
     },
@@ -171,8 +231,10 @@ const HANDLERS = {
     related: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         const result = index.related(p.name, {
             file: p.file,
+            className: p.className,
             top: num(p.top, undefined),
             all: p.all,
         });
@@ -185,6 +247,7 @@ const HANDLERS = {
     find: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         // Auto-include tests when pattern clearly targets test functions
         // But only if the user didn't explicitly set include_tests=false
         let includeTests = p.includeTests;
@@ -194,20 +257,28 @@ const HANDLERS = {
         const exclude = applyTestExclusions(p.exclude, includeTests);
         const result = index.find(p.name, {
             file: p.file,
+            className: p.className,
             exact: p.exact || false,
             exclude,
             in: p.in,
         });
-        return { ok: true, result };
+        // Warn if exact mode silently disables glob expansion
+        let note;
+        if (p.exact && p.name && (p.name.includes('*') || p.name.includes('?'))) {
+            note = `Note: exact=true treats "${p.name}" as a literal name (glob expansion disabled).`;
+        }
+        return { ok: true, result, note };
     },
 
     usages: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         const exclude = applyTestExclusions(p.exclude, p.includeTests);
         const result = index.usages(p.name, {
             codeOnly: p.codeOnly || false,
             context: num(p.context, 0),
+            className: p.className,
             exclude,
             in: p.in,
         });
@@ -242,8 +313,10 @@ const HANDLERS = {
     tests: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         const result = index.tests(p.name, {
             callsOnly: p.callsOnly || false,
+            className: p.className,
         });
         return { ok: true, result };
     },
@@ -264,6 +337,7 @@ const HANDLERS = {
     fn: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
 
         const fnNames = p.name.includes(',')
             ? p.name.split(',').map(n => n.trim()).filter(Boolean)
@@ -273,11 +347,23 @@ const HANDLERS = {
         const notes = [];
 
         for (const fnName of fnNames) {
-            const matches = index.find(fnName, { file: p.file, skipCounts: true })
+            // For comma-separated names, each may have Class.method syntax
+            const fnSplit = splitClassMethod(fnName);
+            const actualName = fnSplit ? fnSplit.methodName : fnName;
+            const fnClassName = fnSplit ? fnSplit.className : p.className;
+            const matches = index.find(actualName, { file: p.file, className: fnClassName, skipCounts: true })
                 .filter(m => m.type === 'function' || m.params !== undefined);
 
             if (matches.length === 0) {
-                notes.push(`Function "${fnName}" not found.`);
+                // Check if it's a class — suggest `class` command instead
+                const CLASS_TYPES = ['class', 'interface', 'type', 'enum', 'struct', 'trait'];
+                const classMatches = index.find(actualName, { file: p.file, className: fnClassName, skipCounts: true })
+                    .filter(m => CLASS_TYPES.includes(m.type));
+                if (classMatches.length > 0) {
+                    notes.push(`"${fnName}" is a ${classMatches[0].type}, not a function. Use \`class ${fnName}\` instead.`);
+                } else {
+                    notes.push(`Function "${fnName}" not found.`);
+                }
                 continue;
             }
 
@@ -472,13 +558,15 @@ const HANDLERS = {
     verify: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
-        const result = index.verify(p.name, { file: p.file });
+        applyClassMethodSyntax(p);
+        const result = index.verify(p.name, { file: p.file, className: p.className });
         return { ok: true, result };
     },
 
     plan: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
         if (!p.addParam && !p.removeParam && !p.renameTo) {
             return { ok: false, error: 'Plan requires an operation: add_param, remove_param, or rename_to.' };
         }
@@ -488,6 +576,7 @@ const HANDLERS = {
             renameTo: p.renameTo,
             defaultValue: p.defaultValue,
             file: p.file,
+            className: p.className,
         });
         return { ok: true, result };
     },
@@ -506,7 +595,8 @@ const HANDLERS = {
     typedef: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
-        const result = index.typedef(p.name, { exact: p.exact || false });
+        applyClassMethodSyntax(p);
+        const result = index.typedef(p.name, { exact: p.exact || false, className: p.className });
         return { ok: true, result };
     },
 

package/core/project.js

@@ -700,6 +700,14 @@ class ProjectIndex {
             return { def: null, definitions: [], warnings: [] };
         }
 
+        // Filter by class name (Class.method syntax)
+        if (options.className) {
+            const filtered = definitions.filter(d => d.className === options.className);
+            if (filtered.length > 0) {
+                definitions = filtered;
+            }
+        }
+
         // Filter by file if specified
         if (options.file) {
             const filtered = definitions.filter(d =>
@@ -826,6 +834,11 @@ class ProjectIndex {
     _applyFindFilters(matches, options) {
         let filtered = matches;
 
+        // Filter by class name (Class.method syntax)
+        if (options.className) {
+            filtered = filtered.filter(m => m.className === options.className);
+        }
+
         // Filter by file pattern
         if (options.file) {
             filtered = filtered.filter(m =>
@@ -958,7 +971,10 @@ class ProjectIndex {
         const usages = [];
 
         // Get definitions (filtered)
-        const allDefinitions = this.symbols.get(name) || [];
+        let allDefinitions = this.symbols.get(name) || [];
+        if (options.className) {
+            allDefinitions = allDefinitions.filter(d => d.className === options.className);
+        }
         const definitions = options.exclude || options.in
             ? allDefinitions.filter(d => this.matchesFilters(d.relativePath, options))
             : allDefinitions;
@@ -1150,7 +1166,7 @@ class ProjectIndex {
     context(name, options = {}) {
         this._beginOp();
         try {
-        const resolved = this.resolveSymbol(name, { file: options.file });
+        const resolved = this.resolveSymbol(name, { file: options.file, className: options.className });
         let { def, definitions, warnings } = resolved;
         if (!def) {
             return null;
@@ -1310,7 +1326,7 @@ class ProjectIndex {
     smart(name, options = {}) {
         this._beginOp();
         try {
-        const { def } = this.resolveSymbol(name, { file: options.file });
+        const { def } = this.resolveSymbol(name, { file: options.file, className: options.className });
         if (!def) {
             return null;
         }
@@ -2362,7 +2378,7 @@ class ProjectIndex {
     related(name, options = {}) {
         this._beginOp();
         try {
-        const { def } = this.resolveSymbol(name, { file: options.file });
+        const { def } = this.resolveSymbol(name, { file: options.file, className: options.className });
         if (!def) {
             return null;
         }
@@ -2513,7 +2529,7 @@ class ProjectIndex {
         // trace defaults to includeMethods=true (execution flow should show method calls)
         const includeMethods = options.includeMethods ?? true;
 
-        const { def, definitions, warnings } = this.resolveSymbol(name, { file: options.file });
+        const { def, definitions, warnings } = this.resolveSymbol(name, { file: options.file, className: options.className });
         if (!def) {
             return null;
         }
@@ -2619,7 +2635,7 @@ class ProjectIndex {
     impact(name, options = {}) {
         this._beginOp();
         try {
-        const { def } = this.resolveSymbol(name, { file: options.file });
+        const { def } = this.resolveSymbol(name, { file: options.file, className: options.className });
         if (!def) {
             return null;
         }
@@ -2773,10 +2789,10 @@ class ProjectIndex {
         const includeMethods = options.includeMethods ?? true;
 
         // Find symbol definition(s) — skip counts since about() computes its own via usages()
-        const definitions = this.find(name, { exact: true, file: options.file, skipCounts: true });
+        const definitions = this.find(name, { exact: true, file: options.file, className: options.className, skipCounts: true });
         if (definitions.length === 0) {
             // Try fuzzy match (needs counts for suggestion ranking)
-            const fuzzy = this.find(name, { file: options.file });
+            const fuzzy = this.find(name, { file: options.file, className: options.className });
             if (fuzzy.length === 0) {
                 return null;
             }
@@ -2794,7 +2810,7 @@ class ProjectIndex {
         }
 
         // Use resolveSymbol for consistent primary selection (prefers non-test files)
-        const { def: resolved } = this.resolveSymbol(name, { file: options.file });
+        const { def: resolved } = this.resolveSymbol(name, { file: options.file, className: options.className });
         const primary = resolved || definitions[0];
         const others = definitions.filter(d =>
             d.relativePath !== primary.relativePath || d.startLine !== primary.startLine
@@ -3258,11 +3274,12 @@ class ProjectIndex {
      * @param {string} name - Symbol name
      * @returns {{ best: object, totalCalls: number } | null}
      */
-    example(name) {
+    example(name, options = {}) {
         this._beginOp();
         try {
         const usages = this.usages(name, {
             codeOnly: true,
+            className: options.className,
             exclude: ['test', 'spec', '__tests__', '__mocks__', 'fixture', 'mock'],
             context: 5
         });

package/core/verify.js

@@ -177,7 +177,7 @@ function identifyCallPatterns(callSites, funcName) {
 function verify(index, name, options = {}) {
     index._beginOp();
     try {
-    const { def } = index.resolveSymbol(name, { file: options.file });
+    const { def } = index.resolveSymbol(name, { file: options.file, className: options.className });
     if (!def) {
         return { found: false, function: name };
     }
@@ -315,9 +315,9 @@ function plan(index, name, options = {}) {
         return { found: false, function: name };
     }
 
-    const resolved = index.resolveSymbol(name, { file: options.file });
+    const resolved = index.resolveSymbol(name, { file: options.file, className: options.className });
     const def = resolved.def || definitions[0];
-    const impact = index.impact(name, { file: options.file });
+    const impact = index.impact(name, { file: options.file, className: options.className });
     const currentParams = def.paramsStructured || [];
     const currentSignature = index.formatSignature(def);
 

package/mcp/server.js

@@ -297,7 +297,7 @@ server.registerTool(
 
             case 'impact': {
                 const index = getIndex(project_dir);
-                const ep = normalizeParams({ name, file, exclude });
+                const ep = normalizeParams({ name, file, exclude, top });
                 const { ok, result, error } = execute(index, 'impact', ep);
                 if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatImpact(result));
@@ -346,9 +346,11 @@ server.registerTool(
             case 'find': {
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, file, exclude, include_tests, exact, in: inPath });
-                const { ok, result, error } = execute(index, 'find', ep);
+                const { ok, result, error, note } = execute(index, 'find', ep);
                 if (!ok) return toolResult(error); // soft error
-                return toolResult(output.formatFind(result, name, top));
+                let text = output.formatFind(result, name, top);
+                if (note) text += '\n\n' + note;
+                return toolResult(text);
             }
 
             case 'usages': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.30",
+  "version": "3.7.31",
   "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",