ucn 4.2.3 → 5.0.2

package/core/search.js

@@ -10,9 +10,17 @@
 const path = require('path');
 const { escapeRegExp, codeUnitCompare, inlineTestRanges, lineInRanges, classDispatchNames, CALLABLE_SYMBOL_KINDS } = require('./shared');
 const { isTestFile } = require('./discovery');
-const { detectLanguage, getParser, getLanguageModule, langTraits } = require('../languages');
-const { getCachedCalls, _nameBindingReaches } = require('./callers');
+const { detectLanguage, getParser, getLanguageAdapter, langTraits } = require('../languages');
+const { getCachedCalls } = require('./callers');
 const { extractImports } = require('./imports');
+const isSafeRegex = require('safe-regex2');
+const { RE2JS } = require('re2js');
+
+// Keep the established search-input contract for the canonical catastrophic
+// nested-single-atom family even though the RE2-compatible engine could run it
+// safely. Rejecting these patterns avoids silently changing behavior if an
+// advanced construct later forces the guarded JavaScript fallback.
+const NESTED_SINGLE_ATOM_REPEAT = /\((?:\?:)?(?:\\.|\[[^\]]*\]|[^\\()[\]{}|?+*])(?:[+*]|\{\d+(?:,\d*)?\})\)(?:[+*]|\{\d+(?:,\d*)?\})/;
 
 /**
  * Build a glob-style matcher: * matches any sequence, ? matches one char.
@@ -26,7 +34,11 @@ function buildGlobMatcher(pattern, caseSensitive) {
     return (name) => regex.test(name);
 }
 
-const STRUCTURAL_TYPES = new Set(['function', 'class', 'call', 'method', 'type']);
+const STRUCTURAL_TYPES = new Set([
+    'function', 'class', 'call', 'method', 'type', 'constructor',
+    'state', 'field', 'constant', 'macro', 'variable',
+    'interface', 'enum', 'struct', 'trait', 'record', 'namespace',
+]);
 
 /**
  * Substring match. Case-insensitive by default.
@@ -37,6 +49,61 @@ function matchesSubstring(text, pattern, caseSensitive) {
     return text.toLowerCase().includes(pattern.toLowerCase());
 }
 
+function literalNameRegex(name) {
+    return new RegExp(
+        `(?<![A-Za-z0-9_$])${escapeRegExp(name)}(?![A-Za-z0-9_$])`,
+    );
+}
+
+/**
+ * Complete the AST-classified usage inventory with literal-name lines that
+ * occur only in comments, strings, or docstrings. Do not reintroduce code
+ * references that the language adapter intentionally filtered (for example,
+ * a Rust enum variant that shares a struct's name).
+ * `usages` promises this observed-text complement unless codeOnly=true.
+ */
+function appendTextComplements(index, {
+    usagesList,
+    filePath,
+    fileEntry,
+    content,
+    lines,
+    name,
+    context,
+}) {
+    const represented = new Set(usagesList
+        .filter(usage => usage.file === filePath)
+        .map(usage => usage.line));
+    const pattern = literalNameRegex(name);
+    for (let idx = 0; idx < lines.length; idx++) {
+        const line = lines[idx];
+        const match = pattern.exec(line);
+        if (!match || represented.has(idx + 1)) continue;
+        const lineNum = idx + 1;
+        const commentOrString = index.isCommentOrStringAtPosition(
+            content, lineNum, match.index, filePath);
+        if (!commentOrString) continue;
+        const usage = {
+            file: filePath,
+            relativePath: fileEntry.relativePath,
+            line: lineNum,
+            content: line,
+            usageType: 'text',
+            textKind: 'comment-or-string',
+            isDefinition: false,
+        };
+        if (context > 0) {
+            usage.before = [];
+            usage.after = [];
+            for (let i = 1; i <= context; i++) {
+                if (idx - i >= 0) usage.before.unshift(lines[idx - i]);
+                if (idx + i < lines.length) usage.after.push(lines[idx + i]);
+            }
+        }
+        usagesList.push(usage);
+    }
+}
+
 /**
  * Find symbols by name with fuzzy/glob matching.
  *
@@ -116,9 +183,11 @@ function _applyFindFilters(index, matches, options) {
 
     // Filter by file pattern
     if (options.file) {
-        filtered = filtered.filter(m =>
-            m.relativePath && m.relativePath.includes(options.file)
-        );
+        const resolved = index.resolveFilePathForQuery(options.file);
+        filtered = typeof resolved === 'string'
+            ? filtered.filter(m => m.file === resolved)
+            : filtered.filter(m =>
+                m.relativePath && m.relativePath.includes(options.file));
     }
 
     // Apply semantic filters (--exclude, --in)
@@ -136,10 +205,40 @@ function _applyFindFilters(index, matches, options) {
     // Add per-symbol usage counts for disambiguation
     const withCounts = filtered.map(m => {
         const counts = index.countSymbolUsages(m);
+        // The fast count supplies cheap definition/import totals, but its
+        // name-only call bucket cannot distinguish json.dumps from a project
+        // dumps, or one class's save from another's. The public `find`
+        // activity count must use the same pinned caller adjudication as
+        // show/impact so command answers never contradict each other.
+        const callers = index.findCallers(m.name, {
+            targetDefinitions: [m],
+            includeTests: true,
+            collectAccount: true,
+        });
+        const confirmedCalls = callers.filter(caller =>
+            caller.tier !== 'unverified').length;
+        const unverifiedCalls = callers.unverifiedEntries?.length || 0;
+        const otherTargetCalls = callers.accountRaw?.excludedEntries?.length || 0;
+        // `find` is an inventory/orientation command. Its activity headline
+        // must not turn engine abstention into "0 calls", but it also must not
+        // attribute calls adjudicated as a different same-name target to this
+        // pinned definition. Report confirmed + visible unverified candidates;
+        // retain excluded same-name calls as an explicit boundary only.
+        const targetCallCandidates = confirmedCalls + unverifiedCalls;
+        const exactCounts = {
+            ...counts,
+            calls: targetCallCandidates,
+            confirmedCalls,
+            unverifiedCalls,
+            otherTargetCalls,
+            total: targetCallCandidates + counts.definitions + counts.imports +
+                (counts.references || 0),
+            countKind: 'target-call-candidates-with-tier-breakdown-excludes-references',
+        };
         return {
             ...m,
-            usageCount: counts.total,
-            usageCounts: counts  // { total, calls, definitions, imports, references }
+            usageCount: exactCounts.total,
+            usageCounts: exactCounts,
         };
     });
 
@@ -162,7 +261,8 @@ function usages(index, name, options = {}) {
     try {
     const usagesList = [];
 
-    // Resolve file pattern for --file filter
+    // Resolve file pattern for --file scan filter. A stable-handle caller can
+    // separately pin definitions with definitionFile while scanning globally.
     const fileFilterRaw = options.file ? index.resolveFilePathForQuery(options.file) : null;
     // resolveFilePathForQuery may return error objects for ambiguous/not-found — fall back to substring matching
     const fileFilter = typeof fileFilterRaw === 'string' ? fileFilterRaw : null;
@@ -173,7 +273,12 @@ function usages(index, name, options = {}) {
     if (options.className) {
         allDefinitions = allDefinitions.filter(d => d.className === options.className);
     }
-    if (fileFilter) {
+    const definitionFileRaw = options.definitionFile
+        ? index.resolveFilePathForQuery(options.definitionFile) : null;
+    const definitionFile = typeof definitionFileRaw === 'string' ? definitionFileRaw : null;
+    if (definitionFile) {
+        allDefinitions = allDefinitions.filter(d => d.file === definitionFile);
+    } else if (fileFilter) {
         allDefinitions = allDefinitions.filter(d => d.file === fileFilter);
     } else if (fileSubstring) {
         allDefinitions = allDefinitions.filter(d => d.relativePath && d.relativePath.includes(fileSubstring));
@@ -181,14 +286,13 @@ function usages(index, name, options = {}) {
     const definitions = options.exclude || options.in
         ? allDefinitions.filter(d => index.matchesFilters(d.relativePath, options))
         : allDefinitions;
-    const targetFiles = new Set(allDefinitions.map(d => d.file).filter(Boolean));
-
     for (const def of definitions) {
         usagesList.push({
             ...def,
+            usageType: 'definition',
             isDefinition: true,
-            line: def.startLine,
-            content: index.getLineContent(def.file, def.startLine),
+            line: def.nameLine || def.startLine,
+            content: index.getLineContent(def.file, def.nameLine || def.startLine),
             signature: index.formatSignature(def)
         });
     }
@@ -217,148 +321,17 @@ function usages(index, name, options = {}) {
             // Try AST-based detection first (with per-operation cache)
             const astUsages = index._getCachedUsages(filePath, name);
             if (astUsages !== null) {
-                // Pre-compute: does any imported project file define this name?
-                // Used to filter namespace member expressions (e.g., DropdownMenuPrimitive.Separator)
-                // while keeping module access patterns (e.g., output.formatExample())
-                const _importedHasDef = new Map();
-                const importedFileHasDef = (receiver) => {
-                    const cacheKey = receiver || '';
-                    if (_importedHasDef.has(cacheKey)) return _importedHasDef.get(cacheKey);
-                    const importedFiles = index.importGraph.get(filePath);
-                    let found = false;
-                    if (importedFiles) for (const imp of importedFiles) {
-                        const impEntry = index.files.get(imp);
-                        if (impEntry?.symbols?.some(s => s.name === name)) {
-                            found = true;
-                            break;
-                        }
-                        // A module namespace may expose the target through a
-                        // re-export chain (`import httpx; httpx.URL(...)`,
-                        // where httpx/__init__.py re-exports URL).  Direct-file
-                        // symbol checks silently dropped these compiler-true
-                        // usages.  Reuse the caller engine's conservative
-                        // name-ownership chase: yes confirms; unknown stays
-                        // visible in this raw-usage inventory; only a proven
-                        // no is filtering evidence.
-                        if (targetFiles.size > 0 &&
-                            _nameBindingReaches(index, imp, name, targetFiles) !== 'no') {
-                            found = true;
-                            break;
-                        }
-                    }
-
-                    // Named namespace surfaces need one more ownership axis:
-                    // `import { util } from './core'; util.helper()` where
-                    // core exports `* as util` from the helper's module. The
-                    // imported file does not itself define `helper`; entering
-                    // the namespace is what reaches the owning file.
-                    if (!found && receiver && targetFiles.size > 0) {
-                        const queue = [];
-                        let unknown = false;
-                        for (const b of (fileEntry.importBindings || [])) {
-                            if (b.name !== receiver && b.alias !== receiver) continue;
-                            const rel = fileEntry.moduleResolved?.[b.module];
-                            if (rel) queue.push({ file: path.join(index.root, rel), attr: b.name, depth: 0 });
-                            else if (String(b.module).startsWith('.')) unknown = true;
-                        }
-                        const seen = new Set();
-                        while (!found && queue.length > 0) {
-                            const cur = queue.shift();
-                            const state = `${cur.file}\0${cur.attr || ''}`;
-                            if (seen.has(state)) continue;
-                            seen.add(state);
-                            if (targetFiles.has(cur.file)) { found = true; break; }
-                            if (cur.depth >= 4) { unknown = true; continue; }
-                            const fe = index.files.get(cur.file);
-                            if (!fe) { unknown = true; continue; }
-                            for (const e of (fe.exportDetails || [])) {
-                                if (!e.source) continue;
-                                let nextAttr;
-                                if (e.type === 're-export-all' && e.alias === cur.attr) {
-                                    nextAttr = null; // entered the namespace
-                                } else if (e.type === 're-export-all' && !e.alias && cur.attr) {
-                                    nextAttr = cur.attr; // transparent barrel
-                                } else if (e.type === 're-export' &&
-                                    (e.alias || e.name) === cur.attr) {
-                                    nextAttr = e.name;
-                                } else {
-                                    continue;
-                                }
-                                const rel = fe.moduleResolved?.[e.source];
-                                if (rel) {
-                                    queue.push({
-                                        file: path.join(index.root, rel),
-                                        attr: nextAttr,
-                                        depth: cur.depth + 1,
-                                    });
-                                } else if (String(e.source).startsWith('.')) {
-                                    unknown = true;
-                                }
-                            }
-                            // Dynamic/CJS export objects cannot prove that a
-                            // namespace property is unrelated. Keep the usage
-                            // visible rather than manufacturing a false miss.
-                            if ((fe.exportDetails || []).some(e =>
-                                e.type === 'exports' || e.type === 'module.exports') ||
-                                (fe.moduleAssignedNames || []).includes(cur.attr)) {
-                                unknown = true;
-                            }
-                        }
-                        if (!found && unknown) found = true;
-                    }
-                    _importedHasDef.set(cacheKey, found);
-                    return found;
-                };
-
-                // A qualified usage whose RECEIVER is a symbol defined in this
-                // file is never external-package noise — `Geometry.area(3, 4)`
-                // in the file declaring namespace Geometry was dropped by the
-                // receiver filter while find's usageCounts counted it (fix
-                // #241). Keyed on the receiver, not the target name: a file
-                // defining its own `Separator` while using external
-                // `Ns.Separator` must still filter the latter (bug #23).
-                const receiverDefinedHere = (recv) =>
-                    !!recv && fileEntry.symbols && fileEntry.symbols.some(s => s.name === recv);
-
                 for (const u of astUsages) {
                     // Skip if this is a definition line (already added above)
-                    if (definitions.some(d => d.file === filePath && d.startLine === u.line)) {
+                    if (definitions.some(d => d.file === filePath &&
+                        (d.startLine === u.line || d.nameLine === u.line))) {
                         continue;
                     }
 
-                    // Rust `Type::method` method values carry their owner from
-                    // the AST. Keep them only for a matching method owner;
-                    // class/struct queries must not absorb `Enum::Variant`
-                    // references that happen to share the target type name.
-                    // Owners are CALLABLE member defs only — an enum variant
-                    // member also carries className, and counting it as an
-                    // owner would let `Boundary::Grid` survive a struct-Grid
-                    // query via its own enum. Lowercase receivers are module
-                    // paths (`render::draw` reaches the free fn); `Self` is
-                    // the enclosing type — both keep escape-hatch visibility.
-                    if (fileEntry.language === 'rust' && u.scopedReference &&
-                        u.receiver && /^[A-Z]/.test(u.receiver) && u.receiver !== 'Self') {
-                        const methodOwners = new Set(definitions
-                            .filter(d => d.className && CALLABLE_SYMBOL_KINDS.has(d.type))
-                            .map(d => d.className));
-                        if (!methodOwners.has(u.receiver)) continue;
-                    }
-
-                    // Filter member expressions with unrelated receivers in JS/TS/Python.
-                    // Keeps: standalone usages, self/this/cls/super, method calls on known types,
-                    //        qualified usages whose receiver this file defines,
-                    //        and module access (output.fn()) when the imported file defines the name.
-                    // Filters: namespace access to external packages (DropdownMenuPrimitive.Separator).
-                    if (u.receiver && !['self', 'this', 'cls', 'super'].includes(u.receiver) &&
-                        fileEntry.language !== 'go' && fileEntry.language !== 'java' && fileEntry.language !== 'rust') {
-                        const hasMethodDef = definitions.some(d => d.className);
-                        const sameFileMember = definitions.some(d =>
-                            d.file === filePath && d.memberAssigned);
-                        if (!hasMethodDef && !sameFileMember && !receiverDefinedHere(u.receiver) &&
-                            !importedFileHasDef(u.receiver)) {
-                            continue;
-                        }
-                    }
+                    // `usages` is the literal-name escape hatch. Unlike callers,
+                    // it must never discard an AST occurrence merely because
+                    // ownership or receiver dispatch cannot be proven. Consumers
+                    // can use usageType/receiver plus `show` for semantic tiers.
 
                     const lineContent = lines[u.line - 1] || '';
 
@@ -400,6 +373,17 @@ function usages(index, name, options = {}) {
 
                     usagesList.push(usage);
                 }
+                if (!options.codeOnly) {
+                    appendTextComplements(index, {
+                        usagesList,
+                        filePath,
+                        fileEntry,
+                        content,
+                        lines,
+                        name,
+                        context: options.context || 0,
+                    });
+                }
                 continue; // Skip to next file
             }
 
@@ -419,13 +403,13 @@ function usages(index, name, options = {}) {
                         return;
                     }
 
-                    // Skip if the match is inside a string literal
-                    if (index.isInsideStringAST(content, lineNum, line, name, filePath)) {
-                        return;
-                    }
-
                     // Classify usage type (AST-based, defaults to 'reference' for unsupported languages)
-                    const usageType = index.classifyUsageAST(content, lineNum, name, filePath) ?? 'reference';
+                    const inText = index.isInsideStringAST(
+                        content, lineNum, line, name, filePath);
+                    const usageType = !options.codeOnly && inText
+                        ? 'text'
+                        : (index.classifyUsageAST(
+                            content, lineNum, name, filePath) ?? 'reference');
 
                     // BUG-4: enrich call usages with enclosing-function info.
                     let callerSym = null;
@@ -440,6 +424,9 @@ function usages(index, name, options = {}) {
                         content: line,
                         usageType,
                         isDefinition: false,
+                        ...(usageType === 'text' && {
+                            textKind: 'comment-or-string',
+                        }),
                         ...(callerSym && {
                             callerName: callerSym.name,
                             callerStartLine: callerSym.startLine
@@ -497,16 +484,39 @@ function search(index, term, options = {}) {
     let filesSkipped = 0;
     let filesFilteredByFlag = 0;
     const regexFlags = options.caseSensitive ? 'g' : 'gi';
-    const useRegex = options.regex !== false; // Default: regex ON
+    const useRegex = options.regex === true; // Safe default: literal text
     let regex;
-    let regexFallback = false;
+    let linearRegex = null;
     if (useRegex) {
+        if (NESTED_SINGLE_ATOM_REPEAT.test(term)) {
+            throw new Error(
+                `Unsafe regular expression "${term}": nested repetition is not accepted. Simplify it or use ripgrep.`,
+            );
+        }
         try {
             regex = new RegExp(term, regexFlags);
         } catch (e) {
-            // Invalid regex — fall back to plain text
-            regex = new RegExp(escapeRegExp(term), regexFlags);
-            regexFallback = e.message;
+            throw new Error(
+                `Invalid regular expression "${term}": ${e.message}`,
+                { cause: e },
+            );
+        }
+        // Prefer the RE2-compatible DFA engine: ordinary code-search patterns
+        // stay linear-time even for ambiguous repetition such as `(a|a)*`.
+        // Advanced JavaScript-only constructs (backreferences/lookarounds)
+        // retain V8 compatibility only when the conservative fallback guard
+        // can establish that their repetition shape is safe.
+        try {
+            let re2Flags = options.caseSensitive ? 0 : RE2JS.CASE_INSENSITIVE;
+            if (/\(\?<([=!])/.test(term)) re2Flags |= RE2JS.LOOKBEHINDS;
+            linearRegex = RE2JS.compile(term, re2Flags);
+        } catch (re2Error) {
+            if (!isSafeRegex(term)) {
+                throw new Error(
+                    `Unsafe regular expression "${term}": this JavaScript-only pattern cannot run in UCN's linear-time engine and its repetition shape may backtrack catastrophically. Simplify it or use ripgrep.`,
+                    { cause: re2Error },
+                );
+            }
         }
     } else {
         regex = new RegExp(escapeRegExp(term), regexFlags);
@@ -541,7 +551,12 @@ function search(index, term, options = {}) {
                     try {
                         const parser = getParser(language);
                         const { findMatchesWithASTFilter } = require('../languages/utils');
-                        const astMatches = findMatchesWithASTFilter(content, term, parser, { codeOnly: true, regex: useRegex });
+                        const astMatches = findMatchesWithASTFilter(content, term, parser, {
+                            codeOnly: true,
+                            regex: useRegex,
+                            caseSensitive: options.caseSensitive,
+                            compiledRegex: linearRegex,
+                        });
 
                         for (const m of astMatches) {
                             const match = {
@@ -580,8 +595,9 @@ function search(index, term, options = {}) {
 
             // Fallback to regex-based search (non-codeOnly or unsupported language)
             lines.forEach((line, idx) => {
-                regex.lastIndex = 0; // Reset regex state
-                if (regex.test(line)) {
+                regex.lastIndex = 0; // Reset V8 fallback state
+                if ((linearRegex && linearRegex.test(line)) ||
+                    (!linearRegex && regex.test(line))) {
                     const lineNum = idx + 1;
                     // Skip if codeOnly and line is comment/string
                     if (options.codeOnly && index.isCommentOrStringAtPosition(content, lineNum, 0, filePath)) {
@@ -623,6 +639,7 @@ function search(index, term, options = {}) {
 
     // Apply top limit (limits total matches across all files)
     const totalMatches = results.reduce((sum, r) => sum + r.matches.length, 0);
+    const totalMatchedFiles = results.length;
     let truncatedMatches = 0;
     if (options.top && options.top > 0 && totalMatches > options.top) {
         let remaining = options.top;
@@ -642,7 +659,19 @@ function search(index, term, options = {}) {
         results.push(...truncated);
     }
 
-    results.meta = { filesScanned, filesSkipped, filesFilteredByFlag, totalFiles: index.files.size, regexFallback, totalMatches, truncatedMatches, projectLanguage: index._getPredominantLanguage() };
+    results.meta = {
+        filesScanned,
+        filesSkipped,
+        filesFilteredByFlag,
+        totalFiles: index.files.size,
+        mode: useRegex ? 'regex' : 'literal',
+        totalMatches,
+        totalMatchedFiles,
+        shownMatches: totalMatches - truncatedMatches,
+        truncatedMatches,
+        limit: options.top || null,
+        projectLanguage: index._getPredominantLanguage(),
+    };
     return results;
     } finally { index._endOp(); }
 }
@@ -730,6 +759,9 @@ function structuralSearch(index, options = {}) {
                 const calls = getCachedCalls(index, filePath);
                 if (!calls) continue;
                 for (const call of calls) {
+                    // Potential callback/value references are useful to the
+                    // caller engine, but they are not invocations.
+                    if (call.isFunctionReference || call.isTypeReference) continue;
                     if (nameMatcher && !nameMatcher(call.name)) continue;
                     // Field-hop receivers (`tm.service.Save()`) carry
                     // receiverRoot/receiverField instead of receiver —
@@ -764,6 +796,8 @@ function structuralSearch(index, options = {}) {
             const classTypes = new Set(['class', 'struct', 'interface', 'impl', 'trait', 'record', 'enum']);
             const typeTypes = new Set(['type', 'enum', 'interface', 'trait', 'record', 'namespace']);
             const methodTypes = new Set(['method', 'constructor']);
+            const variableTypes = new Set(['state', 'field', 'constant', 'macro']);
+            const groupedTypes = new Set(['function', 'class', 'method', 'type', 'variable']);
 
             for (const [symbolName, definitions] of index.symbols) {
                 if (nameMatcher && !nameMatcher(symbolName)) continue;
@@ -774,6 +808,8 @@ function structuralSearch(index, options = {}) {
                     if (type === 'class' && !classTypes.has(def.type)) continue;
                     if (type === 'method' && !methodTypes.has(def.type) && !def.isMethod) continue;
                     if (type === 'type' && !typeTypes.has(def.type)) continue;
+                    if (type === 'variable' && !variableTypes.has(def.type)) continue;
+                    if (type && !groupedTypes.has(type) && def.type !== type) continue;
 
                     // File filters
                     const fileEntry = index.files.get(def.file);
@@ -811,16 +847,17 @@ function structuralSearch(index, options = {}) {
 
                     // Exported filter
                     if (exported) {
-                        const mods = def.modifiers || [];
-                        const isExp = (fileEntry && fileEntry.exports.includes(symbolName)) ||
-                            mods.includes('export') || mods.includes('public') ||
-                            mods.some(m => m.startsWith('pub')) ||
-                            (fileEntry && langTraits(fileEntry.language)?.exportVisibility === 'capitalization' && /^[A-Z]/.test(symbolName));
+                        const { symbolIsExported } = require('./graph');
+                        const isExp = fileEntry && symbolIsExported(
+                            def, fileEntry, new Set(fileEntry.exports || []));
                         if (!isExp) continue;
                     }
 
                     // Unused filter (expensive — last check)
                     if (unused) {
+                        // This query has call-edge semantics. Reference-live
+                        // types/classes/fields are handled by `deadcode`.
+                        if (!functionTypes.has(def.type)) continue;
                         // Named function expressions are consumed by their
                         // expression position — never "unused" (the deadcode
                         // twin of the bodyScopedName audit skip).
@@ -854,7 +891,7 @@ function structuralSearch(index, options = {}) {
                         // #234, campaign G2 ×4 languages: Go main/init, Java
                         // main, Rust main/#[test] all listed — the deadcode
                         // protection, applied here).
-                        const langModule = fileEntry && getLanguageModule(fileEntry.language);
+                        const langModule = fileEntry && getLanguageAdapter(fileEntry.language);
                         if (langModule?.isEntryPoint?.(def)) continue;
                         // A bare decorator application (@with_logging) invokes
                         // the decorator at import time but is recorded as a
@@ -917,6 +954,10 @@ function structuralSearch(index, options = {}) {
                 }).filter(([, v]) => v !== undefined && v !== null)),
                 totalMatched: total,
                 shown: results.length,
+                ...(unused && {
+                    unusedScope: 'callable-symbols-only',
+                    unusedSafety: 'candidate-only; use deadcode before deletion',
+                }),
             }
         };
     } finally { index._endOp(); }
@@ -1269,6 +1310,50 @@ function tests(index, nameOrFile, options = {}) {
         if (targetRels.size === 0) targetRels = null;
     }
 
+    // File targets answer "which tests exercise code from this file?", not
+    // "which tests mention the file's basename?". The old basename scan turned
+    // `tests cli/index.js` into a project-wide search for the symbol `index`,
+    // producing huge, unrelated answers. Pin every callable declared by the
+    // resolved file and let the caller engine prove test call sites instead.
+    // Import-linked tests are still handled below so class/type-only use and
+    // module-level coverage remain visible.
+    const fileTargetCallerSites = new Map(); // absolute test file → tiered sites
+    if (isFilePath && targetRels) {
+        const testFileInfo = new Map(testFiles.map(info => [info.path, info]));
+        const fileTargetDefs = [];
+        for (const [, fe] of index.files) {
+            if (!targetRels.has(fe.relativePath)) continue;
+            for (const symbol of fe.symbols || []) {
+                if (CALLABLE_SYMBOL_KINDS.has(symbol.type)) fileTargetDefs.push(symbol);
+            }
+        }
+        for (const def of fileTargetDefs) {
+            const raw = index.findCallers(def.name, {
+                targetDefinitions: [def],
+                collectAccount: true,
+            });
+            const globallyUnique = index.find(def.name, { exact: true }).length === 1;
+            const sites = [
+                ...raw.map(site => ({ ...site, _testEvidenceTier: 'confirmed' })),
+                ...(globallyUnique ? (raw.unverifiedEntries || []).map(site => ({
+                    ...site,
+                    _testEvidenceTier: 'unverified',
+                })) : []),
+            ];
+            for (const site of sites) {
+                const info = testFileInfo.get(site.file);
+                if (!info) continue;
+                if (info.testRanges && !lineInRanges(site.line, info.testRanges)) continue;
+                let rows = fileTargetCallerSites.get(site.file);
+                if (!rows) {
+                    rows = [];
+                    fileTargetCallerSites.set(site.file, rows);
+                }
+                rows.push(site);
+            }
+        }
+    }
+
     const className = options.className || null;
     // className scoping accepts the class plus its non-overriding
     // descendants — a subclass instance without its own override dispatches
@@ -1301,14 +1386,28 @@ function tests(index, nameOrFile, options = {}) {
                     if (hits.length > 0) linkedRecords = hits;
                 }
             }
+            const provenFileSites = fileTargetCallerSites.get(testPath) || [];
 
             // Fast pre-check: skip if searchTerm doesn't appear in file
-            if (!content.includes(searchTerm) && !linkedRecords) continue;
+            if (!isFilePath && !content.includes(searchTerm) && !linkedRecords) continue;
+            if (isFilePath && !linkedRecords && provenFileSites.length === 0) continue;
             const sourceFileLinked = !sourceFileFilter || sourceFileFilter.has(testPath);
+            // A class-qualified query can still identify a possible test link
+            // in source layouts that have no modeled module edge (notably
+            // Rust macro/test fixtures). Keep it visibly unverified when the
+            // test contains an AST reference to the exact class name; never
+            // promote that hint to confirmed source ownership.
+            const classIdentityHint = !sourceFileLinked && className &&
+                (index._getCachedUsages(testPath, className) || []).some(u =>
+                    u.usageType !== 'definition' && u.usageType !== 'import');
 
             // AST-based usage detection
-            const astUsages = index._getCachedUsages(testPath, searchTerm) || [];
-            if (astUsages.length === 0 && !linkedRecords) continue;
+            // A file path is not a symbol. Its basename must never be sent
+            // through the usage index (e.g. `index.js` → every local `index`).
+            const astUsages = isFilePath
+                ? []
+                : (index._getCachedUsages(testPath, searchTerm) || []);
+            if (astUsages.length === 0 && !linkedRecords && provenFileSites.length === 0) continue;
             // Compiler attributes can invoke generated builder methods across
             // workspace/facade boundaries that the source import graph cannot
             // represent (`#[arg(value_delimiter = ',')]`). Keep these explicit
@@ -1316,7 +1415,7 @@ function tests(index, nameOrFile, options = {}) {
             // test. Ordinary calls/references still require source ownership.
             const hasAttributeReference = astUsages.some(u => u.inAttribute &&
                 (!testRanges || lineInRanges(u.line, testRanges)));
-            if (!sourceFileLinked && !hasAttributeReference) continue;
+            if (!sourceFileLinked && !hasAttributeReference && !classIdentityHint) continue;
             // className scoping normally requires the class or a dispatching
             // descendant in the file. Generated attribute references are the
             // conservative exception: they carry an explicit unverified tier.
@@ -1360,7 +1459,7 @@ function tests(index, nameOrFile, options = {}) {
 
             for (const usage of astUsages) {
                 if (usage.usageType === 'definition') continue; // not relevant in test files
-                if (!sourceFileLinked && !usage.inAttribute) continue;
+                if (!sourceFileLinked && !usage.inAttribute && !classIdentityHint) continue;
                 // Inline-test-promoted file: only lines inside the test
                 // ranges are test code (fix #244).
                 if (testRanges && !lineInRanges(usage.line, testRanges)) continue;
@@ -1378,7 +1477,7 @@ function tests(index, nameOrFile, options = {}) {
                 if (usage.usageType === 'import') {
                     matchType = 'import';
                 } else if (usage.usageType === 'call') {
-                    matchType = 'call';
+                    matchType = classIdentityHint ? 'unverified-call' : 'call';
                 } else {
                     // 'reference' — check if inside string literal
                     matchType = strPattern.test(lineContent) ? 'string-ref' :
@@ -1386,7 +1485,7 @@ function tests(index, nameOrFile, options = {}) {
                 }
 
                 // className scoping for calls: check receiver
-                if (className && matchType === 'call') {
+                if (className && (matchType === 'call' || matchType === 'unverified-call')) {
                     if (!_receiverMatchesClass(usage, dispatchNames, instanceTypeMap, lineContent, searchTerm)) continue;
                 }
 
@@ -1416,7 +1515,11 @@ function tests(index, nameOrFile, options = {}) {
                 matches.push({
                     line: usage.line,
                     content: lineContent.trim(),
-                    matchType
+                    matchType,
+                    ...(matchType === 'unverified-call' && {
+                        evidenceTier: 'unverified',
+                        reason: 'class-reference-without-source-ownership',
+                    }),
                 });
             }
 
@@ -1455,10 +1558,29 @@ function tests(index, nameOrFile, options = {}) {
                 }
             }
 
+            // Exact-target caller evidence for callable declarations in a file
+            // target. This covers same-package tests (notably Go) that do not
+            // import the implementation file, without falling back to a
+            // basename text heuristic.
+            for (const site of provenFileSites) {
+                const matchType = site._testEvidenceTier === 'confirmed'
+                    ? 'call'
+                    : 'unverified-call';
+                if (matches.some(m => m.line === site.line && m.matchType === matchType)) continue;
+                matches.push({
+                    line: site.line,
+                    content: (site.content || index.getLineContent(testPath, site.line) || '').trim(),
+                    matchType,
+                    evidenceTier: site._testEvidenceTier,
+                    ...(site.resolution && { resolution: site.resolution }),
+                    ...(site.reason && { reason: site.reason }),
+                });
+            }
+
             // Language-aware test-case detection. Under a local same-name
             // shadow the term on a test line is the file's OWN helper —
             // only anchor test cases to matches that survived the shadow.
-            if (sourceFileLinked &&
+            if (!isFilePath && sourceFileLinked &&
                 (!localShadow || matches.some(m => m.matchType !== 'import'))) {
                 _addTestCaseMatches(index, testPath, entry, searchTerm, className, instanceTypeMap, matches);
             }
@@ -1477,7 +1599,7 @@ function tests(index, nameOrFile, options = {}) {
             }
 
             const filtered = options.callsOnly
-                ? finalMatches.filter(m => m.matchType === 'call' || m.matchType === 'test-case')
+                ? finalMatches.filter(m => ['call', 'unverified-call', 'test-case'].includes(m.matchType))
                 : finalMatches;
             if (filtered.length > 0) {
                 results.push({
@@ -1542,7 +1664,8 @@ function tests(index, nameOrFile, options = {}) {
             const localSameName = (info.entry.symbols || []).some(s => s.name === searchTerm);
             const importsTargetName = (info.entry.importBindings || []).some(b => b.name === searchTerm);
             const explicitlyScopedToLocal = !!options.file && targetDefs.some(d => d.file === site.file);
-            if (localSameName && !importsTargetName && !explicitlyScopedToLocal && !site.receiver) continue;
+            if (localSameName && !importsTargetName && !explicitlyScopedToLocal &&
+                !site.receiver && !site.isMethod) continue;
 
             let fileResult = results.find(r => r.file === info.entry.relativePath);
             if (!fileResult) {
@@ -1639,7 +1762,16 @@ function _buildSourceFileImporters(index, defs) {
             // If so, add it to the queue so its importers are also discovered.
             if (!visited.has(imp)) {
                 const fe = index.files.get(imp);
-                if (fe && _fileReExportsSymbol(index, fe, symbolName, current)) {
+                const currentEntry = index.files.get(current);
+                // C/C++ #include is textual inclusion, not a module import.
+                // Names flow through every transitive include edge regardless
+                // of extension (`common.h` may intentionally include a .c
+                // implementation), so no re-export declaration is required.
+                const cFamilyIncludeChain =
+                    ['c', 'cpp'].includes(currentEntry?.language) &&
+                    ['c', 'cpp'].includes(fe?.language);
+                if (fe && (cFamilyIncludeChain ||
+                    _fileReExportsSymbol(index, fe, symbolName, current))) {
                     visited.add(imp);
                     queue.push(imp);
                 }
@@ -1921,7 +2053,7 @@ function _addTestCaseMatches(index, filePath, fileEntry, searchTerm, className,
         // Go/Python/Java/Rust: check if any AST usage falls within a test function's range
         if (!fileEntry.symbols) return;
         try {
-            const langModule = getLanguageModule(lang);
+            const langModule = getLanguageAdapter(lang);
             if (!langModule) return;
             // Prefer kinded predicate so fn main() and fn init() aren't classified
             // as test cases (BUG-CX). Fall back to isEntryPoint for compat.