ucn 3.7.23 → 3.7.25

package/core/deadcode.js

@@ -0,0 +1,320 @@
+/**
+ * core/deadcode.js - Dead code detection (unused functions/classes)
+ *
+ * Extracted from project.js. All functions take an `index` (ProjectIndex)
+ * as the first argument instead of using `this`.
+ */
+
+const { detectLanguage, getParser, getLanguageModule, safeParse } = require('../languages');
+const { isTestFile } = require('./discovery');
+
+/**
+ * Build a usage index for all identifiers in the codebase (optimized for deadcode)
+ * Scans all files ONCE and builds a reverse index: name -> [usages]
+ * @param {object} index - ProjectIndex instance
+ * @returns {Map<string, Array>} Usage index
+ */
+function buildUsageIndex(index) {
+    const usageIndex = new Map(); // name -> [{file, line}]
+
+    for (const [filePath, fileEntry] of index.files) {
+        try {
+            const language = detectLanguage(filePath);
+            if (!language) continue;
+
+            const content = index._readFile(filePath);
+
+            // For HTML files, parse the virtual JS content instead of raw HTML
+            // (HTML tree-sitter sees script content as raw_text, not JS identifiers)
+            let tree;
+            if (language === 'html') {
+                const htmlModule = getLanguageModule('html');
+                const htmlParser = getParser('html');
+                const jsParser = getParser('javascript');
+                const blocks = htmlModule.extractScriptBlocks(content, htmlParser);
+                if (blocks.length === 0 && !htmlModule.extractEventHandlerCalls) continue;
+                if (blocks.length > 0) {
+                    const virtualJS = htmlModule.buildVirtualJSContent(content, blocks);
+                    tree = safeParse(jsParser, virtualJS);
+                }
+            } else {
+                const parser = getParser(language);
+                if (!parser) continue;
+                tree = safeParse(parser, content);
+            }
+
+            // Collect all identifiers from this file in one pass
+            const traverse = (node) => {
+                // Match all identifier-like nodes across languages
+                if (node.type === 'identifier' ||
+                    node.type === 'property_identifier' ||
+                    node.type === 'type_identifier' ||
+                    node.type === 'shorthand_property_identifier' ||
+                    node.type === 'shorthand_property_identifier_pattern' ||
+                    node.type === 'field_identifier') {
+                    const name = node.text;
+                    if (!usageIndex.has(name)) {
+                        usageIndex.set(name, []);
+                    }
+                    usageIndex.get(name).push({
+                        file: filePath,
+                        line: node.startPosition.row + 1,
+                        relativePath: fileEntry.relativePath
+                    });
+                }
+                for (let i = 0; i < node.childCount; i++) {
+                    traverse(node.child(i));
+                }
+            };
+            if (tree) traverse(tree.rootNode);
+
+            // For HTML files, also extract identifiers from event handler attributes
+            // (onclick="foo()" etc. — these are in HTML, not in <script> blocks)
+            if (language === 'html') {
+                const htmlModule = getLanguageModule('html');
+                const htmlParser = getParser('html');
+                const handlerCalls = htmlModule.extractEventHandlerCalls(content, htmlParser);
+                for (const call of handlerCalls) {
+                    if (!usageIndex.has(call.name)) {
+                        usageIndex.set(call.name, []);
+                    }
+                    usageIndex.get(call.name).push({
+                        file: filePath,
+                        line: call.line,
+                        relativePath: fileEntry.relativePath
+                    });
+                }
+            }
+        } catch (e) {
+            // Skip files that can't be processed
+        }
+    }
+
+    return usageIndex;
+}
+
+/**
+ * Find dead code (unused functions/classes)
+ * @param {object} index - ProjectIndex instance
+ * @param {object} options - { includeExported, includeTests }
+ * @returns {Array} Unused symbols
+ */
+function deadcode(index, options = {}) {
+    index._beginOp();
+    try {
+    const results = [];
+    let excludedDecorated = 0;
+    let excludedExported = 0;
+
+    // Build usage index once (instead of per-symbol)
+    const usageIndex = buildUsageIndex(index);
+
+    for (const [name, symbols] of index.symbols) {
+        for (const symbol of symbols) {
+            // Skip non-function/class types
+            // Include various method types from different languages:
+            // - function: standalone functions
+            // - class, struct, interface: type definitions (skip them in deadcode)
+            // - method: class methods
+            // - static, public, abstract: Java method modifiers used as types
+            // - constructor: constructors
+            const callableTypes = ['function', 'method', 'static', 'public', 'abstract', 'constructor'];
+            if (!callableTypes.includes(symbol.type)) {
+                continue;
+            }
+
+            const fileEntry = index.files.get(symbol.file);
+            const lang = fileEntry?.language;
+
+            // Skip bundled/minified files (webpack bundles, build artifacts)
+            if (fileEntry?.isBundled) {
+                continue;
+            }
+
+            // Skip test files unless requested
+            if (!options.includeTests && isTestFile(symbol.relativePath, lang)) {
+                continue;
+            }
+
+            // Apply exclude and in filters
+            if ((options.exclude && options.exclude.length > 0) || options.in) {
+                if (!index.matchesFilters(symbol.relativePath, { exclude: options.exclude, in: options.in })) {
+                    continue;
+                }
+            }
+
+            const mods = symbol.modifiers || [];
+
+            // Language-specific entry points (called by runtime, no AST-visible callers)
+            // Go: main() and init() are called by runtime
+            const isGoEntryPoint = lang === 'go' && (name === 'main' || name === 'init');
+
+            // Java: public static void main(String[] args) is the entry point
+            const isJavaEntryPoint = lang === 'java' && name === 'main' &&
+                mods.includes('public') && mods.includes('static');
+
+            // Python: Magic/dunder methods are called by the interpreter, not user code
+            // test_* functions/methods are called by pytest/unittest via reflection
+            // setUp/tearDown are unittest.TestCase framework methods called by test runner
+            // pytest_* are pytest plugin hooks called by the framework
+            const isPythonEntryPoint = lang === 'python' &&
+                (/^__\w+__$/.test(name) || /^test_/.test(name) ||
+                 /^(setUp|tearDown)(Class|Module)?$/.test(name) ||
+                 /^pytest_/.test(name));
+
+            // Rust: main() is entry point, #[test] and #[bench] functions are called by test/bench runner
+            const isRustEntryPoint = lang === 'rust' &&
+                (name === 'main' || mods.includes('test') || mods.includes('bench'));
+
+            // Rust: trait impl methods are invoked via trait dispatch, not direct calls
+            // They can never be "dead" - the trait contract requires them to exist
+            // className for trait impls contains " for " (e.g., "PartialEq for Glob")
+            const isRustTraitImpl = lang === 'rust' && symbol.isMethod &&
+                symbol.className && symbol.className.includes(' for ');
+
+            // Go: Test*, Benchmark*, Example* functions are called by go test
+            const isGoTestFunc = lang === 'go' &&
+                /^(Test|Benchmark|Example)[A-Z]/.test(name);
+
+            // Java: @Test annotated methods are called by JUnit
+            const isJavaTestMethod = lang === 'java' && mods.includes('test');
+
+            // Java: @Override methods are invoked via polymorphic dispatch
+            // They implement interface/superclass contracts and can't be dead
+            const isJavaOverride = lang === 'java' && mods.includes('override');
+
+            // Skip trait impl / @Override methods entirely - they're required by the type system
+            if (isRustTraitImpl || isJavaOverride) {
+                continue;
+            }
+
+            // JavaScript/TypeScript: framework lifecycle methods called by runtime
+            // React class components, Web Components, Angular, Vue
+            const jsLifecycleMethods = new Set([
+                // React class component lifecycle
+                'render', 'componentDidMount', 'componentDidUpdate', 'componentWillUnmount',
+                'getDerivedStateFromProps', 'getDerivedStateFromError', 'componentDidCatch',
+                'getSnapshotBeforeUpdate', 'shouldComponentUpdate',
+                // Web Components lifecycle
+                'connectedCallback', 'disconnectedCallback', 'attributeChangedCallback', 'adoptedCallback'
+            ]);
+            const isJsEntryPoint = (lang === 'javascript' || lang === 'typescript' || lang === 'tsx') &&
+                symbol.isMethod && jsLifecycleMethods.has(name);
+
+            const isEntryPoint = isGoEntryPoint || isGoTestFunc ||
+                isJavaEntryPoint || isJavaTestMethod ||
+                isPythonEntryPoint || isRustEntryPoint || isJsEntryPoint;
+
+            // Entry points are always excluded — they're invoked by the runtime, not user code
+            if (isEntryPoint) {
+                continue;
+            }
+
+            // Framework registration decorators — excluded by default to reduce noise
+            // Python: decorators with '.' (attribute access) like @router.get, @app.route, @celery.task
+            // Java: non-standard annotations like @Bean, @Scheduled, @GetMapping
+            // These functions are invoked by frameworks, not by user code — AST can't see the call path
+            const javaKeywords = new Set(['public', 'private', 'protected', 'static', 'final', 'abstract', 'synchronized', 'native', 'default']);
+            const hasRegistrationDecorator = (() => {
+                if (lang === 'python') {
+                    const decorators = symbol.decorators || [];
+                    return decorators.some(d => d.includes('.'));
+                }
+                if (lang === 'java') {
+                    return mods.some(m => !javaKeywords.has(m));
+                }
+                return false;
+            })();
+
+            if (hasRegistrationDecorator && !options.includeDecorated) {
+                excludedDecorated++;
+                continue;
+            }
+
+            const isExported = fileEntry && (
+                fileEntry.exports.includes(name) ||
+                mods.includes('export') ||
+                mods.includes('public') ||
+                (lang === 'go' && /^[A-Z]/.test(name))
+            );
+
+            // Skip exported unless requested
+            if (isExported && !options.includeExported) {
+                excludedExported++;
+                continue;
+            }
+
+            // Use pre-built index for O(1) lookup instead of O(files) scan
+            const allUsages = usageIndex.get(name) || [];
+
+            // Filter out usages that are at the definition location
+            // nameLine: when decorators/annotations are present, startLine is the decorator line
+            // but the name identifier is on a different line (nameLine). Check both.
+            let nonDefUsages = allUsages.filter(u =>
+                !(u.file === symbol.file && (u.line === symbol.startLine || u.line === symbol.nameLine))
+            );
+
+            // For exported symbols in --include-exported mode, also filter out export-site
+            // references (e.g., `module.exports = { helperC }` or `export { helperC }`).
+            // These are just re-statements of the export, not actual consumption.
+            if (isExported && options.includeExported) {
+                nonDefUsages = nonDefUsages.filter(u => {
+                    if (u.file !== symbol.file) return true; // cross-file usage always counts
+                    // Check if same-file usage is on an export line
+                    let content;
+                    try { content = index._readFile(u.file); } catch { return true; }
+                    if (!content) return true;
+                    const lines = content.split('\n');
+                    const line = lines[u.line - 1] || '';
+                    const trimmed = line.trim();
+                    // CJS: module.exports = { ... } or exports.name = ...
+                    if (trimmed.startsWith('module.exports') || /^exports\.\w+\s*=/.test(trimmed)) return false;
+                    // ESM: export { ... } or export default
+                    if (/^export\s*\{/.test(trimmed) || /^export\s+default\s/.test(trimmed)) return false;
+                    return true;
+                });
+            }
+
+            // Total includes all usage types (calls, references, callbacks, re-exports)
+            const totalUsages = nonDefUsages.length;
+
+            if (totalUsages === 0) {
+                // Collect decorators/annotations for hint display
+                // Python: symbol.decorators (e.g., ['app.route("/path")', 'login_required'])
+                // Java/Rust/Go: symbol.modifiers may contain annotations (e.g., 'bean', 'scheduled')
+                const decorators = symbol.decorators || [];
+                // For Java, extract annotation-like modifiers (javaKeywords defined above)
+                const annotations = lang === 'java'
+                    ? mods.filter(m => !javaKeywords.has(m))
+                    : [];
+
+                results.push({
+                    name: symbol.name,
+                    type: symbol.type,
+                    file: symbol.relativePath,
+                    startLine: symbol.startLine,
+                    endLine: symbol.endLine,
+                    isExported,
+                    usageCount: 0,
+                    ...(decorators.length > 0 && { decorators }),
+                    ...(annotations.length > 0 && { annotations })
+                });
+            }
+        }
+    }
+
+    // Sort by file then line
+    results.sort((a, b) => {
+        if (a.file !== b.file) return a.file.localeCompare(b.file);
+        return a.startLine - b.startLine;
+    });
+
+    // Attach exclusion counts as array properties (backwards-compatible)
+    results.excludedDecorated = excludedDecorated;
+    results.excludedExported = excludedExported;
+
+    return results;
+    } finally { index._endOp(); }
+}
+
+module.exports = { buildUsageIndex, deadcode };

package/core/discovery.js

@@ -254,7 +254,7 @@ function parseGlobPattern(pattern, root) {
  * Convert a glob pattern to a regular expression
  */
 function globToRegex(glob) {
-    let regex = glob.replace(/[.+^$[\]\\]/g, '\\$&');
+    let regex = glob.replace(/[.+^$[\]\\()|]/g, '\\$&');
 
     // Handle brace expansion: {js,ts} -> (js|ts)
     regex = regex.replace(/\{([^}]+)\}/g, (_, group) => {

package/core/execute.js

@@ -1,21 +1,20 @@
 /**
  * Shared Command Executor — single dispatch for CLI, MCP, and interactive mode.
  *
- * Handles: input validation, exclude normalization, test exclusion, index calls.
- * Does NOT handle: output formatting, expand caching, file I/O commands.
+ * Handles: input validation, exclude normalization, test exclusion, index calls,
+ * and code extraction (fn, class, lines).
  *
  * Each handler returns { ok: true, result } or { ok: false, error }.
- * Adapters handle formatting and surface-specific concerns.
+ * Adapters handle formatting, path security (MCP), and surface-specific concerns.
  */
 
 'use strict';
 
-const { addTestExclusions } = require('./shared');
-
-// Commands handled directly by adapters (not in HANDLERS below).
-// fn, class, lines need raw file content / line-range logic.
-// expand needs per-session cache state that differs by surface.
-const ADAPTER_ONLY_COMMANDS = new Set(['fn', 'class', 'lines', 'expand']);
+const fs = require('fs');
+const path = require('path');
+const { addTestExclusions, pickBestDefinition } = require('./shared');
+const { cleanHtmlScriptTags, detectLanguage } = require('./parser');
+const { renderExpandItem } = require('./expand-cache');
 
 // ============================================================================
 // HELPERS
@@ -75,6 +74,14 @@ function num(val, fallback) {
     return isNaN(n) ? fallback : n;
 }
 
+/** Read a file and extract lines for a symbol match, applying HTML cleanup. */
+function readAndExtract(match) {
+    const content = fs.readFileSync(match.file, 'utf-8');
+    const lines = content.split('\n');
+    const extracted = lines.slice(match.startLine - 1, match.endLine);
+    return cleanHtmlScriptTags(extracted, detectLanguage(match.file)).join('\n');
+}
+
 // ============================================================================
 // COMMAND HANDLERS
 // ============================================================================
@@ -96,6 +103,7 @@ const HANDLERS = {
             maxCallers: num(p.top, undefined),
             maxCallees: num(p.top, undefined),
         });
+        if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
         return { ok: true, result };
     },
 
@@ -119,6 +127,7 @@ const HANDLERS = {
             file: p.file,
             exclude: toExcludeArray(p.exclude),
         });
+        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
         return { ok: true, result };
     },
 
@@ -146,6 +155,7 @@ const HANDLERS = {
             includeMethods: p.includeMethods,
             includeUncertain: p.includeUncertain || false,
         });
+        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
         return { ok: true, result };
     },
 
@@ -153,6 +163,7 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         const result = index.example(p.name);
+        if (!result) return { ok: false, error: `No examples found for "${p.name}".` };
         return { ok: true, result };
     },
 
@@ -164,6 +175,7 @@ const HANDLERS = {
             top: num(p.top, undefined),
             all: p.all,
         });
+        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
         return { ok: true, result };
     },
 
@@ -240,6 +252,173 @@ const HANDLERS = {
         return { ok: true, result };
     },
 
+    // ── Extracting Code ─────────────────────────────────────────────────
+
+    fn: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+
+        const fnNames = p.name.includes(',')
+            ? p.name.split(',').map(n => n.trim()).filter(Boolean)
+            : [p.name];
+
+        const entries = [];
+        const notes = [];
+
+        for (const fnName of fnNames) {
+            const matches = index.find(fnName, { file: p.file, skipCounts: true })
+                .filter(m => m.type === 'function' || m.params !== undefined);
+
+            if (matches.length === 0) {
+                notes.push(`Function "${fnName}" not found.`);
+                continue;
+            }
+
+            if (matches.length > 1 && !p.file && p.all) {
+                for (const m of matches) {
+                    const code = readAndExtract(m);
+                    entries.push({ match: m, code });
+                }
+                continue;
+            }
+
+            const match = matches.length > 1 && !p.file
+                ? pickBestDefinition(matches)
+                : matches[0];
+
+            if (matches.length > 1 && !p.file) {
+                const others = matches.filter(m => m !== match)
+                    .map(m => `${m.relativePath}:${m.startLine}`).join(', ');
+                notes.push(`Found ${matches.length} definitions for "${fnName}". Showing ${match.relativePath}:${match.startLine}. Also in: ${others}. Use --file to disambiguate or --all to show all.`);
+            }
+
+            const code = readAndExtract(match);
+            entries.push({ match, code });
+        }
+
+        if (entries.length === 0 && notes.length > 0) {
+            return { ok: false, error: notes.join('\n') };
+        }
+        return { ok: true, result: { entries, notes } };
+    },
+
+    class: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+
+        const CLASS_TYPES = ['class', 'interface', 'type', 'enum', 'struct', 'trait'];
+        const matches = index.find(p.name, { file: p.file, skipCounts: true })
+            .filter(m => CLASS_TYPES.includes(m.type));
+
+        if (matches.length === 0) {
+            return { ok: false, error: `Class "${p.name}" not found.` };
+        }
+
+        const entries = [];
+        const notes = [];
+        const maxLines = num(p.maxLines, null);
+
+        if (p.maxLines != null && (maxLines === null || !Number.isInteger(maxLines) || maxLines < 1)) {
+            return { ok: false, error: '--max-lines must be a positive integer.' };
+        }
+
+        if (matches.length > 1 && !p.file && p.all) {
+            for (const m of matches) {
+                const code = readAndExtract(m);
+                const totalLines = m.endLine - m.startLine + 1;
+                entries.push({ match: m, code, totalLines, summaryMode: false, truncated: false });
+            }
+            return { ok: true, result: { entries, notes } };
+        }
+
+        const match = matches.length > 1 && !p.file
+            ? pickBestDefinition(matches)
+            : matches[0];
+
+        if (matches.length > 1 && !p.file) {
+            const others = matches.filter(m => m !== match)
+                .map(m => `${m.relativePath}:${m.startLine}`).join(', ');
+            notes.push(`Found ${matches.length} definitions for "${p.name}". Showing ${match.relativePath}:${match.startLine}. Also in: ${others}. Use --file to disambiguate or --all to show all.`);
+        }
+
+        const totalLines = match.endLine - match.startLine + 1;
+
+        // Large class summary mode (>200 lines, no maxLines)
+        if (totalLines > 200 && !maxLines) {
+            const methods = index.findMethodsForType(match.name);
+            entries.push({ match, code: null, methods, totalLines, summaryMode: true, truncated: false });
+            return { ok: true, result: { entries, notes } };
+        }
+
+        // Truncated mode (maxLines specified and class exceeds it)
+        if (maxLines && totalLines > maxLines) {
+            const content = fs.readFileSync(match.file, 'utf-8');
+            const fileLines = content.split('\n');
+            const truncated = fileLines.slice(match.startLine - 1, match.startLine - 1 + maxLines);
+            const code = cleanHtmlScriptTags(truncated, detectLanguage(match.file)).join('\n');
+            entries.push({ match, code, totalLines, summaryMode: false, truncated: true, maxLines });
+            return { ok: true, result: { entries, notes } };
+        }
+
+        // Full extraction
+        const code = readAndExtract(match);
+        entries.push({ match, code, totalLines, summaryMode: false, truncated: false });
+        return { ok: true, result: { entries, notes } };
+    },
+
+    lines: (index, p) => {
+        const err = requireFile(p.file);
+        if (err) return { ok: false, error: err };
+        if (!p.range || (typeof p.range === 'string' && !p.range.trim())) {
+            return { ok: false, error: 'Line range is required (e.g. "10-20" or "15").' };
+        }
+
+        const rangeStr = String(p.range).trim();
+        const rangeMatch = rangeStr.match(/^(\d+)(?:-(\d+))?$/);
+        if (!rangeMatch) {
+            return { ok: false, error: `Invalid line range: "${p.range}". Expected format: <start>-<end> or <line>.` };
+        }
+
+        const rawStart = parseInt(rangeMatch[1], 10);
+        const rawEnd = rangeMatch[2] !== undefined ? parseInt(rangeMatch[2], 10) : rawStart;
+        if (rawStart < 1 || rawEnd < 1) {
+            return { ok: false, error: 'Invalid line range: line numbers must be >= 1.' };
+        }
+
+        // Auto-swap reversed ranges
+        const startLine = Math.min(rawStart, rawEnd);
+        const endLine = Math.max(rawStart, rawEnd);
+
+        const filePath = index.findFile(p.file);
+        if (!filePath) {
+            return { ok: false, error: `File not found in project: ${p.file}` };
+        }
+
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const fileLines = content.split('\n');
+
+        if (startLine > fileLines.length) {
+            return { ok: false, error: `Line ${startLine} is out of bounds. File has ${fileLines.length} lines.` };
+        }
+
+        const actualEnd = Math.min(endLine, fileLines.length);
+        const extracted = [];
+        for (let i = startLine - 1; i < actualEnd; i++) {
+            extracted.push(fileLines[i]);
+        }
+
+        return {
+            ok: true,
+            result: {
+                filePath,
+                relativePath: path.relative(index.root, filePath),
+                lines: extracted,
+                startLine,
+                endLine: actualEnd,
+            },
+        };
+    },
+
     // ── File Dependencies ───────────────────────────────────────────────
 
     imports: (index, p) => {
@@ -347,6 +526,24 @@ const HANDLERS = {
         });
         return { ok: true, result };
     },
+
+    // ── Expand (context drill-down) ──────────────────────────────────────
+
+    expand: (index, p) => {
+        if (p.itemNum == null || isNaN(p.itemNum)) {
+            return { ok: false, error: 'Item number is required.' };
+        }
+        if (!p.match) {
+            if (p.itemCount > 0) {
+                const scopeHint = p.symbolName ? ` (from context for "${p.symbolName}")` : '';
+                return { ok: false, error: `Item ${p.itemNum} not found${scopeHint}. Available: 1-${p.itemCount}` };
+            }
+            return { ok: false, error: 'No expandable items. Run context first.' };
+        }
+        const rendered = renderExpandItem(p.match, index.root, { validateRoot: p.validateRoot || false });
+        if (!rendered.ok) return { ok: false, error: rendered.error };
+        return { ok: true, result: rendered };
+    },
 };
 
 // ============================================================================
@@ -373,4 +570,4 @@ function execute(index, command, params = {}) {
     }
 }
 
-module.exports = { execute, ADAPTER_ONLY_COMMANDS };
+module.exports = { execute };

package/core/expand-cache.js

@@ -47,7 +47,13 @@ class ExpandCache {
                     oldestKey = k;
                 }
             }
-            if (oldestKey) this.entries.delete(oldestKey);
+            if (oldestKey) {
+                this.entries.delete(oldestKey);
+                // Clean up lastKey if it pointed to the evicted entry
+                for (const [r, k] of this.lastKey) {
+                    if (k === oldestKey) { this.lastKey.delete(r); break; }
+                }
+            }
         }
 
         this.entries.set(key, { items, root, symbolName: name, usedAt: Date.now() });
@@ -68,25 +74,30 @@ class ExpandCache {
         const recent = recentKey ? this.entries.get(recentKey) : null;
 
         if (recent && recent.items) {
-            recent.usedAt = Date.now();
             const match = recent.items.find(i => i.num === itemNum);
             if (match) {
+                recent.usedAt = Date.now();
                 return { match, itemCount: recent.items.length, symbolName: recent.symbolName };
             }
         }
 
         // Fallback: scan all entries for this project
         let maxCount = recent?.items?.length || 0;
+        let foundEntry = null;
         for (const [, cached] of this.entries) {
             if (cached.root === root && cached.items) {
-                cached.usedAt = Date.now();
                 maxCount = Math.max(maxCount, cached.items.length);
                 const found = cached.items.find(i => i.num === itemNum);
-                if (found) {
-                    return { match: found, itemCount: maxCount, symbolName: cached.symbolName };
+                if (found && !foundEntry) {
+                    foundEntry = { match: found, cached };
                 }
             }
         }
+        if (foundEntry) {
+            // Only refresh the entry that actually contains the match
+            foundEntry.cached.usedAt = Date.now();
+            return { match: foundEntry.match, itemCount: maxCount, symbolName: foundEntry.cached.symbolName };
+        }
 
         return {
             match: null,