ucn 3.8.18 → 3.8.20

package/core/search.js

@@ -10,7 +10,8 @@
 const path = require('path');
 const { escapeRegExp } = require('./shared');
 const { isTestFile } = require('./discovery');
-const { detectLanguage, getParser, langTraits } = require('../languages');
+const { detectLanguage, getParser, getLanguageModule, langTraits } = require('../languages');
+const { getCachedCalls } = require('./callers');
 
 /**
  * Build a glob-style matcher: * matches any sequence, ? matches one char.
@@ -799,11 +800,15 @@ function typedef(index, name, options = {}) {
 }
 
 /**
- * Find tests for a function or file
+ * Find tests for a function or file (AST-based).
+ *
+ * Uses _getCachedUsages() for AST-based detection of imports, calls, and references.
+ * className scoping uses the AST receiver field from findUsagesInCode() instead of
+ * regex heuristics. Test-case detection is language-aware via isEntryPoint().
  *
  * @param {object} index - ProjectIndex instance
  * @param {string} nameOrFile - Function name or file path
- * @param {object} options - { callsOnly }
+ * @param {object} options - { callsOnly, className, file, exclude }
  * @returns {Array} Test files and matches
  */
 function tests(index, nameOrFile, options = {}) {
@@ -817,6 +822,19 @@ function tests(index, nameOrFile, options = {}) {
         nameOrFile.endsWith('.py') || nameOrFile.endsWith('.go') ||
         nameOrFile.endsWith('.java') || nameOrFile.endsWith('.rs');
 
+    // Resolve --file scoping: find the source file that defines this symbol
+    // and only include test files that import from it (directly or via re-exports).
+    let sourceFileFilter = null;
+    if (options.file && !isFilePath) {
+        const defs = index.find(nameOrFile, { exact: true, file: options.file, className: options.className });
+        if (defs.length > 0) {
+            sourceFileFilter = _buildSourceFileImporters(index, defs);
+        }
+        // If no defs found, sourceFileFilter stays null → no file scoping applied.
+        // The execute handler validates before calling, so this path means
+        // the file matched but no exact symbol — fall through gracefully.
+    }
+
     // Find all test files
     const testFiles = [];
     for (const [filePath, fileEntry] of index.files) {
@@ -824,7 +842,6 @@ function tests(index, nameOrFile, options = {}) {
             testFiles.push({ path: filePath, entry: fileEntry });
         } else if (fileEntry.language === 'rust') {
             // Rust idiomatically puts tests in #[cfg(test)] modules inside source files.
-            // Check if file has any symbols with 'test' modifier (#[test] attribute).
             const hasInlineTests = fileEntry.symbols?.some(s =>
                 s.modifiers?.includes('test')
             );
@@ -838,155 +855,109 @@ function tests(index, nameOrFile, options = {}) {
         ? path.basename(nameOrFile, path.extname(nameOrFile))
         : nameOrFile;
 
-    // Note: no 'g' flag - we only need to test for presence per line
-    // The 'i' flag is kept for case-insensitive matching
-    const regex = new RegExp('\\b' + escapeRegExp(searchTerm) + '\\b', 'i');
-    // Pre-compile patterns used inside per-line loop
-    const callPattern = new RegExp(escapeRegExp(searchTerm) + '\\s*\\(');
+    const className = options.className || null;
+    // Pre-compile string-ref pattern (only regex left — used on single AST-identified lines)
     const strPattern = new RegExp("['\"`]" + escapeRegExp(searchTerm) + "['\"`]");
 
-    // When className is provided, build patterns for match-level scoping.
-    const classNameFilter = options.className
-        ? new RegExp('\\b' + escapeRegExp(options.className) + '\\b')
-        : null;
-    // Match-level class scoping: for calls, check receiver or nearby context;
-    // e.g., "new ClassName().method()" or "instance.method()" where instance is typed.
-    const classReceiverPattern = options.className
-        ? new RegExp('\\b' + escapeRegExp(options.className) + '\\s*[\\.\\(]')
-        : null;
+    // --exclude filtering
+    const excludeArr = options.exclude ? (Array.isArray(options.exclude) ? options.exclude : [options.exclude]) : [];
 
     for (const { path: testPath, entry } of testFiles) {
         try {
+            // Apply exclude filters
+            if (excludeArr.length > 0 && !index.matchesFilters(entry.relativePath, { exclude: excludeArr })) continue;
+
             const content = index._readFile(testPath);
 
+            // Fast pre-check: skip if searchTerm doesn't appear in file
+            if (!content.includes(searchTerm)) continue;
             // className scoping: skip test files that don't reference the class at all
-            if (classNameFilter && !classNameFilter.test(content)) {
+            if (className && !content.includes(className)) continue;
+
+            // --file scoping: only include test files that import from the target source
+            if (sourceFileFilter && !sourceFileFilter.has(testPath)) {
                 continue;
             }
 
-            const lines = content.split('\n');
+            // AST-based usage detection
+            const astUsages = index._getCachedUsages(testPath, searchTerm);
+            if (astUsages === null) continue; // no parser available — skip
 
-            // Build a map of variable names → line ranges where they're bound to the target class.
-            // Tracks reassignment: a variable is only an instance of the target class between
-            // its assignment to that class and any subsequent reassignment to something else.
-            // Pre-compiles receiver regexes for O(1) per-line checks.
-            const instanceVarReceiverRegexes = []; // [{regex, fromLine, toLine}]
-            if (options.className) {
-                const cn = escapeRegExp(options.className);
-                const bindingPattern = new RegExp(
-                    '(?:const|let|var|)\\s+(\\w+)\\s*=\\s*(?:new\\s+' + cn + '|' + cn + '\\.\\w+)\\s*\\(', 'g'
-                );
-                // Also detect reassignment to a DIFFERENT class/value
-                const reassignPattern = /(\w+)\s*=\s*(?:new\s+\w|[^=])/g;
-
-                // First pass: find all bindings to the target class
-                const bindings = []; // [{varName, line}]
-                for (let i = 0; i < lines.length; i++) {
-                    let m;
-                    bindingPattern.lastIndex = 0;
-                    while ((m = bindingPattern.exec(lines[i])) !== null) {
-                        bindings.push({ varName: m[1], line: i });
-                    }
-                }
+            if (astUsages.length === 0) continue;
 
-                // Second pass: for each binding, find where the var is reassigned (scope end)
-                const escapedTerm = escapeRegExp(searchTerm);
-                for (const b of bindings) {
-                    let toLine = lines.length; // default: valid until end of file
-                    for (let i = b.line + 1; i < lines.length; i++) {
-                        // Check if this variable is reassigned to something else
-                        const line = lines[i];
-                        if (new RegExp('\\b' + escapeRegExp(b.varName) + '\\s*=\\s*(?!\\s*=)').test(line)
-                            && !bindingPattern.test(line)) {
-                            toLine = i;
-                            break;
-                        }
-                    }
-                    instanceVarReceiverRegexes.push({
-                        regex: new RegExp('\\b' + escapeRegExp(b.varName) + '\\.' + escapedTerm + '\\s*\\('),
-                        nameRegex: new RegExp('\\b' + escapeRegExp(b.varName) + '\\b'),
-                        fromLine: b.line,
-                        toLine,
-                    });
-                }
+            // Build instance variable → className map from getCachedCalls()
+            // for receiver-precise className scoping.
+            // e.g., `const svc = new B()` → svc maps to 'B'
+            let instanceTypeMap = null; // lazily built
+            if (className) {
+                instanceTypeMap = _buildInstanceTypeMap(index, testPath, content, className);
             }
 
-            // Check if a line's receiver is the target class (direct or via bound variable).
-            function lineHasClassReceiver(line, lineIdx) {
-                if (classNameFilter.test(line)) return true;
-                // Check pre-compiled instance variable regexes (scoped to assignment range)
-                for (const entry of instanceVarReceiverRegexes) {
-                    if (lineIdx >= entry.fromLine && lineIdx < entry.toLine) {
-                        if (entry.regex.test(line) || entry.nameRegex.test(line)) return true;
-                    }
+            const matches = [];
+            const seenLines = new Set(); // deduplicate same-line matches
+
+            for (const usage of astUsages) {
+                if (usage.usageType === 'definition') continue; // not relevant in test files
+
+                const lineKey = `${usage.line}:${usage.usageType}`;
+                if (seenLines.has(lineKey)) continue;
+                seenLines.add(lineKey);
+
+                const lineContent = index.getLineContent(testPath, usage.line);
+
+                let matchType;
+                if (usage.usageType === 'import') {
+                    matchType = 'import';
+                } else if (usage.usageType === 'call') {
+                    matchType = 'call';
+                } else {
+                    // 'reference' — check if inside string literal
+                    matchType = strPattern.test(lineContent) ? 'string-ref' : 'reference';
                 }
-                return false;
-            }
 
-            const matches = [];
+                // className scoping for calls: check receiver
+                if (className && matchType === 'call') {
+                    if (!_receiverMatchesClass(usage, className, instanceTypeMap, lineContent, searchTerm)) continue;
+                }
 
-            lines.forEach((line, idx) => {
-                if (regex.test(line)) {
-                    let matchType = 'reference';
-                    if (/\b(describe|it|test|spec)\s*\(/.test(line)) {
-                        matchType = 'test-case';
-                    } else if (/\b(import|require|from)\b/.test(line)) {
-                        matchType = 'import';
-                    } else if (callPattern.test(line)) {
-                        matchType = 'call';
-                    }
-                    // Detect if the match is inside a string literal (e.g., 'parseFile' or "parseFile")
-                    if (matchType === 'reference' || matchType === 'call') {
-                        if (strPattern.test(line)) {
-                            matchType = 'string-ref';
-                        }
+                // className scoping for references: require class-associated receiver
+                if (className && (matchType === 'reference' || matchType === 'string-ref')) {
+                    // Bare references (no receiver) like `fn = save` have no class
+                    // association — skip them. Only keep member-access references
+                    // where the receiver matches the target class.
+                    if (!usage.receiver) continue;
+                    if (usage.receiver !== className &&
+                        !(instanceTypeMap && instanceTypeMap.get(usage.receiver) === className)) {
+                        continue;
                     }
+                }
 
-                    // Match-level className scoping: for call matches,
-                    // the class name or a bound instance variable must appear
-                    // on the same line as the method call.
-                    if (classReceiverPattern && matchType === 'call') {
-                        if (!lineHasClassReceiver(line, idx)) return; // skip — different receiver
-                    }
+                matches.push({
+                    line: usage.line,
+                    content: lineContent.trim(),
+                    matchType
+                });
+            }
 
-                    // For reference matches, check same line or ±1 line.
-                    if (classReceiverPattern && matchType === 'reference') {
-                        let classNearby = lineHasClassReceiver(line, idx);
-                        if (!classNearby && idx > 0) classNearby = lineHasClassReceiver(lines[idx - 1], idx - 1);
-                        if (!classNearby && idx + 1 < lines.length) classNearby = lineHasClassReceiver(lines[idx + 1], idx + 1);
-                        if (!classNearby) return; // skip this match
-                    }
+            // Language-aware test-case detection
+            _addTestCaseMatches(index, testPath, entry, searchTerm, className, instanceTypeMap, matches);
 
-                    // For test-case matches with className, keep if the test
-                    // description mentions the class or the test body
-                    // references the class (directly or via bound instance).
-                    if (classNameFilter && matchType === 'test-case') {
-                        let classInContext = classNameFilter.test(line);
-                        if (!classInContext) {
-                            // Look forward into the test body for class usage
-                            for (let d = 1; d <= 5 && !classInContext; d++) {
-                                if (idx + d < lines.length) {
-                                    const bodyLine = lines[idx + d];
-                                    // Stop at next test-case boundary
-                                    if (/\b(describe|it|test|spec)\s*\(/.test(bodyLine)) break;
-                                    if (lineHasClassReceiver(bodyLine, idx + d)) classInContext = true;
-                                }
-                            }
-                        }
-                        if (!classInContext) return; // skip test-case not related to this class
-                    }
+            // Deduplicate: if a line already has a 'call' or 'import', don't also add 'test-case'
+            let finalMatches = _deduplicateMatches(matches);
 
-                    matches.push({
-                        line: idx + 1,
-                        content: line.trim(),
-                        matchType
-                    });
+            // className scoping: only include imports if the file has class-scoped
+            // call/reference/test-case matches. An import of the searchTerm alone
+            // (e.g., `from app import B, save`) is not evidence of B.save() usage.
+            if (className) {
+                const hasClassScopedMatch = finalMatches.some(m => m.matchType !== 'import');
+                if (!hasClassScopedMatch) {
+                    finalMatches = [];
                 }
-            });
+            }
 
             const filtered = options.callsOnly
-                ? matches.filter(m => m.matchType === 'call' || m.matchType === 'test-case')
-                : matches;
+                ? finalMatches.filter(m => m.matchType === 'call' || m.matchType === 'test-case')
+                : finalMatches;
             if (filtered.length > 0) {
                 results.push({
                     file: entry.relativePath,
@@ -1002,4 +973,388 @@ function tests(index, nameOrFile, options = {}) {
     } finally { index._endOp(); }
 }
 
+/**
+ * Build a map of instance variable names → class names from call objects and AST usages.
+ * Language-generic: uses receiverType from getCachedCalls() (already inferred
+ * by _buildTypedLocalTypeMap for Go/Java/Rust and binding analysis for JS/TS/Python),
+ * plus AST usages of targetClassName for assignment patterns not captured by calls
+ * (e.g., Rust `let svc = B;` inside macro bodies).
+ *
+ * Three sources:
+/**
+ * Build a set of absolute file paths that import (directly or transitively via
+ * re-exports) from the source files where the symbol is defined.
+ * Uses the index's resolved importGraph/exportGraph for path-precise matching.
+ */
+function _buildSourceFileImporters(index, defs) {
+    const symbolName = defs[0]?.name;
+    const sourceAbsPaths = new Set();
+    for (const d of defs) {
+        for (const [absPath, fe] of index.files) {
+            if (fe.relativePath === d.relativePath) {
+                sourceAbsPaths.add(absPath);
+                break;
+            }
+        }
+    }
+
+    // BFS through the export graph: walk from source files outward through
+    // re-export chains. At each hop, verify the intermediate file actually
+    // exports the target symbol (prevents overmatching barrels that import
+    // the source file for a different symbol).
+    const importers = new Set();
+    const queue = [...sourceAbsPaths];
+    const visited = new Set(sourceAbsPaths);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const directImporters = index.exportGraph?.get(current) || [];
+        for (const imp of directImporters) {
+            importers.add(imp);
+            // Check if this importer re-exports the symbol (barrel pattern).
+            // 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(fe, symbolName, current)) {
+                    visited.add(imp);
+                    queue.push(imp);
+                }
+            }
+        }
+    }
+
+    // Language-aware test file discovery: add test files matched by naming
+    // convention or same-package membership, which don't use import statements.
+    // Go: same directory (package-scoped), Java: *Test.java convention,
+    // Rust: inline #[cfg(test)] in the source file itself.
+    for (const srcPath of sourceAbsPaths) {
+        const srcEntry = index.files.get(srcPath);
+        if (!srcEntry) continue;
+        const traits = langTraits(srcEntry.language);
+        if (!traits?.testFileCandidates) continue;
+
+        const srcBase = path.basename(srcPath, path.extname(srcPath));
+        const srcExt = path.extname(srcPath);
+        const srcDir = path.dirname(srcPath);
+        const candidates = traits.testFileCandidates(srcBase, srcExt);
+
+        // Build set of directories to check for convention-based test files:
+        // same directory + configured testDirs (e.g., __tests__, tests/)
+        // + Java src/main→src/test mirror convention
+        const candidateDirs = new Set([srcDir]);
+        for (const td of (traits.testDirs || [])) {
+            candidateDirs.add(path.join(srcDir, td));
+        }
+        // Java convention: src/main/java/com/pkg → src/test/java/com/pkg
+        if (srcDir.includes(path.sep + 'main' + path.sep)) {
+            candidateDirs.add(srcDir.replace(path.sep + 'main' + path.sep, path.sep + 'test' + path.sep));
+        }
+
+        for (const [absPath, fe] of index.files) {
+            if (importers.has(absPath)) continue; // already included
+            if (!isTestFile(fe.relativePath, fe.language) &&
+                !(fe.language === 'rust' && fe.symbols?.some(s => s.modifiers?.includes('test')))) {
+                continue; // not a test file
+            }
+
+            const testDir = path.dirname(absPath);
+
+            // Check naming convention match — must be in same dir or a test subdir
+            if (candidateDirs.has(testDir)) {
+                const testBaseName = path.basename(absPath);
+                if (candidates.some(c => testBaseName === c)) {
+                    importers.add(absPath);
+                    continue;
+                }
+            }
+
+            // Go: same-directory tests (package-scoped, no imports needed)
+            if (traits.packageScope === 'directory' && testDir === srcDir) {
+                importers.add(absPath);
+                continue;
+            }
+
+            // Rust: inline tests in the source file itself
+            if (srcPath === absPath) {
+                importers.add(absPath);
+            }
+        }
+    }
+
+    return importers;
+}
+
+/**
+ * Check if a file re-exports a symbol from a source file.
+ * Handles: named re-exports, `module.exports = require(...)` blanket re-exports,
+ * `export * from ...`, and files that both import from source and export the symbol.
+ */
+function _fileReExportsSymbol(fileEntry, symbolName, sourceAbsPath) {
+    if (!fileEntry.exports || fileEntry.exports.length === 0) return false;
+    // Check if any export matches the symbol name
+    if (symbolName && fileEntry.exports.some(exp => exp.name === symbolName)) return true;
+    // Blanket re-exports: module.exports = require(...), export * from ...
+    // These have undefined or generic names but re-export everything from the imported module
+    const hasBlanketExport = fileEntry.exports.some(exp =>
+        !exp.name || exp.type === 'module.exports' || exp.type === 're-export' || exp.type === 'export-all'
+    );
+    if (hasBlanketExport) return true;
+    return false;
+}
+
+/**
+ * Build a map of instance variable names → class names from call objects and AST usages.
+ * Language-generic: uses receiverType from getCachedCalls() (already inferred
+ * by _buildTypedLocalTypeMap for Go/Java/Rust and binding analysis for JS/TS/Python),
+ * plus AST usages of targetClassName for assignment patterns not captured by calls
+ * (e.g., Rust `let svc = B;` inside macro bodies).
+ *
+ * Three sources:
+ * 1. receiverType on method calls: `svc.Save()` with receiverType=B → svc maps to B
+ * 2. Constructor calls: `new B()`, `B()`, `&B{}` assigned to a variable
+ * 3. AST usages of className on assignment lines: `let svc = B;` or `svc = B{}`
+ */
+function _buildInstanceTypeMap(index, filePath, content, targetClassName) {
+    const typeMap = new Map(); // varName → className
+
+    const calls = getCachedCalls(index, filePath);
+    if (calls) {
+        for (const call of calls) {
+            // Source 1: receiverType from method calls (works across all languages)
+            // e.g., svc.Save() where receiverType='B' → svc maps to 'B'
+            if (call.isMethod && call.receiver && call.receiverType === targetClassName) {
+                typeMap.set(call.receiver, targetClassName);
+            }
+
+            // Source 2: Constructor/factory calls assigned to a variable
+            // e.g., `const svc = new B()` (JS), `svc = B()` (Python), `svc := &B{}` (Go)
+            if (call.name === targetClassName && !call.isMethod) {
+                const lineContent = index.getLineContent(filePath, call.line);
+                const assignMatch = lineContent.match(/(?:const|let|var|)\s*(\w+)\s*:?=\s/);
+                if (assignMatch) {
+                    typeMap.set(assignMatch[1], targetClassName);
+                }
+            }
+
+            // Source 3: Factory methods — ClassName.create(), ClassName.build(), etc.
+            if (call.isMethod && call.receiver === targetClassName) {
+                const lineContent = index.getLineContent(filePath, call.line);
+                const assignMatch = lineContent.match(/(?:const|let|var|)\s*(\w+)\s*:?=\s/);
+                if (assignMatch) {
+                    typeMap.set(assignMatch[1], targetClassName);
+                }
+            }
+        }
+    }
+
+    // Source 4: AST usages of targetClassName on assignment lines.
+    // Catches patterns not visible to getCachedCalls (e.g., Rust macro bodies
+    // where `let svc = B;` is inside a token_tree, or Go `svc := B{}`).
+    const classUsages = index._getCachedUsages(filePath, targetClassName);
+    if (classUsages) {
+        for (const u of classUsages) {
+            if (u.usageType === 'import' || u.usageType === 'definition') continue;
+            const lineContent = index.getLineContent(filePath, u.line);
+            // Match: `let/const/var varName = ClassName` or `varName := ClassName`
+            const assignMatch = lineContent.match(/(?:const|let|var|)\s*(\w+)\s*:?=\s/);
+            if (assignMatch && assignMatch[1] !== targetClassName) {
+                typeMap.set(assignMatch[1], targetClassName);
+            }
+        }
+    }
+
+    return typeMap;
+}
+
+/**
+ * Check if a usage's receiver matches the target className.
+ * Uses direct receiver check and instance type map for indirect bindings.
+ * @param {object} usage - AST usage with optional receiver field
+ * @param {string} className - Target class name
+ * @param {Map} instanceTypeMap - varName → className map
+ * @param {string} [lineContent] - Line content for fallback checks
+ */
+function _receiverMatchesClass(usage, className, instanceTypeMap, lineContent, searchTerm) {
+    // Direct receiver: ClassName.method() or ClassName.staticMethod()
+    if (usage.receiver === className) return true;
+    // Instance variable: check if receiver is bound to the target class
+    if (usage.receiver && instanceTypeMap && instanceTypeMap.get(usage.receiver) === className) return true;
+    // Receiver is some other known identifier — doesn't match
+    if (usage.receiver) return false;
+    // No receiver: bare function call. Only match if className is the direct
+    // receiver expression — e.g., `new B().save()`, `B().save()`, `B{}.save()`.
+    // Reject cases like `svc = B(); save()` where className is elsewhere on the line.
+    if (lineContent && searchTerm) {
+        // Check for chained call: ClassName followed by constructor/call then .methodName(
+        const pat = new RegExp(
+            '\\b' + escapeRegExp(className) + '\\s*(?:(?:\\([^)]*\\)|\\{[^}]*\\})\\s*\\.\\s*' +
+            escapeRegExp(searchTerm) + '\\s*\\(|' +
+            'new\\s+' + escapeRegExp(className) + '\\s*\\([^)]*\\)\\s*\\.\\s*' +
+            escapeRegExp(searchTerm) + '\\s*\\()'
+        );
+        if (pat.test(lineContent)) return true;
+    }
+    return false;
+}
+
+/**
+ * Language-aware test-case detection.
+ *
+ * JS/TS: describe, it, test, spec calls with searchTerm in the description.
+ * Go: TestXxx, BenchmarkXxx, ExampleXxx functions containing a usage of searchTerm.
+ * Python: test_ functions or TestCase methods containing a usage of searchTerm.
+ * Java: @Test-annotated methods containing a usage of searchTerm.
+ * Rust: #[test]-attributed functions containing a usage of searchTerm.
+ */
+function _addTestCaseMatches(index, filePath, fileEntry, searchTerm, className, instanceTypeMap, matches) {
+    const matchLines = new Set(matches.map(m => m.line));
+    const lang = fileEntry.language;
+
+    if (lang === 'javascript' || lang === 'typescript' || lang === 'tsx') {
+        // JS/TS: find describe/it/test/spec calls from getCachedCalls
+        const calls = getCachedCalls(index, filePath);
+        if (!calls) return;
+        const testFrameworkCalls = new Set(['describe', 'it', 'test', 'spec']);
+        for (const call of calls) {
+            if (!testFrameworkCalls.has(call.name)) continue;
+            const lineContent = index.getLineContent(filePath, call.line);
+            // Check if searchTerm appears in the description string on this line
+            if (lineContent.includes(searchTerm) && !matchLines.has(call.line)) {
+                // className scoping: only add test-case if the test body has a
+                // class-scoped match (call or class-receiver reference) — not just
+                // any mention of className.
+                if (className) {
+                    const endLine = _estimateTestBlockEnd(index, filePath, call.line);
+                    const hasClassScopedMatch = matches.some(m =>
+                        m.line >= call.line && m.line <= endLine &&
+                        m.matchType !== 'import'
+                    );
+                    if (!hasClassScopedMatch) continue;
+                }
+                matches.push({
+                    line: call.line,
+                    content: lineContent.trim(),
+                    matchType: 'test-case'
+                });
+                matchLines.add(call.line);
+            }
+        }
+    } else {
+        // 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);
+            if (!langModule || !langModule.isEntryPoint) return;
+
+            // Find test symbols
+            for (const symbol of fileEntry.symbols) {
+                if (!langModule.isEntryPoint(symbol)) continue;
+                // Check if any non-import usage of searchTerm falls within this test function
+                const usageInRange = matches.some(m =>
+                    m.line >= symbol.startLine && m.line <= symbol.endLine &&
+                    m.matchType !== 'import'
+                );
+                if (usageInRange && !matchLines.has(symbol.startLine)) {
+                    // className scoping: verify the test body has class-scoped matches
+                    if (className) {
+                        const hasClassScopedMatch = matches.some(m =>
+                            m.line >= symbol.startLine && m.line <= symbol.endLine &&
+                            m.matchType !== 'import'
+                        );
+                        if (!hasClassScopedMatch) continue;
+                    }
+                    const lineContent = index.getLineContent(filePath, symbol.startLine);
+                    matches.push({
+                        line: symbol.startLine,
+                        content: lineContent.trim(),
+                        matchType: 'test-case'
+                    });
+                    matchLines.add(symbol.startLine);
+                }
+            }
+        } catch (e) {
+            // Skip if language module unavailable
+        }
+    }
+}
+
+/**
+ * Check if a test body references the target class (directly or via instance variable).
+ * Looks at AST usages of className within the test function's line range.
+ */
+function _testBodyReferencesClass(index, filePath, fileEntry, testLine, className, instanceTypeMap) {
+    // Find the enclosing test function to get its line range
+    const enclosing = index.findEnclosingFunction(filePath, testLine, true);
+    let startLine, endLine;
+    if (enclosing) {
+        startLine = enclosing.startLine;
+        endLine = enclosing.endLine;
+    } else {
+        // No enclosing function found (common for JS/TS it/test callbacks which
+        // aren't in the symbol table). Estimate range from file content.
+        startLine = testLine;
+        endLine = _estimateTestBlockEnd(index, filePath, testLine);
+    }
+
+    // Check if className appears as AST usage in the range
+    const classUsages = index._getCachedUsages(filePath, className);
+    if (classUsages) {
+        for (const u of classUsages) {
+            if (u.line >= startLine && u.line <= endLine) return true;
+        }
+    }
+
+    // Check if any instance variable bound to className is used in the range
+    if (instanceTypeMap) {
+        for (const [varName, cls] of instanceTypeMap) {
+            if (cls !== className) continue;
+            const varUsages = index._getCachedUsages(filePath, varName);
+            if (varUsages) {
+                for (const u of varUsages) {
+                    if (u.line >= startLine && u.line <= endLine) return true;
+                }
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Estimate the end line of a test block (it/test/describe callback) by tracking
+ * brace nesting from the start line.
+ */
+function _estimateTestBlockEnd(index, filePath, startLine) {
+    const content = index._readFile(filePath);
+    if (!content) return startLine + 5;
+    const lines = content.split('\n');
+    let depth = 0;
+    let started = false;
+    for (let i = startLine - 1; i < lines.length; i++) {
+        const line = lines[i];
+        for (const ch of line) {
+            if (ch === '{' || ch === '(') { depth++; started = true; }
+            else if (ch === '}' || ch === ')') { depth--; }
+        }
+        if (started && depth <= 0) return i + 1; // 1-based
+    }
+    return Math.min(startLine + 10, lines.length);
+}
+
+/**
+ * Deduplicate matches: prefer more specific matchTypes on the same line.
+ * Priority: test-case > call > import > string-ref > reference
+ */
+function _deduplicateMatches(matches) {
+    const byLine = new Map();
+    const priority = { 'test-case': 5, 'call': 4, 'import': 3, 'string-ref': 2, 'reference': 1 };
+    for (const m of matches) {
+        const existing = byLine.get(m.line);
+        if (!existing || (priority[m.matchType] || 0) > (priority[existing.matchType] || 0)) {
+            byLine.set(m.line, m);
+        }
+    }
+    return [...byLine.values()].sort((a, b) => a.line - b.line);
+}
+
 module.exports = { find, _applyFindFilters, usages, search, structuralSearch, example, typedef, tests };