ucn 3.8.22 → 3.8.25

package/core/search.js

@@ -221,11 +221,15 @@ function usages(index, name, options = {}) {
                 let _importedHasDef = null;
                 const importedFileHasDef = () => {
                     if (_importedHasDef !== null) return _importedHasDef;
-                    const importedFiles = index.importGraph.get(filePath) || [];
-                    _importedHasDef = importedFiles.some(imp => {
+                    const importedFiles = index.importGraph.get(filePath);
+                    _importedHasDef = false;
+                    if (importedFiles) for (const imp of importedFiles) {
                         const impEntry = index.files.get(imp);
-                        return impEntry?.symbols?.some(s => s.name === name);
-                    });
+                        if (impEntry?.symbols?.some(s => s.name === name)) {
+                            _importedHasDef = true;
+                            break;
+                        }
+                    }
                     return _importedHasDef;
                 };
 
@@ -249,6 +253,15 @@ function usages(index, name, options = {}) {
 
                     const lineContent = lines[u.line - 1] || '';
 
+                    // BUG-4: enrich call usages with enclosing-function info so
+                    // the JSON `handle` shows the real caller, not `_topLevel`.
+                    // Only resolve for call usages — definitions, imports, and
+                    // bare references don't need a caller token.
+                    let callerSym = null;
+                    if (u.usageType === 'call') {
+                        callerSym = index.findEnclosingFunction(filePath, u.line, true);
+                    }
+
                     const usage = {
                         file: filePath,
                         relativePath: fileEntry.relativePath,
@@ -256,7 +269,11 @@ function usages(index, name, options = {}) {
                         content: lineContent,
                         usageType: u.usageType,
                         isDefinition: false,
-                        ...(u.receiver && { receiver: u.receiver })
+                        ...(u.receiver && { receiver: u.receiver }),
+                        ...(callerSym && {
+                            callerName: callerSym.name,
+                            callerStartLine: callerSym.startLine
+                        })
                     };
 
                     // Add context lines if requested
@@ -301,13 +318,23 @@ function usages(index, name, options = {}) {
                     // Classify usage type (AST-based, defaults to 'reference' for unsupported languages)
                     const usageType = index.classifyUsageAST(content, lineNum, name, filePath) ?? 'reference';
 
+                    // BUG-4: enrich call usages with enclosing-function info.
+                    let callerSym = null;
+                    if (usageType === 'call') {
+                        callerSym = index.findEnclosingFunction(filePath, lineNum, true);
+                    }
+
                     const usage = {
                         file: filePath,
                         relativePath: fileEntry.relativePath,
                         line: lineNum,
                         content: line,
                         usageType,
-                        isDefinition: false
+                        isDefinition: false,
+                        ...(callerSym && {
+                            callerName: callerSym.name,
+                            callerStartLine: callerSym.startLine
+                        })
                     };
 
                     // Add context lines if requested
@@ -718,25 +745,50 @@ function structuralSearch(index, options = {}) {
 }
 
 /**
- * Find the best usage example of a function
+ * Find the best usage example of a function (or, with `diverse`, one
+ * representative per distinct argument-shape cluster).
  *
  * @param {object} index - ProjectIndex instance
  * @param {string} name - Function name
- * @param {object} options - { className }
- * @returns {object|null} Best example with score
+ * @param {object} options - { className, diverse, top }
+ * @returns {object|null} Best example with score; with diverse=true, also `clusters`
  */
 function example(index, name, options = {}) {
     index._beginOp();
     try {
+    // MEDIUM-8: respect --include-tests. By default, test/fixture/mock files
+    // are excluded as low-signal examples. When the user passes
+    // includeTests:true, return matches from those files too.
+    const exclude = options.includeTests
+        ? []
+        : ['test', 'spec', '__tests__', '__mocks__', 'fixture', 'mock'];
     const usageResults = usages(index, name, {
         codeOnly: true,
         className: options.className,
-        exclude: ['test', 'spec', '__tests__', '__mocks__', 'fixture', 'mock'],
+        exclude,
         context: 5
     });
 
     const calls = usageResults.filter(u => u.usageType === 'call' && !u.isDefinition);
-    if (calls.length === 0) return null;
+    if (calls.length === 0) {
+        // No matches in non-test files. Look at how many WERE excluded so we
+        // can tell the user there's something they could see with
+        // --include-tests, instead of saying "no examples found" silently.
+        if (!options.includeTests) {
+            const allUsages = usages(index, name, {
+                codeOnly: true,
+                className: options.className,
+                exclude: [],
+                context: 0,
+            });
+            const excludedCalls = allUsages.filter(u =>
+                u.usageType === 'call' && !u.isDefinition).length;
+            if (excludedCalls > 0) {
+                return { best: null, totalCalls: 0, excludedTestCalls: excludedCalls };
+            }
+        }
+        return null;
+    }
 
     const scored = calls.map(call => {
         let score = 0;
@@ -777,7 +829,73 @@ function example(index, name, options = {}) {
     });
 
     scored.sort((a, b) => b.score - a.score);
-    return { best: scored[0], totalCalls: calls.length };
+    const best = scored[0];
+
+    // Default behavior: one best representative.
+    if (!options.diverse) {
+        return { best, totalCalls: calls.length };
+    }
+
+    // --diverse: cluster call sites by AST argument-shape and return one
+    // representative per cluster (up to `top`, default 3).
+    //
+    // Shape key = "argCount:argKind1,argKind2,..." (see classifyArgNode in
+    // verify.js for the kind set). Calls with no resolvable AST shape go into
+    // a single 'unknown' cluster so they're still surfaced.
+    //
+    // Representative selection: highest existing example score within the
+    // cluster — this reuses the quality heuristic above (typed assignment,
+    // documented, standalone, etc.) so each cluster's example is the *best*
+    // member of that shape, not just the first-seen one.
+    const top = (options.top != null && Number(options.top) > 0) ? Number(options.top) : 3;
+    const clusterMap = new Map(); // shapeKey -> { shapeKey, kinds, count, members:[] }
+
+    for (const call of scored) {
+        const shape = index._analyzeCallShape(call.file, call.line, name);
+        const key = shape ? shape.shapeKey : 'unknown';
+        if (!clusterMap.has(key)) {
+            clusterMap.set(key, {
+                shapeKey: key,
+                argKinds: shape ? shape.argKinds : null,
+                argCount: shape ? shape.argCount : null,
+                count: 0,
+                members: [],
+            });
+        }
+        const c = clusterMap.get(key);
+        c.count++;
+        c.members.push({ ...call, _argTexts: shape ? shape.argTexts : null });
+    }
+
+    // Order clusters: largest first, ties broken by shapeKey for determinism.
+    const clusterList = [...clusterMap.values()].sort((a, b) =>
+        (b.count - a.count) || a.shapeKey.localeCompare(b.shapeKey)
+    );
+
+    // Pick representative per cluster: highest-scoring member; ties broken
+    // by (file, line) for stable output across runs.
+    const clusters = clusterList.slice(0, top).map(cluster => {
+        const sortedMembers = [...cluster.members].sort((a, b) =>
+            (b.score - a.score) ||
+            (a.relativePath || a.file || '').localeCompare(b.relativePath || b.file || '') ||
+            (a.line || 0) - (b.line || 0)
+        );
+        const rep = sortedMembers[0];
+        return {
+            shapeKey: cluster.shapeKey,
+            argKinds: cluster.argKinds,
+            argCount: cluster.argCount,
+            count: cluster.count,
+            representative: rep,
+        };
+    });
+
+    return {
+        best,
+        totalCalls: calls.length,
+        clusters,
+        totalClusters: clusterList.length,
+    };
     } finally { index._endOp(); }
 }
 
@@ -1008,7 +1126,7 @@ function _buildSourceFileImporters(index, defs) {
 
     while (queue.length > 0) {
         const current = queue.shift();
-        const directImporters = index.exportGraph?.get(current) || [];
+        const directImporters = index.exportGraph?.get(current) || new Set();
         for (const imp of directImporters) {
             importers.add(imp);
             // Check if this importer re-exports the symbol (barrel pattern).
@@ -1244,11 +1362,17 @@ function _addTestCaseMatches(index, filePath, fileEntry, searchTerm, className,
         if (!fileEntry.symbols) return;
         try {
             const langModule = getLanguageModule(lang);
-            if (!langModule || !langModule.isEntryPoint) return;
+            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.
+            const classify = langModule.getEntryPointKind
+                ? (s) => langModule.getEntryPointKind(s) === 'test'
+                : langModule.isEntryPoint;
+            if (!classify) return;
 
             // Find test symbols
             for (const symbol of fileEntry.symbols) {
-                if (!langModule.isEntryPoint(symbol)) continue;
+                if (!classify(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 &&

package/core/shared.js

@@ -5,29 +5,61 @@
 const { isTestFile } = require('./discovery');
 const { detectLanguage } = require('./parser');
 
+/**
+ * Path-based test heuristic — matches the same patterns as `find`'s exclusion
+ * logic so that `about` and `find` agree on which files are de-emphasized.
+ *
+ * Triggers when any of `test|tests|spec|__tests__|__mocks__|fixture|mock`
+ * appears as a path segment (with word boundaries on both sides).
+ *
+ * Complement to `isTestFile` (filename pattern check) — together they catch
+ * both `foo.test.js` (filename) AND `test/agent-benchmark.js` (directory).
+ */
+function isTestPath(rp) {
+    if (!rp) return false;
+    return /(^|[/._-])(test|tests|spec|__tests__|__mocks__|fixture|mock)s?([/._-]|$)/i.test(rp);
+}
+
 /**
  * Pick the best definition from multiple matches.
  * Prefers non-test, src/lib files, larger function bodies.
+ *
+ * BUG-M4: align with `find`'s exclusion ordering so `about` and `find` pick
+ * the same primary. Adds path-based test detection (covers `test/foo.js`
+ * which `isTestFile` misses) and prefers files that are imported by others
+ * (real source) over test/fixture files.
  */
-function pickBestDefinition(matches) {
+function pickBestDefinition(matches, opts = {}) {
     const typeOrder = new Set(['class', 'struct', 'interface', 'type', 'impl']);
+    const importGraph = opts.importGraph;
     const scored = matches.map(m => {
         let score = 0;
         const rp = m.relativePath || '';
         // Prefer class/struct/interface types (+1000) - same as resolveSymbol
         if (typeOrder.has(m.type)) score += 1000;
-        if (isTestFile(rp, detectLanguage(m.file))) score -= 500;
+        // Test file penalties: -500 for filename pattern OR path segment.
+        // Both checks because `isTestFile` only matches `*.test.js`/`__tests__/`,
+        // not `test/agent-benchmark.js` which `find` excludes via path regex.
+        if (isTestFile(rp, detectLanguage(m.file)) || isTestPath(rp)) score -= 500;
         if (/^(examples?|docs?|vendor|third[_-]?party|benchmarks?|samples?)\//i.test(rp)) score -= 300;
         if (/^(lib|src|core|internal|pkg|crates)\//i.test(rp)) score += 200;
+        // Prefer files that are imported by something — real source over scripts/fixtures.
+        if (importGraph && m.file) {
+            for (const [, importedFiles] of importGraph) {
+                if (importedFiles.has(m.file)) { score += 100; break; }
+            }
+        }
         // Deprioritize type-only overload signatures (TypeScript function_signature)
         if (m.isSignature) score -= 200;
         // Tiebreaker: prefer larger function bodies (more important/complex)
         if (m.startLine && m.endLine) {
             score += Math.min(m.endLine - m.startLine, 100);
         }
-        return { match: m, score };
+        return { match: m, score, rp };
     });
-    scored.sort((a, b) => b.score - a.score);
+    // Stable sort: by score desc, then alphabetical relativePath (so two equal-score
+    // matches always pick the same one across runs).
+    scored.sort((a, b) => (b.score - a.score) || a.rp.localeCompare(b.rp));
     return scored[0].match;
 }
 
@@ -52,4 +84,68 @@ function escapeRegExp(text) {
 // Symbol types that are not callable (used to filter class/struct/type declarations from call analysis)
 const NON_CALLABLE_TYPES = new Set(['class', 'struct', 'interface', 'type', 'enum', 'trait', 'state', 'impl', 'field']);
 
-module.exports = { pickBestDefinition, addTestExclusions, escapeRegExp, NON_CALLABLE_TYPES };
+/**
+ * Stable symbol handle: `relativePath:line` or `relativePath:line:name`.
+ *
+ * Handles let multi-step workflows roundtrip without name disambiguation —
+ * `find` returns handles, `brief`/`impact`/`context` accept them, and the result
+ * targets the exact same symbol even when names overlap. Renames break handles
+ * (intentionally — that's a real change, not noise).
+ *
+ * Format chosen because:
+ *   - colon is the existing UCN location separator (`file.js:42`)
+ *   - line number is the second-most-stable ID (after path); names move within files
+ *   - the optional :name disambiguates when multiple symbols share a startLine
+ *     (rare but possible: e.g. `class Foo {}` and a same-line method def)
+ */
+function formatSymbolHandle(symbol) {
+    if (!symbol || !symbol.startLine) return null;
+    const file = symbol.relativePath || symbol.file;
+    if (!file) return null;
+    return symbol.name ? `${file}:${symbol.startLine}:${symbol.name}` : `${file}:${symbol.startLine}`;
+}
+
+/**
+ * Parse a handle string back into its components.
+ * Returns { file, line, name? } or null if input doesn't look like a handle.
+ *
+ * Strategy: scan from the right so paths containing `:` (Windows drive letters
+ * if anyone ever uses them as relative paths) survive. The line number is the
+ * rightmost run of digits between two colons or at the end.
+ */
+function parseSymbolHandle(input) {
+    if (!input || typeof input !== 'string') return null;
+    // Two forms:
+    //   path:digits           → file + line
+    //   path:digits:name      → file + line + name (name may contain anything)
+    // The line is always digits; the path is everything before the line; the
+    // optional name is everything after the line.
+    const m = input.match(/^(.+):(\d+)(?::(.+))?$/);
+    if (!m) return null;
+    const file = m[1];
+    const line = parseInt(m[2], 10);
+    if (!Number.isFinite(line) || line < 1) return null;
+    const handle = { file, line };
+    if (m[3] != null) handle.name = m[3];
+    return handle;
+}
+
+/**
+ * Quick predicate: does this string look like a handle (vs a plain symbol name)?
+ * Used to short-circuit handle resolution before name lookup.
+ */
+function looksLikeHandle(input) {
+    if (!input || typeof input !== 'string') return false;
+    return /^.+:\d+(?::.+)?$/.test(input);
+}
+
+module.exports = {
+    pickBestDefinition,
+    addTestExclusions,
+    escapeRegExp,
+    NON_CALLABLE_TYPES,
+    formatSymbolHandle,
+    parseSymbolHandle,
+    looksLikeHandle,
+    isTestPath,
+};

package/core/tracing.js

@@ -32,7 +32,7 @@ function trace(index, name, options = {}) {
     // trace defaults to includeMethods=true (execution flow should show method calls)
     const includeMethods = options.includeMethods ?? true;
 
-    const { def, definitions, warnings } = index.resolveSymbol(name, { file: options.file, className: options.className });
+    const { def, definitions, warnings } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
     if (!def) {
         return null;
     }
@@ -159,7 +159,7 @@ function blast(index, name, options = {}) {
         const includeUncertain = options.includeUncertain || false;
         const exclude = options.exclude || [];
 
-        const { def, definitions, warnings } = index.resolveSymbol(name, { file: options.file, className: options.className });
+        const { def, definitions, warnings } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
         if (!def) return null;
 
         const visited = new Set();
@@ -334,7 +334,7 @@ function reverseTrace(index, name, options = {}) {
         const includeUncertain = options.includeUncertain || false;
         const exclude = options.exclude || [];
 
-        const { def, definitions, warnings } = index.resolveSymbol(name, { file: options.file, className: options.className });
+        const { def, definitions, warnings } = index.resolveSymbol(name, { file: options.file, className: options.className, line: options.line });
         if (!def) return null;
 
         const visited = new Set();
@@ -435,13 +435,22 @@ function reverseTrace(index, name, options = {}) {
                 if (callerEntries.length > maxChildren) {
                     node.truncatedChildren = callerEntries.length - maxChildren;
                     // Count entry points in truncated branches so summary is accurate
+                    // Use callerCache to avoid redundant findCallers calls
                     for (const { def: cDef } of callerEntries.slice(maxChildren)) {
-                        const key = `${cDef.file}:${cDef.startLine}`;
-                        if (!visited.has(key)) {
-                            const cCallers = index.findCallers(cDef.name, {
-                                includeMethods, includeUncertain,
-                                targetDefinitions: cDef.bindingId ? [cDef] : undefined,
-                            });
+                        const cKey = `${cDef.file}:${cDef.startLine}`;
+                        if (!visited.has(cKey)) {
+                            const cCacheKey = cDef.bindingId
+                                ? `${cDef.name}:${cDef.bindingId}`
+                                : `${cDef.name}:${cKey}`;
+                            let cCallers = callerCache.get(cCacheKey);
+                            if (!cCallers) {
+                                cCallers = index.findCallers(cDef.name, {
+                                    includeMethods, includeUncertain,
+                                    targetDefinitions: cDef.bindingId ? [cDef] : undefined,
+                                    maxResults: 1, // Only need to know if any exist
+                                });
+                                callerCache.set(cCacheKey, cCallers);
+                            }
                             if (cCallers.length === 0) {
                                 entryPoints.push({ name: cDef.name, file: cDef.relativePath || path.relative(index.root, cDef.file), line: cDef.startLine });
                             }
@@ -552,8 +561,11 @@ function affectedTests(index, name, options = {}) {
         for (const [filePath, fileEntry] of index.files) {
             let isTest = isTestFile(fileEntry.relativePath, fileEntry.language);
             // Rust inline #[cfg(test)] modules: source files with #[test]-marked symbols
+            // or symbols inside a #[cfg(test)] mod block (BUG-CY).
             if (!isTest && fileEntry.language === 'rust') {
-                isTest = fileEntry.symbols?.some(s => s.modifiers?.includes('test'));
+                isTest = fileEntry.symbols?.some(s =>
+                    s.modifiers?.includes('test') || s.modifiers?.includes('cfg_test_module')
+                );
             }
             if (!isTest) continue;
             if (excludeArr.length > 0 && !index.matchesFilters(fileEntry.relativePath, { exclude: excludeArr })) continue;
@@ -735,9 +747,16 @@ function _addAffectedTestCases(index, filePath, fileEntry, funcName, fileMatches
         if (!fileEntry.symbols) return;
         try {
             const langModule = getLanguageModule(lang);
-            if (!langModule || !langModule.isEntryPoint) return;
+            if (!langModule) return;
+            // Prefer the kinded predicate so we don't mis-tag fn main() / fn init()
+            // (runtime entries) as test cases (BUG-CX). Fall back to isEntryPoint
+            // for backward compat with language modules that haven't been migrated.
+            const classify = langModule.getEntryPointKind
+                ? (s) => langModule.getEntryPointKind(s) === 'test'
+                : langModule.isEntryPoint;
+            if (!classify) return;
             for (const symbol of fileEntry.symbols) {
-                if (!langModule.isEntryPoint(symbol)) continue;
+                if (!classify(symbol)) continue;
                 // Only add test-case if a call match exists in the test body
                 const hasCallInRange = existingMatches.some(m =>
                     m.line >= symbol.startLine && m.line <= symbol.endLine &&