ucn 3.8.15 → 3.8.16

package/cli/index.js

@@ -14,7 +14,7 @@ const { parseFile, detectLanguage } = require('../core/parser');
 const { ProjectIndex } = require('../core/project');
 const { expandGlob, findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
-// pickBestDefinition moved to execute.js — no longer needed here
+const { escapeRegExp } = require('../core/shared');
 const { getCliCommandSet, resolveCommand, FLAG_APPLICABILITY, toCliName } = require('../core/registry');
 const { execute } = require('../core/execute');
 const { ExpandCache } = require('../core/expand-cache');
@@ -115,6 +115,7 @@ function parseFlags(tokens) {
         showConfidence: !tokens.includes('--no-confidence'),
         minConfidence: parseFloat(getValueFlag('--min-confidence') || '0') || 0,
         framework: getValueFlag('--framework'),
+        stack: getValueFlag('--stack'),
         workers: (() => {
             const v = getValueFlag('--workers');
             if (v === null) return undefined;
@@ -327,11 +328,11 @@ function runFileCommand(filePath, command, arg) {
         fn:      { name: arg, file: relativePath, ...flags },
         class:   { name: arg, file: relativePath, ...flags },
         find:    { name: arg, file: relativePath, ...flags },
-        usages:  { name: arg, ...flags },
+        usages:  { name: arg, file: relativePath, ...flags },
         search:  { term: arg, ...flags },
         lines:   { file: relativePath, range: arg },
-        typedef: { name: arg, ...flags },
-        api:     { file: relativePath },
+        typedef: { name: arg, file: relativePath, ...flags },
+        api:     { file: relativePath, limit: flags.limit },
     };
 
     const { ok, result, error, note } = execute(index, canonical, paramsByCommand[canonical]);
@@ -427,6 +428,11 @@ function runProjectCommand(rootDir, command, arg) {
     if (!usedCache) {
         index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles, workers: flags.workers });
         needsCacheSave = flags.cache;
+        // Clear stale expand cache — line ranges may have shifted after rebuild
+        try {
+            const expandPath = path.join(index.root, '.ucn-cache', 'expandable.json');
+            if (fs.existsSync(expandPath)) fs.unlinkSync(expandPath);
+        } catch (_) { /* best-effort */ }
     }
 
     try {
@@ -439,7 +445,7 @@ function runProjectCommand(rootDir, command, arg) {
         // Map from camelCase flag name to CLI flag string
         const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
         // Flags that are global (not command-specific) or have truthy defaults — skip warning for these
-        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', 'stack', 'showConfidence']);
+        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', 'showConfidence']);
         for (const [key, value] of Object.entries(flags)) {
             if (globalFlags.has(key)) continue;
             // Skip falsy/default values (0, undefined, false, empty array)
@@ -487,7 +493,7 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'example': {
-            const { ok, result, error } = execute(index, 'example', { name: arg });
+            const { ok, result, error } = execute(index, 'example', { name: arg, file: flags.file, className: flags.className });
             if (!ok) fail(error);
             printOutput(result,
                 r => output.formatExampleJson(r, arg),
@@ -550,7 +556,7 @@ function runProjectCommand(rootDir, command, arg) {
             const items = cached?.items || [];
             const match = items.find(i => i.num === expandNum);
             const { ok, result, error } = execute(index, 'expand', {
-                match, itemNum: expandNum, itemCount: items.length
+                match, itemNum: expandNum, itemCount: items.length, validateRoot: true
             });
             if (!ok) fail(error);
             console.log(result.text);
@@ -558,21 +564,23 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'smart': {
-            const { ok, result, error } = execute(index, 'smart', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'smart', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result, output.formatSmartJson, r => output.formatSmart(r, {
                 uncertainHint: 'use --include-uncertain to include all'
             }));
+            if (note) console.error(note);
             break;
         }
 
         case 'about': {
-            const { ok, result, error } = execute(index, 'about', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'about', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result,
                 output.formatAboutJson,
                 r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence })
             );
+            if (note) console.error(note);
             break;
         }
 
@@ -616,7 +624,7 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'stacktrace': {
-            const { ok, result, error } = execute(index, 'stacktrace', { stack: arg });
+            const { ok, result, error } = execute(index, 'stacktrace', { stack: flags.stack || arg });
             if (!ok) fail(error);
             printOutput(result, output.formatStackTraceJson, output.formatStackTrace);
             break;
@@ -641,7 +649,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'fn': {
             requireArg(arg, 'Usage: ucn . fn <name>');
-            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: flags.file, all: flags.all });
+            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: flags.file, all: flags.all, className: flags.className });
             if (!ok) fail(error);
             if (note) console.error(note);
             printOutput(result, output.formatFnResultJson, output.formatFnResult);
@@ -650,7 +658,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'class': {
             requireArg(arg, 'Usage: ucn . class <name>');
-            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines });
+            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines, className: flags.className });
             if (!ok) fail(error);
             if (note) console.error(note);
             printOutput(result, output.formatClassResultJson, output.formatClassResult);
@@ -659,8 +667,9 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'lines': {
             requireArg(arg, 'Usage: ucn . lines <range> --file <path>');
-            const { ok, result, error } = execute(index, 'lines', { file: flags.file, range: arg });
+            const { ok, result, error, note } = execute(index, 'lines', { file: flags.file, range: arg });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result, output.formatLinesJson, r => output.formatLines(r));
             break;
         }
@@ -694,7 +703,7 @@ function runProjectCommand(rootDir, command, arg) {
             const { ok, result, error } = execute(index, 'fileExports', { file: filePath });
             if (!ok) fail(error);
             printOutput(result,
-                r => JSON.stringify({ file: filePath, exports: r }, null, 2),
+                output.formatFileExportsJson,
                 r => output.formatFileExports(r, filePath)
             );
             break;
@@ -705,11 +714,7 @@ function runProjectCommand(rootDir, command, arg) {
             const { ok, result, error } = execute(index, 'graph', { file: filePath, direction: flags.direction, depth: flags.depth, all: flags.all });
             if (!ok) fail(error);
             printOutput(result,
-                r => JSON.stringify({
-                    root: path.relative(index.root, r.root),
-                    nodes: r.nodes.map(n => ({ file: n.relativePath, depth: n.depth })),
-                    edges: r.edges.map(e => ({ from: path.relative(index.root, e.from), to: path.relative(index.root, e.to) }))
-                }, null, 2),
+                output.formatGraphJson,
                 r => output.formatGraph(r, { showAll: flags.all || flags.depth != null, maxDepth: flags.depth != null ? parseInt(flags.depth, 10) : 2, file: filePath })
             );
             break;
@@ -725,7 +730,7 @@ function runProjectCommand(rootDir, command, arg) {
         // ── Remaining commands ──────────────────────────────────────────
 
         case 'typedef': {
-            const { ok, result, error } = execute(index, 'typedef', { name: arg, exact: flags.exact });
+            const { ok, result, error } = execute(index, 'typedef', { name: arg, exact: flags.exact, file: flags.file, className: flags.className });
             if (!ok) fail(error);
             printOutput(result,
                 r => output.formatTypedefJson(r, arg),
@@ -735,7 +740,7 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'tests': {
-            const { ok, result, error } = execute(index, 'tests', { name: arg, callsOnly: flags.callsOnly });
+            const { ok, result, error } = execute(index, 'tests', { name: arg, callsOnly: flags.callsOnly, className: flags.className });
             if (!ok) fail(error);
             printOutput(result,
                 r => output.formatTestsJson(r, arg),
@@ -794,8 +799,9 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'entrypoints': {
-            const { ok, result, error } = execute(index, 'entrypoints', { type: flags.type, framework: flags.framework, file: flags.file, exclude: flags.exclude });
+            const { ok, result, error, note } = execute(index, 'entrypoints', { type: flags.type, framework: flags.framework, file: flags.file, exclude: flags.exclude, includeTests: flags.includeTests, limit: flags.limit });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 output.formatEntrypointsJson,
                 r => output.formatEntrypoints(r)
@@ -814,8 +820,9 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'diffImpact': {
-            const { ok, result, error } = execute(index, 'diffImpact', { base: flags.base, staged: flags.staged, file: flags.file });
+            const { ok, result, error, note } = execute(index, 'diffImpact', { base: flags.base, staged: flags.staged, file: flags.file, limit: flags.limit, all: flags.all });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result, output.formatDiffImpactJson, r => output.formatDiffImpact(r, { all: flags.all }));
             break;
         }
@@ -1062,10 +1069,6 @@ function searchGlobFiles(files, term) {
 // HELPERS
 // ============================================================================
 
-function escapeRegExp(text) {
-    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 function isCommentOrString(line) {
     const trimmed = line.trim();
     return trimmed.startsWith('//') ||
@@ -1279,6 +1282,8 @@ Flags can be added per-command: context myFunc --include-methods
         if (input === 'rebuild') {
             console.log('Rebuilding index...');
             index.build(null, { quiet: true, forceRebuild: true, workers: flags.workers });
+            // Clear expand cache — stale line ranges after rebuild
+            if (iExpandCache) iExpandCache.clearForRoot(index.root);
             console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} symbols`);
             rl.prompt();
             return;
@@ -1344,7 +1349,7 @@ const INTERACTIVE_DISPATCH = {
     trace:        { params: 'name', format: (r) => output.formatTrace(r) },
     reverseTrace: { params: 'name', format: (r) => output.formatReverseTrace(r) },
     related:      { params: 'name', format: (r, _a, f) => output.formatRelated(r, { all: f.all, top: f.top }) },
-    example:      { params: (a) => ({ name: a }), format: (r, a) => output.formatExample(r, a) },
+    example:      { params: 'name', format: (r, a) => output.formatExample(r, a) },
 
     // ── Finding Code ─────────────────────────────────────────────────
     find:          { params: 'name', format: (r, a, f) => output.formatFindDetailed(r, a, { depth: f.depth, top: f.top, all: f.all }) },
@@ -1364,12 +1369,12 @@ const INTERACTIVE_DISPATCH = {
     // ── Refactoring Helpers ──────────────────────────────────────────
     plan:         { params: 'name', format: (r) => output.formatPlan(r) },
     verify:       { params: 'name', format: (r) => output.formatVerify(r) },
-    diffImpact:   { params: 'flags', format: (r, _a, f) => output.formatDiffImpact(r, { all: f.all }) },
-    entrypoints:  { params: (a, f) => ({ type: f.type, framework: f.framework, file: f.file, exclude: f.exclude }), format: (r) => output.formatEntrypoints(r) },
+    diffImpact:   { params: (a, f) => ({ base: f.base, staged: f.staged, file: f.file, limit: f.limit, all: f.all }), format: (r, _a, f) => output.formatDiffImpact(r, { all: f.all }) },
+    entrypoints:  { params: (a, f) => ({ type: f.type, framework: f.framework, file: f.file, exclude: f.exclude, includeTests: f.includeTests, limit: f.limit }), format: (r) => output.formatEntrypoints(r) },
 
     // ── Other ────────────────────────────────────────────────────────
     api:          { params: (a, f) => ({ file: a || f.file, limit: f.limit }), format: (r, a, f) => output.formatApi(r, a || f.file || '.') },
-    stacktrace:   { params: (a) => ({ stack: a }), format: (r) => output.formatStackTrace(r) },
+    stacktrace:   { params: (a, f) => ({ stack: f.stack || a }), format: (r) => output.formatStackTrace(r) },
     stats:        { params: 'flags', format: (r, _a, f) => output.formatStats(r, { top: f.top }) },
 };
 
@@ -1395,8 +1400,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
     switch (command) {
 
         case 'fn': {
-            if (!arg) { console.log('Usage: fn <name>[,name2,...] [--file=<pattern>]'); return; }
-            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: iflags.file, all: iflags.all });
+            if (!arg) { console.log('Usage: fn <name>[,name2,...] [--file=<pattern>] [--class-name=<class>]'); return; }
+            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: iflags.file, all: iflags.all, className: iflags.className });
             if (!ok) { console.log(error); return; }
             if (note) console.log(note);
             console.log(output.formatFnResult(result));
@@ -1443,7 +1448,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
                 itemCount = items.length;
             }
             const { ok, result, error } = execute(index, 'expand', {
-                match, itemNum: expandNum, itemCount, symbolName
+                match, itemNum: expandNum, itemCount, symbolName, validateRoot: true
             });
             if (!ok) { console.log(error); return; }
             console.log(result.text);
@@ -1451,7 +1456,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         }
 
         case 'context': {
-            const { ok, result, error } = execute(index, 'context', { name: arg, ...iflags });
+            const { ok, result, error, note } = execute(index, 'context', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
             const { text, expandable } = output.formatContext(result, {
                 methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
@@ -1460,6 +1465,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
                 showConfidence: iflags.showConfidence,
             });
             console.log(text);
+            if (note) console.log(note);
             if (cache) {
                 cache.save(index.root, arg, iflags.file, expandable);
             } else {
@@ -1469,8 +1475,9 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         }
 
         case 'deadcode': {
-            const { ok, result, error } = execute(index, 'deadcode', iflags);
+            const { ok, result, error, note } = execute(index, 'deadcode', iflags);
             if (!ok) { console.log(error); return; }
+            if (note) console.log(note);
             console.log(output.formatDeadcode(result, {
                 top: iflags.top,
                 decoratedHint: !iflags.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
@@ -1480,8 +1487,9 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         }
 
         case 'search': {
-            const { ok, result, error, structural } = execute(index, 'search', { term: arg, ...iflags });
+            const { ok, result, error, structural, note } = execute(index, 'search', { term: arg, ...iflags });
             if (!ok) { console.log(error); return; }
+            if (note) console.log(note);
             if (structural) {
                 console.log(output.formatStructuralSearch(result));
             } else {

package/core/execute.js

@@ -62,14 +62,14 @@ function splitClassMethod(name) {
 /**
  * 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.
+ * When p.className is already set, still split the name to extract the method
+ * part (explicit --class-name takes precedence over the class from dot notation).
  */
 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;
+        if (!p.className) p.className = split.className;
     }
 }
 
@@ -343,7 +343,8 @@ const HANDLERS = {
             withTypes: p.withTypes || false,
         });
         if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
-        return { ok: true, result };
+        const tNote = truncationNote(index);
+        return { ok: true, result, ...(tNote && { note: tNote }) };
     },
 
     trace: (index, p) => {

package/core/registry.js

@@ -106,7 +106,7 @@ const FLAG_APPLICABILITY = {
     example:      ['file', 'className'],
     related:      ['file', 'className', 'top', 'all'],
     // Finding code
-    find:         ['file', 'exclude', 'className', 'includeTests', 'top', 'limit', 'exact', 'in', 'all'],
+    find:         ['file', 'exclude', 'className', 'includeTests', 'top', 'limit', 'exact', 'in', 'all', 'depth'],
     usages:       ['file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in'],
     toc:          ['file', 'exclude', 'top', 'limit', 'all', 'detailed', 'topLevel', 'in'],
     search:       ['file', 'exclude', 'includeTests', 'top', 'limit', 'codeOnly', 'caseSensitive', 'context', 'regex', 'in', 'type', 'param', 'receiver', 'returns', 'decorator', 'exported', 'unused'],

package/core/search.js

@@ -161,7 +161,10 @@ function usages(index, name, options = {}) {
     const usagesList = [];
 
     // Resolve file pattern for --file filter
-    const fileFilter = options.file ? index.resolveFilePathForQuery(options.file) : null;
+    const fileFilterRaw = options.file ? index.resolveFilePathForQuery(options.file) : null;
+    // resolveFilePathForQuery may return error objects for ambiguous/not-found — fall back to substring matching
+    const fileFilter = typeof fileFilterRaw === 'string' ? fileFilterRaw : null;
+    const fileSubstring = options.file || null; // fallback for unresolved patterns
 
     // Get definitions (filtered)
     let allDefinitions = index.symbols.get(name) || [];
@@ -170,6 +173,8 @@ function usages(index, name, options = {}) {
     }
     if (fileFilter) {
         allDefinitions = allDefinitions.filter(d => d.file === fileFilter);
+    } else if (fileSubstring) {
+        allDefinitions = allDefinitions.filter(d => d.relativePath && d.relativePath.includes(fileSubstring));
     }
     const definitions = options.exclude || options.in
         ? allDefinitions.filter(d => index.matchesFilters(d.relativePath, options))
@@ -187,9 +192,11 @@ function usages(index, name, options = {}) {
 
     // Scan all files for usages
     for (const [filePath, fileEntry] of index.files) {
-        // Apply --file filter
+        // Apply --file filter (exact match if resolved, substring fallback otherwise)
         if (fileFilter && filePath !== fileFilter) {
             continue;
+        } else if (!fileFilter && fileSubstring && !fileEntry.relativePath.includes(fileSubstring)) {
+            continue;
         }
         // Apply filters
         if (!index.matchesFilters(fileEntry.relativePath, options)) {
@@ -838,9 +845,21 @@ function tests(index, nameOrFile, options = {}) {
     const callPattern = new RegExp(escapeRegExp(searchTerm) + '\\s*\\(');
     const strPattern = new RegExp("['\"`]" + escapeRegExp(searchTerm) + "['\"`]");
 
+    // When className is provided, build a pattern to scope matches.
+    // We require the test file to also reference the class name (import, instantiation, or receiver).
+    const classNameFilter = options.className
+        ? new RegExp('\\b' + escapeRegExp(options.className) + '\\b')
+        : null;
+
     for (const { path: testPath, entry } of testFiles) {
         try {
             const content = index._readFile(testPath);
+
+            // className scoping: skip test files that don't reference the class at all
+            if (classNameFilter && !classNameFilter.test(content)) {
+                continue;
+            }
+
             const lines = content.split('\n');
             const matches = [];
 

package/mcp/server.js

@@ -178,13 +178,6 @@ function resolveAndValidatePath(index, file) {
     return resolved;
 }
 
-function requireName(name) {
-    if (!name || !name.trim()) {
-        return toolError('Symbol name is required.');
-    }
-    return null;
-}
-
 // ============================================================================
 // CONSOLIDATED TOOL REGISTRATION
 // ============================================================================
@@ -332,19 +325,21 @@ server.registerTool(
 
             case 'about': {
                 index = getIndex(project_dir, ep);
-                const { ok, result, error } = execute(index, 'about', ep);
-                if (!ok) return tr(error); // soft error — won't kill sibling calls
-                return tr(output.formatAbout(result, {
+                const { ok, result, error, note } = execute(index, 'about', ep);
+                if (!ok) return toolError(error);
+                let aboutText = output.formatAbout(result, {
                     allHint: 'Repeat with all=true to show all.',
                     methodsHint: 'Note: obj.method() callers/callees excluded. Use include_methods=true to include them.',
                     showConfidence: ep.showConfidence !== false,
-                }));
+                });
+                if (note) aboutText += '\n\n' + note;
+                return tr(aboutText);
             }
 
             case 'context': {
                 index = getIndex(project_dir, ep);
                 const { ok, result: ctx, error, note } = execute(index, 'context', ep);
-                if (!ok) return tr(error); // context uses soft error (not toolError)
+                if (!ok) return toolError(error);
                 const { text, expandable } = output.formatContext(ctx, {
                     expandHint: 'Use expand command with item number to see code for any item.',
                     showConfidence: ep.showConfidence !== false,
@@ -358,7 +353,7 @@ server.registerTool(
             case 'impact': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'impact', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 let impactText = output.formatImpact(result);
                 if (note) impactText += '\n\n' + note;
                 return tr(impactText);
@@ -367,7 +362,7 @@ server.registerTool(
             case 'blast': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'blast', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 let blastText = output.formatBlast(result, {
                     allHint: 'Set depth to expand all children.',
                 });
@@ -377,15 +372,17 @@ server.registerTool(
 
             case 'smart': {
                 index = getIndex(project_dir, ep);
-                const { ok, result, error } = execute(index, 'smart', ep);
-                if (!ok) return tr(error); // soft error
-                return tr(output.formatSmart(result));
+                const { ok, result, error, note } = execute(index, 'smart', ep);
+                if (!ok) return toolError(error);
+                let smartText = output.formatSmart(result);
+                if (note) smartText += '\n\n' + note;
+                return tr(smartText);
             }
 
             case 'trace': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'trace', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 let traceText = output.formatTrace(result, {
                     allHint: 'Set depth to expand all children.',
                     methodsHint: 'Note: obj.method() calls excluded. Use include_methods=true to include them.'
@@ -397,7 +394,7 @@ server.registerTool(
             case 'reverse_trace': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'reverseTrace', ep);
-                if (!ok) return tr(error);
+                if (!ok) return toolError(error);
                 let rtText = output.formatReverseTrace(result, {
                     allHint: 'Set depth to expand all children.',
                 });
@@ -408,16 +405,14 @@ server.registerTool(
             case 'example': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'example', ep);
-                if (!ok) return tr(error);
-                if (!result) return tr(`No usage examples found for "${ep.name}".`);
+                if (!ok) return toolError(error);
                 return tr(output.formatExample(result, ep.name));
             }
 
             case 'related': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'related', ep);
-                if (!ok) return tr(error);
-                if (!result) return tr(`Symbol "${ep.name}" not found.`);
+                if (!ok) return toolError(error);
                 let relText = output.formatRelated(result, {
                     all: ep.all || false, top: ep.top,
                     allHint: 'Repeat with all=true to show all.'
@@ -431,7 +426,7 @@ server.registerTool(
             case 'find': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'find', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 let text = output.formatFind(result, ep.name, ep.top);
                 if (note) text += '\n\n' + note;
                 return tr(text);
@@ -440,7 +435,7 @@ server.registerTool(
             case 'usages': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'usages', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 let text = output.formatUsages(result, ep.name);
                 if (note) text += '\n\n' + note;
                 return tr(text);
@@ -449,7 +444,7 @@ server.registerTool(
             case 'toc': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'toc', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 let text = output.formatToc(result, {
                     topHint: 'Set top=N or use detailed=false for compact view.'
                 });
@@ -459,25 +454,31 @@ server.registerTool(
 
             case 'search': {
                 index = getIndex(project_dir, ep);
-                const { ok, result, error, structural } = execute(index, 'search', ep);
-                if (!ok) return tr(error); // soft error
+                const { ok, result, error, structural, note } = execute(index, 'search', ep);
+                if (!ok) return toolError(error);
+                let searchText;
                 if (structural) {
-                    return tr(output.formatStructuralSearch(result));
+                    searchText = output.formatStructuralSearch(result);
+                } else {
+                    searchText = output.formatSearch(result, ep.term);
                 }
-                return tr(output.formatSearch(result, ep.term));
+                if (note) searchText += '\n\n' + note;
+                return tr(searchText);
             }
 
             case 'tests': {
                 index = getIndex(project_dir, ep);
-                const { ok, result, error } = execute(index, 'tests', ep);
-                if (!ok) return tr(error); // soft error
-                return tr(output.formatTests(result, ep.name));
+                const { ok, result, error, note } = execute(index, 'tests', ep);
+                if (!ok) return toolError(error);
+                let testsText = output.formatTests(result, ep.name);
+                if (note) testsText += '\n\n' + note;
+                return tr(testsText);
             }
 
             case 'affected_tests': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'affectedTests', ep);
-                if (!ok) return tr(error);
+                if (!ok) return toolError(error);
                 let atText = output.formatAffectedTests(result, { all: ep.all });
                 if (note) atText += '\n\n' + note;
                 return tr(atText);
@@ -486,7 +487,7 @@ server.registerTool(
             case 'deadcode': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'deadcode', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 const dcNote = note;
                 let dcText = output.formatDeadcode(result, {
                     top: ep.top || 0,
@@ -499,9 +500,11 @@ server.registerTool(
 
             case 'entrypoints': {
                 index = getIndex(project_dir, ep);
-                const { ok, result, error } = execute(index, 'entrypoints', ep);
-                if (!ok) return tr(error);
-                return tr(output.formatEntrypoints(result));
+                const { ok, result, error, note } = execute(index, 'entrypoints', ep);
+                if (!ok) return toolError(error);
+                let epText = output.formatEntrypoints(result);
+                if (note) epText += '\n\n' + note;
+                return tr(epText);
             }
 
             // ── File Dependencies ───────────────────────────────────────
@@ -509,28 +512,28 @@ server.registerTool(
             case 'imports': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'imports', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(output.formatImports(result, ep.file));
             }
 
             case 'exporters': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'exporters', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(output.formatExporters(result, ep.file));
             }
 
             case 'file_exports': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'fileExports', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(output.formatFileExports(result, ep.file));
             }
 
             case 'graph': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'graph', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(output.formatGraph(result, {
                     showAll: ep.all || ep.depth !== undefined,
                     maxDepth: ep.depth ?? 2, file: ep.file,
@@ -542,7 +545,7 @@ server.registerTool(
             case 'circular_deps': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'circularDeps', ep);
-                if (!ok) return tr(error);
+                if (!ok) return toolError(error);
                 return tr(output.formatCircularDeps(result));
             }
 
@@ -551,22 +554,24 @@ server.registerTool(
             case 'verify': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'verify', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(output.formatVerify(result));
             }
 
             case 'plan': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'plan', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(output.formatPlan(result));
             }
 
             case 'diff_impact': {
                 index = getIndex(project_dir, ep);
-                const { ok, result, error } = execute(index, 'diffImpact', ep);
-                if (!ok) return tr(error); // soft error — e.g. "not a git repo"
-                return tr(output.formatDiffImpact(result, { all: ep.all }));
+                const { ok, result, error, note } = execute(index, 'diffImpact', ep);
+                if (!ok) return toolError(error);
+                let diText = output.formatDiffImpact(result, { all: ep.all });
+                if (note) diText += '\n\n' + note;
+                return tr(diText);
             }
 
             // ── Other ───────────────────────────────────────────────────
@@ -574,21 +579,21 @@ server.registerTool(
             case 'typedef': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'typedef', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(output.formatTypedef(result, ep.name));
             }
 
             case 'stacktrace': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'stacktrace', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(output.formatStackTrace(result));
             }
 
             case 'api': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'api', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 let apiText = output.formatApi(result, ep.file || '.');
                 if (note) apiText += '\n\n' + note;
                 return tr(apiText);
@@ -596,19 +601,19 @@ server.registerTool(
 
             case 'stats': {
                 index = getIndex(project_dir, ep);
-                const { ok, result, error } = execute(index, 'stats', ep);
-                if (!ok) return tr(error); // soft error
-                return tr(output.formatStats(result, { top: ep.top || 0 }));
+                const { ok, result, error, note } = execute(index, 'stats', ep);
+                if (!ok) return toolError(error);
+                let statsText = output.formatStats(result, { top: ep.top || 0 });
+                if (note) statsText += '\n\n' + note;
+                return tr(statsText);
             }
 
             // ── Extracting Code (via execute) ────────────────────────────
 
             case 'fn': {
-                const err = requireName(ep.name);
-                if (err) return err;
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'fn', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 // MCP path security: validate all result files are within project root
                 for (const entry of result.entries) {
                     const check = resolveAndValidatePath(index, entry.match.relativePath || path.relative(index.root, entry.match.file));
@@ -619,14 +624,9 @@ server.registerTool(
             }
 
             case 'class': {
-                const err = requireName(ep.name);
-                if (err) return err;
-                if (ep.maxLines !== undefined && (!Number.isInteger(ep.maxLines) || ep.maxLines < 1)) {
-                    return toolError(`Invalid max_lines: ${ep.maxLines}. Must be a positive integer.`);
-                }
                 index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'class', ep);
-                if (!ok) return tr(error);  // soft error (class not found)
+                if (!ok) return toolError(error);  // soft error (class not found)
                 // MCP path security: validate all result files are within project root
                 for (const entry of result.entries) {
                     const check = resolveAndValidatePath(index, entry.match.relativePath || path.relative(index.root, entry.match.file));
@@ -639,7 +639,7 @@ server.registerTool(
             case 'lines': {
                 index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'lines', ep);
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 // MCP path security: validate file is within project root
                 const check = resolveAndValidatePath(index, result.relativePath);
                 if (typeof check !== 'string') return check;
@@ -657,7 +657,7 @@ server.registerTool(
                     itemCount: lookup.itemCount, symbolName: lookup.symbolName,
                     validateRoot: true
                 });
-                if (!ok) return tr(error); // soft error
+                if (!ok) return toolError(error);
                 return tr(result.text);
             }
 

package/package.json

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