grepmax 0.17.2 → 0.17.4

package/README.md

@@ -64,6 +64,7 @@ gmax log src/lib/auth.ts                 # Git commit history for a path or symb
 gmax test handleAuth                     # Find tests via reverse call graph
 gmax impact handleAuth                   # Dependents + affected tests
 gmax similar handleAuth                  # Find similar code patterns
+gmax dead handleAuth                     # Unused-symbol check via call graph (DEAD / PUBLIC EXPORT / LIVE)
 gmax context "auth system" --budget 4000 # Token-budgeted topic summary
 ```
 
@@ -121,6 +122,7 @@ Plugins auto-update when you run `npm install -g grepmax@latest` — no need to
 | `trace_calls` | Call graph: importers, callers (multi-hop), callees with file:line. |
 | `extract_symbol` | Complete function/class body by symbol name. |
 | `peek_symbol` | Compact overview: signature + callers + callees. |
+| `dead` | Unused-symbol check via call graph. Returns `DEAD`, `PUBLIC EXPORT`, or `LIVE` with caller count. |
 | `list_symbols` | Indexed symbols with role and export status. |
 | `index_status` | Index health: chunks, files, projects, watcher status. |
 | `summarize_project` | Project overview: languages, structure, key symbols, entry points. |
@@ -277,6 +279,7 @@ fixtures/
 | `GMAX_WORKER_THREADS` | Worker threads for embedding | 50% of cores |
 | `GMAX_DEBUG` | Debug logging | Off |
 | `GMAX_SUMMARIZER` | Enable summarizer auto-start (`1`) | Off |
+| `GMAX_RERANK` | Enable ColBERT rerank (`1`) — off by default since v0.17.1 ([why](docs/known-limitations.md)) | Off |
 
 ## Troubleshooting
 
@@ -293,6 +296,20 @@ gmax watch stop && gmax watch --daemon -b  # Restart daemon
 
 See [CLAUDE.md](CLAUDE.md) for development setup, commands, and architecture details.
 
+### Benchmarks
+
+Two evaluation harnesses live in the repo. Both emit stable JSON via `:json` variants.
+
+```bash
+pnpm bench:recall          # 97-case internal eval against gmax's own repo
+pnpm bench:recall:json
+pnpm bench:oss             # P1 definition-lookup across express, lodash, platform (sverklo-bench fixtures)
+pnpm bench:oss:json
+GMAX_EVAL_RERANK=1 pnpm bench:oss   # toggle ColBERT rerank
+```
+
+The OSS bench requires the fixture repos to be indexed first — see [`docs/known-limitations.md`](docs/known-limitations.md) for the most recent rerank-on-vs-off comparison across 4 datasets / 131 cases.
+
 ## Attribution
 
 grepmax is built upon the foundation of [mgrep](https://github.com/mixedbread-ai/mgrep) by MixedBread. See the [NOTICE](NOTICE) file for details.

package/dist/commands/context.js

@@ -44,18 +44,111 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.context = void 0;
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const searcher_1 = require("../lib/search/searcher");
 const skeleton_1 = require("../lib/skeleton");
 const vector_db_1 = require("../lib/store/vector-db");
-const filter_builder_1 = require("../lib/utils/filter-builder");
+const arrow_1 = require("../lib/utils/arrow");
 const exit_1 = require("../lib/utils/exit");
+const filter_builder_1 = require("../lib/utils/filter-builder");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
-const arrow_1 = require("../lib/utils/arrow");
 function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
+function addSection(state, text, budget) {
+    const tokens = estimateTokens(text);
+    if (state.tokensUsed + tokens > budget)
+        return false;
+    state.sections.push(text);
+    state.tokensUsed += tokens;
+    return true;
+}
+function relPath(projectRoot, p) {
+    return p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
+}
+function chunkPath(chunk) {
+    const metadata = chunk.metadata;
+    return String(chunk.path || (metadata === null || metadata === void 0 ? void 0 : metadata.path) || "");
+}
+function chunkStartLine(chunk) {
+    var _a, _b, _c, _d;
+    return Number((_d = (_b = (_a = chunk.start_line) !== null && _a !== void 0 ? _a : chunk.startLine) !== null && _b !== void 0 ? _b : (_c = chunk.generated_metadata) === null || _c === void 0 ? void 0 : _c.start_line) !== null && _d !== void 0 ? _d : 0);
+}
+function chunkEndLine(chunk) {
+    var _a, _b, _c, _d;
+    const start = chunkStartLine(chunk);
+    return Number((_d = (_b = (_a = chunk.end_line) !== null && _a !== void 0 ? _a : chunk.endLine) !== null && _b !== void 0 ? _b : (_c = chunk.generated_metadata) === null || _c === void 0 ? void 0 : _c.end_line) !== null && _d !== void 0 ? _d : start);
+}
+function resolveExistingPath(target, root, projectRoot) {
+    const candidates = [
+        path.isAbsolute(target) ? target : path.resolve(root, target),
+        path.resolve(projectRoot, target),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function renderPathContext(target, absPath, projectRoot, budget) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const state = {
+            sections: [],
+            tokensUsed: 0,
+        };
+        const header = `=== Context: "${target}" ===`;
+        addSection(state, header, budget);
+        const stat = fs.statSync(absPath);
+        const targetSection = [
+            "\n## Target",
+            `${relPath(projectRoot, absPath)} [${stat.isDirectory() ? "directory" : "file"}]`,
+        ].join("\n");
+        addSection(state, targetSection, budget);
+        if (stat.isDirectory()) {
+            const entries = fs
+                .readdirSync(absPath, { withFileTypes: true })
+                .filter((entry) => !entry.name.startsWith("."))
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .slice(0, 40)
+                .map((entry) => `${entry.isDirectory() ? "dir " : "file"} ${entry.name}`);
+            if (entries.length > 0) {
+                addSection(state, ["\n## Directory Entries", ...entries].join("\n"), budget);
+            }
+            return state;
+        }
+        const content = fs.readFileSync(absPath, "utf-8");
+        const skeletonizer = new skeleton_1.Skeletonizer();
+        yield skeletonizer.init();
+        if (skeletonizer.isSupported(absPath).supported) {
+            try {
+                const result = yield skeletonizer.skeletonizeFile(absPath, content);
+                if (result.success) {
+                    addSection(state, [
+                        "\n## File Structure",
+                        `--- ${relPath(projectRoot, absPath)} (skeleton, ~${result.tokenEstimate} tokens) ---`,
+                        result.skeleton,
+                    ].join("\n"), budget);
+                }
+            }
+            catch (_a) {
+                // Skeleton is a convenience in path mode; fall through to excerpt.
+            }
+        }
+        const lines = content.split("\n");
+        const excerptLines = lines.slice(0, Math.min(lines.length, 120));
+        const omitted = lines.length > excerptLines.length
+            ? `\n... (+${lines.length - excerptLines.length} more lines)`
+            : "";
+        addSection(state, [
+            "\n## File Excerpt",
+            `--- ${relPath(projectRoot, absPath)}:1 ---`,
+            `${excerptLines.join("\n")}${omitted}`,
+        ].join("\n"), budget);
+        return state;
+    });
+}
 exports.context = new commander_1.Command("context")
     .description("Generate a token-budgeted topic summary (search + skeleton + extract)")
     .argument("<topic>", "Natural language topic or directory path")
@@ -64,7 +157,7 @@ exports.context = new commander_1.Command("context")
     .option("--root <dir>", "Project root directory")
     .option("--agent", "Compact output for AI agents", false)
     .action((topic, opts) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    var _a, _b, _c, _d, _e;
     const budget = Number.parseInt(opts.budget || "4000", 10) || 4000;
     const maxResults = Number.parseInt(opts.maxResults || "10", 10) || 10;
     let vectorDb = null;
@@ -75,8 +168,14 @@ exports.context = new commander_1.Command("context")
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
         const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
+        const pathTarget = resolveExistingPath(topic, root, projectRoot);
+        if (pathTarget) {
+            const rendered = yield renderPathContext(topic, pathTarget, projectRoot, budget);
+            rendered.sections.push(`\n(~${rendered.tokensUsed}/${budget} tokens used)`);
+            console.log(rendered.sections.join("\n"));
+            return;
+        }
         const searcher = new searcher_1.Searcher(vectorDb);
-        const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
         // Phase 1: Semantic search
         const response = yield searcher.search(topic, maxResults, { rerank: true }, {}, projectRoot);
         if (response.data.length === 0) {
@@ -94,11 +193,11 @@ exports.context = new commander_1.Command("context")
         const entryPoints = orchestrators.length > 0 ? orchestrators : response.data.slice(0, 3);
         const epSection = ["\n## Entry Points"];
         for (const r of entryPoints.slice(0, 5)) {
-            const p = String(r.path || ((_b = r.metadata) === null || _b === void 0 ? void 0 : _b.path) || "");
-            const line = Number((_c = r.start_line) !== null && _c !== void 0 ? _c : 0);
-            const sym = (_e = (_d = (0, arrow_1.toArr)(r.defined_symbols)) === null || _d === void 0 ? void 0 : _d[0]) !== null && _e !== void 0 ? _e : "";
+            const p = chunkPath(r);
+            const line = chunkStartLine(r);
+            const sym = (_c = (_b = (0, arrow_1.toArr)(r.defined_symbols)) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : "";
             const role = String(r.role || "IMPLEMENTATION");
-            epSection.push(`${rel(p)}:${line + 1} ${sym} [${role}]`);
+            epSection.push(`${relPath(projectRoot, p)}:${line + 1} ${sym} [${role}]`);
         }
         const epText = epSection.join("\n");
         if (tokensUsed + estimateTokens(epText) <= budget) {
@@ -109,24 +208,24 @@ exports.context = new commander_1.Command("context")
         const topChunks = entryPoints.slice(0, 3);
         const bodySection = ["\n## Key Functions"];
         for (const r of topChunks) {
-            const absP = String(r.path || "");
-            const startLine = Number((_f = r.start_line) !== null && _f !== void 0 ? _f : 0);
-            const endLine = Number((_g = r.end_line) !== null && _g !== void 0 ? _g : startLine);
-            const sym = (_j = (_h = (0, arrow_1.toArr)(r.defined_symbols)) === null || _h === void 0 ? void 0 : _h[0]) !== null && _j !== void 0 ? _j : "";
+            const absP = chunkPath(r);
+            const startLine = chunkStartLine(r);
+            const endLine = chunkEndLine(r);
+            const sym = (_e = (_d = (0, arrow_1.toArr)(r.defined_symbols)) === null || _d === void 0 ? void 0 : _d[0]) !== null && _e !== void 0 ? _e : "";
             try {
                 const content = fs.readFileSync(absP, "utf-8");
                 const allLines = content.split("\n");
                 const body = allLines
                     .slice(startLine, Math.min(endLine + 1, allLines.length))
                     .join("\n");
-                const blob = `\n--- ${rel(absP)}:${startLine + 1} ${sym} ---\n${body}`;
+                const blob = `\n--- ${relPath(projectRoot, absP)}:${startLine + 1} ${sym} ---\n${body}`;
                 const blobTokens = estimateTokens(blob);
                 if (tokensUsed + blobTokens > budget)
                     break;
                 bodySection.push(blob);
                 tokensUsed += blobTokens;
             }
-            catch (_k) {
+            catch (_f) {
                 // File not readable — skip
             }
         }
@@ -135,9 +234,7 @@ exports.context = new commander_1.Command("context")
         }
         // Phase 4: File skeletons for unique files
         const uniqueFiles = [
-            ...new Set(response.data
-                .map((r) => String(r.path || ""))
-                .filter(Boolean)),
+            ...new Set(response.data.map((r) => chunkPath(r)).filter(Boolean)),
         ].slice(0, 5);
         const skelSection = ["\n## File Structure"];
         const skeletonizer = new skeleton_1.Skeletonizer();
@@ -150,14 +247,14 @@ exports.context = new commander_1.Command("context")
                 const result = yield skeletonizer.skeletonizeFile(absP, content);
                 if (!result.success)
                     continue;
-                const blob = `\n--- ${rel(absP)} (skeleton, ~${result.tokenEstimate} tokens) ---\n${result.skeleton}`;
+                const blob = `\n--- ${relPath(projectRoot, absP)} (skeleton, ~${result.tokenEstimate} tokens) ---\n${result.skeleton}`;
                 const blobTokens = estimateTokens(blob);
                 if (tokensUsed + blobTokens > budget)
                     break;
                 skelSection.push(blob);
                 tokensUsed += blobTokens;
             }
-            catch (_l) {
+            catch (_g) {
                 // Skip unreadable files
             }
         }
@@ -195,7 +292,7 @@ exports.context = new commander_1.Command("context")
             if (topRelated.length > 0) {
                 const relSection = ["\n## Related Files"];
                 for (const [p, count] of topRelated) {
-                    relSection.push(`${rel(p)} — ${count} shared symbol${count > 1 ? "s" : ""}`);
+                    relSection.push(`${relPath(projectRoot, p)} — ${count} shared symbol${count > 1 ? "s" : ""}`);
                 }
                 const relText = relSection.join("\n");
                 if (tokensUsed + estimateTokens(relText) <= budget) {
@@ -218,7 +315,7 @@ exports.context = new commander_1.Command("context")
             try {
                 yield vectorDb.close();
             }
-            catch (_m) { }
+            catch (_h) { }
         }
         yield (0, exit_1.gracefulExit)();
     }