grepmax 0.16.3 → 0.16.4

package/dist/commands/extract.js

@@ -110,6 +110,7 @@ exports.extract = new commander_1.Command("extract")
     .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--agent", "Compact output for AI agents", false)
     .option("--imports", "Prepend file imports", false)
+    .option("--no-tests", "Suppress the tests footer")
     .action((symbol, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     let vectorDb = null;
@@ -176,6 +177,16 @@ exports.extract = new commander_1.Command("extract")
             }
             console.log(`${relPath}:${startLine + 1}-${endLine + 1}`);
             console.log(body.join("\n"));
+            if (opts.tests !== false) {
+                const { fetchTestsForFooter, renderTestsFooterAgent } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/tests-footer")));
+                const tests = yield fetchTestsForFooter(symbol, vectorDb, scope.pathPrefix, scope.excludePrefixes);
+                if (tests && tests.length > 0) {
+                    console.log("--- tests:");
+                    for (const line of renderTestsFooterAgent(tests, projectRoot)) {
+                        console.log(line);
+                    }
+                }
+            }
         }
         else {
             // Rich output with line numbers
@@ -207,6 +218,15 @@ exports.extract = new commander_1.Command("extract")
                 .join(", ");
             console.log(`\n${style.dim(`Also defined in: ${otherLocs}`)}`);
         }
+        if (!opts.agent && opts.tests !== false) {
+            const { fetchTestsForFooter, renderTestsFooterHuman } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/tests-footer")));
+            const tests = yield fetchTestsForFooter(symbol, vectorDb, scope.pathPrefix, scope.excludePrefixes);
+            if (tests && tests.length > 0) {
+                for (const line of renderTestsFooterHuman(tests, projectRoot)) {
+                    console.log(line);
+                }
+            }
+        }
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";

package/dist/commands/peek.js

@@ -98,6 +98,7 @@ exports.peek = new commander_1.Command("peek")
     .option("--in <subpath>", "Restrict to a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--agent", "Compact output for AI agents", false)
+    .option("--no-tests", "Suppress the tests footer")
     .action((symbol, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     let vectorDb = null;
@@ -225,6 +226,15 @@ exports.peek = new commander_1.Command("peek")
             if (calleeList.length > MAX_CALLEES) {
                 console.log(`-> ... ${calleeList.length - MAX_CALLEES} more`);
             }
+            if (opts.tests !== false) {
+                const { fetchTestsForFooter, renderTestsFooterAgent } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/tests-footer")));
+                const tests = yield fetchTestsForFooter(symbol, vectorDb, scope.pathPrefix, scope.excludePrefixes);
+                if (tests && tests.length > 0) {
+                    for (const line of renderTestsFooterAgent(tests, projectRoot)) {
+                        console.log(line);
+                    }
+                }
+            }
         }
         else {
             // Rich output
@@ -276,6 +286,15 @@ exports.peek = new commander_1.Command("peek")
             else {
                 console.log(style.dim("No known callees."));
             }
+            if (opts.tests !== false) {
+                const { fetchTestsForFooter, renderTestsFooterHuman } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/tests-footer")));
+                const tests = yield fetchTestsForFooter(symbol, vectorDb, scope.pathPrefix, scope.excludePrefixes);
+                if (tests && tests.length > 0) {
+                    for (const line of renderTestsFooterHuman(tests, projectRoot)) {
+                        console.log(line);
+                    }
+                }
+            }
         }
     }
     catch (error) {

package/dist/commands/related.js

@@ -138,6 +138,52 @@ exports.related = new commander_1.Command("related")
         const topRevs = Array.from(revCounts.entries())
             .sort((a, b) => b[1] - a[1])
             .slice(0, limit);
+        // Mention-based fallback: when symbol intersection turns up nothing
+        // in either direction, look for files in scope whose content mentions
+        // this file's basename. Catches leaf modules with no shared symbols
+        // and side-effect-only imports.
+        const GENERIC_BASENAMES = new Set([
+            "index",
+            "main",
+            "mod",
+            "init",
+            "lib",
+            "types",
+            "util",
+            "utils",
+            "common",
+            "shared",
+        ]);
+        let mentions = [];
+        let basename = "";
+        let basenameRejected = false;
+        if (topDeps.length === 0 && topRevs.length === 0) {
+            const ext = path.extname(absPath);
+            basename = path.basename(absPath, ext);
+            if (basename.length < 4 || GENERIC_BASENAMES.has(basename.toLowerCase())) {
+                basenameRejected = true;
+            }
+            else {
+                const rows = yield table
+                    .query()
+                    .select(["path"])
+                    .where(`content LIKE '%${(0, filter_builder_1.escapeSqlString)(basename)}%' AND ${pathScope}`)
+                    .limit(limit * 4)
+                    .toArray();
+                const seen = new Set();
+                for (const row of rows) {
+                    const p = String(row.path || "");
+                    if (!p || p === absPath)
+                        continue;
+                    if (seen.has(p))
+                        continue;
+                    seen.add(p);
+                    mentions.push(p);
+                    if (mentions.length >= limit)
+                        break;
+                }
+            }
+        }
         if (opts.agent) {
             const rel = (p) => p.startsWith(`${projectRoot}/`)
                 ? p.slice(projectRoot.length + 1)
@@ -149,7 +195,18 @@ exports.related = new commander_1.Command("related")
                 console.log(`rev: ${rel(p)}\t${count}`);
             }
             if (!topDeps.length && !topRevs.length) {
-                console.log("(none)");
+                if (basenameRejected) {
+                    console.log(`(no semantic neighbors; basename '${basename}' too generic to fall back)`);
+                }
+                else if (mentions.length > 0) {
+                    console.log(`(no semantic neighbors; showing ${mentions.length} files mentioning '${basename}')`);
+                    for (const p of mentions) {
+                        console.log(`imp: ${rel(p)}\t1`);
+                    }
+                }
+                else {
+                    console.log("(none)");
+                }
             }
         }
         else {
@@ -179,6 +236,21 @@ exports.related = new commander_1.Command("related")
             else {
                 console.log("Dependents: none found");
             }
+            if (topDeps.length === 0 && topRevs.length === 0) {
+                console.log("");
+                if (basenameRejected) {
+                    console.log(`(basename '${basename}' too generic to fall back to mentions)`);
+                }
+                else if (mentions.length > 0) {
+                    console.log(`Mentions of "${basename}" in other files:`);
+                    for (const p of mentions) {
+                        const rel = p.startsWith(`${projectRoot}/`)
+                            ? p.slice(projectRoot.length + 1)
+                            : p;
+                        console.log(`  ${rel}`);
+                    }
+                }
+            }
         }
     }
     catch (error) {

package/dist/commands/search.js

@@ -712,53 +712,26 @@ Examples:
                 process.exitCode = 1;
             }
             else {
-                // In agent mode, print imports header per file
-                const seenImportFiles = new Set();
+                // Pre-pass: group by absolute path in first-occurrence order so we
+                // can collapse same-file repeats under a one-line header. Score
+                // order is preserved globally for first-of-file; siblings cluster
+                // under their first hit's rank.
+                const groups = new Map();
                 for (const r of filteredData) {
                     const absP = (_j = (_g = r.path) !== null && _g !== void 0 ? _g : (_h = r.metadata) === null || _h === void 0 ? void 0 : _h.path) !== null && _j !== void 0 ? _j : "";
-                    const relPath = absP.startsWith(effectiveRoot)
-                        ? absP.slice(effectiveRoot.length + 1)
-                        : absP;
-                    const startLine = Math.max(1, ((_o = (_l = (_k = r.startLine) !== null && _k !== void 0 ? _k : r.start_line) !== null && _l !== void 0 ? _l : (_m = r.generated_metadata) === null || _m === void 0 ? void 0 : _m.start_line) !== null && _o !== void 0 ? _o : 0) + 1);
-                    const defs = Array.isArray(r.defined_symbols)
-                        ? r.defined_symbols
-                        : [];
-                    const symbol = defs[0] || "";
-                    const role = ((_p = r.role) !== null && _p !== void 0 ? _p : "")
-                        .slice(0, 4)
-                        .toUpperCase();
-                    let hint = "";
-                    if (r.summary) {
-                        hint = ` — ${r.summary}`;
+                    const arr = groups.get(absP);
+                    if (arr) {
+                        arr.push(r);
                     }
                     else {
-                        // Extract first meaningful signature line from content
-                        const raw = (_r = (_q = r.content) !== null && _q !== void 0 ? _q : r.text) !== null && _r !== void 0 ? _r : "";
-                        const lines = raw.split("\n");
-                        for (const line of lines) {
-                            const trimmed = line.trim();
-                            // Skip empty, comments, imports, braces, and mid-line fragments
-                            if (!trimmed || trimmed.length < 5)
-                                continue;
-                            if (trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*"))
-                                continue;
-                            if (trimmed.startsWith("import ") || trimmed.startsWith("#") || trimmed.startsWith("File:"))
-                                continue;
-                            if (trimmed === "{" || trimmed === "}")
-                                continue;
-                            // Skip lines that look like continuations (start with punctuation, closing braces, or spread)
-                            if (/^[.),;:}\]|&(+`'"!~]/.test(trimmed))
-                                continue;
-                            if (trimmed.startsWith("} ") || trimmed.startsWith("- ") || trimmed.startsWith("..."))
-                                continue;
-                            // Skip lines that look like mid-expression fragments (no keyword/declaration prefix)
-                            if (/^[a-z]/.test(trimmed) && !/^(export|function|class|interface|type|const|let|var|async|return|if|for|while|switch|enum|struct|pub |fn |def |impl |mod |use )/.test(trimmed))
-                                continue;
-                            hint = ` — ${trimmed.length > 120 ? trimmed.slice(0, 117) + "..." : trimmed}`;
-                            break;
-                        }
+                        groups.set(absP, [r]);
                     }
-                    // Print file imports once per file when --imports is used
+                }
+                const seenImportFiles = new Set();
+                for (const [absP, members] of groups) {
+                    const relPath = absP.startsWith(effectiveRoot)
+                        ? absP.slice(effectiveRoot.length + 1)
+                        : absP;
                     if (options.imports && absP && !seenImportFiles.has(absP)) {
                         seenImportFiles.add(absP);
                         const imports = getImportsForFile(absP);
@@ -766,14 +739,62 @@ Examples:
                             console.log(`[imports ${relPath}] ${imports.split("\n").join(" | ")}`);
                         }
                     }
-                    const sym = symbol ? ` ${symbol}` : "";
-                    const rl = role ? ` [${role}]` : "";
-                    const score = r.score;
-                    const scoreCol = typeof score === "number" ? `\ts=${score.toFixed(3)}` : "";
-                    const explainSuffix = options.explain && r.scoreBreakdown
-                        ? `\texplain:rerank=${r.scoreBreakdown.rerank.toFixed(3)},fused=${r.scoreBreakdown.fused.toFixed(3)},boost=${r.scoreBreakdown.boost.toFixed(2)}x,score=${r.scoreBreakdown.normalized.toFixed(3)}`
-                        : "";
-                    console.log(`${relPath}:${startLine}${scoreCol}${sym}${rl}${hint}${explainSuffix}`);
+                    const grouped = members.length > 1;
+                    if (grouped) {
+                        console.log(`${relPath} (${members.length} hits):`);
+                    }
+                    for (const r of members) {
+                        const startLine = Math.max(1, ((_o = (_l = (_k = r.startLine) !== null && _k !== void 0 ? _k : r.start_line) !== null && _l !== void 0 ? _l : (_m = r.generated_metadata) === null || _m === void 0 ? void 0 : _m.start_line) !== null && _o !== void 0 ? _o : 0) + 1);
+                        const defs = Array.isArray(r.defined_symbols)
+                            ? r.defined_symbols
+                            : [];
+                        const symbol = defs[0] || "";
+                        const role = ((_p = r.role) !== null && _p !== void 0 ? _p : "")
+                            .slice(0, 4)
+                            .toUpperCase();
+                        let hint = "";
+                        if (r.summary) {
+                            hint = ` — ${r.summary}`;
+                        }
+                        else {
+                            // Extract first meaningful signature line from content
+                            const raw = (_r = (_q = r.content) !== null && _q !== void 0 ? _q : r.text) !== null && _r !== void 0 ? _r : "";
+                            const lines = raw.split("\n");
+                            for (const line of lines) {
+                                const trimmed = line.trim();
+                                // Skip empty, comments, imports, braces, and mid-line fragments
+                                if (!trimmed || trimmed.length < 5)
+                                    continue;
+                                if (trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*"))
+                                    continue;
+                                if (trimmed.startsWith("import ") || trimmed.startsWith("#") || trimmed.startsWith("File:"))
+                                    continue;
+                                if (trimmed === "{" || trimmed === "}")
+                                    continue;
+                                // Skip lines that look like continuations (start with punctuation, closing braces, or spread)
+                                if (/^[.),;:}\]|&(+`'"!~]/.test(trimmed))
+                                    continue;
+                                if (trimmed.startsWith("} ") || trimmed.startsWith("- ") || trimmed.startsWith("..."))
+                                    continue;
+                                // Skip lines that look like mid-expression fragments (no keyword/declaration prefix)
+                                if (/^[a-z]/.test(trimmed) && !/^(export|function|class|interface|type|const|let|var|async|return|if|for|while|switch|enum|struct|pub |fn |def |impl |mod |use )/.test(trimmed))
+                                    continue;
+                                hint = ` — ${trimmed.length > 120 ? trimmed.slice(0, 117) + "..." : trimmed}`;
+                                break;
+                            }
+                        }
+                        const sym = symbol ? ` ${symbol}` : "";
+                        const rl = role ? ` [${role}]` : "";
+                        const score = r.score;
+                        const scoreCol = typeof score === "number" ? `\ts=${score.toFixed(3)}` : "";
+                        const explainSuffix = options.explain && r.scoreBreakdown
+                            ? `\texplain:rerank=${r.scoreBreakdown.rerank.toFixed(3)},fused=${r.scoreBreakdown.fused.toFixed(3)},boost=${r.scoreBreakdown.boost.toFixed(2)}x,score=${r.scoreBreakdown.normalized.toFixed(3)}`
+                            : "";
+                        const locator = grouped
+                            ? `  :${startLine}`
+                            : `${relPath}:${startLine}`;
+                        console.log(`${locator}${scoreCol}${sym}${rl}${hint}${explainSuffix}`);
+                    }
                 }
             }
             // Agent trace (compact)

package/dist/commands/test-find.js

@@ -93,14 +93,22 @@ exports.testFind = new commander_1.Command("test")
         const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
         if (opts.agent) {
             for (const t of tests) {
-                const hopLabel = t.hops === 0 ? "direct" : `${t.hops}-hop`;
+                const hopLabel = t.hops === -1
+                    ? "via-import"
+                    : t.hops === 0
+                        ? "direct"
+                        : `${t.hops}-hop`;
                 console.log(`${rel(t.file)}:${t.line + 1}\t${t.symbol}\t${hopLabel}`);
             }
         }
         else {
             console.log(`Tests for ${target}:\n`);
             for (const t of tests) {
-                const hopLabel = t.hops === 0 ? "calls directly" : `${t.hops} hop${t.hops > 1 ? "s" : ""} away`;
+                const hopLabel = t.hops === -1
+                    ? "via import"
+                    : t.hops === 0
+                        ? "calls directly"
+                        : `${t.hops} hop${t.hops > 1 ? "s" : ""} away`;
                 console.log(`  ${rel(t.file)}:${t.line + 1}  ${t.symbol}  (${hopLabel})`);
             }
         }

package/dist/commands/trace.js

@@ -43,6 +43,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.trace = void 0;
+const fs = __importStar(require("node:fs"));
 const commander_1 = require("commander");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const formatter_1 = require("../lib/output/formatter");
@@ -50,6 +51,9 @@ const vector_db_1 = require("../lib/store/vector-db");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
+const useColors = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => (useColors ? `\x1b[2m${s}\x1b[22m` : s);
+const bold = (s) => (useColors ? `\x1b[1m${s}\x1b[22m` : s);
 function formatTraceAgent(graph, projectRoot) {
     if (!graph.center)
         return "(not found)";
@@ -73,6 +77,117 @@ function formatTraceAgent(graph, projectRoot) {
     }
     return lines.join("\n");
 }
+function findCallSiteSnippet(fileCache, callerFile, callerLine, targetSymbol) {
+    if (!callerFile)
+        return null;
+    let lines = fileCache.get(callerFile);
+    if (!lines) {
+        try {
+            lines = fs.readFileSync(callerFile, "utf-8").split("\n");
+        }
+        catch (_a) {
+            return null;
+        }
+        fileCache.set(callerFile, lines);
+    }
+    // Search a bounded window starting at the caller's definition line.
+    const start = Math.max(0, callerLine);
+    const end = Math.min(lines.length, callerLine + 200);
+    const wordRe = new RegExp(`\\b${targetSymbol.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+    for (let i = start; i < end; i++) {
+        if (wordRe.test(lines[i])) {
+            return { snippet: lines[i].trim(), snippetLine: i };
+        }
+    }
+    // Window didn't contain the symbol — chunker rolled the reference up to a
+    // parent scope. Skip the snippet rather than showing a misleading default;
+    // the caller's file:line is still emitted.
+    return null;
+}
+function buildInboundTree(callerTree, targetSymbol, fileCache, withSnippets, limit) {
+    var _a, _b, _c;
+    const out = [];
+    // Dedupe by call-site location: when getCallers returns multiple chunks of
+    // the same file (e.g. several methods of a class) that all reference the
+    // target on the same line, collapse them into one row.
+    const seen = new Set();
+    for (const t of callerTree) {
+        const snippet = withSnippets
+            ? findCallSiteSnippet(fileCache, t.node.file, t.node.line, targetSymbol)
+            : null;
+        const dedupeKey = `${t.node.file}:${(_a = snippet === null || snippet === void 0 ? void 0 : snippet.snippetLine) !== null && _a !== void 0 ? _a : t.node.line}`;
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        out.push({
+            symbol: t.node.symbol,
+            file: t.node.file,
+            line: t.node.line,
+            snippet: (_b = snippet === null || snippet === void 0 ? void 0 : snippet.snippet) !== null && _b !== void 0 ? _b : null,
+            snippetLine: (_c = snippet === null || snippet === void 0 ? void 0 : snippet.snippetLine) !== null && _c !== void 0 ? _c : null,
+            callers: buildInboundTree(t.callers, t.node.symbol, fileCache, withSnippets, limit),
+        });
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+function formatInboundAgent(center, tree, projectRoot, withSnippets) {
+    const rel = (p) => p.startsWith(projectRoot) ? p.slice(projectRoot.length + 1) : p;
+    const lines = [];
+    lines.push(`${center.symbol}\t${rel(center.file)}:${center.line + 1}\t${center.role}`);
+    const walk = (nodes, depth) => {
+        var _a, _b;
+        for (const n of nodes) {
+            const prefix = "  ".repeat(depth);
+            const loc = n.file ? `${rel(n.file)}:${((_a = n.snippetLine) !== null && _a !== void 0 ? _a : n.line) + 1}` : "(not indexed)";
+            const cols = withSnippets
+                ? `${loc}\t${n.symbol}\t${(_b = n.snippet) !== null && _b !== void 0 ? _b : ""}`
+                : `${loc}\t${n.symbol}`;
+            lines.push(`${prefix}${cols}`);
+            walk(n.callers, depth + 1);
+        }
+    };
+    walk(tree, 0);
+    return lines.join("\n");
+}
+function formatInboundHuman(center, tree, projectRoot, withSnippets) {
+    const rel = (p) => p.startsWith(projectRoot) ? p.slice(projectRoot.length + 1) : p;
+    const flatCount = (() => {
+        let n = 0;
+        const walk = (nodes) => {
+            for (const node of nodes) {
+                n++;
+                walk(node.callers);
+            }
+        };
+        walk(tree);
+        return n;
+    })();
+    const lines = [];
+    lines.push(`${bold(`inbound callers of ${center.symbol}`)} ${dim(`(${flatCount})`)}`);
+    lines.push(`  ${dim(`${rel(center.file)}:${center.line + 1}  [${center.role}]`)}`);
+    if (tree.length === 0) {
+        lines.push(dim("  (none in scope)"));
+        return lines.join("\n");
+    }
+    const walk = (nodes, depth) => {
+        var _a;
+        for (const n of nodes) {
+            const indent = "  ".repeat(depth + 1);
+            const loc = n.file
+                ? `${rel(n.file)}:${((_a = n.snippetLine) !== null && _a !== void 0 ? _a : n.line) + 1}`
+                : "(not indexed)";
+            lines.push(`${indent}${n.symbol}  ${dim(loc)}`);
+            if (withSnippets && n.snippet) {
+                lines.push(`${indent}  ${dim(n.snippet)}`);
+            }
+            walk(n.callers, depth + 1);
+        }
+    };
+    walk(tree, 0);
+    return lines.join("\n");
+}
 exports.trace = new commander_1.Command("trace")
     .description("Trace the call graph for a symbol")
     .argument("<symbol>", "The symbol to trace")
@@ -81,9 +196,13 @@ exports.trace = new commander_1.Command("trace")
     .option("--in <subpath>", "Restrict to a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--agent", "Compact output for AI agents", false)
+    .option("--inbound", "Show only callers, with call-site snippets", false)
+    .option("--no-snippets", "Suppress call-site snippets in --inbound output")
+    .option("--limit <n>", "Max callers shown per node in --inbound (default 10)", "10")
     .action((symbol, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const depth = Math.min(Math.max(Number.parseInt(opts.depth || "1", 10), 1), 3);
+    const inboundLimit = Math.min(Math.max(Number.parseInt(opts.limit || "10", 10), 1), 30);
     const root = (0, project_registry_1.resolveRootOrExit)(opts.root);
     if (root === null)
         return;
@@ -100,14 +219,32 @@ exports.trace = new commander_1.Command("trace")
         });
         const graphBuilder = new graph_builder_1.GraphBuilder(vectorDb, scope.pathPrefix, scope.excludePrefixes);
         const graph = yield graphBuilder.buildGraphMultiHop(symbol, depth);
-        if (opts.agent) {
+        if (opts.inbound) {
+            if (!graph.center) {
+                console.log(opts.agent ? "(not found)" : `Symbol not found: ${symbol}`);
+                process.exitCode = 1;
+            }
+            else {
+                const fileCache = new Map();
+                const withSnippets = opts.snippets !== false;
+                const tree = buildInboundTree(graph.callerTree, symbol, fileCache, withSnippets, inboundLimit);
+                if (opts.agent) {
+                    console.log(formatInboundAgent(graph.center, tree, projectRoot, withSnippets));
+                }
+                else {
+                    console.log(formatInboundHuman(graph.center, tree, projectRoot, withSnippets));
+                }
+            }
+        }
+        else if (opts.agent) {
             console.log(formatTraceAgent(graph, projectRoot));
+            if (!graph.center)
+                process.exitCode = 1;
         }
         else {
             console.log((0, formatter_1.formatTrace)(graph, { symbol }));
-        }
-        if (!graph.center) {
-            process.exitCode = 1;
+            if (!graph.center)
+                process.exitCode = 1;
         }
     }
     catch (error) {

package/dist/lib/graph/impact.js

@@ -95,6 +95,11 @@ function expandFileSymbols(symbols, vectorDb, projectRoot, excludePrefixes) {
 }
 /**
  * Find test files that exercise a set of symbols, using reverse call graph traversal.
+ * When the call-graph walk returns nothing, falls back to test files that
+ * reference the symbol via referenced_symbols or textual content match —
+ * catching the common case where a test imports a symbol but doesn't call it
+ * through the graph the chunker captures (UI components, mocked modules, etc).
+ * Fallback hits are tagged with hops = -1.
  */
 function findTests(symbols_1, vectorDb_1, projectRoot_1) {
     return __awaiter(this, arguments, void 0, function* (symbols, vectorDb, projectRoot, depth = 1, excludePrefixes) {
@@ -105,9 +110,55 @@ function findTests(symbols_1, vectorDb_1, projectRoot_1) {
         for (const symbol of expanded) {
             yield walkCallers(symbol, graphBuilder, testHits, 0, depth, new Set());
         }
+        if (testHits.size === 0) {
+            const importFiles = yield findImportFallbackTests(expanded, vectorDb, projectRoot, excludePrefixes);
+            for (const file of importFiles) {
+                testHits.set(`${file}:(referenced)`, {
+                    file,
+                    symbol: "(referenced)",
+                    line: 0,
+                    hops: -1,
+                });
+            }
+        }
         return [...testHits.values()].sort((a, b) => a.hops - b.hops || a.file.localeCompare(b.file));
     });
 }
+function findImportFallbackTests(symbols, vectorDb, projectRoot, excludePrefixes) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const files = new Set();
+        // Signal 1: referenced_symbols match (precise; works when the chunker
+        // captured call references in test bodies).
+        const dependents = yield findDependents(symbols, vectorDb, projectRoot, undefined, 50, excludePrefixes);
+        for (const d of dependents) {
+            if (isTestPath(d.file))
+                files.add(d.file);
+        }
+        // Signal 2: content LIKE match (textual; survives chunker quirks where a
+        // test body's referenced_symbols ends up empty).
+        const table = yield vectorDb.ensureTable();
+        const prefix = projectRoot.endsWith("/") ? projectRoot : `${projectRoot}/`;
+        let pathScope = `path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`;
+        for (const ex of excludePrefixes !== null && excludePrefixes !== void 0 ? excludePrefixes : []) {
+            const exNorm = ex.endsWith("/") ? ex : `${ex}/`;
+            pathScope += ` AND path NOT LIKE '${(0, filter_builder_1.escapeSqlString)(exNorm)}%'`;
+        }
+        for (const sym of symbols) {
+            const rows = yield table
+                .query()
+                .select(["path"])
+                .where(`content LIKE '%${(0, filter_builder_1.escapeSqlString)(sym)}%' AND ${pathScope}`)
+                .limit(100)
+                .toArray();
+            for (const row of rows) {
+                const p = String(row.path || "");
+                if (isTestPath(p))
+                    files.add(p);
+            }
+        }
+        return files;
+    });
+}
 function walkCallers(symbol, graphBuilder, testHits, currentHop, maxDepth, visited) {
     return __awaiter(this, void 0, void 0, function* () {
         if (visited.has(symbol))

package/dist/lib/utils/tests-footer.js

@@ -0,0 +1,78 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchTestsForFooter = fetchTestsForFooter;
+exports.renderTestsFooterAgent = renderTestsFooterAgent;
+exports.renderTestsFooterHuman = renderTestsFooterHuman;
+const impact_1 = require("../graph/impact");
+const FOOTER_TIMEOUT_MS = 1500;
+const MAX_SHOWN = 5;
+const useColors = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => (useColors ? `\x1b[2m${s}\x1b[22m` : s);
+function withTimeout(p, ms) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), ms);
+        });
+        try {
+            return yield Promise.race([p, timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    });
+}
+function fetchTestsForFooter(symbol, vectorDb, pathPrefix, excludePrefixes) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return withTimeout((0, impact_1.findTests)([symbol], vectorDb, pathPrefix, 1, excludePrefixes), FOOTER_TIMEOUT_MS);
+    });
+}
+function relPath(p, projectRoot) {
+    return p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
+}
+function hopLabelAgent(hops) {
+    if (hops === -1)
+        return "via-import";
+    if (hops === 0)
+        return "direct";
+    return `${hops}-hop`;
+}
+function hopLabelHuman(hops) {
+    if (hops === -1)
+        return "via import";
+    if (hops === 0)
+        return "direct";
+    return `${hops} hop${hops > 1 ? "s" : ""}`;
+}
+function renderTestsFooterAgent(tests, projectRoot) {
+    const lines = [];
+    for (const t of tests.slice(0, MAX_SHOWN)) {
+        lines.push(`t: ${relPath(t.file, projectRoot)}:${t.line + 1}\t${t.symbol}\t${hopLabelAgent(t.hops)}`);
+    }
+    if (tests.length > MAX_SHOWN) {
+        lines.push(`t: ... ${tests.length - MAX_SHOWN} more`);
+    }
+    return lines;
+}
+function renderTestsFooterHuman(tests, projectRoot) {
+    const lines = [];
+    lines.push("");
+    lines.push(`tests (${tests.length}):`);
+    for (const t of tests.slice(0, MAX_SHOWN)) {
+        lines.push(`  ${t.symbol.padEnd(25)} ${dim(`${relPath(t.file, projectRoot)}:${t.line + 1}`)} ${dim(`(${hopLabelHuman(t.hops)})`)}`);
+    }
+    if (tests.length > MAX_SHOWN) {
+        lines.push(dim(`  ... and ${tests.length - MAX_SHOWN} more`));
+    }
+    return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {

package/plugins/grepmax/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",

package/plugins/grepmax/skills/grepmax/SKILL.md

@@ -53,7 +53,7 @@ gmax "auth" --root ~/other/project --agent # search a different project
 gmax "auth" --imports --agent              # show file imports per file
 ```
 
-Output: `file:line symbol [ROLE] — signature_hint` (one line per result)
+Output: `file:line symbol [ROLE] — signature_hint` (one line per result). When multiple hits land in the same file, they collapse under a `path/to/file.ts (N hits):` header with indented children — saves the repeated path prefix.
 
 All search flags: `--agent --plain -m <n> --per-file <n> --min-score <n> --root <dir> --file <name> --exclude <prefix> --lang <ext> --role <role> --symbol --imports --name <regex> -C <n> --compact --content --scores --skeleton --explain --context-for-llm --budget <tokens>`
 
@@ -87,6 +87,9 @@ gmax trace handleAuth                      # 1-hop: callers + callees
 gmax trace handleAuth -d 2                 # 2-hop: callers-of-callers
 gmax trace handleAuth --root ~/project     # trace in a different project
 gmax trace handleAuth --agent              # compact: symbol\tpath:line, <- callers, -> callees
+gmax trace handleAuth --inbound --agent    # callers-only with call-site snippets (path:line\tsymbol\tsnippet)
+gmax trace handleAuth --inbound --no-snippets   # drop the snippet column
+gmax trace handleAuth --inbound --limit 20      # show up to 20 callers (default 10, max 30)
 ```
 
 ### Extract — `gmax extract <symbol>`
@@ -95,7 +98,9 @@ gmax extract handleAuth                    # full function body with line number
 gmax extract handleAuth --agent            # compact: path:start-end then raw code
 gmax extract handleAuth --imports          # prepend file imports
 gmax extract handleAuth --root ~/project   # extract from different project
+gmax extract handleAuth --no-tests         # suppress tests footer (default-on)
 ```
+Output ends with a `--- tests:` footer listing tests that exercise the symbol (default-on; opt-out with `--no-tests`).
 
 ### Peek — `gmax peek <symbol>`
 ```
@@ -103,7 +108,9 @@ gmax peek handleAuth                       # signature + callers + callees
 gmax peek handleAuth --agent               # compact TSV output
 gmax peek handleAuth -d 2                  # 2-hop callers
 gmax peek handleAuth --root ~/project      # peek in different project
+gmax peek handleAuth --no-tests            # suppress tests footer (default-on)
 ```
+Agent output ends with `t: <test-file>:line\t<test-symbol>\t<hop-label>` rows where hop-label is `direct`, `N-hop`, or `via-import`.
 
 ### Skeleton — `gmax skeleton <target>`
 ```
@@ -124,6 +131,7 @@ gmax project --root ~/other/project        # different project
 gmax related src/lib/index/syncer.ts       # dependencies + dependents
 gmax related src/lib/index/syncer.ts --root ~/project
 ```
+When both directions are empty, falls back to files mentioning the input file's basename. Generic basenames (`index`, `main`, `lib`, etc.) skip the fallback.
 
 ### Commit history — `gmax log <path-or-symbol>`
 ```
@@ -148,11 +156,12 @@ gmax symbols --agent                       # compact: symbol\tpath:line\tcount
 
 ### Test — `gmax test <symbol|file>`
 ```
-gmax test handleAuth                   # tests calling handleAuth
+gmax test handleAuth                   # tests calling handleAuth (call-graph + import-fallback)
 gmax test src/lib/auth.ts              # tests for symbols in this file
 gmax test handleAuth -d 2              # 2-hop: tests calling callers too
 gmax test handleAuth --agent           # compact output
 ```
+Hop labels: `direct` (calls the symbol), `N-hop` (calls a transitive caller), `via-import` (test references the symbol via import or mock when no call-graph match exists).
 
 ### Impact — `gmax impact <symbol|file>`
 ```