ucn 3.7.29 → 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

@@ -719,11 +719,20 @@ function findCallees(index, def, options = {}) {
                         const sameDir = symbols.find(s => path.dirname(s.file) === defDir);
                         if (sameDir) {
                             callee = sameDir;
-                        } else if (defReceiver) {
-                            // Priority 3: Same receiver type (for methods)
-                            const sameReceiver = symbols.find(s => s.receiver === defReceiver);
-                            if (sameReceiver) {
-                                callee = sameReceiver;
+                        } else {
+                            // Priority 2.5: Imported file — check if the caller's file imports
+                            // from any of the candidate callee files
+                            const callerImports = fileEntry?.imports || [];
+                            const importedFiles = new Set(callerImports.map(imp => imp.resolvedPath).filter(Boolean));
+                            const importedCallee = symbols.find(s => importedFiles.has(s.file));
+                            if (importedCallee) {
+                                callee = importedCallee;
+                            } else if (defReceiver) {
+                                // Priority 3: Same receiver type (for methods)
+                                const sameReceiver = symbols.find(s => s.receiver === defReceiver);
+                                if (sameReceiver) {
+                                    callee = sameReceiver;
+                                }
                             }
                         }
                     }
@@ -749,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,9 +176,12 @@ 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),
         });
         if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
         return { ok: true, result };
@@ -134,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,
@@ -147,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,
@@ -162,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 };
     },
@@ -170,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,
         });
@@ -184,28 +247,38 @@ 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;
-        if (!includeTests && p.name && /^test[_*?]/i.test(p.name)) {
+        if (includeTests === undefined && p.name && /^test[_*?]/i.test(p.name)) {
             includeTests = true;
         }
         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,
         });
@@ -240,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 };
     },
@@ -262,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)
@@ -271,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;
             }
 
@@ -470,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.' };
         }
@@ -486,6 +576,7 @@ const HANDLERS = {
             renameTo: p.renameTo,
             defaultValue: p.defaultValue,
             file: p.file,
+            className: p.className,
         });
         return { ok: true, result };
     },
@@ -504,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/expand-cache.js

@@ -125,6 +125,50 @@ class ExpandCache {
     }
 }
 
+/**
+ * Detect the end of a function/method body starting from startLine.
+ * Uses brace/indent counting to find the closing boundary.
+ * Falls back to startLine + 30 if detection fails.
+ */
+function _detectFunctionEnd(fileLines, startLine) {
+    const maxScan = 500; // Avoid scanning huge files
+    const idx = startLine - 1;
+    if (idx >= fileLines.length) return startLine;
+
+    const firstLine = fileLines[idx];
+
+    // Python: indentation-based — find the first non-empty line at same or lesser indent
+    if (/^\s*def\s|^\s*class\s|^\s*async\s+def\s/.test(firstLine)) {
+        const baseIndent = firstLine.match(/^(\s*)/)[1].length;
+        let end = startLine;
+        for (let i = idx + 1; i < Math.min(idx + maxScan, fileLines.length); i++) {
+            const line = fileLines[i];
+            if (line.trim() === '') { end = i + 1; continue; } // blank lines are part of body
+            const indent = line.match(/^(\s*)/)[1].length;
+            if (indent <= baseIndent) break;
+            end = i + 1;
+        }
+        return end;
+    }
+
+    // Brace-based languages (JS/TS/Go/Java/Rust): count braces
+    let braceCount = 0;
+    let foundBrace = false;
+    for (let i = idx; i < Math.min(idx + maxScan, fileLines.length); i++) {
+        const line = fileLines[i];
+        for (const ch of line) {
+            if (ch === '{') { braceCount++; foundBrace = true; }
+            else if (ch === '}') { braceCount--; }
+        }
+        if (foundBrace && braceCount <= 0) {
+            return i + 1;
+        }
+    }
+
+    // Fallback: show 30 lines from start
+    return Math.min(startLine + 30, fileLines.length);
+}
+
 /**
  * Render an expand match to text lines.
  * Shared by MCP and interactive mode to avoid duplicated rendering logic.
@@ -156,7 +200,13 @@ function renderExpandItem(match, root, { validateRoot = false } = {}) {
     const content = fs.readFileSync(filePath, 'utf-8');
     const fileLines = content.split('\n');
     const startLine = match.startLine || match.line || 1;
-    const endLine = match.endLine || startLine + 20;
+    let endLine = match.endLine;
+
+    // When endLine is missing or equals startLine, the expand would show only 1 line.
+    // Scan forward from startLine to find the actual function/method body end.
+    if (!endLine || endLine <= startLine) {
+        endLine = _detectFunctionEnd(fileLines, startLine);
+    }
 
     const lines = [];
     lines.push(`[${match.num}] ${match.name} (${match.type})`);

package/core/output.js

@@ -938,7 +938,11 @@ function formatImpact(impact, options = {}) {
     lines.push('');
 
     // Summary
-    lines.push(`CALL SITES: ${impact.totalCallSites}`);
+    if (impact.shownCallSites !== undefined && impact.shownCallSites < impact.totalCallSites) {
+        lines.push(`CALL SITES: ${impact.shownCallSites} shown of ${impact.totalCallSites} total`);
+    } else {
+        lines.push(`CALL SITES: ${impact.totalCallSites}`);
+    }
     lines.push(`  Files affected: ${impact.byFile.length}`);
 
     // Patterns

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 =>
@@ -735,6 +743,20 @@ class ProjectIndex {
         // Sort by score descending, then by index order for stability
         scored.sort((a, b) => b.score - a.score);
 
+        // Tiebreaker: when top candidates have equal score, prefer by usage count
+        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 candidate of tiedCandidates) {
+                candidate.usageCount = this.countSymbolUsages(candidate.def).total;
+            }
+            tiedCandidates.sort((a, b) => b.usageCount - a.usageCount);
+            // Rebuild scored array: sorted tied candidates first, then rest
+            const rest = scored.filter(s => s.score !== tiedScore);
+            scored.length = 0;
+            scored.push(...tiedCandidates, ...rest);
+        }
+
         const def = scored[0].def;
 
         // Build warnings
@@ -812,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 =>
@@ -944,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;
@@ -1136,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;
@@ -1296,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;
         }
@@ -2348,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;
         }
@@ -2499,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;
         }
@@ -2605,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;
         }
@@ -2668,6 +2698,12 @@ class ProjectIndex {
             filteredSites = callSites.filter(s => this.matchesFilters(s.file, { exclude: options.exclude }));
         }
 
+        // Apply top limit if specified (limits total call sites shown)
+        const totalBeforeLimit = filteredSites.length;
+        if (options.top && options.top > 0 && filteredSites.length > options.top) {
+            filteredSites = filteredSites.slice(0, options.top);
+        }
+
         // Group by file
         const byFile = new Map();
         for (const site of filteredSites) {
@@ -2687,7 +2723,8 @@ class ProjectIndex {
             signature: this.formatSignature(def),
             params: def.params,
             paramsStructured: def.paramsStructured,
-            totalCallSites: filteredSites.length,
+            totalCallSites: totalBeforeLimit,
+            shownCallSites: filteredSites.length,
             byFile: Array.from(byFile.entries()).map(([file, sites]) => ({
                 file,
                 count: sites.length,
@@ -2752,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;
             }
@@ -2773,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
@@ -3237,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);
 
@@ -433,6 +433,29 @@ function plan(index, name, options = {}) {
                 });
             }
         }
+
+        // Also include import statements that reference the renamed function
+        const usages = index.usages(name, { codeOnly: true });
+        const importUsages = usages.filter(u => u.usageType === 'import' && !u.isDefinition);
+        for (const imp of importUsages) {
+            // Skip if already covered by a call site change in the same file:line
+            const alreadyCovered = changes.some(c =>
+                c.file === (imp.relativePath || imp.file) && c.line === imp.line
+            );
+            if (alreadyCovered) continue;
+            const newImport = imp.content.trim().replace(
+                new RegExp('\\b' + escapeRegExp(name) + '\\b'),
+                options.renameTo
+            );
+            changes.push({
+                file: imp.relativePath || imp.file,
+                line: imp.line,
+                expression: imp.content.trim(),
+                suggestion: `Update import: ${newImport}`,
+                newExpression: newImport,
+                isImport: true
+            });
+        }
     }
 
     return {

package/languages/python.js

@@ -330,6 +330,14 @@ function findStateObjects(code, parser) {
     const objects = [];
 
     const statePattern = /^(CONFIG|SETTINGS|[A-Z][A-Z0-9_]+|[A-Z][a-zA-Z]*(?:Config|Settings|Options|State|Store|Context))$/;
+    // Pattern for UPPER_CASE constants that may have scalar values (string, number, bool, etc.)
+    const constantPattern = /^[A-Z][A-Z0-9_]{1,}$/;
+    // RHS types that are scalar/simple values (not dict/list which are handled separately)
+    const scalarTypes = new Set([
+        'string', 'concatenated_string', 'integer', 'float', 'true', 'false', 'none',
+        'unary_operator', 'binary_operator', 'tuple', 'set', 'parenthesized_expression',
+        'call', 'attribute', 'identifier', 'subscript',
+    ]);
 
     traverseTree(tree.rootNode, (node) => {
         if (node.type === 'expression_statement' && node.parent === tree.rootNode) {
@@ -346,6 +354,10 @@ function findStateObjects(code, parser) {
                     if ((isObject || isArray) && statePattern.test(name)) {
                         const { startLine, endLine } = nodeToLocation(node, code);
                         objects.push({ name, startLine, endLine });
+                    } else if (constantPattern.test(name) && scalarTypes.has(rightNode.type)) {
+                        // Module-level UPPER_CASE constants with scalar values
+                        const { startLine, endLine } = nodeToLocation(node, code);
+                        objects.push({ name, startLine, endLine, isConstant: true });
                     }
                 }
             }

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.29",
+  "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",