grepmax 0.16.3 → 0.16.5

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.5",
   "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.5",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",

package/plugins/grepmax/hooks/start.js

@@ -175,8 +175,28 @@ async function main() {
   const response = {
     hookSpecificOutput: {
       hookEventName: "SessionStart",
-      additionalContext:
-        'gmax ready. Use Bash(gmax "query" --agent) for search (one line per result, 89% fewer tokens). Bash(gmax extract <symbol>) for full function body. Bash(gmax peek <symbol>) for quick overview (sig+callers+callees). Bash(gmax trace <symbol>) for call graphs. Bash(gmax skeleton <path>) for structure. Bash(gmax diff [ref]) for git changes. Bash(gmax test <symbol>) for test coverage. Bash(gmax impact <symbol>) for blast radius. Bash(gmax similar <symbol>) for similar code. Bash(gmax context "topic" --budget 4000) for topic summary. Bash(gmax status) to check indexed projects. Role tags in results: [DEFI]=definition, [ORCH]=orchestration, [IMPL]=implementation, [DOCS]=docs. --agent flag works on search, trace, symbols, related, recent, status, project, extract, peek, diff, test, impact, similar. If search says "not added yet", run Bash(gmax add). If results look stale, run Bash(gmax index) to repair.',
+      additionalContext: `gmax ready. Add --agent to any command for compact output (~89% fewer tokens).
+
+Find:
+  gmax "topic"                       semantic search
+  gmax similar <symbol>              similar code
+
+Understand:
+  gmax peek <symbol>                 signature + callers + callees + tests
+  gmax extract <symbol>              full body + tests
+  gmax trace <symbol>                call graph (--inbound = callers + snippets)
+  gmax test <symbol>                 tests for symbol
+  gmax impact <symbol>               blast radius
+
+Survey:
+  gmax skeleton <file>               file structure (file path, NOT a directory)
+  gmax context "topic" --budget 4000 multi-file topic summary
+  gmax log <path-or-symbol>          git commits (replaces recent/diff)
+  gmax status                        indexed projects
+
+Scope flags: --root <name|path>, --in <subpath>, --exclude <subpath>.
+Roles in results: [DEFI] [ORCH] [IMPL] [DOCS].
+Recovery: "not added yet" → gmax add; stale results → gmax index.`,
     },
   };
   process.stdout.write(JSON.stringify(response));

package/plugins/grepmax/hooks/subagent-start.js

@@ -52,7 +52,7 @@ async function main() {
     hookSpecificOutput: {
       hookEventName: "SubagentStart",
       additionalContext:
-        'gmax semantic search is available. Use Bash(gmax "query" --agent) for concept search, Bash(gmax peek <symbol>) for overview, Bash(gmax extract <symbol>) for full body, Bash(gmax trace <symbol>) for call graph. If results look stale, run Bash(gmax index) to repair.',
+        'gmax available: gmax "query" --agent (search), gmax peek/extract/trace <symbol> --agent (symbol info / call graph). Stale results → gmax index.',
     },
   };
   process.stdout.write(JSON.stringify(response));

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>`
 ```