ucn 3.7.16 → 3.7.18

package/.claude/skills/ucn/SKILL.md

@@ -99,6 +99,12 @@ ucn deadcode --exclude=test         # Skip test files (most useful)
 | Preview a rename or param change | `ucn plan <name> --rename-to=new_name` | Shows what would change without doing it |
 | File-level dependency tree | `ucn graph <file> --depth=1` | Visual import tree. Setting `--depth=N` expands all children. Can be noisy — use depth=1 for large projects. For function-level flow, use `trace` instead |
 | Find which tests cover a function | `ucn tests <name>` | Test files and test function names |
+| Extract specific lines from a file | `ucn lines --file=<file> --range=10-20` | Pull a line range without reading the whole file |
+| Find type definitions | `ucn typedef <name>` | Interfaces, enums, structs, traits, type aliases |
+| See a project's public API | `ucn api` or `ucn api --file=<file>` | All exported/public symbols with signatures |
+| Drill into context results | `ucn expand <N>` | Show source code for item N from a previous `context` call |
+| Best usage example of a function | `ucn example <name>` | Finds and scores the best call site with surrounding context |
+| Debug a stack trace | `ucn stacktrace --stack="<trace>"` | Parses stack frames and shows source context per frame |
 
 ## Command Format
 
@@ -126,9 +132,20 @@ ucn [target] <command> [name] [--flags]
 | `--base=<ref>` | Git ref for diff-impact (default: HEAD) |
 | `--staged` | Analyze staged changes (diff-impact) |
 | `--no-cache` | Force re-index after editing files |
+| `--clear-cache` | Delete cached index entirely before running |
 | `--context=N` | Lines of surrounding context in `usages`/`search` output |
 | `--no-regex` | Force plain text search (regex is default) |
 | `--functions` | Show per-function line counts in `stats` (complexity audit) |
+| `--json` | Machine-readable JSON output (wrapped in `{meta, data}`) |
+| `--code-only` | Exclude matches in comments and strings (`search`/`usages`) |
+| `--with-types` | Include related type definitions in `smart`/`about` output |
+| `--detailed` | Show full symbol listing per file in `toc` |
+| `--top=N` | Limit result count (default: 10 for most commands) |
+| `--case-sensitive` | Case-sensitive text search (default: case-insensitive) |
+| `--exact` | Exact name match only in `find`/`typedef` (no substring) |
+| `--include-uncertain` | Include ambiguous/uncertain matches in `context`/`smart`/`about` |
+| `--include-exported` | Include exported symbols in `deadcode` results |
+| `--include-decorated` | Include decorated/annotated symbols in `deadcode` results |
 
 ## Workflow Integration
 

package/cli/index.js

@@ -86,7 +86,9 @@ const flags = {
     // Regex search mode (default: ON; --no-regex to force plain text)
     regex: args.includes('--no-regex') ? false : undefined,
     // Stats: per-function line counts
-    functions: args.includes('--functions')
+    functions: args.includes('--functions'),
+    // Class: max lines to show (0 = no limit)
+    maxLines: parseInt(args.find(a => a.startsWith('--max-lines='))?.split('=')[1] || '0') || null
 };
 
 // Handle --file flag with space
@@ -106,7 +108,8 @@ const knownFlags = new Set([
     '--depth', '--direction', '--add-param', '--remove-param', '--rename-to',
     '--default', '--top', '--no-follow-symlinks',
     '--base', '--staged',
-    '--regex', '--no-regex', '--functions'
+    '--regex', '--no-regex', '--functions',
+    '--max-lines'
 ]);
 
 // Handle help flag
@@ -841,7 +844,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'about': {
             requireArg(arg, 'Usage: ucn . about <name>');
-            const aboutResult = index.about(arg, { withTypes: flags.withTypes, file: flags.file, all: flags.all, includeMethods: flags.includeMethods, includeUncertain: flags.includeUncertain, exclude: flags.exclude });
+            const aboutResult = index.about(arg, { withTypes: flags.withTypes, file: flags.file, all: flags.all, includeMethods: flags.includeMethods, includeUncertain: flags.includeUncertain, exclude: flags.exclude, maxCallers: flags.top || undefined, maxCallees: flags.top || undefined });
             printOutput(aboutResult,
                 output.formatAboutJson,
                 r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth })
@@ -899,8 +902,8 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'related': {
             requireArg(arg, 'Usage: ucn . related <name>');
-            const relatedResult = index.related(arg, { file: flags.file, all: flags.all });
-            printOutput(relatedResult, output.formatRelatedJson, r => output.formatRelated(r, { showAll: flags.all }));
+            const relatedResult = index.related(arg, { file: flags.file, top: flags.top, all: flags.all });
+            printOutput(relatedResult, output.formatRelatedJson, r => output.formatRelated(r, { showAll: flags.all, top: flags.top }));
             break;
         }
 
@@ -997,7 +1000,11 @@ function runProjectCommand(rootDir, command, arg) {
             });
             printOutput(deadcodeResults,
                 output.formatDeadcodeJson,
-                r => output.formatDeadcode(r, { top: flags.top })
+                r => output.formatDeadcode(r, {
+                    top: flags.top,
+                    decoratedHint: !flags.includeDecorated && deadcodeResults.excludedDecorated > 0 ? `${deadcodeResults.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
+                    exportedHint: !flags.includeExported && deadcodeResults.excludedExported > 0 ? `${deadcodeResults.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.` : undefined
+                })
             );
             break;
         }
@@ -1162,6 +1169,45 @@ function extractClassFromProject(index, name, overrideFlags) {
     // Use index data directly instead of re-parsing the file
     const code = fs.readFileSync(match.file, 'utf-8');
     const codeLines = code.split('\n');
+    const classLineCount = match.endLine - match.startLine + 1;
+
+    // Large class summary (>200 lines) when no --max-lines specified
+    if (classLineCount > 200 && !f.maxLines) {
+        if (f.json) {
+            const extracted = codeLines.slice(match.startLine - 1, match.endLine);
+            const clsCode = cleanHtmlScriptTags(extracted, detectLanguage(match.file)).join('\n');
+            console.log(JSON.stringify({ ...match, code: clsCode }, null, 2));
+        } else {
+            const lines = [];
+            lines.push(`${match.relativePath}:${match.startLine}`);
+            lines.push(`${output.lineRange(match.startLine, match.endLine)} ${output.formatClassSignature(match)}`);
+            lines.push('\u2500'.repeat(60));
+            const methods = index.findMethodsForType(match.name);
+            if (methods.length > 0) {
+                lines.push(`\nMethods (${methods.length}):`);
+                for (const m of methods) {
+                    lines.push(`  ${output.formatFunctionSignature(m)}  [line ${m.startLine}]`);
+                }
+            }
+            lines.push(`\nClass is ${classLineCount} lines. Use --max-lines=N to see source, or "fn <method>" for individual methods.`);
+            console.log(lines.join('\n'));
+        }
+        return;
+    }
+
+    // Truncated source with --max-lines
+    if (f.maxLines && classLineCount > f.maxLines) {
+        const truncated = codeLines.slice(match.startLine - 1, match.startLine - 1 + f.maxLines);
+        const truncatedCode = cleanHtmlScriptTags(truncated, detectLanguage(match.file)).join('\n');
+        if (f.json) {
+            console.log(JSON.stringify({ ...match, code: truncatedCode, truncated: true, totalLines: classLineCount }, null, 2));
+        } else {
+            console.log(output.formatClass(match, truncatedCode));
+            console.log(`\n... showing ${f.maxLines} of ${classLineCount} lines`);
+        }
+        return;
+    }
+
     const extracted = codeLines.slice(match.startLine - 1, match.endLine);
     const clsCode = cleanHtmlScriptTags(extracted, detectLanguage(match.file)).join('\n');
 
@@ -1902,6 +1948,7 @@ function parseInteractiveFlags(tokens) {
         includeUncertain: tokens.includes('--include-uncertain'),
         includeMethods: tokens.includes('--include-methods=false') ? false : tokens.includes('--include-methods') ? true : undefined,
         detailed: tokens.includes('--detailed'),
+        topLevel: tokens.includes('--top-level'),
         all: tokens.includes('--all'),
         exact: tokens.includes('--exact'),
         callsOnly: tokens.includes('--calls-only'),
@@ -1928,9 +1975,10 @@ function parseInteractiveFlags(tokens) {
 function executeInteractiveCommand(index, command, arg, iflags = {}) {
     switch (command) {
         case 'toc': {
-            const toc = index.getToc({ detailed: iflags.detailed });
+            const toc = index.getToc({ detailed: iflags.detailed, topLevel: iflags.topLevel, all: iflags.all, top: iflags.top });
             console.log(output.formatToc(toc, {
-                detailedHint: 'Add --detailed to list all functions, or "about <name>" for full details on a symbol'
+                detailedHint: 'Add --detailed to list all functions, or "about <name>" for full details on a symbol',
+                uncertainHint: 'use --include-uncertain to include all'
             }));
             break;
         }
@@ -1940,7 +1988,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: find <name>');
                 return;
             }
-            const found = index.find(arg, { exact: iflags.exact, exclude: iflags.exclude, in: iflags.in, includeTests: iflags.includeTests });
+            const findExclude = iflags.includeTests ? iflags.exclude : addTestExclusions(iflags.exclude);
+            const found = index.find(arg, { file: iflags.file, exact: iflags.exact, exclude: findExclude, in: iflags.in });
             if (found.length === 0) {
                 console.log(`No symbols found for "${arg}"`);
             } else {
@@ -1954,7 +2003,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: about <name>');
                 return;
             }
-            const aboutResult = index.about(arg, { includeMethods: iflags.includeMethods, includeUncertain: iflags.includeUncertain, file: iflags.file, exclude: iflags.exclude });
+            const aboutResult = index.about(arg, { withTypes: iflags.withTypes, file: iflags.file, all: iflags.all, includeMethods: iflags.includeMethods, includeUncertain: iflags.includeUncertain, exclude: iflags.exclude, maxCallers: iflags.top || undefined, maxCallees: iflags.top || undefined });
             console.log(output.formatAbout(aboutResult, { expand: iflags.expand, root: index.root, showAll: iflags.all }));
             break;
         }
@@ -1964,7 +2013,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: usages <name>');
                 return;
             }
-            const usages = index.usages(arg, { context: iflags.context, codeOnly: iflags.codeOnly, includeTests: iflags.includeTests });
+            const usagesExclude = iflags.includeTests ? iflags.exclude : addTestExclusions(iflags.exclude);
+            const usages = index.usages(arg, { codeOnly: iflags.codeOnly, context: iflags.context, exclude: usagesExclude, in: iflags.in });
             console.log(output.formatUsages(usages, arg));
             break;
         }
@@ -1994,7 +2044,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: smart <name>');
                 return;
             }
-            const smart = index.smart(arg, { file: iflags.file, includeUncertain: iflags.includeUncertain, withTypes: iflags.withTypes });
+            const smart = index.smart(arg, { file: iflags.file, withTypes: iflags.withTypes, includeMethods: iflags.includeMethods, includeUncertain: iflags.includeUncertain });
             if (smart) {
                 console.log(output.formatSmart(smart, {
                     uncertainHint: 'use --include-uncertain to include all'
@@ -2010,7 +2060,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: impact <name>');
                 return;
             }
-            const impactResult = index.impact(arg, { file: iflags.file });
+            const impactResult = index.impact(arg, { file: iflags.file, exclude: iflags.exclude });
             console.log(output.formatImpact(impactResult));
             break;
         }
@@ -2076,7 +2126,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
             const graphDepth = iflags.depth ? parseInt(iflags.depth) : 2;
             const graphDirection = iflags.direction || 'both';
             const graphResult = index.graph(arg, { direction: graphDirection, maxDepth: graphDepth });
-            console.log(output.formatGraph(graphResult, { showAll: iflags.all, maxDepth: graphDepth }));
+            console.log(output.formatGraph(graphResult, { showAll: iflags.all || !!iflags.depth, maxDepth: graphDepth, file: arg }));
             break;
         }
 
@@ -2128,7 +2178,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: search <term>');
                 return;
             }
-            const results = index.search(arg, { codeOnly: iflags.codeOnly, caseSensitive: iflags.caseSensitive, context: iflags.context, exclude: iflags.exclude, in: iflags.in, regex: iflags.regex });
+            const searchExclude = iflags.includeTests ? iflags.exclude : addTestExclusions(iflags.exclude);
+            const results = index.search(arg, { codeOnly: iflags.codeOnly, caseSensitive: iflags.caseSensitive, context: iflags.context, exclude: searchExclude, in: iflags.in, regex: iflags.regex });
             console.log(output.formatSearch(results, arg));
             break;
         }
@@ -2138,14 +2189,14 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: typedef <name>');
                 return;
             }
-            const types = index.typedef(arg);
+            const types = index.typedef(arg, { exact: iflags.exact });
             console.log(output.formatTypedef(types, arg));
             break;
         }
 
         case 'api': {
-            const api = index.api();
-            console.log(output.formatApi(api, '.'));
+            const api = index.api(arg);
+            console.log(output.formatApi(api, arg || '.'));
             break;
         }
 
@@ -2197,7 +2248,11 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 exclude: iflags.exclude,
                 in: iflags.in
             });
-            console.log(output.formatDeadcode(deadResult, { top: iflags.top }));
+            console.log(output.formatDeadcode(deadResult, {
+                top: iflags.top,
+                decoratedHint: !iflags.includeDecorated && deadResult.excludedDecorated > 0 ? `${deadResult.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
+                exportedHint: !iflags.includeExported && deadResult.excludedExported > 0 ? `${deadResult.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.` : undefined
+            }));
             break;
         }
 
@@ -2206,8 +2261,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: related <name>');
                 return;
             }
-            const relResult = index.related(arg, { file: iflags.file, all: iflags.all });
-            console.log(output.formatRelated(relResult, { showAll: iflags.all }));
+            const relResult = index.related(arg, { file: iflags.file, top: iflags.top, all: iflags.all });
+            console.log(output.formatRelated(relResult, { showAll: iflags.all, top: iflags.top }));
             break;
         }
 

package/mcp/server.js

@@ -268,7 +268,9 @@ server.registerTool(
             range: z.string().optional().describe('Line range to extract, e.g. "10-20" or "15" (lines command)'),
             base: z.string().optional().describe('Git ref to diff against (default: HEAD). E.g. "HEAD~3", "main", a commit SHA'),
             staged: z.boolean().optional().describe('Analyze staged changes (diff_impact command)'),
-            case_sensitive: z.boolean().optional().describe('Case-sensitive search (default: false, case-insensitive)')
+            case_sensitive: z.boolean().optional().describe('Case-sensitive search (default: false, case-insensitive)'),
+            all: z.boolean().optional().describe('Show all results (expand truncated sections). Applies to about, toc, related, trace, and others.'),
+            top_level: z.boolean().optional().describe('Show only top-level functions in toc (exclude nested/indented)')
         })
     },
     async (args) => {
@@ -278,7 +280,7 @@ server.registerTool(
                 include_exported, include_decorated, calls_only, max_lines,
                 direction, term, add_param, remove_param, rename_to,
                 default_value, stack, item, range, base, staged,
-                case_sensitive, regex, functions } = args;
+                case_sensitive, regex, functions, all, top_level } = args;
 
         try {
             switch (command) {
@@ -291,9 +293,9 @@ server.registerTool(
                 const err = requireName(name);
                 if (err) return err;
                 const index = getIndex(project_dir);
-                const result = index.about(name, { file, exclude: parseExclude(exclude), withTypes: with_types || false, includeMethods: include_methods ?? undefined, maxCallers: top, maxCallees: top });
+                const result = index.about(name, { file, exclude: parseExclude(exclude), withTypes: with_types || false, includeMethods: include_methods ?? undefined, includeUncertain: include_uncertain || false, all: all || false, maxCallers: top, maxCallees: top });
                 return toolResult(output.formatAbout(result, {
-                    allHint: 'Repeat with top set higher to show all.',
+                    allHint: 'Repeat with all=true to show all.',
                     methodsHint: 'Note: obj.method() callers/callees excluded. Use include_methods=true to include them.'
                 }));
             }
@@ -378,12 +380,12 @@ server.registerTool(
                 const err = requireName(name);
                 if (err) return err;
                 const index = getIndex(project_dir);
-                const result = index.related(name, { file, top, all: top !== undefined });
+                const result = index.related(name, { file, top, all: all || false });
                 if (!result) return toolResult(`Symbol "${name}" not found.`);
                 return toolResult(output.formatRelated(result, {
-                    showAll: top !== undefined,
+                    showAll: all || false,
                     top,
-                    allHint: 'Repeat with top set higher to show all.'
+                    allHint: 'Repeat with all=true to show all.'
                 }));
             }
 
@@ -416,7 +418,7 @@ server.registerTool(
 
             case 'toc': {
                 const index = getIndex(project_dir);
-                const toc = index.getToc({ detailed: detailed || false, top });
+                const toc = index.getToc({ detailed: detailed || false, topLevel: top_level || false, all: all || false, top });
                 return toolResult(output.formatToc(toc, {
                     topHint: 'Set top=N or use detailed=false for compact view.'
                 }));
@@ -484,6 +486,19 @@ server.registerTool(
                         continue;
                     }
 
+                    // Show all definitions when all=true and multiple matches
+                    if (matches.length > 1 && !file && all) {
+                        for (const m of matches) {
+                            const mPathCheck = resolveAndValidatePath(index, m.relativePath || path.relative(index.root, m.file));
+                            if (typeof mPathCheck !== 'string') return mPathCheck;
+                            const mCode = fs.readFileSync(m.file, 'utf-8');
+                            const mLines = mCode.split('\n');
+                            const mFnCode = mLines.slice(m.startLine - 1, m.endLine).join('\n');
+                            parts.push(output.formatFn(m, mFnCode));
+                        }
+                        continue;
+                    }
+
                     const match = matches.length > 1 ? pickBestDefinition(matches) : matches[0];
                     const fnPathCheck = resolveAndValidatePath(index, match.relativePath || path.relative(index.root, match.file));
                     if (typeof fnPathCheck !== 'string') return fnPathCheck;
@@ -493,7 +508,7 @@ server.registerTool(
 
                     let note = '';
                     if (matches.length > 1 && !file) {
-                        note = `Note: Found ${matches.length} definitions for "${fnName}". Showing ${match.relativePath}:${match.startLine}. Use file parameter to disambiguate.\n`;
+                        note = `Note: Found ${matches.length} definitions for "${fnName}". Showing ${match.relativePath}:${match.startLine}. Use file parameter or all=true to show all.\n`;
                     }
                     parts.push(note + output.formatFn(match, fnCode));
                 }
@@ -514,6 +529,20 @@ server.registerTool(
                     return toolResult(`Class "${name}" not found.`);
                 }
 
+                // Show all definitions when all=true and multiple matches
+                if (matches.length > 1 && !file && all) {
+                    const allParts = [];
+                    for (const m of matches) {
+                        const mPathCheck = resolveAndValidatePath(index, m.relativePath || path.relative(index.root, m.file));
+                        if (typeof mPathCheck !== 'string') return mPathCheck;
+                        const mCode = fs.readFileSync(m.file, 'utf-8');
+                        const mLines = mCode.split('\n');
+                        const clsCode = mLines.slice(m.startLine - 1, m.endLine).join('\n');
+                        allParts.push(output.formatClass(m, clsCode));
+                    }
+                    return toolResult(allParts.join('\n\n'));
+                }
+
                 const match = matches.length > 1 ? pickBestDefinition(matches) : matches[0];
                 // Validate file is within project root
                 const clsPathCheck = resolveAndValidatePath(index, match.relativePath || path.relative(index.root, match.file));
@@ -728,7 +757,8 @@ server.registerTool(
                 if (result?.error === 'file-not-found') return toolError(`File not found in project: ${file}`);
                 if (result?.error === 'file-ambiguous') return toolError(`Ambiguous file "${file}". Candidates:\n${result.candidates.map(c => '  ' + c).join('\n')}`);
                 return toolResult(output.formatGraph(result, {
-                    showAll: depth !== undefined,
+                    showAll: all || depth !== undefined,
+                    maxDepth: depth ?? 2,
                     file,
                     depthHint: 'Set depth parameter for deeper graph.',
                     allHint: 'Set depth to expand all children.'
@@ -810,7 +840,7 @@ server.registerTool(
             case 'stats': {
                 const index = getIndex(project_dir);
                 const stats = index.getStats({ functions: functions || false });
-                return toolResult(output.formatStats(stats, { top: top || 30 }));
+                return toolResult(output.formatStats(stats, { top: top || 0 }));
             }
 
             default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.16",
+  "version": "3.7.18",
   "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,7 @@
     "ucn-mcp": "mcp/server.js"
   },
   "scripts": {
-    "test": "node --test test/parser.test.js test/accuracy.test.js test/systematic-test.js test/mcp-edge-cases.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"
   },
   "keywords": [
     "mcp",