ucn 3.8.10 → 3.8.12

package/languages/utils.js

@@ -26,12 +26,13 @@ function traverseTree(node, callback, options) {
  * @param {string} code - Original source code
  * @returns {{ startLine: number, endLine: number, indent: number }}
  */
-function nodeToLocation(node, code) {
+function nodeToLocation(node, codeOrLines) {
     const startLine = node.startPosition.row + 1;  // tree-sitter is 0-indexed
     const endLine = node.endPosition.row + 1;
 
     // Calculate indent from start of line
-    const lines = code.split('\n');
+    // Accept pre-split lines array to avoid repeated code.split('\n')
+    const lines = Array.isArray(codeOrLines) ? codeOrLines : codeOrLines.split('\n');
     const firstLine = lines[node.startPosition.row] || '';
     const indentMatch = firstLine.match(/^(\s*)/);
     const indent = indentMatch ? indentMatch[1].length : 0;
@@ -235,8 +236,8 @@ function parseJavaParam(param, info) {
  * @param {number} startLine - 1-indexed line number of the function/class
  * @returns {string|null} First line of docstring or null
  */
-function extractJSDocstring(code, startLine) {
-    const lines = code.split('\n');
+function extractJSDocstring(codeOrLines, startLine) {
+    const lines = Array.isArray(codeOrLines) ? codeOrLines : codeOrLines.split('\n');
     const lineIndex = startLine - 1;
     if (lineIndex <= 0) return null;
 
@@ -280,8 +281,8 @@ function extractJSDocstring(code, startLine) {
  * @param {number} defLine - 1-indexed line number of the def/class (not decorator)
  * @returns {string|null} First line of docstring or null
  */
-function extractPythonDocstring(code, defLine) {
-    const lines = code.split('\n');
+function extractPythonDocstring(codeOrLines, defLine) {
+    const lines = Array.isArray(codeOrLines) ? codeOrLines : codeOrLines.split('\n');
     // Python docstring is INSIDE the function, on lines after the def:
     let i = defLine; // Start after the def line (defLine is 1-indexed)
     // Skip to find the first non-empty line inside the function
@@ -316,8 +317,8 @@ function extractPythonDocstring(code, defLine) {
  * @param {number} startLine - 1-indexed line number of the function
  * @returns {string|null} First line of doc comment or null
  */
-function extractGoDocstring(code, startLine) {
-    const lines = code.split('\n');
+function extractGoDocstring(codeOrLines, startLine) {
+    const lines = Array.isArray(codeOrLines) ? codeOrLines : codeOrLines.split('\n');
     const lineIndex = startLine - 1;
     if (lineIndex <= 0) return null;
 
@@ -349,8 +350,8 @@ function extractGoDocstring(code, startLine) {
  * @param {number} startLine - 1-indexed line number of the item
  * @returns {string|null} First line of doc comment or null
  */
-function extractRustDocstring(code, startLine) {
-    const lines = code.split('\n');
+function extractRustDocstring(codeOrLines, startLine) {
+    const lines = Array.isArray(codeOrLines) ? codeOrLines : codeOrLines.split('\n');
     const lineIndex = startLine - 1;
     if (lineIndex <= 0) return null;
 
@@ -515,8 +516,86 @@ function findMatchesWithASTFilter(content, term, parser, options = {}) {
     return matches;
 }
 
+/**
+ * Single-entry cache for flat node lists.
+ * During indexFile(), the same tree is traversed 5+ times (findFunctions,
+ * findClasses, findStateObjects, findImports, findExports). Building a flat
+ * list once and iterating it for each pass eliminates repeated recursive
+ * traversal overhead (namedChild object creation, function call overhead).
+ */
+let _cachedRootNode = null;
+let _cachedNodeList = null;
+let _cachedSubtreeEnds = null;
+
+function _buildNodeList(rootNode) {
+    const nodes = [];
+    const subtreeEnds = [];
+    const stack = [rootNode];
+    // Iterative DFS with subtreeEnd tracking
+    // We use a post-processing step to fill subtreeEnds
+    function collect(node) {
+        const idx = nodes.length;
+        nodes.push(node);
+        subtreeEnds.push(0);
+        for (let i = 0; i < node.namedChildCount; i++) {
+            collect(node.namedChild(i));
+        }
+        subtreeEnds[idx] = nodes.length;
+    }
+    collect(rootNode);
+    return { nodes, subtreeEnds };
+}
+
+/**
+ * Get or build a cached flat node list for the given tree.
+ * Returns { nodes: SyntaxNode[], subtreeEnds: number[] }.
+ * subtreeEnds[i] is the index past the last descendant of nodes[i],
+ * enabling O(1) subtree skipping (for 'return false' semantics).
+ */
+function getCachedNodeList(rootNode) {
+    if (rootNode === _cachedRootNode && _cachedNodeList) {
+        return { nodes: _cachedNodeList, subtreeEnds: _cachedSubtreeEnds };
+    }
+    const { nodes, subtreeEnds } = _buildNodeList(rootNode);
+    _cachedRootNode = rootNode;
+    _cachedNodeList = nodes;
+    _cachedSubtreeEnds = subtreeEnds;
+    return { nodes, subtreeEnds };
+}
+
+/**
+ * Traverse a tree-sitter AST using a cached flat node list.
+ * Semantically equivalent to traverseTree() but ~3x faster when the same
+ * tree is traversed multiple times (which happens 5+ times per file during build).
+ * Supports 'return false' to skip a node's entire subtree.
+ *
+ * NOTE: Does not support onLeave callbacks. Use traverseTree() for those.
+ */
+function traverseTreeCached(rootNode, callback) {
+    const { nodes, subtreeEnds } = getCachedNodeList(rootNode);
+    for (let i = 0; i < nodes.length; ) {
+        if (callback(nodes[i]) === false) {
+            i = subtreeEnds[i];
+        } else {
+            i++;
+        }
+    }
+}
+
+/**
+ * Clear the cached node list (call when the tree changes).
+ */
+function clearNodeListCache() {
+    _cachedRootNode = null;
+    _cachedNodeList = null;
+    _cachedSubtreeEnds = null;
+}
+
 module.exports = {
     traverseTree,
+    traverseTreeCached,
+    getCachedNodeList,
+    clearNodeListCache,
     nodeToLocation,
     extractParams,
     parseStructuredParams,

package/mcp/server.js

@@ -114,12 +114,17 @@ const server = new McpServer({
 // TOOL HELPERS
 // ============================================================================
 
-const DEFAULT_OUTPUT_CHARS = 10000;  // ~2.5K tokens — compact default for AI agents
+const DEFAULT_OUTPUT_CHARS = 10000;  // ~2.5K tokens — targeted commands (about, context, smart, etc.)
+const BROAD_OUTPUT_CHARS = 3000;     // ~750 tokens — broad commands where truncated listings are useless
 const MAX_OUTPUT_CHARS = 100000;     // hard ceiling even with max_chars override
 
+// Broad commands: output is project-wide, truncation means you need a filter, not more text
+const BROAD_COMMANDS = new Set(['toc', 'entrypoints', 'diff_impact', 'affected_tests', 'deadcode', 'usages']);
+
 function toolResult(text, command, maxChars) {
     if (!text) return { content: [{ type: 'text', text: '(no output)' }] };
-    const limit = Math.min(maxChars || DEFAULT_OUTPUT_CHARS, MAX_OUTPUT_CHARS);
+    const defaultLimit = BROAD_COMMANDS.has(command) ? BROAD_OUTPUT_CHARS : DEFAULT_OUTPUT_CHARS;
+    const limit = Math.min(maxChars || defaultLimit, MAX_OUTPUT_CHARS);
     if (text.length > limit) {
         const fullSize = text.length;
         const fullTokens = Math.round(fullSize / 4);
@@ -128,14 +133,15 @@ function toolResult(text, command, maxChars) {
         const lastNewline = truncated.lastIndexOf('\n');
         const cleanCut = lastNewline > limit * 0.8 ? truncated.substring(0, lastNewline) : truncated;
         // Command-specific narrowing hints
-        let narrow = 'Use file=/in=/exclude= to narrow scope.';
-        if (command === 'toc') {
-            narrow = 'Use in= to scope to a subdirectory, or detailed=false for compact view.';
-        } else if (command === 'diff_impact') {
-            narrow = 'Use file= to scope to specific files/directories.';
-        } else if (command === 'affected_tests') {
-            narrow = 'Use file= to scope, exclude= to skip patterns.';
-        }
+        const hints = {
+            toc: 'Use in= to scope to a subdirectory, or detailed=false for compact view.',
+            entrypoints: 'Use framework= to filter by framework, exclude= to skip patterns.',
+            diff_impact: 'Use file= to scope to specific files/directories.',
+            affected_tests: 'Use file= to scope, exclude= to skip patterns.',
+            deadcode: 'Use file= to scope, exclude= to skip patterns.',
+            usages: 'Use file= to scope to specific files.',
+        };
+        const narrow = hints[command] || 'Use file=/in=/exclude= to narrow scope.';
         return { content: [{ type: 'text', text: cleanCut + `\n\n... OUTPUT TRUNCATED: showing ${limit} of ${fullSize} chars. Full output would be ~${fullTokens} tokens. ${narrow} Or use all=true to see everything (warning: ~${fullTokens} tokens).` }] };
     }
     return { content: [{ type: 'text', text }] };
@@ -285,7 +291,7 @@ server.registerTool(
             class_name: z.string().optional().describe('Class name to scope method analysis (e.g. "MarketDataFetcher" for close)'),
             limit: z.number().optional().describe('Max results to return (default: 500). Caps find, usages, search, deadcode, api, toc --detailed.'),
             max_files: z.number().optional().describe('Max files to index (default: 10000). Use for very large codebases.'),
-            max_chars: z.number().optional().describe('Max output chars before truncation (default: 30000 ~7.5K tokens, max: 100000 ~25K tokens). Use all=true to bypass all caps, or set this for fine-grained control. Truncation message shows full size.'),
+            max_chars: z.number().optional().describe('Max output chars before truncation. Targeted commands (about, context, smart, etc.): 10K default. Broad commands (toc, entrypoints, deadcode, etc.): 3K default. Max: 100K. Use all=true to bypass all caps.'),
             // Structural search flags (search command)
             type: z.string().optional().describe('Symbol type filter for structural search: function, class, call, method, type. Triggers index-based search.'),
             param: z.string().optional().describe('Filter by parameter name or type (structural search). E.g. "Request", "ctx".'),
@@ -308,9 +314,10 @@ server.registerTool(
         // all=true bypasses both formatter caps AND char truncation (parity with CLI --all)
         const maxChars = ep.all ? MAX_OUTPUT_CHARS : ep.maxChars;
 
-        // Wrap toolResult to auto-inject maxChars from this request
-        const tr = (text, cmd) => toolResult(text, cmd, maxChars);
+        // Wrap toolResult to auto-inject command + maxChars from this request
+        const tr = (text) => toolResult(text, command, maxChars);
 
+        let index = null; // Track for post-command cache save
         try {
             switch (command) {
 
@@ -321,7 +328,7 @@ server.registerTool(
             // ── Commands using shared executor ─────────────────────────
 
             case 'about': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'about', ep);
                 if (!ok) return tr(error); // soft error — won't kill sibling calls
                 return tr(output.formatAbout(result, {
@@ -332,7 +339,7 @@ server.registerTool(
             }
 
             case 'context': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result: ctx, error } = execute(index, 'context', ep);
                 if (!ok) return tr(error); // context uses soft error (not toolError)
                 const { text, expandable } = output.formatContext(ctx, {
@@ -344,14 +351,14 @@ server.registerTool(
             }
 
             case 'impact': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'impact', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatImpact(result));
             }
 
             case 'blast': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'blast', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatBlast(result, {
@@ -360,14 +367,14 @@ server.registerTool(
             }
 
             case 'smart': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'smart', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatSmart(result));
             }
 
             case 'trace': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'trace', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatTrace(result, {
@@ -377,7 +384,7 @@ server.registerTool(
             }
 
             case 'reverse_trace': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'reverseTrace', ep);
                 if (!ok) return tr(error);
                 return tr(output.formatReverseTrace(result, {
@@ -386,7 +393,7 @@ server.registerTool(
             }
 
             case 'example': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'example', ep);
                 if (!ok) return tr(error);
                 if (!result) return tr(`No usage examples found for "${ep.name}".`);
@@ -394,7 +401,7 @@ server.registerTool(
             }
 
             case 'related': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'related', ep);
                 if (!ok) return tr(error);
                 if (!result) return tr(`Symbol "${ep.name}" not found.`);
@@ -407,7 +414,7 @@ server.registerTool(
             // ── Finding Code ────────────────────────────────────────────
 
             case 'find': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'find', ep);
                 if (!ok) return tr(error); // soft error
                 let text = output.formatFind(result, ep.name, ep.top);
@@ -416,7 +423,7 @@ server.registerTool(
             }
 
             case 'usages': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'usages', ep);
                 if (!ok) return tr(error); // soft error
                 let text = output.formatUsages(result, ep.name);
@@ -425,18 +432,18 @@ server.registerTool(
             }
 
             case 'toc': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'toc', ep);
                 if (!ok) return tr(error); // soft error
                 let text = output.formatToc(result, {
                     topHint: 'Set top=N or use detailed=false for compact view.'
                 });
                 if (note) text += '\n\n' + note;
-                return tr(text, 'toc');
+                return tr(text);
             }
 
             case 'search': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error, structural } = execute(index, 'search', ep);
                 if (!ok) return tr(error); // soft error
                 if (structural) {
@@ -446,21 +453,21 @@ server.registerTool(
             }
 
             case 'tests': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'tests', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatTests(result, ep.name));
             }
 
             case 'affected_tests': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'affectedTests', ep);
                 if (!ok) return tr(error);
-                return tr(output.formatAffectedTests(result, { all: ep.all }), 'affected_tests');
+                return tr(output.formatAffectedTests(result, { all: ep.all }));
             }
 
             case 'deadcode': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'deadcode', ep);
                 if (!ok) return tr(error); // soft error
                 const dcNote = note;
@@ -474,7 +481,7 @@ server.registerTool(
             }
 
             case 'entrypoints': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'entrypoints', ep);
                 if (!ok) return tr(error);
                 return tr(output.formatEntrypoints(result));
@@ -483,28 +490,28 @@ server.registerTool(
             // ── File Dependencies ───────────────────────────────────────
 
             case 'imports': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'imports', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatImports(result, ep.file));
             }
 
             case 'exporters': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'exporters', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatExporters(result, ep.file));
             }
 
             case 'file_exports': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'fileExports', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatFileExports(result, ep.file));
             }
 
             case 'graph': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'graph', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatGraph(result, {
@@ -516,7 +523,7 @@ server.registerTool(
             }
 
             case 'circular_deps': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'circularDeps', ep);
                 if (!ok) return tr(error);
                 return tr(output.formatCircularDeps(result));
@@ -525,44 +532,44 @@ server.registerTool(
             // ── Refactoring ─────────────────────────────────────────────
 
             case 'verify': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'verify', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatVerify(result));
             }
 
             case 'plan': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'plan', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatPlan(result));
             }
 
             case 'diff_impact': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'diffImpact', ep);
                 if (!ok) return tr(error); // soft error — e.g. "not a git repo"
-                return tr(output.formatDiffImpact(result, { all: ep.all }), 'diff_impact');
+                return tr(output.formatDiffImpact(result, { all: ep.all }));
             }
 
             // ── Other ───────────────────────────────────────────────────
 
             case 'typedef': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'typedef', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatTypedef(result, ep.name));
             }
 
             case 'stacktrace': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'stacktrace', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatStackTrace(result));
             }
 
             case 'api': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error, note } = execute(index, 'api', ep);
                 if (!ok) return tr(error); // soft error
                 let apiText = output.formatApi(result, ep.file || '.');
@@ -571,7 +578,7 @@ server.registerTool(
             }
 
             case 'stats': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'stats', ep);
                 if (!ok) return tr(error); // soft error
                 return tr(output.formatStats(result, { top: ep.top || 0 }));
@@ -582,7 +589,7 @@ server.registerTool(
             case 'fn': {
                 const err = requireName(ep.name);
                 if (err) return err;
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'fn', ep);
                 if (!ok) return tr(error); // soft error
                 // MCP path security: validate all result files are within project root
@@ -600,7 +607,7 @@ server.registerTool(
                 if (ep.maxLines !== undefined && (!Number.isInteger(ep.maxLines) || ep.maxLines < 1)) {
                     return toolError(`Invalid max_lines: ${ep.maxLines}. Must be a positive integer.`);
                 }
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'class', ep);
                 if (!ok) return tr(error);  // soft error (class not found)
                 // MCP path security: validate all result files are within project root
@@ -613,7 +620,7 @@ server.registerTool(
             }
 
             case 'lines': {
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const { ok, result, error } = execute(index, 'lines', ep);
                 if (!ok) return tr(error); // soft error
                 // MCP path security: validate file is within project root
@@ -626,7 +633,7 @@ server.registerTool(
                 if (ep.item === undefined || ep.item === null) {
                     return toolError('Item number is required (e.g. item=1).');
                 }
-                const index = getIndex(project_dir, ep);
+                index = getIndex(project_dir, ep);
                 const lookup = expandCacheInstance.lookup(index.root, ep.item);
                 const { ok, result, error } = execute(index, 'expand', {
                     match: lookup.match, itemNum: ep.item,
@@ -642,6 +649,15 @@ server.registerTool(
             }
         } catch (e) {
             return toolError(e.message);
+        } finally {
+            // Persist calls cache after command execution.
+            // getIndex() only saves after build (when callsCache is empty).
+            // Commands like context/about/impact populate callsCache lazily,
+            // so we save here to avoid re-parsing all files on every MCP session.
+            if (index && index.callsCacheDirty) {
+                try { index.saveCache(); } catch (_) { /* best-effort */ }
+                index.callsCacheDirty = false;
+            }
         }
     }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.8.10",
+  "version": "3.8.12",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Code intelligence toolkit for AI agents — extract functions, trace call chains, find callers, detect dead code without reading entire files. Works as MCP server, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java.",
   "main": "index.js",

package/.claude/scheduled_tasks.lock

@@ -1 +0,0 @@
-{"sessionId":"5e2a28ce-7f65-4369-a922-8d1d902f9d8f","pid":18086,"acquiredAt":1773363188494}