ucn 3.7.6 → 3.7.8

package/README.md

@@ -5,6 +5,7 @@ UCN gives AI agents call-graph-level understanding of code. Instead of reading e
 Designed for large codebases where agents waste context on reading large files. UCN's surgical output means agents spend tokens on reasoning, not on ingesting thousands of lines to find three callers, discourages agents from cutting corners, as without UCN, agents working with large codebases tend to skip parts of the code structure, assuming they have "enough data".
 
 Everything runs locally on your machine and nothing leaves your project.
+The ucn mcp is kept light, as all 28 commands ship as a single MCP tool, under 2k tokens total.
 
 ---
 
@@ -43,7 +44,7 @@ Precise answers without reading files.
   │      $ ucn about myFunc     Works standalone, no agent required.     │
   │                                                                      │
   │   2. MCP Server             Any MCP-compatible AI agent connects     │
-  │      $ ucn --mcp            and gets 28 commands automatically.         │
+  │      $ ucn --mcp            and gets 28 commands automatically.      │
   │                                                                      │
   │   3. Agent Skill            Drop-in skill for Claude Code and        │
   │      /ucn about myFunc      OpenAI Codex CLI. No server needed.      │

package/cli/index.js

@@ -983,7 +983,7 @@ function runProjectCommand(rootDir, command, arg) {
             });
             printOutput(deadcodeResults,
                 output.formatDeadcodeJson,
-                r => output.formatDeadcode(r)
+                r => output.formatDeadcode(r, { top: flags.top })
             );
             break;
         }
@@ -1720,7 +1720,7 @@ Common Flags:
   --depth=N           Trace/graph depth (default: 3, also expands all children)
   --direction=X       Graph direction: imports, importers, or both (default: both)
   --all               Expand truncated sections (about, trace, graph, related)
-  --top=N             Limit results (find)
+  --top=N             Limit results (find, deadcode)
   --context=N         Lines of context around matches
   --json              Machine-readable output
   --code-only         Filter out comments and strings
@@ -2154,7 +2154,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 exclude: iflags.exclude,
                 in: iflags.in
             });
-            console.log(output.formatDeadcode(deadResult));
+            console.log(output.formatDeadcode(deadResult, { top: iflags.top }));
             break;
         }
 

package/core/output.js

@@ -1724,12 +1724,20 @@ function formatDeadcode(results, options = {}) {
     }
 
     const lines = [];
+    const top = options.top > 0 ? options.top : 0;
+    const showing = top > 0 ? results.slice(0, top) : results;
+    const hidden = results.length - showing.length;
+
     if (results.length > 0) {
-        lines.push(`Dead code: ${results.length} unused symbol(s)\n`);
+        if (hidden > 0) {
+            lines.push(`Dead code: ${results.length} unused symbol(s) (showing ${showing.length})\n`);
+        } else {
+            lines.push(`Dead code: ${results.length} unused symbol(s)\n`);
+        }
     }
 
     let currentFile = null;
-    for (const item of results) {
+    for (const item of showing) {
         if (item.file !== currentFile) {
             currentFile = item.file;
             lines.push(item.file);
@@ -1747,6 +1755,10 @@ function formatDeadcode(results, options = {}) {
         lines.push(`  ${lineRange(item.startLine, item.endLine)} ${item.name} (${item.type})${exported}${hintStr}`);
     }
 
+    if (hidden > 0) {
+        lines.push(`\n${hidden} more result(s) not shown. Use --top=${results.length} or --all to see all.`);
+    }
+
     // Show counts of excluded items with expansion hints
     if (results.length === 0) {
         lines.push('No dead code found.');

package/mcp/server.js

@@ -451,6 +451,7 @@ server.registerTool(
                     includeTests: include_tests || false
                 });
                 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,
                     exportedHint: !include_exported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use include_exported=true to audit them.` : undefined
                 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.6",
+  "version": "3.7.8",
   "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",
   "bin": {

package/test/parser.test.js

@@ -9647,6 +9647,34 @@ it('formatDeadcode handles zero exclusions without hints', () => {
     assert.ok(text.includes('helper'), 'Should still show the result');
 });
 
+it('formatDeadcode respects --top option', () => {
+    const { formatDeadcode } = require('../core/output');
+
+    const results = [
+        { name: 'a', type: 'function', file: 'a.js', startLine: 1, endLine: 3, isExported: false },
+        { name: 'b', type: 'function', file: 'b.js', startLine: 1, endLine: 3, isExported: false },
+        { name: 'c', type: 'function', file: 'c.js', startLine: 1, endLine: 3, isExported: false },
+        { name: 'd', type: 'function', file: 'd.js', startLine: 1, endLine: 3, isExported: false },
+        { name: 'e', type: 'function', file: 'e.js', startLine: 1, endLine: 3, isExported: false }
+    ];
+    results.excludedDecorated = 0;
+    results.excludedExported = 0;
+
+    // With top=2, should show only 2 results
+    const text = formatDeadcode(results, { top: 2 });
+    assert.ok(text.includes('(showing 2)'), 'Should indicate showing 2');
+    assert.ok(text.includes('a (function)'), 'Should show first result');
+    assert.ok(text.includes('b (function)'), 'Should show second result');
+    assert.ok(!text.includes('c (function)'), 'Should not show third result');
+    assert.ok(text.includes('3 more result(s) not shown'), 'Should show hidden count');
+
+    // Without top, should show all results
+    const textAll = formatDeadcode(results);
+    assert.ok(!textAll.includes('showing'), 'Should not indicate partial results');
+    assert.ok(textAll.includes('e (function)'), 'Should show all results');
+    assert.ok(!textAll.includes('more result(s) not shown'), 'Should not show hidden hint');
+});
+
 it('deadcode Python: simple decorators NOT excluded (only attribute access)', () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-dc-simple-deco-'));
     try {