ucn 3.7.27 → 3.7.29

package/README.md

@@ -20,13 +20,13 @@ Instead of reading full files, UCN gives precise, AST-verified answers.
 ```bash
 npm install -g ucn
 
-ucn about handleRequest       # full picture: definition, callers, callees, tests
-ucn impact handleRequest      # all call sites with arguments
-ucn trace main --depth=3      # call tree, no file reads
-ucn deadcode                  # unused functions, AST-verified
-ucn fn handleRequest             # extract a function without reading the file
-ucn toc                          # project overview
-ucn --interactive                # REPL mode, index stays in memory
+ucn about handleRequest   # full picture: definition, callers, callees, tests
+ucn impact handleRequest  # all call sites with arguments
+ucn trace main --depth=3  # call tree, no file reads
+ucn deadcode              # unused functions, AST-verified
+ucn fn handleRequest      # extract a function without reading the file
+ucn toc                   # project overview
+ucn --interactive         # REPL mode, index stays in memory
 ```
 
 Parses JS/TS, Python, Go, Rust, Java, and HTML with tree-sitter. Runs locally.

package/core/callers.js

@@ -386,6 +386,13 @@ function findCallees(index, def, options = {}) {
         let selfAttrCalls = null;   // collected for Python self.attr.method() resolution
         let selfMethodCalls = null; // collected for Python self.method() resolution
 
+        // Build local variable type map for receiver resolution
+        // Scans for patterns like: bt = Backtester(...) → bt maps to Backtester
+        let localTypes = null;
+        if (language === 'python' || language === 'javascript') {
+            localTypes = _buildLocalTypeMap(index, def, calls);
+        }
+
         for (const call of calls) {
             // Filter to calls within this function's scope
             // Method 1: Direct match via enclosingFunction (fast path for direct calls)
@@ -412,6 +419,22 @@ function findCallees(index, def, options = {}) {
                     // self.method() / cls.method() / this.method() — resolve to same-class method below
                 } else if (call.receiver === 'super') {
                     // super().method() — resolve to parent class method below
+                } else if (localTypes && localTypes.has(call.receiver)) {
+                    // Resolve method calls on locally-constructed objects:
+                    // bt = Backtester(...); bt.run_backtest() → Backtester.run_backtest
+                    const className = localTypes.get(call.receiver);
+                    const symbols = index.symbols.get(call.name);
+                    const match = symbols?.find(s => s.className === className);
+                    if (match) {
+                        const key = match.bindingId || `${className}.${call.name}`;
+                        const existing = callees.get(key);
+                        if (existing) {
+                            existing.count += 1;
+                        } else {
+                            callees.set(key, { name: call.name, bindingId: match.bindingId, count: 1 });
+                        }
+                    }
+                    continue;
                 } else if (language !== 'go' && language !== 'java' && language !== 'rust' && !options.includeMethods) {
                     continue;
                 }
@@ -704,7 +727,18 @@ function findCallees(index, def, options = {}) {
                             }
                         }
                     }
-                    // Priority 4: If default (symbols[0]) is a test file, prefer non-test
+                    // Priority 4: If default is from a bundled/minified file, prefer non-bundled
+                    if (!bindingId) {
+                        const calleeFileEntry = index.files.get(callee.file);
+                        if (calleeFileEntry && calleeFileEntry.isBundled) {
+                            const nonBundled = symbols.find(s => {
+                                const fe = index.files.get(s.file);
+                                return fe && !fe.isBundled;
+                            });
+                            if (nonBundled) callee = nonBundled;
+                        }
+                    }
+                    // Priority 5: If default is a test file, prefer non-test
                     if (!bindingId) {
                         const calleeFileEntry = index.files.get(callee.file);
                         if (calleeFileEntry && isTestFile(calleeFileEntry.relativePath, calleeFileEntry.language)) {
@@ -778,6 +812,60 @@ function getInstanceAttributeTypes(index, filePath, className) {
     return fileCache.get(className) || null;
 }
 
+/**
+ * Build a local variable type map for a function body.
+ * Scans for constructor-call assignments: var = ClassName(...)
+ * Returns Map<varName, className> or null if none found.
+ * @param {object} index - ProjectIndex instance
+ * @param {object} def - Function definition with file, startLine, endLine
+ * @param {Array} calls - Cached call sites for the file
+ */
+function _buildLocalTypeMap(index, def, calls) {
+    let content;
+    try {
+        content = index._readFile(def.file);
+    } catch {
+        return null;
+    }
+    const lines = content.split('\n');
+    const localTypes = new Map();
+
+    for (const call of calls) {
+        // Only look at calls within this function's scope
+        if (call.line < def.startLine || call.line > def.endLine) continue;
+        // Only direct calls (not method calls) — these are potential constructors
+        if (call.isMethod || call.isPotentialCallback) continue;
+
+        // Check if this call's name corresponds to a class in the symbol table
+        const symbols = index.symbols.get(call.name);
+        if (!symbols) continue;
+        const isClass = symbols.some(s => NON_CALLABLE_TYPES.has(s.type));
+        if (!isClass) continue;
+
+        // Check the source line for assignment pattern: var = ClassName(...)
+        const sourceLine = lines[call.line - 1];
+        if (!sourceLine) continue;
+
+        // Match: identifier = ClassName(...) or identifier: Type = ClassName(...)
+        const escapedName = call.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const assignMatch = sourceLine.match(
+            new RegExp(`(\\w+)\\s*(?::\\s*\\w+)?\\s*=\\s*${escapedName}\\s*\\(`)
+        );
+        if (assignMatch) {
+            localTypes.set(assignMatch[1], call.name);
+        }
+        // Match: with ClassName(...) as identifier:
+        const withMatch = sourceLine.match(
+            new RegExp(`with\\s+${escapedName}\\s*\\([^)]*\\)\\s+as\\s+(\\w+)`)
+        );
+        if (withMatch) {
+            localTypes.set(withMatch[1], call.name);
+        }
+    }
+
+    return localTypes.size > 0 ? localTypes : null;
+}
+
 /**
  * Check if a function is used as a callback anywhere in the codebase
  * @param {object} index - ProjectIndex instance

package/core/discovery.js

@@ -30,6 +30,7 @@ const DEFAULT_IGNORES = [
 
     // Build outputs
     'dist',
+    '*-dist',
     'build',
     'out',
     '.next',
@@ -38,6 +39,12 @@ const DEFAULT_IGNORES = [
     '.output',
     '.vercel',
     '.netlify',
+    '.turbo',
+    '.parcel-cache',
+    '.svelte-kit',
+    '.docusaurus',
+    'storybook-static',
+    '_site',
 
     // Test/coverage
     'coverage',

package/core/execute.js

@@ -184,7 +184,12 @@ const HANDLERS = {
     find: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
-        const exclude = applyTestExclusions(p.exclude, p.includeTests);
+        // Auto-include tests when pattern clearly targets test functions
+        let includeTests = p.includeTests;
+        if (!includeTests && p.name && /^test[_*?]/i.test(p.name)) {
+            includeTests = true;
+        }
+        const exclude = applyTestExclusions(p.exclude, includeTests);
         const result = index.find(p.name, {
             file: p.file,
             exact: p.exact || false,

package/core/imports.js

@@ -507,6 +507,32 @@ function loadTsConfig(tsconfigPath, visited) {
         }
     }
 
+    // Follow project references to collect paths from referenced configs
+    // (tsconfig.json with "references" pointing to tsconfig.app.json, tsconfig.node.json, etc.)
+    if (config.references && Array.isArray(config.references)) {
+        for (const ref of config.references) {
+            if (!ref.path) continue;
+            let refPath = path.resolve(configDir, ref.path);
+            // If reference points to a directory, look for tsconfig.json inside it
+            if (fs.existsSync(refPath) && fs.statSync(refPath).isDirectory()) {
+                refPath = path.join(refPath, 'tsconfig.json');
+            }
+            // Add .json extension if not present
+            if (!refPath.endsWith('.json')) refPath += '.json';
+            if (fs.existsSync(refPath)) {
+                try {
+                    const refResult = loadTsConfig(refPath, visited);
+                    if (refResult) {
+                        basePaths = { ...basePaths, ...refResult.paths };
+                        if (refResult.baseUrl && !baseUrl) baseUrl = refResult.baseUrl;
+                    }
+                } catch {
+                    // Skip malformed reference config
+                }
+            }
+        }
+    }
+
     // Child config values override base config
     const mergedPaths = { ...basePaths, ...(config.compilerOptions?.paths || {}) };
     const compiledPaths = Object.entries(mergedPaths).map(([pattern, targets]) => ({

package/core/output.js

@@ -613,6 +613,10 @@ function formatApi(symbols, filePath) {
 
     if (symbols.length === 0) {
         lines.push('  (none found)');
+        if (filePath && filePath.endsWith('.py')) {
+            lines.push('');
+            lines.push('Note: Python requires __all__ for export detection. Use \'toc\' command to see all functions/classes.');
+        }
     } else {
         // Group by file
         const byFile = new Map();

package/core/project.js

@@ -759,10 +759,17 @@ class ProjectIndex {
         // Glob pattern matching (e.g., _update*, handle*Request, get?ata)
         const isGlob = name.includes('*') || name.includes('?');
         if (isGlob && !options.exact) {
-            // Guard against bare wildcards that would match everything
+            // Bare wildcard: return all symbols
             const stripped = name.replace(/[*?]/g, '');
             if (stripped.length === 0) {
-                return [];
+                const all = [];
+                for (const [, symbols] of this.symbols) {
+                    for (const sym of symbols) {
+                        all.push({ ...sym, _fuzzyScore: 800 });
+                    }
+                }
+                all.sort((a, b) => (a.name || '').localeCompare(b.name || ''));
+                return this._applyFindFilters(all, options);
             }
             const globRegex = new RegExp('^' + name.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i');
             const matches = [];
@@ -1477,42 +1484,145 @@ class ProjectIndex {
      */
     isKeyword(name, language) {
         if (!LANGUAGE_KEYWORDS) {
-            // Initialize on first use
+            // Initialize on first use — includes both keywords AND builtins
+            // to prevent cross-language false positives (e.g. Python set() → JS bundle)
             LANGUAGE_KEYWORDS = {
                 javascript: new Set([
+                    // Keywords
                     'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'break',
                     'continue', 'return', 'function', 'class', 'const', 'let', 'var',
                     'new', 'this', 'super', 'import', 'export', 'default', 'from',
                     'try', 'catch', 'finally', 'throw', 'async', 'await', 'yield',
-                    'typeof', 'instanceof', 'in', 'of', 'delete', 'void', 'with'
+                    'typeof', 'instanceof', 'in', 'of', 'delete', 'void', 'with',
+                    // Global builtins
+                    'undefined', 'NaN', 'Infinity', 'globalThis',
+                    'parseInt', 'parseFloat', 'isNaN', 'isFinite',
+                    'encodeURI', 'decodeURI', 'encodeURIComponent', 'decodeURIComponent',
+                    'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval',
+                    'console', 'JSON', 'Math', 'Date', 'RegExp',
+                    'Object', 'Array', 'String', 'Number', 'Boolean', 'Symbol', 'BigInt',
+                    'Map', 'Set', 'WeakMap', 'WeakSet', 'WeakRef',
+                    'Promise', 'Proxy', 'Reflect',
+                    'Error', 'TypeError', 'RangeError', 'ReferenceError', 'SyntaxError',
+                    'URIError', 'EvalError', 'AggregateError',
+                    'ArrayBuffer', 'SharedArrayBuffer', 'DataView',
+                    'Int8Array', 'Uint8Array', 'Int16Array', 'Uint16Array',
+                    'Int32Array', 'Uint32Array', 'Float32Array', 'Float64Array',
+                    'BigInt64Array', 'BigUint64Array',
+                    'TextEncoder', 'TextDecoder', 'URL', 'URLSearchParams',
+                    'fetch', 'Request', 'Response', 'Headers',
+                    'atob', 'btoa', 'structuredClone', 'queueMicrotask',
+                    'require'
                 ]),
                 python: new Set([
+                    // Keywords
                     'if', 'else', 'elif', 'for', 'while', 'def', 'class', 'return',
                     'import', 'from', 'try', 'except', 'finally', 'raise', 'async',
                     'await', 'yield', 'with', 'as', 'lambda', 'pass', 'break',
                     'continue', 'del', 'global', 'nonlocal', 'assert', 'is', 'not',
-                    'and', 'or', 'in', 'True', 'False', 'None', 'self', 'cls'
+                    'and', 'or', 'in', 'True', 'False', 'None', 'self', 'cls',
+                    // Type constructors
+                    'int', 'float', 'str', 'bool', 'list', 'dict', 'set', 'tuple',
+                    'bytes', 'bytearray', 'frozenset', 'complex', 'memoryview',
+                    'object', 'type',
+                    // Common builtins
+                    'print', 'len', 'range', 'abs', 'round', 'min', 'max', 'sum',
+                    'sorted', 'reversed', 'enumerate', 'zip', 'map', 'filter',
+                    'any', 'all', 'iter', 'next', 'hash', 'id', 'repr', 'format',
+                    'chr', 'ord', 'hex', 'oct', 'bin', 'pow', 'divmod',
+                    'input', 'open', 'super',
+                    // Introspection
+                    'isinstance', 'issubclass', 'hasattr', 'getattr', 'setattr',
+                    'delattr', 'callable', 'dir', 'vars', 'globals', 'locals', 'help',
+                    // Decorators / descriptors
+                    'property', 'staticmethod', 'classmethod',
+                    // Exception types
+                    'Exception', 'BaseException', 'ValueError', 'TypeError',
+                    'KeyError', 'IndexError', 'AttributeError', 'RuntimeError',
+                    'NotImplementedError', 'StopIteration', 'StopAsyncIteration',
+                    'GeneratorExit', 'OSError', 'IOError', 'FileNotFoundError',
+                    'FileExistsError', 'PermissionError', 'IsADirectoryError',
+                    'ImportError', 'ModuleNotFoundError', 'NameError',
+                    'UnboundLocalError', 'ZeroDivisionError', 'OverflowError',
+                    'FloatingPointError', 'ArithmeticError', 'LookupError',
+                    'RecursionError', 'MemoryError', 'SystemExit',
+                    'KeyboardInterrupt', 'AssertionError',
+                    'UnicodeError', 'UnicodeDecodeError', 'UnicodeEncodeError',
+                    'Warning', 'DeprecationWarning', 'FutureWarning',
+                    'UserWarning', 'SyntaxWarning', 'RuntimeWarning',
+                    'ConnectionError', 'TimeoutError', 'BrokenPipeError',
+                    // Other builtins
+                    'NotImplemented', 'Ellipsis', '__import__', '__name__',
+                    '__file__', '__doc__', '__all__', '__init__', '__new__',
+                    '__del__', '__repr__', '__str__', '__len__', '__iter__'
                 ]),
                 go: new Set([
+                    // Keywords
                     'if', 'else', 'for', 'switch', 'case', 'break', 'continue',
                     'return', 'func', 'type', 'struct', 'interface', 'package',
                     'import', 'go', 'defer', 'select', 'chan', 'map', 'range',
-                    'fallthrough', 'goto', 'var', 'const', 'default'
+                    'fallthrough', 'goto', 'var', 'const', 'default',
+                    // Builtins
+                    'append', 'cap', 'close', 'copy', 'delete', 'len', 'make',
+                    'new', 'panic', 'recover', 'print', 'println', 'complex',
+                    'real', 'imag', 'clear', 'min', 'max',
+                    // Builtin types (prevent cross-language matches)
+                    'error', 'string', 'bool', 'byte', 'rune',
+                    'int', 'int8', 'int16', 'int32', 'int64',
+                    'uint', 'uint8', 'uint16', 'uint32', 'uint64', 'uintptr',
+                    'float32', 'float64', 'complex64', 'complex128',
+                    'nil', 'true', 'false', 'iota'
                 ]),
                 rust: new Set([
+                    // Keywords
                     'if', 'else', 'for', 'while', 'loop', 'fn', 'impl', 'pub',
                     'mod', 'use', 'crate', 'self', 'super', 'match', 'unsafe',
                     'move', 'ref', 'mut', 'where', 'let', 'const', 'struct',
                     'enum', 'trait', 'async', 'await', 'return', 'break',
-                    'continue', 'type', 'as', 'in', 'dyn', 'static'
+                    'continue', 'type', 'as', 'in', 'dyn', 'static',
+                    // Macros (common calls that aren't project functions)
+                    'println', 'print', 'eprintln', 'eprint', 'format',
+                    'vec', 'panic', 'assert', 'assert_eq', 'assert_ne',
+                    'debug_assert', 'debug_assert_eq', 'debug_assert_ne',
+                    'todo', 'unimplemented', 'unreachable',
+                    'cfg', 'derive', 'include', 'include_str', 'include_bytes',
+                    'env', 'concat', 'stringify', 'file', 'line', 'column',
+                    // Std prelude types/traits
+                    'Some', 'None', 'Ok', 'Err', 'Box', 'Vec', 'String',
+                    'Option', 'Result', 'Clone', 'Copy', 'Drop',
+                    'Default', 'Debug', 'Display', 'Iterator',
+                    'From', 'Into', 'TryFrom', 'TryInto',
+                    'AsRef', 'AsMut', 'Deref', 'DerefMut',
+                    'Send', 'Sync', 'Sized', 'Unpin',
+                    'Fn', 'FnMut', 'FnOnce',
+                    'PartialEq', 'Eq', 'PartialOrd', 'Ord', 'Hash'
                 ]),
                 java: new Set([
+                    // Keywords
                     'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'break',
                     'continue', 'return', 'class', 'interface', 'enum', 'extends',
                     'implements', 'new', 'this', 'super', 'import', 'package',
                     'try', 'catch', 'finally', 'throw', 'throws', 'abstract',
                     'static', 'final', 'synchronized', 'volatile', 'transient',
-                    'native', 'void', 'instanceof', 'default'
+                    'native', 'void', 'instanceof', 'default',
+                    // Primitive types
+                    'boolean', 'byte', 'char', 'short', 'int', 'long',
+                    'float', 'double', 'null', 'true', 'false',
+                    // java.lang builtins (auto-imported)
+                    'System', 'String', 'Object', 'Class', 'Integer', 'Long',
+                    'Double', 'Float', 'Boolean', 'Character', 'Byte', 'Short',
+                    'Math', 'StringBuilder', 'StringBuffer',
+                    'Thread', 'Runnable', 'Throwable',
+                    'Exception', 'RuntimeException', 'Error',
+                    'NullPointerException', 'IllegalArgumentException',
+                    'IllegalStateException', 'IndexOutOfBoundsException',
+                    'ClassCastException', 'UnsupportedOperationException',
+                    'ArithmeticException', 'SecurityException',
+                    'StackOverflowError', 'OutOfMemoryError',
+                    'Override', 'Deprecated', 'SuppressWarnings',
+                    'FunctionalInterface', 'SafeVarargs',
+                    'Iterable', 'Comparable', 'AutoCloseable', 'Cloneable',
+                    'Enum', 'Record', 'Void'
                 ])
             };
             // TypeScript/TSX share JavaScript keywords

package/languages/python.js

@@ -487,10 +487,25 @@ function findCallsInCode(code, parser) {
                         }
                     }
                 }
-                // Track non-callable assignments: count = 5, name = "hello"
+                // Track non-callable assignments.
+                // First: explicit literal check (handles dicts-with-lambdas correctly)
                 if (right && isNonCallableInit(right)) {
                     nonCallableNames.add(left.text);
                 }
+                // Second: function call results are generally non-callable data
+                // (e.g., close = series.dropna(), result = db.query(...))
+                // Exception: partial() already handled above via alias tracking.
+                else if (right?.type === 'call' && !aliases.has(left.text)) {
+                    nonCallableNames.add(left.text);
+                }
+                // Third: subscript/attribute access results are non-callable data
+                // (e.g., close = candles["close"].values, item = data[0])
+                else if (right && !aliases.has(left.text) &&
+                    ['subscript', 'attribute', 'binary_operator', 'comparison_operator',
+                     'unary_operator', 'conditional_expression', 'await',
+                     'parenthesized_expression', 'not_operator', 'boolean_operator'].includes(right.type)) {
+                    nonCallableNames.add(left.text);
+                }
             }
         }
 

package/mcp/server.js

@@ -276,7 +276,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, file, exclude, with_types, all, include_methods, include_uncertain, top });
                 const { ok, result, error } = execute(index, 'about', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error — won't kill sibling calls
                 return toolResult(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.'
@@ -299,7 +299,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, file, exclude });
                 const { ok, result, error } = execute(index, 'impact', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatImpact(result));
             }
 
@@ -315,7 +315,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, file, depth, all, include_methods, include_uncertain });
                 const { ok, result, error } = execute(index, 'trace', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatTrace(result, {
                     allHint: 'Set depth to expand all children.',
                     methodsHint: 'Note: obj.method() calls excluded. Use include_methods=true to include them.'
@@ -347,7 +347,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, file, exclude, include_tests, exact, in: inPath });
                 const { ok, result, error } = execute(index, 'find', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatFind(result, name, top));
             }
 
@@ -355,7 +355,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, exclude, include_tests, code_only, context: ctxLines, in: inPath });
                 const { ok, result, error } = execute(index, 'usages', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatUsages(result, name));
             }
 
@@ -363,7 +363,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ detailed, top_level, all, top });
                 const { ok, result, error } = execute(index, 'toc', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatToc(result, {
                     topHint: 'Set top=N or use detailed=false for compact view.'
                 }));
@@ -373,7 +373,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ term, exclude, include_tests, code_only, context: ctxLines, case_sensitive, in: inPath, regex });
                 const { ok, result, error } = execute(index, 'search', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatSearch(result, term));
             }
 
@@ -381,7 +381,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, calls_only });
                 const { ok, result, error } = execute(index, 'tests', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatTests(result, name));
             }
 
@@ -389,7 +389,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ exclude, in: inPath, include_exported, include_decorated, include_tests });
                 const { ok, result, error } = execute(index, 'deadcode', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatDeadcode(result, {
                     top: top || 0,
                     decoratedHint: !include_decorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use include_decorated=true to include them.` : undefined,
@@ -402,28 +402,28 @@ server.registerTool(
             case 'imports': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'imports', { file });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatImports(result, file));
             }
 
             case 'exporters': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'exporters', { file });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatExporters(result, file));
             }
 
             case 'file_exports': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'fileExports', { file });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatFileExports(result, file));
             }
 
             case 'graph': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'graph', { file, direction, depth, all });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatGraph(result, {
                     showAll: all || depth !== undefined,
                     maxDepth: depth ?? 2, file,
@@ -437,7 +437,7 @@ server.registerTool(
             case 'verify': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'verify', { name, file });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatVerify(result));
             }
 
@@ -445,14 +445,14 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, add_param, remove_param, rename_to, default_value, file });
                 const { ok, result, error } = execute(index, 'plan', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatPlan(result));
             }
 
             case 'diff_impact': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'diffImpact', { base, staged, file });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error — e.g. "not a git repo"
                 return toolResult(output.formatDiffImpact(result));
             }
 
@@ -461,28 +461,28 @@ server.registerTool(
             case 'typedef': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'typedef', { name, exact });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatTypedef(result, name));
             }
 
             case 'stacktrace': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'stacktrace', { stack });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatStackTrace(result));
             }
 
             case 'api': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'api', { file });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatApi(result, file || '.'));
             }
 
             case 'stats': {
                 const index = getIndex(project_dir);
                 const { ok, result, error } = execute(index, 'stats', { functions });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(output.formatStats(result, { top: top || 0 }));
             }
 
@@ -494,7 +494,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ name, file, all });
                 const { ok, result, error } = execute(index, 'fn', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft 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));
@@ -527,7 +527,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const ep = normalizeParams({ file, range });
                 const { ok, result, error } = execute(index, 'lines', ep);
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 // MCP path security: validate file is within project root
                 const check = resolveAndValidatePath(index, result.relativePath);
                 if (typeof check !== 'string') return check;
@@ -545,7 +545,7 @@ server.registerTool(
                     itemCount: lookup.itemCount, symbolName: lookup.symbolName,
                     validateRoot: true
                 });
-                if (!ok) return toolError(error);
+                if (!ok) return toolResult(error); // soft error
                 return toolResult(result.text);
             }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.27",
+  "version": "3.7.29",
   "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",
@@ -9,7 +9,8 @@
     "ucn-mcp": "mcp/server.js"
   },
   "scripts": {
-    "test": "node --test test/parser-unit.test.js test/integration.test.js test/cache.test.js test/formatter.test.js test/interactive.test.js test/feature.test.js test/regression-js.test.js test/regression-py.test.js test/regression-go.test.js test/regression-java.test.js test/regression-rust.test.js test/regression-cross.test.js test/accuracy.test.js test/systematic-test.js test/mcp-edge-cases.js test/parity-test.js"
+    "test": "node --test test/parser-unit.test.js test/integration.test.js test/cache.test.js test/formatter.test.js test/interactive.test.js test/feature.test.js test/regression-js.test.js test/regression-py.test.js test/regression-go.test.js test/regression-java.test.js test/regression-rust.test.js test/regression-cross.test.js test/accuracy.test.js test/systematic-test.js test/mcp-edge-cases.js test/parity-test.js",
+    "benchmark:agent": "node test/agent-understanding-benchmark.js"
   },
   "keywords": [
     "mcp",