ucn 3.8.23 → 3.8.25

package/core/brief.js

@@ -0,0 +1,408 @@
+/**
+ * core/brief.js — Brief: AST-only one-screen summary for a symbol.
+ *
+ * Returns a compact "before-I-touch-this" snapshot:
+ *   - typed signature
+ *   - first-sentence docstring
+ *   - side-effect classification (fs/network/global mutation/process)
+ *   - complexity (branches, maxDepth, lineCount)
+ *   - async/generator flags
+ *
+ * No LLM, no heuristics that pretend to "summarize" intent.
+ * Everything here is derivable from the AST and existing symbol fields.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parse } = require('./parser');
+const { detectLanguage, langTraits } = require('../languages');
+const { formatSymbolHandle } = require('./shared');
+
+// ============================================================================
+// Side-effect signal sets (per-language, conservative)
+// ============================================================================
+
+// Module/import names that signal a category.
+// Keys are language; values are { fs: Set, network: Set, process: Set }.
+const SIDE_EFFECT_IMPORTS = {
+    javascript: {
+        fs: new Set(['fs', 'fs/promises', 'graceful-fs', 'node:fs', 'node:fs/promises']),
+        network: new Set(['http', 'https', 'net', 'tls', 'dgram', 'axios', 'node-fetch', 'got', 'undici', 'ws', 'node:http', 'node:https', 'node:net']),
+        process: new Set(['child_process', 'cluster', 'worker_threads', 'os', 'node:child_process', 'node:cluster', 'node:worker_threads', 'node:os']),
+    },
+    typescript: {
+        fs: new Set(['fs', 'fs/promises', 'graceful-fs', 'node:fs', 'node:fs/promises']),
+        network: new Set(['http', 'https', 'net', 'tls', 'dgram', 'axios', 'node-fetch', 'got', 'undici', 'ws', 'node:http', 'node:https', 'node:net']),
+        process: new Set(['child_process', 'cluster', 'worker_threads', 'os', 'node:child_process', 'node:cluster', 'node:worker_threads', 'node:os']),
+    },
+    python: {
+        fs: new Set(['os', 'os.path', 'pathlib', 'shutil', 'tempfile', 'io']),
+        network: new Set(['urllib', 'urllib.request', 'http', 'http.client', 'socket', 'requests', 'httpx', 'aiohttp']),
+        process: new Set(['subprocess', 'multiprocessing', 'os', 'signal', 'threading']),
+    },
+    go: {
+        fs: new Set(['os', 'io', 'io/ioutil', 'path/filepath', 'embed']),
+        network: new Set(['net', 'net/http', 'net/url', 'net/rpc']),
+        process: new Set(['os/exec', 'syscall', 'runtime']),
+    },
+    java: {
+        fs: new Set(['java.io', 'java.nio', 'java.nio.file']),
+        network: new Set(['java.net', 'java.net.http']),
+        process: new Set(['java.lang.Runtime', 'java.lang.ProcessBuilder']),
+    },
+    rust: {
+        fs: new Set(['std::fs', 'std::path']),
+        network: new Set(['std::net', 'reqwest', 'hyper', 'tokio::net']),
+        process: new Set(['std::process']),
+    },
+};
+
+// Identifier names that signal side effects when called or referenced.
+// Plain identifier match — not regex. We require the call to be the receiver-less form
+// (e.g. `fetch(...)`) OR a member of a recognized object (`fs.readFile`).
+const SIDE_EFFECT_CALLS_BY_LANG = {
+    javascript: {
+        network: new Set(['fetch', 'XMLHttpRequest']),
+        // Top-level browser globals that mutate state
+        process: new Set(['exit']),
+    },
+    typescript: {
+        network: new Set(['fetch', 'XMLHttpRequest']),
+        process: new Set(['exit']),
+    },
+    python: {
+        fs: new Set(['open']),
+        process: new Set(['exit', 'system']),
+    },
+    // Nominal languages: imports already give a strong signal (e.g. `java.io`),
+    // and direct-call tokens like `exit` would cause false positives across
+    // generic identifiers. We deliberately keep this empty.
+    go: {},
+    java: {},
+    rust: {},
+};
+
+// ============================================================================
+// brief()
+// ============================================================================
+
+/**
+ * Compute a brief AST summary for a symbol.
+ *
+ * @param {object} index - ProjectIndex
+ * @param {string} name - Symbol name (function/method/class)
+ * @param {object} options - { file, className, git }
+ * @returns {object|null}
+ */
+function brief(index, name, options = {}) {
+    index._beginOp();
+    try {
+        const { def } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
+        if (!def) return null;
+
+        const language = detectLanguage(def.relativePath || def.file);
+        const symbol = {
+            name: def.name,
+            type: def.type,
+            file: def.relativePath || def.file,
+            startLine: def.startLine,
+            endLine: def.endLine,
+            handle: formatSymbolHandle(def),
+            language,
+            ...(def.params != null && { params: def.params }),
+            ...(def.paramsStructured && { paramsStructured: def.paramsStructured }),
+            ...(def.paramTypes && { paramTypes: def.paramTypes }),
+            ...(def.returnType && { returnType: def.returnType }),
+            ...(def.modifiers && def.modifiers.length && { modifiers: def.modifiers }),
+            ...(def.decorators && def.decorators.length && { decorators: def.decorators }),
+            ...(def.docstring && { docstring: firstSentence(def.docstring) }),
+            ...(def.className && { className: def.className }),
+            ...(def.isAsync && { isAsync: true }),
+            ...(def.isGenerator && { isGenerator: true }),
+        };
+
+        // Optional git enrichment for the primary symbol's file.
+        // Skipped silently outside git repos; formatters check `git.available`.
+        let gitInfo = null;
+        if (options.git) {
+            const { getGitInfo } = require('./git-enrich');
+            gitInfo = getGitInfo(index.root, def.relativePath || def.file);
+        }
+
+        // For non-callable types (class/struct/interface/type), most fields don't apply
+        if (['class', 'struct', 'interface', 'type', 'enum'].includes(def.type)) {
+            return {
+                symbol,
+                kind: 'type',
+                lineCount: (def.endLine || def.startLine) - def.startLine + 1,
+                memberCount: countMembers(index, def),
+                ...(gitInfo && { git: gitInfo }),
+            };
+        }
+
+        // For callable symbols, scan the body
+        const filePath = path.isAbsolute(def.file) ? def.file : path.join(index.root, def.file);
+        let bodyText = '';
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const lines = content.split('\n');
+            const start = Math.max(0, (def.startLine || 1) - 1);
+            const end = Math.min(lines.length, def.endLine || def.startLine || 1);
+            bodyText = lines.slice(start, end).join('\n');
+        } catch (e) {
+            return {
+                symbol,
+                kind: 'function',
+                lineCount: 0,
+                sideEffects: [],
+                complexity: { branches: 0, maxDepth: 0, lineCount: 0 },
+                isAsync: !!def.isAsync,
+                error: 'Could not read source',
+                ...(gitInfo && { git: gitInfo }),
+            };
+        }
+
+        const fileEntry = index.files.get(def.file);
+        const fileImports = collectImportNames(fileEntry);
+
+        const sideEffects = classifySideEffects(bodyText, language, fileImports);
+        const complexity = computeComplexity(bodyText, language);
+
+        return {
+            symbol,
+            kind: 'function',
+            lineCount: complexity.lineCount,
+            sideEffects,
+            complexity,
+            isAsync: !!def.isAsync,
+            isGenerator: !!def.isGenerator,
+            ...(gitInfo && { git: gitInfo }),
+        };
+    } finally {
+        index._endOp();
+    }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function firstSentence(text) {
+    if (!text) return null;
+    const trimmed = text.trim();
+    // Cut on first sentence terminator. Cap at 200 chars to avoid runaway.
+    const m = trimmed.match(/^(.+?[.!?])\s/);
+    let s = m ? m[1] : trimmed;
+    if (s.length > 200) s = s.slice(0, 197) + '...';
+    return s;
+}
+
+function countMembers(index, def) {
+    if (!def || !def.file) return 0;
+    let count = 0;
+    for (const arr of index.symbols.values()) {
+        for (const s of arr) {
+            if (s.file === def.file && s.className === def.name && s.isMethod) count++;
+        }
+    }
+    return count;
+}
+
+function collectImportNames(fileEntry) {
+    if (!fileEntry) return new Set();
+    const names = new Set();
+    if (fileEntry.exportDetails) {
+        // exportDetails are exports — skip
+    }
+    // imports map: importName → modulePath (or { source, ... })
+    if (fileEntry.imports && typeof fileEntry.imports === 'object') {
+        for (const v of Object.values(fileEntry.imports)) {
+            if (typeof v === 'string') names.add(v);
+            else if (v && v.source) names.add(v.source);
+            else if (v && v.from) names.add(v.from);
+        }
+    }
+    if (fileEntry.importDetails && Array.isArray(fileEntry.importDetails)) {
+        for (const imp of fileEntry.importDetails) {
+            if (imp && imp.source) names.add(imp.source);
+            if (imp && imp.from) names.add(imp.from);
+        }
+    }
+    return names;
+}
+
+/**
+ * Classify side-effects from a function body using string scans.
+ *
+ * Returns: array of categories the function appears to touch:
+ *   'fs' — filesystem reads/writes
+ *   'network' — outbound network calls
+ *   'process' — child processes / OS-level effects
+ *   'global_mutation' — assignments to module-level identifiers (heuristic)
+ *
+ * NOTE: We use textual scanning over the function body — tree-sitter is great
+ * for top-level structure but reparsing every function body for the full AST
+ * just to detect well-known names is overkill. The signal sets are tight.
+ */
+function classifySideEffects(bodyText, language, fileImports) {
+    const out = new Set();
+    if (!bodyText) return [];
+
+    const importsBuckets = SIDE_EFFECT_IMPORTS[language] || {};
+    const callsBuckets = SIDE_EFFECT_CALLS_BY_LANG[language] || {};
+
+    // Resolve which categories the file's imports touch (file-level signal).
+    // E.g. if the file imports `fs`, ANY function in the file *could* use it.
+    // We confirm by looking for the import-binding name being used in the body.
+    // For now, surface category as a "potential" signal if the body references
+    // ANY imported binding from a category.
+    const fileImportLower = new Set([...fileImports].map(s => s.toLowerCase()));
+    for (const [cat, modSet] of Object.entries(importsBuckets)) {
+        for (const m of modSet) {
+            if (fileImportLower.has(m.toLowerCase())) {
+                // Also confirm the body references the module name as an identifier
+                // (very common: `fs.readFile`, `requests.get(`, etc.).
+                const baseName = m.split(/[./]/).pop();
+                if (baseName && new RegExp(`\\b${escapeRegExp(baseName)}\\b`).test(bodyText)) {
+                    out.add(cat);
+                    break;
+                }
+            }
+        }
+    }
+
+    // Direct-call signals (no import context needed): `fetch(`, `open(`, etc.
+    for (const [cat, callSet] of Object.entries(callsBuckets)) {
+        for (const fn of callSet) {
+            const re = new RegExp(`\\b${escapeRegExp(fn)}\\s*\\(`);
+            if (re.test(bodyText)) {
+                out.add(cat);
+                break;
+            }
+        }
+    }
+
+    // Process category for JS console.* (informational, not flagged)
+    // Skip — too noisy for "side effect" semantics.
+
+    // Global-mutation heuristic (cheap):
+    //   - JS/TS:    `module.exports.X = ` / `exports.X = ` / global identifier reassignment at top-level of function body
+    //   - Python:   `global X`
+    //   - Go:       package-level ident on lhs (hard without full AST — skip)
+    if (language === 'javascript' || language === 'typescript') {
+        if (/\b(module\.exports|exports)\.[A-Za-z_]\w*\s*=/.test(bodyText)) {
+            out.add('global_mutation');
+        }
+    } else if (language === 'python') {
+        if (/^\s*global\s+\w/m.test(bodyText)) {
+            out.add('global_mutation');
+        }
+    }
+
+    return [...out].sort();
+}
+
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Compute complexity metrics from a function body.
+ * Cheap, AST-free counts on tokenized source.
+ */
+function computeComplexity(bodyText, language) {
+    const lines = bodyText.split('\n');
+    const lineCount = lines.length;
+
+    // Branch count: count keywords that introduce a new branching path.
+    // We deliberately ignore final `else` (it's just the alternate of an `if`).
+    const branchPatterns = [
+        /\bif\s*\(/g,        // JS/TS/Java/Rust/Go/C-like
+        /\bif\s+/g,          // Python (if x:)
+        /\belif\b/g,         // Python
+        /\belse\s+if\b/g,    // JS/Java/etc.
+        /\bcase\b/g,         // switch case
+        /\bwhen\b/g,         // Rust match arms (and Kotlin/Scala but we don't support those)
+        /\bfor\s*\(/g,       // C-like for
+        /\bfor\s+\w/g,       // Python for x in
+        /\bwhile\s*\(/g,     // C-like while
+        /\bwhile\s+/g,       // Python while x:
+        /\?[^?]/g,           // ternary (rough)
+        /\bcatch\s*\(/g,     // catch
+        /\bexcept\b/g,       // Python except
+    ];
+    let branches = 0;
+    for (const re of branchPatterns) branches += (bodyText.match(re) || []).length;
+
+    // maxDepth: indent-based proxy. Fast, language-agnostic, off-by-one safe.
+    let maxDepth = 0;
+    let firstNonBlankIndent = -1;
+    for (const line of lines) {
+        if (!line.trim()) continue;
+        const m = line.match(/^(\s*)/);
+        const spaces = m ? expandIndent(m[1]) : 0;
+        if (firstNonBlankIndent === -1) firstNonBlankIndent = spaces;
+        // depth = (current - first) / unit; we don't know "unit", so just track
+        // raw delta and divide by 2 (conservative — most code is 2 or 4 space indented).
+        const rawDepth = Math.max(0, spaces - firstNonBlankIndent);
+        if (rawDepth > maxDepth) maxDepth = rawDepth;
+    }
+    // Translate raw spaces to depth levels (assume 2-space indent baseline)
+    const depth = Math.round(maxDepth / 2);
+
+    return { branches, maxDepth: depth, lineCount };
+}
+
+function expandIndent(s) {
+    let n = 0;
+    for (const c of s) n += (c === '\t') ? 4 : 1;
+    return n;
+}
+
+/**
+ * Lazy classifier: side-effect tags for an arbitrary symbol record.
+ * Used by callee output (`context`, `about`) to surface [fs]/[net]/[proc] tags
+ * inline. Cached on the index in `_sideEffectCache` (key: file:startLine).
+ *
+ * Cheap on cache hit; first hit reads + scans the symbol's body. Returns
+ * `null` for non-callable types or unreadable files.
+ */
+function sideEffectsFor(index, symbol) {
+    if (!index || !symbol) return null;
+    if (NON_CALLABLE_KIND.has(symbol.type)) return null;
+    const key = `${symbol.file || symbol.relativePath}:${symbol.startLine || 0}`;
+    if (!index._sideEffectCache) index._sideEffectCache = new Map();
+    if (index._sideEffectCache.has(key)) return index._sideEffectCache.get(key);
+
+    const filePath = path.isAbsolute(symbol.file || '') ? symbol.file : path.join(index.root, symbol.file || symbol.relativePath || '');
+    let bodyText = '';
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        const start = Math.max(0, (symbol.startLine || 1) - 1);
+        const end = Math.min(lines.length, symbol.endLine || symbol.startLine || 1);
+        bodyText = lines.slice(start, end).join('\n');
+    } catch (e) {
+        index._sideEffectCache.set(key, null);
+        return null;
+    }
+    const language = detectLanguage(symbol.relativePath || symbol.file);
+    const fileEntry = index.files.get(symbol.file);
+    const fileImports = collectImportNames(fileEntry);
+    const tags = classifySideEffects(bodyText, language, fileImports);
+    index._sideEffectCache.set(key, tags);
+    return tags;
+}
+
+const NON_CALLABLE_KIND = new Set(['class', 'struct', 'interface', 'type', 'enum', 'trait', 'impl', 'state', 'field']);
+
+module.exports = {
+    brief,
+    sideEffectsFor,
+    // exposed for tests
+    classifySideEffects,
+    computeComplexity,
+    firstSentence,
+};

package/core/cache.js

@@ -82,11 +82,39 @@ function saveCache(index, cachePath) {
     // calleeIndex is NOT persisted in index.json — it's rebuilt lazily from callsCache
     // on first findCallers/buildCalleeIndex call. Removing it saves ~22MB (14%) on large projects.
 
+    // PERF-1: persist _reachableSymbols if computed. Set keys are
+    // "absolutePath:line"; we strip the root prefix on save and re-attach on
+    // load so paths stay portable. Sorted for stable output ordering.
+    //
+    // Also save a fingerprint so we can detect index drift on load: if the
+    // saved fingerprint matches the loaded index state, the cached set is
+    // still valid. If the index was rebuilt after load (stale cache → build),
+    // the fingerprint won't match and computeReachability will recompute.
+    let reachableSymbolsRel = undefined;
+    let reachableFingerprint = undefined;
+    if (index._reachableSymbols && index._reachableSymbols.size > 0) {
+        const rels = [];
+        for (const k of index._reachableSymbols) {
+            const colon = k.lastIndexOf(':');
+            if (colon < 0) continue;
+            const absFile = k.slice(0, colon);
+            const lineStr = k.slice(colon + 1);
+            const relFile = path.relative(root, absFile);
+            rels.push(`${relFile}:${lineStr}`);
+        }
+        rels.sort();  // stable ordering — output contract
+        reachableSymbolsRel = rels;
+        reachableFingerprint = _computeReachabilityFingerprint(index);
+    }
+
     const cacheData = {
-        version: 8,  // v8: remove calleeIndex from index.json (rebuilt from callsCache)
+        // v10: persist _reachableSymbols set (computed by entrypoints.computeReachability)
+        version: 10,
         ucnVersion: UCN_VERSION,  // Invalidate cache when UCN is updated
         configHash,
         root,
+        // PERF-2: refresh buildTime on each save so partial rebuilds report
+        // accurate stats. Falls back to original on first save.
         buildTime: index.buildTime,
         timestamp: Date.now(),
         files: strippedFiles,
@@ -99,9 +127,24 @@ function saveCache(index, cachePath) {
         failedFiles: index.failedFiles
             ? Array.from(index.failedFiles).map(f => path.relative(root, f))
             : [],
+        ...(reachableSymbolsRel !== undefined && {
+            reachableSymbols: reachableSymbolsRel,
+            reachableFingerprint,
+        }),
     };
 
-    fs.writeFileSync(cacheFile, JSON.stringify(cacheData));
+    // PERF-3: atomic write — tmp file + rename so concurrent readers/writers
+    // never see a torn JSON. The calls/ shard write below already does this.
+    const tmpFile = cacheFile + '.tmp';
+    fs.writeFileSync(tmpFile, JSON.stringify(cacheData));
+    fs.renameSync(tmpFile, cacheFile);
+
+    // MED-1 (Round 5): clear the reachabilityDirty flag now that the set is
+    // safely persisted. The cli/index.js cache-save guard checks this flag
+    // along with needsCacheSave/callsCacheDirty.
+    if (index.reachabilityDirty) {
+        index.reachabilityDirty = false;
+    }
 
     // Save callsCache sharded by directory for lazy loading.
     // Write to a temp directory first, then atomic swap to avoid data loss on crash.
@@ -170,8 +213,9 @@ function loadCache(index, cachePath) {
 
         // Check version compatibility
         // v7: symbols/bindings stripped from file entries (dedup)
-        // v8: calleeIndex removed from index.json (rebuilt from callsCache)
-        if (cacheData.version !== 7 && cacheData.version !== 8) {
+        // v9: addSymbol propagates isAsync/isGenerator/paramTypes (force rebuild for old)
+        // v10: persists _reachableSymbols set
+        if (cacheData.version !== 10) {
             return false;
         }
 
@@ -285,6 +329,29 @@ function loadCache(index, cachePath) {
             }
         }
 
+        // PERF-1: restore _reachableSymbols if persisted (v10+).
+        // Saved as relative-path keys; rehydrate to absolute keys here so the
+        // in-memory set matches what computeReachability would produce fresh.
+        // The fingerprint is checked by computeReachability before reuse — if
+        // the index drifts (e.g. a rebuild after stale cache), the cached set
+        // is dropped and recomputed.
+        if (Array.isArray(cacheData.reachableSymbols)) {
+            const reachable = new Set();
+            for (const k of cacheData.reachableSymbols) {
+                if (typeof k !== 'string') continue;
+                const colon = k.lastIndexOf(':');
+                if (colon < 0) continue;
+                const relFile = k.slice(0, colon);
+                const lineStr = k.slice(colon + 1);
+                const absFile = path.isAbsolute(relFile) ? relFile : toAbs(relFile);
+                reachable.add(`${absFile}:${lineStr}`);
+            }
+            index._reachableSymbols = reachable;
+            if (cacheData.reachableFingerprint) {
+                index._reachableFingerprint = cacheData.reachableFingerprint;
+            }
+        }
+
         // Only rebuild graphs if config changed (e.g., aliases modified)
         const currentConfigHash = crypto.createHash('md5')
             .update(JSON.stringify(index.config || {})).digest('hex');
@@ -467,4 +534,37 @@ function _loadCallsShard(index, hash) {
     }
 }
 
-module.exports = { saveCache, loadCache, loadCallsCache, isCacheStale, ensureCallsCacheLoaded };
+/**
+ * Compute a cheap fingerprint of the index used to detect drift since the
+ * last reachability computation. Two states with the same fingerprint are
+ * indistinguishable for reachability purposes (file count + symbol count are
+ * monotonic with structural changes; an extra `entries[0]` byte detects most
+ * incremental rebuilds even when counts happen to match).
+ *
+ * Used by entrypoints.computeReachability to decide whether the persisted
+ * `_reachableSymbols` set is still valid.
+ *
+ * @param {object} index - ProjectIndex instance
+ * @returns {string} compact fingerprint
+ */
+function _computeReachabilityFingerprint(index) {
+    const fileCount = index.files ? index.files.size : 0;
+    const symbolCount = index.symbols ? index.symbols.size : 0;
+    // Sample a tiny prefix of the symbol map for a cheap structural check.
+    // Map iteration order is insertion order, which is stable across an
+    // unmodified load (built from cacheData.symbols in the same order).
+    let sample = '';
+    if (index.symbols && index.symbols.size > 0) {
+        let count = 0;
+        for (const [name, defs] of index.symbols) {
+            sample += name + ':' + (Array.isArray(defs) ? defs.length : 0) + '|';
+            if (++count >= 8) break;
+        }
+    }
+    return `${fileCount}:${symbolCount}:${sample}`;
+}
+
+module.exports = {
+    saveCache, loadCache, loadCallsCache, isCacheStale, ensureCallsCacheLoaded,
+    _computeReachabilityFingerprint,
+};

package/core/callers.js

@@ -160,6 +160,11 @@ function findCallers(index, name, options = {}) {
     const pendingByFile = new Map(); // filePath -> [{ call, fileEntry, callerSymbol, isMethod, isFunctionReference, receiver }]
     let pendingCount = 0;
     const maxResults = options.maxResults;
+    // BUG-H1: when consumers (like `about`) need an accurate truncation header
+    // ("showing N of <total>"), they pass needsTotal:true so Phase 1 runs to
+    // completion. Phase 2 still only enriches the first `maxResults` items —
+    // file reads stay bounded, but the candidate count reflects the true total.
+    const needsTotal = !!options.needsTotal;
     const localTypeCache = new Map(); // `${filePath}:${startLine}` -> localTypes Map or null
 
     // Use inverted callee index to skip files that don't contain calls to this name
@@ -169,8 +174,8 @@ function findCallers(index, name, options = {}) {
         : index.files;
 
     for (const [filePath, fileEntry] of fileIterator) {
-        // Early exit when maxResults is reached
-        if (maxResults && pendingCount >= maxResults) break;
+        // Early exit when maxResults is reached (skip when caller needs the true total)
+        if (maxResults && !needsTotal && pendingCount >= maxResults) break;
         try {
             const calls = getCachedCalls(index, filePath);
             if (!calls) continue;
@@ -643,34 +648,83 @@ function findCallers(index, name, options = {}) {
         }
     }
 
+    // True total candidate count from Phase 1 (before any Phase 2 truncation).
+    // Used by callers that need accurate "showing N of <total>" headers.
+    const totalCount = pendingCount;
+    // When needsTotal is set with a maxResults cap, only enrich the first
+    // `maxResults` candidates in Phase 2 — file reads stay bounded.
+    const enrichLimit = (needsTotal && maxResults) ? maxResults : Infinity;
+    let enrichedCount = 0;
+
+    // BUG-H1: shadow records for un-enriched candidates so post-call filters
+    // (exclude / minConfidence) can produce an accurate total without forcing
+    // a Phase-2 file read for every candidate. Each shadow has just enough
+    // info to drive the filter predicates: relativePath + confidence.
+    const shadowEntries = [];
+
     // Phase 2: Read content only for files with matching calls (eliminates ~98% of file reads)
-    for (const [filePath, pending] of pendingByFile) {
-        try {
-            const content = fs.readFileSync(filePath, 'utf-8');
-            for (const { call, fileEntry, callerSymbol, isMethod, isFunctionReference, receiver, receiverType, _evidence } of pending) {
-                const scored = scoreEdge(_evidence || {});
-                callers.push({
+    outer: for (const [filePath, pending] of pendingByFile) {
+        let content = null;
+        for (const { call, fileEntry, callerSymbol, isMethod, isFunctionReference, receiver, receiverType, _evidence } of pending) {
+            const scored = scoreEdge(_evidence || {});
+            if (enrichedCount >= enrichLimit) {
+                // Push shadow only — no file read needed.
+                shadowEntries.push({
                     file: filePath,
                     relativePath: fileEntry.relativePath,
                     line: call.line,
-                    content: getLine(content, call.line),
-                    callerName: callerSymbol ? callerSymbol.name : null,
-                    callerFile: callerSymbol ? filePath : null,
-                    callerStartLine: callerSymbol ? callerSymbol.startLine : null,
-                    callerEndLine: callerSymbol ? callerSymbol.endLine : null,
-                    isMethod,
+                    confidence: scored.confidence,
+                    resolution: scored.resolution,
+                    isMethod: call.isMethod || false,
                     ...(isFunctionReference && { isFunctionReference: true }),
                     ...(receiver !== undefined && { receiver }),
                     ...(receiverType && { receiverType }),
-                    confidence: scored.confidence,
-                    resolution: scored.resolution,
                 });
+                continue;
             }
-        } catch (e) {
-            // File may have been deleted between Phase 1 and Phase 2
+            // First time we hit this file's enrichment loop — read the file once.
+            if (content === null) {
+                try { content = fs.readFileSync(filePath, 'utf-8'); }
+                catch (e) { content = ''; /* deleted/unreadable; skip enrichment for rest */ break; }
+            }
+            callers.push({
+                file: filePath,
+                relativePath: fileEntry.relativePath,
+                line: call.line,
+                content: getLine(content, call.line),
+                callerName: callerSymbol ? callerSymbol.name : null,
+                callerFile: callerSymbol ? filePath : null,
+                callerStartLine: callerSymbol ? callerSymbol.startLine : null,
+                callerEndLine: callerSymbol ? callerSymbol.endLine : null,
+                isMethod,
+                ...(isFunctionReference && { isFunctionReference: true }),
+                ...(receiver !== undefined && { receiver }),
+                ...(receiverType && { receiverType }),
+                confidence: scored.confidence,
+                resolution: scored.resolution,
+            });
+            enrichedCount++;
         }
     }
 
+    // Tag the returned array with the true total candidate count (only meaningful
+    // when needsTotal:true was passed). Defined as non-enumerable so JSON.stringify
+    // won't surprise consumers; defaults to callers.length when not set.
+    Object.defineProperty(callers, 'totalCount', {
+        value: needsTotal ? totalCount : callers.length,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+    // Attach shadow entries so consumers can compute post-filter totals without
+    // re-running findCallers. Empty when needsTotal:false or all candidates fit.
+    Object.defineProperty(callers, 'shadowEntries', {
+        value: shadowEntries,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+
     return callers;
     } finally { index._endOp(); }
 }