ucn 3.7.27 → 3.7.28

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

@@ -704,7 +704,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)) {

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/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

@@ -1477,42 +1477,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/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.28",
   "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",