ucn 5.4.1 → 5.5.0

package/languages/utils.js

@@ -10,18 +10,58 @@
  * @param {function} [options.onLeave] - Called when leaving each node (after children processed)
  */
 function traverseTree(node, callback, options) {
+    // The flat node list an extractor pass already built for this tree
+    // (fix #388): the same nodes in the same order, without a native
+    // children read per node. Never built here, so a walk of an uncached
+    // tree cannot evict a list another pass still uses.
+    const range = cachedNodeRange(node);
+    if (range) {
+        traverseNodeRange(range, callback, options?.onLeave);
+        return;
+    }
+    traverseTreeWalk(node, callback, options);
+}
+
+function traverseTreeWalk(node, callback, options) {
     if (callback(node) === false) return;
     // Single batched native call per node — namedChildCount + N × namedChild(i)
     // costs N+1 native round-trips for the same children.
     const children = node.namedChildren;
     for (let i = 0; i < children.length; i++) {
-        traverseTree(children[i], callback, options);
+        traverseTreeWalk(children[i], callback, options);
     }
     if (options?.onLeave) {
         options.onLeave(node);
     }
 }
 
+/**
+ * Depth-first visit of one subtree of a cached flat node list: `callback`
+ * on entry (false skips the node's descendants and its `onLeave`), then
+ * `onLeave` after its descendants, exactly as the recursive walk orders them.
+ */
+function traverseNodeRange({ nodes, subtreeEnds, index }, callback, onLeave) {
+    const end = subtreeEnds[index];
+    if (!onLeave) {
+        for (let i = index; i < end; ) {
+            if (callback(nodes[i]) === false) i = subtreeEnds[i];
+            else i++;
+        }
+        return;
+    }
+    const open = [];
+    for (let i = index; i < end; ) {
+        while (open.length > 0 && subtreeEnds[open[open.length - 1]] <= i) onLeave(nodes[open.pop()]);
+        if (callback(nodes[i]) === false) {
+            i = subtreeEnds[i];
+        } else {
+            open.push(i);
+            i++;
+        }
+    }
+    while (open.length > 0) onLeave(nodes[open.pop()]);
+}
+
 /**
  * Get line locations from tree-sitter node
  * Returns 1-indexed lines to match UCN output format
@@ -776,8 +816,29 @@ function findMatchesWithASTFilter(content, term, parser, options = {}) {
  * traversal overhead (namedChild object creation, function call overhead).
  */
 let _cachedRootNode = null;
+let _cachedRootId = null;
 let _cachedNodeList = null;
 let _cachedSubtreeEnds = null;
+let _previousRootNode = null;
+let _previousRootId = null;
+let _previousNodeList = null;
+let _previousSubtreeEnds = null;
+
+// The same syntax node can reach a caller through a different wrapper: the
+// binding keeps one wrapper per node only while the last one is alive, so a
+// collected wrapper makes every later `tree.rootNode` a fresh object (fix
+// #387). A node is identified by its tree plus the native node id.
+function nodeIdOf(node) {
+    const id = node?.tree ? node.id : undefined;
+    return typeof id === 'number' ? id : null;
+}
+
+function sameCachedNode(node, cached, cachedId) {
+    if (!cached || cachedId === null || node.tree !== cached.tree) return false;
+    return nodeIdOf(node) === cachedId;
+}
+
+const NAMED_CHILDREN_LIST = Symbol.for('ucn.namedChildrenList');
 
 function _buildNodeList(rootNode) {
     const nodes = [];
@@ -788,8 +849,9 @@ function _buildNodeList(rootNode) {
         const idx = nodes.length;
         nodes.push(node);
         subtreeEnds.push(0);
-        // Batched children read — one native call instead of N+1 (see traverseTree)
-        const children = node.namedChildren;
+        // Batched children read — one native call instead of N+1 (see
+        // traverseTree); the array stays on the node for later reads.
+        const children = node[NAMED_CHILDREN_LIST] ? node[NAMED_CHILDREN_LIST]() : node.namedChildren;
         for (let i = 0; i < children.length; i++) {
             collect(children[i]);
         }
@@ -806,16 +868,87 @@ function _buildNodeList(rootNode) {
  * enabling O(1) subtree skipping (for 'return false' semantics).
  */
 function getCachedNodeList(rootNode) {
-    if (rootNode === _cachedRootNode && _cachedNodeList) {
+    if (_cachedNodeList && (rootNode === _cachedRootNode ||
+        sameCachedNode(rootNode, _cachedRootNode, _cachedRootId))) {
         return { nodes: _cachedNodeList, subtreeEnds: _cachedSubtreeEnds };
     }
+    // Two slots (fix #365): C/C++ indexing alternates between a selected
+    // recovery tree and its literal all-source tree, which evicted a single
+    // slot on every extractor pass.
+    if (_previousNodeList && (rootNode === _previousRootNode ||
+        sameCachedNode(rootNode, _previousRootNode, _previousRootId))) {
+        const nodes = _previousNodeList;
+        const subtreeEnds = _previousSubtreeEnds;
+        const id = _previousRootId;
+        _previousRootNode = _cachedRootNode;
+        _previousRootId = _cachedRootId;
+        _previousNodeList = _cachedNodeList;
+        _previousSubtreeEnds = _cachedSubtreeEnds;
+        _cachedRootNode = rootNode;
+        _cachedRootId = id;
+        _cachedNodeList = nodes;
+        _cachedSubtreeEnds = subtreeEnds;
+        return { nodes, subtreeEnds };
+    }
     const { nodes, subtreeEnds } = _buildNodeList(rootNode);
+    _previousRootNode = _cachedRootNode;
+    _previousRootId = _cachedRootId;
+    _previousNodeList = _cachedNodeList;
+    _previousSubtreeEnds = _cachedSubtreeEnds;
     _cachedRootNode = rootNode;
+    _cachedRootId = nodeIdOf(rootNode);
     _cachedNodeList = nodes;
     _cachedSubtreeEnds = subtreeEnds;
     return { nodes, subtreeEnds };
 }
 
+/** Index of `node` in a flat preorder list (sorted by start offset), or -1. */
+function nodeListIndex(nodes, node) {
+    const start = node.startIndex;
+    let lo = 0;
+    let hi = nodes.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (nodes[mid].startIndex < start) lo = mid + 1;
+        else hi = mid;
+    }
+    for (let i = lo; i < nodes.length && nodes[i].startIndex === start; i++) {
+        if (nodes[i] === node) return i;
+    }
+    const id = nodeIdOf(node);
+    if (id === null) return -1;
+    for (let i = lo; i < nodes.length && nodes[i].startIndex === start; i++) {
+        if (nodeIdOf(nodes[i]) === id) return i;
+    }
+    return -1;
+}
+
+/**
+ * The already-built flat node list holding `node` (fix #388), as
+ * { nodes, subtreeEnds, index } with nodes[index] the node, or null when no
+ * cached list covers it. Named nodes only, like `namedChildren`.
+ */
+function cachedNodeRange(node) {
+    if (!node) return null;
+    const tree = node.tree;
+    if (!tree) return null;
+    if (_cachedNodeList && _cachedRootNode?.tree === tree) {
+        if (node === _cachedRootNode || sameCachedNode(node, _cachedRootNode, _cachedRootId)) {
+            return { nodes: _cachedNodeList, subtreeEnds: _cachedSubtreeEnds, index: 0 };
+        }
+        const index = nodeListIndex(_cachedNodeList, node);
+        if (index >= 0) return { nodes: _cachedNodeList, subtreeEnds: _cachedSubtreeEnds, index };
+    }
+    if (_previousNodeList && _previousRootNode?.tree === tree) {
+        if (node === _previousRootNode || sameCachedNode(node, _previousRootNode, _previousRootId)) {
+            return { nodes: _previousNodeList, subtreeEnds: _previousSubtreeEnds, index: 0 };
+        }
+        const index = nodeListIndex(_previousNodeList, node);
+        if (index >= 0) return { nodes: _previousNodeList, subtreeEnds: _previousSubtreeEnds, index };
+    }
+    return null;
+}
+
 /**
  * Traverse a tree-sitter AST using a cached flat node list.
  * Semantically equivalent to traverseTree() but ~3x faster when the same
@@ -873,8 +1006,13 @@ function visitNameNodes(tree, code, name, callback) {
  */
 function clearNodeListCache() {
     _cachedRootNode = null;
+    _cachedRootId = null;
     _cachedNodeList = null;
     _cachedSubtreeEnds = null;
+    _previousRootNode = null;
+    _previousRootId = null;
+    _previousNodeList = null;
+    _previousSubtreeEnds = null;
 }
 
 /**
@@ -1071,13 +1209,168 @@ function sameNode(a, b) {
     return !!a && !!b && (a === b || a.id === b.id);
 }
 
+/**
+ * Whether a function body contains a node of `targetTypes` in its OWN scope:
+ * nested scopes listed in `boundaryTypes` (inner functions, lambdas, classes)
+ * are not descended. Used to recognize generator/iterator functions by their
+ * `yield` (a yield inside a nested def makes the NESTED def the generator).
+ */
+function containsOwnNode(body, targetTypes, boundaryTypes) {
+    if (!body) return false;
+    const stack = [body];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        const count = node.namedChildCount;
+        for (let i = 0; i < count; i++) {
+            const child = node.namedChild(i);
+            if (targetTypes.has(child.type)) return true;
+            if (!boundaryTypes.has(child.type)) stack.push(child);
+        }
+    }
+    return false;
+}
+
+/**
+ * fix #367e: line ranges the parser could only recover, not parse. Inside an
+ * outermost ERROR node, a damaged child (loose token, erroneous or MISSING
+ * content) opens a region; clean statements/expressions that follow extend
+ * it (they sit in unparsed context: `ok();` after a broken signature); a
+ * clean complete declaration/definition/import/directive closes it, and
+ * comments are neutral. A MISSING token outside any ERROR marks its own line.
+ * Only subtrees with `hasError` are visited. Returns merged, sorted
+ * [startLine, endLine] pairs (1-based), or [] for a clean tree.
+ */
+const COMPLETE_CONSTRUCT_RE = /declaration|definition|_item$|^import|^preproc_|^package_clause$|^using_directive$|^module$/;
+
+function parseErrorRegions(rootNode) {
+    const regions = [];
+    if (!rootNode?.hasError) return regions;
+    const lineOf = position => position.row + 1;
+    // Children are read in one batch per node (fix #388).
+    const errorRegions = node => {
+        let open = null;
+        const close = () => { if (open) { regions.push(open); open = null; } };
+        const children = node.children;
+        for (let i = 0; i < children.length; i++) {
+            const child = children[i];
+            const type = child.type;
+            if (type.includes('comment')) continue;
+            const damaged = child.hasError || child.isMissing || type === 'ERROR' ||
+                !child.isNamed || child.childCount === 0;
+            const start = lineOf(child.startPosition);
+            const end = lineOf(child.endPosition);
+            if (damaged) {
+                if (open) open[1] = Math.max(open[1], end);
+                else open = [start, end];
+            } else if (COMPLETE_CONSTRUCT_RE.test(type)) {
+                close();
+            } else if (open) {
+                open[1] = Math.max(open[1], end);
+            }
+        }
+        close();
+    };
+    const visit = node => {
+        if (node.isMissing) {
+            const line = lineOf(node.startPosition);
+            regions.push([line, line]);
+            return;
+        }
+        if (!node.hasError) return;
+        if (node.type === 'ERROR') {
+            errorRegions(node);
+            return;
+        }
+        const children = node.children;
+        for (let i = 0; i < children.length; i++) visit(children[i]);
+    };
+    visit(rootNode);
+    regions.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    const merged = [];
+    for (const region of regions) {
+        const last = merged[merged.length - 1];
+        if (last && region[0] <= last[1]) last[1] = Math.max(last[1], region[1]);
+        else merged.push([...region]);
+    }
+    return merged;
+}
+
+/**
+ * fix #380: generic arity of the LAST segment of a written type name
+ * (`Outcome` 0, `Outcome<int>` 1, `Dictionary<string, List<int>>` 2,
+ * `Outcome<,>` 2, `A<int>.B` 0, `Outcome<int>?` 1). Null for text that is not
+ * a type-name shape.
+ */
+function genericArityOf(text) {
+    if (text == null) return null;
+    let value = String(text).trim().replace(/\?$/, '');
+    while (value.endsWith('[]')) value = value.slice(0, -2).trim();
+    if (!value) return null;
+    if (!value.endsWith('>')) {
+        return /^[A-Za-z_@][\w@]*$/.test(value.split(/::|\./).pop() || '') ? 0 : null;
+    }
+    let depth = 0;
+    let commas = 0;
+    for (let i = value.length - 1; i >= 0; i--) {
+        const ch = value[i];
+        if (ch === '>') depth++;
+        else if (ch === '<') {
+            depth--;
+            if (depth === 0) return commas + 1;
+        } else if (ch === ',' && depth === 1) commas++;
+    }
+    return null;
+}
+
+// Exclusive clauses of one compound statement (fix #398F): `if`/`elif`/
+// `else` and `case` arms never both run; a `try` body and its handlers, two
+// handlers, a handler and the `try` `else` are alternatives. A `try` body and
+// its `else` run in sequence, and `finally` always runs.
+function branchClausesExclusive(a, b) {
+    if (a === b) return false;
+    const kind = tag => tag.split(':')[0];
+    const ka = kind(a), kb = kind(b);
+    const branch = new Set(['if', 'elif', 'else']);
+    if (branch.has(ka) && branch.has(kb)) return true;
+    if (ka === 'case' && kb === 'case') return true;
+    if (ka === 'finally' || kb === 'finally') return false;
+    const pair = new Set([ka, kb]);
+    if (pair.has('except') && (pair.has('try') || pair.has('try-else') || ka === kb)) return true;
+    return false;
+}
+
+/**
+ * The package name a Go import path suggests when the import writes none,
+ * by the Go tools' convention: the last element, or the one before a major
+ * version suffix (v2 and up: `example.com/mod/v3` is package `mod`; a module
+ * path never ends in /v0 or /v1, so such an element is a directory, and
+ * `k8s.io/api/core/v1` declares package `v1`), without a `go-` prefix and up
+ * to the first character no identifier holds (`github.com/goccy/go-json` is
+ * `json`, `gopkg.in/yaml.v3` `yaml`, `k8s.io/mount-utils` `mount`). Only a
+ * suggestion: the local name is the imported package's own clause (fix #400).
+ */
+function goPathPackageName(modulePath) {
+    const parts = String(modulePath).split('/');
+    let base = parts[parts.length - 1];
+    if (/^v([2-9]|[1-9]\d+)$/.test(base) && parts.length > 1) base = parts[parts.length - 2];
+    if (base.startsWith('go-')) base = base.slice(3);
+    const cut = base.search(/[^\p{L}\p{N}_]/u);
+    return cut > 0 ? base.slice(0, cut) : base;
+}
+
 module.exports = {
+    genericArityOf,
+    goPathPackageName,
+    parseErrorRegions,
+    containsOwnNode,
     nodeTextWithoutComments,
     sameNode,
     traverseTree,
     traverseTreeCached,
     visitNameNodes,
     getCachedNodeList,
+    cachedNodeRange,
+    traverseNodeRange,
     clearNodeListCache,
     nodeToLocation,
     extractParams,
@@ -1096,4 +1389,5 @@ module.exports = {
     extractStringArg,
     stripQuotes,
     extractSprintfPrefix,
+    branchClausesExclusive,
 };

package/mcp/server.js

@@ -7,6 +7,11 @@
  * Keeps a per-project index cache for fast repeat queries.
  */
 
+// Reuse V8 code caches across processes (Node >= 22.1; fix #365): compiling
+// the engine's modules is a fixed cost of every command. Node validates each
+// entry against the source, and NODE_DISABLE_COMPILE_CACHE turns it off.
+try { require('module').enableCompileCache?.(); } catch (_) { /* optional */ }
+
 const fs = require('fs');
 const path = require('path');
 const { StdioMcpServer } = require('./stdio-server');
@@ -30,6 +35,7 @@ const {
     formatSurfaceMessage,
 } = require('../core/registry');
 const { execute } = require('../core/execute');
+const { describeError, UcnError } = require('../core/errors');
 const { applyOutputBudget, MAX_OUTPUT_CHARS } = require('../core/output-budget');
 
 // ============================================================================
@@ -41,14 +47,14 @@ const MAX_CACHE_SIZE = 10;
 
 function getIndex(projectDir, options) {
     if (typeof projectDir !== 'string' || projectDir.trim().length === 0) {
-        throw new Error('project_dir is required and must be a non-empty path.');
+        throw new UcnError('project_dir is required and must be a non-empty path.');
     }
     const maxFiles = options && options.maxFiles;
     const followSymlinks = options && options.followSymlinks;
     const includeBundled = options?.includeBundled === true;
     const absDir = path.resolve(projectDir);
     if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory()) {
-        throw new Error(`Project directory not found: ${absDir}`);
+        throw new UcnError(`Project directory not found: ${absDir}`);
     }
     const root = findProjectRoot(absDir);
     const cached = indexCache.get(root);
@@ -119,7 +125,7 @@ const server = new StdioMcpServer({
 
 function toolResult(text, command, maxChars, suffixNote, params = {}) {
     const suffix = suffixNote || '';
-    const budget = applyOutputBudget(text, {
+    const budget = applyOutputBudget(text + suffix, {
         command,
         maxChars,
         surface: 'mcp',
@@ -130,13 +136,18 @@ function toolResult(text, command, maxChars, suffixNote, params = {}) {
     // narrowing hints; preserved contract lines follow). A structuredContent
     // side-channel is rendered INSTEAD of content by MCP clients that prefer
     // structured results, which discards the entire answer (fix #284).
-    return { content: [{ type: 'text', text: budget.text + suffix }] };
+    return { content: [{ type: 'text', text: budget.text }] };
 }
 
 function toolError(message) {
     return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
 }
 
+/** An exception inside UCN: marked internal, never rendered as a refusal (fix #394). */
+function internalToolError(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+
 function paramEditDistance(a, b) {
     if (Math.abs(a.length - b.length) > 2) return 3;
     const prev = new Array(b.length + 1);
@@ -260,7 +271,7 @@ const INPUT_SHAPE = {
     sections: stringParam('Comma-separated projection. show: summary,callers,callees,source,dependencies,tests,types,example,related. repo: summary,files,stats,health.'),
     exclude: stringParam('Comma-separated patterns to exclude (e.g. "test,mock,vendor")'),
     include_tests: booleanParam('Include test files in results (excluded by default)'),
-    exclude_tests: booleanParam('Explicit spelling of the default test-file exclusion (entrypoints). Use include_tests=true to include test files.'),
+    exclude_tests: booleanParam('Exclude test files: the default for entrypoints (include_tests=true lists them); usages and endpoints list test files unless exclude_tests=true.'),
     include_methods: booleanParam('Include method callees where receiver evidence permits. Caller-bearing views always tier method sites.'),
     expand_unverified: booleanParam('trace callers: follow unverified edges; downstream nodes remain marked possible, never confirmed.'),
     min_confidence: numberParam('Minimum ordinal evidence weight (legacy name; not a probability) for caller/callee edges', { minimum: 0, maximum: 1 }),
@@ -292,11 +303,11 @@ const INPUT_SHAPE = {
     git: booleanParam('show summary: attach last-modified, author, and recent-change metadata.'),
     add_param: stringParam('Parameter name to add (plan command)'),
     remove_param: stringParam('Parameter name to remove (plan command)'),
-    rename_to: stringParam('New function name (plan command)'),
+    rename_to: stringParam('New name for the function, method, or type (plan command)'),
     default_value: stringParam('Default value for added parameter (plan command)'),
     stack: stringParam('The stack trace text to parse (stacktrace command)'),
     range: stringParam('source line range, e.g. "10-20" or "15"; requires file.'),
-    base: stringParam('Git ref to diff against (default: HEAD). E.g. "HEAD~3", "main", a commit SHA'),
+    base: stringParam('Git ref (default: HEAD). impact/check without a symbol: diff against it; check with a symbol: compare the declaration with its version there. E.g. "HEAD~3", "main", a commit SHA'),
     staged: booleanParam('impact/check without a symbol: analyze staged changes.'),
     deep: booleanParam('repo: include health and sample the ordinal resolution-evidence profile, not accuracy.'),
     compact: booleanParam('Compact output defaults to true for show/impact and false for usages; set the opposite value to change that command\'s presentation.'),
@@ -305,9 +316,9 @@ const INPUT_SHAPE = {
     top_level: booleanParam('repo files: show only top-level functions.'),
     class_name: stringParam('Class name to scope method analysis (e.g. "MarketDataFetcher" for close)'),
     line: integerParam('Definition line pin. Resolves the symbol defined at this exact line (the middle component of a file:line:name handle). Disambiguates same-file same-name definitions.', { exclusiveMinimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
-    limit: integerParam('Max results to return (default: 500; structural search: 50; usages and lines: uncapped). Caps find, usages, search, deadcode, api, and repo files. Must be a positive integer.', { exclusiveMinimum: 0, maximum: 1000000 }),
+    limit: integerParam('Max results to return (default: 500; structural search: 50; usages and lines: uncapped). Caps find, usages, search, deadcode, api, and repo files. find text shows the top 5 in detail and counts the rest; limit raises both. Must be a positive integer.', { exclusiveMinimum: 0, maximum: 1000000 }),
     max_files: integerParam('Max files to index (default: 10000). Use for very large codebases. Must be a positive integer.', { exclusiveMinimum: 0, maximum: 10000000 }),
-    max_chars: integerParam('Max output chars before truncation. Broad sweep commands (repo, entrypoints, endpoints, deadcode, deps, check, audit_async) default to 3K; all other commands default to 10K. Maximum: 100K. all=true lifts formatter caps but keeps the 100K transport ceiling.', { exclusiveMinimum: 0, maximum: 100000 }),
+    max_chars: integerParam('Max output characters, not UTF-8 bytes, including notes and preserved metadata. Broad sweep commands (repo, entrypoints, endpoints, deadcode, deps, check, audit_async) default to 3K; all other commands default to 10K. Maximum: 100K. all=true lifts formatter caps but keeps the 100K transport ceiling.', { exclusiveMinimum: 0, maximum: 100000 }),
     type: stringParam('Symbol type filter for structural search: function, class, call, method, type, state, field, constant, macro. Triggers index-based search.'),
     param: stringParam('Filter by parameter name or type (structural search). E.g. "Request", "ctx".'),
     receiver: stringParam('Filter calls by receiver (structural search, type=call). E.g. "db", "http".'),
@@ -469,6 +480,7 @@ server.registerTool(
             }
             const execution = execute(index, canonicalCommand, ep);
             if (!execution.ok) {
+                if (execution.internalError) return internalToolError(execution.error + strippedNote);
                 return te(formatSurfaceMessage(execution.error, 'mcp'));
             }
 
@@ -507,7 +519,9 @@ server.registerTool(
             ));
 
         } catch (e) {
-            return te(e.message);
+            const described = describeError(e);
+            if (described.internalError) return internalToolError(described.error + strippedNote);
+            return te(described.error);
         } finally {
             // Persist calls cache after command execution.
             // getIndex() only saves after build (when callsCache is empty).
@@ -516,7 +530,7 @@ server.registerTool(
             // MED-1: also persist when reachability was computed in-process so
             // long-lived MCP servers carry the BFS result forward to disk.
             if (index && !ep.includeBundled && !ep.maxFiles &&
-                (index.callsCacheDirty || index.reachabilityDirty || index.computedDispatchDirty)) {
+                (index.callsCacheDirty || index.reachabilityDirty || index.computedDispatchDirty || index.macroExpansionDirty)) {
                 try { index.saveCache(); } catch (_) { /* best-effort */ }
                 index.callsCacheDirty = false;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.4.1",
+  "version": "5.5.0",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Auditable AST code intelligence for AI agents: 18 task-oriented commands through one MCP tool, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java, C, C++, C#, and HTML.",
   "main": "index.js",