ucn 5.5.0 → 5.5.1

package/README.md

@@ -1,6 +1,6 @@
 # UCN - Universal Code Navigator
 
-See what code does before you touch it.
+Auditable answers, with every match counted, unsure ones marked and blind spots named.
 
 [![npm](https://img.shields.io/npm/v/ucn)](https://www.npmjs.com/package/ucn)
 [![tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/mleoca/0e10a790e16ab61ddd233e05645e203e/raw/ucn-tests.json)](https://github.com/mleoca/ucn/actions/workflows/ci.yml)
@@ -8,7 +8,9 @@ See what code does before you touch it.
 
 If you work with AI Agents, add UCN as a [Skill or MCP tool](#ai-setup). One tool
 gives the agent compact, source-linked answers to caller, impact, and test
-questions, with uncertainty labeled instead of guessed.
+questions, with uncertainty labeled instead of guessed. The answer depends on
+the indexed source, not on who asks: a person at a terminal and an agent over
+MCP receive the same records for the same question.
 
 <img src="assets/readme/ucn-connected-scope.gif" width="736" alt="Conceptual overview of UCN's relationship views, multi-hop exploration, visible uncertainty, index reuse, and refresh after edits. Nodes and timing are illustrative, not a captured query or benchmark.">
 
@@ -103,10 +105,11 @@ Captured findings · [Still image](assets/readme/ucn-evidence-graph.png) · [Dat
 
 The ACCOUNT line reconciles the observed name occurrences: confirmed calls,
 unverified candidates, non-call occurrences, and matches attributed to another
-target. CONTRACT describes the scope of that accounting. Warnings identify
-source the index could not cover. These details survive text truncation for
-an agent's output budget; a budget too small to hold them withholds the answer
-and names the budget that would.
+target. Each occurrence is counted in exactly one category, so the totals can
+be checked line by line rather than taken on trust. CONTRACT describes the
+scope of that accounting. Warnings identify source the index could not cover.
+These details survive text truncation for an agent's output budget; a budget
+too small to hold them withholds the answer and names the budget that would.
 
 An empty result therefore means something specific about the inspected code.
 It cannot establish that reflection, generated code, runtime registration, or
@@ -210,6 +213,8 @@ exits 2, and a successful listing exits 0. `--lines` supports `find`, `show`,
 `usages`, `search`, and `impact`; `show --lines` lists callers by default.
 Use `--json` when the script needs structured fields or a tree result.
 
+Listings are deterministic for a given source tree: a fresh build, a cache
+load, and an incremental rebuild return the same records in the same order.
 Listings have no default row cap. Explicit limits disclose what they omit,
 and a shell-mode character budget fails before writing partial output.
 `source --raw` extracts complete functions and classes unless an explicit

package/cli/index.js

@@ -843,6 +843,11 @@ function runProjectCommand(rootDir, command, arg) {
         // On cache-hit runs, only re-save if callsCache was mutated OR
         // reachability was computed (MED-1: persists the BFS result so
         // subsequent cold invocations don't repeat the 7-11s tax).
+        // Files whose macro-expansion calls the command derived in part are
+        // derived whole first, so the next invocation reads them persisted.
+        if (flags.cache) {
+            try { index.completeMacroCallDerivations(); } catch (e) { /* best-effort */ }
+        }
         if (flags.cache && (needsCacheSave || index.callsCacheDirty || index.reachabilityDirty || index.computedDispatchDirty || index.macroExpansionDirty)) {
             try { index.saveCache(); } catch (e) { /* best-effort */ }
         }

package/core/account.js

@@ -276,6 +276,23 @@ function scanUnsupportedFiles(index, name, opts = {}) {
     return unsupported;
 }
 
+/**
+ * A set of (file, line) keys held per file: `key(file, line)` names one,
+ * and `add`/`has` take a key or a (file, line) pair. Lines compare by their
+ * text, as `${file}:${line}` strings do.
+ */
+class LineKeys {
+    constructor() { this.byFile = new Map(); }
+    key(file, line) { return { file: String(file), line: String(line) }; }
+    add(file, line) {
+        const key = line === undefined ? file : this.key(file, line);
+        let lines = this.byFile.get(key.file);
+        if (!lines) this.byFile.set(key.file, lines = new Set());
+        lines.add(key.line);
+    }
+    has(key) { return this.byFile.get(key.file)?.has(key.line) === true; }
+}
+
 /**
  * Classify ground lines not claimed by engine results.
  *
@@ -289,7 +306,7 @@ function scanUnsupportedFiles(index, name, opts = {}) {
  * @param {object} index - ProjectIndex
  * @param {string} name - Symbol name
  * @param {object} groundSet - from computeGroundSet
- * @param {Set<string>} claimedKeys - `${absPath}:${line}` keys already claimed
+ * @param {LineKeys} claimedKeys - (absPath, line) keys already claimed
  *   (confirmed + unverified + excluded engine lines)
  * @returns {{
  *   nonCall: { imports: number, definitions: number, references: number, unclassifiedText: number, total: number },
@@ -311,12 +328,12 @@ function classifyGroundLines(index, name, groundSet, claimedKeys) {
         if (!defLinesByFile.has(def.file)) defLinesByFile.set(def.file, new Set());
         defLinesByFile.get(def.file).add(def.startLine);
     }
-    let getCachedCalls = null; // lazy require to avoid cycle at module load
+    let getCachedCallsBearing = null; // lazy require to avoid cycle at module load
 
     for (const [filePath, lineNumbers] of groundSet.perFile) {
         let unclaimed = null;
         for (const line of lineNumbers) {
-            if (claimedKeys.has(`${filePath}:${line}`)) continue;
+            if (claimedKeys.has(claimedKeys.key(filePath, line))) continue;
             (unclaimed || (unclaimed = [])).push(line);
         }
         if (!unclaimed) continue;
@@ -324,9 +341,10 @@ function classifyGroundLines(index, name, groundSet, claimedKeys) {
         const fileEntry = index.files.get(filePath);
         const relativePath = fileEntry ? fileEntry.relativePath : path.relative(index.root, filePath);
 
-        // Cheap pass: calls cache + symbol table
-        if (!getCachedCalls) getCachedCalls = require('./callers').getCachedCalls;
-        const cachedCalls = getCachedCalls(index, filePath);
+        // Cheap pass: calls cache + symbol table (only records bearing the
+        // name on unclaimed lines are read below).
+        if (!getCachedCallsBearing) getCachedCallsBearing = require('./callers').getCachedCallsBearing;
+        const cachedCalls = getCachedCallsBearing(index, filePath, name, new Set(unclaimed));
         const callLines = new Set();
         if (Array.isArray(cachedCalls)) {
             for (const c of cachedCalls) {
@@ -419,18 +437,21 @@ function buildAccount(index, name, parts) {
     const unverifiedEntries = parts.unverifiedEntries || [];
     const excludedEntries = parts.excludedEntries || [];
 
-    const groundKeys = new Set();
+    // (file, line) keys, kept per file (fix #405b: one composed string per
+    // ground line and per entry); a line is keyed by its text, as the
+    // composed `${file}:${line}` keys were.
+    const groundKeys = new LineKeys();
     for (const [filePath, lineNumbers] of groundSet.perFile) {
-        for (const line of lineNumbers) groundKeys.add(`${filePath}:${line}`);
+        for (const line of lineNumbers) groundKeys.add(filePath, line);
     }
 
-    const claimedKeys = new Set();
+    const claimedKeys = new LineKeys();
     const beyondText = { count: 0, sample: [] };
     let confirmed = 0;
     let unverified = 0;
 
     const claim = (entry, bucket) => {
-        const key = `${entry.file}:${entry.line}`;
+        const key = claimedKeys.key(entry.file, entry.line);
         if (claimedKeys.has(key)) return; // one bucket per line; first claim wins
         if (!groundKeys.has(key)) {
             // Engine found a call site grep would miss (alias / indirect name).
@@ -454,7 +475,7 @@ function buildAccount(index, name, parts) {
     const excludedByReason = {};
     let excludedTotal = 0;
     for (const e of excludedEntries) {
-        const key = `${e.file}:${e.line}`;
+        const key = claimedKeys.key(e.file, e.line);
         if (claimedKeys.has(key)) continue;
         claimedKeys.add(key);
         if (!groundKeys.has(key)) continue; // excluded non-ground line: irrelevant to both grep and display

package/core/analysis.js

@@ -2509,8 +2509,15 @@ function diffImpact(index, options = {}) {
         const { getCachedCalls } = require('./callers');
         for (const del of deletedFunctions) {
             const remaining = [];
-            const calleeFiles = index.getCalleeFiles(del.name);
-            if (calleeFiles) {
+            // A snapshot: deriving a file's macro-expansion calls re-lists it
+            // in the callee index. Files whose expansions' calls are not
+            // derived yet and whose expanded text holds the name join it
+            // (fix #405).
+            const calleeFiles = new Set(index.getCalleeFiles(del.name) || []);
+            for (const f of require('./rust-macro-expansion').rustPendingFilesBearing(index, [del.name])) {
+                calleeFiles.add(f);
+            }
+            if (calleeFiles.size > 0) {
                 for (const f of calleeFiles) {
                     const calls = getCachedCalls(index, f);
                     if (!Array.isArray(calls)) continue;

package/core/cache.js

@@ -918,7 +918,14 @@ function clearAllCaches() {
 // `passedAsArgument`.
 // v274 (fix #403): a Python reference inside a lambda whose enclosing def
 // binds the name records that def as its `localShadowScope`.
-const CACHE_FORMAT_VERSION = 274;
+// v275 (fix #405): a Rust file whose macro-expansion calls are pending
+// records every expansion's hygiene start and expanded length
+// (`rustMacroExpansion.expansions`); its `words` leave out the text of
+// literals and comments.
+// v276 (fix #405b): a pending Rust file whose expansions the calls pass
+// reads by groups records each group's lines, expanded length and the words
+// its expansions output and its headers hold (`rustMacroExpansion.groups`).
+const CACHE_FORMAT_VERSION = 276;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 /**