grepmax 0.26.48 → 0.26.50

package/dist/lib/search/diagnostics.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchDiagnosticCollector = void 0;
+const stages = [
+    "vector",
+    "fts",
+    "rrf",
+    "fusion",
+    "stage1",
+    "pooled",
+    "rerank",
+    "scored",
+    "dedup",
+    "final",
+];
+const rankingKeys = [
+    "GMAX_PRE_K",
+    "GMAX_STAGE1_K",
+    "GMAX_STAGE2_K",
+    "GMAX_RERANK_TOP",
+    "GMAX_RERANK_BLEND",
+    "GMAX_MAX_PER_FILE",
+    "GMAX_DEF_BOOST",
+    "GMAX_CONCENTRATION_THRESHOLD",
+    "GMAX_ANCHOR_PENALTY",
+    "GMAX_TEST_PENALTY",
+    "GMAX_DOC_PENALTY",
+    "GMAX_PAGERANK",
+    "GMAX_PR_WEIGHT",
+    "GMAX_SEED_FILE_W",
+    "GMAX_SEED_SYMBOL_DEF_W",
+    "GMAX_SEED_SYMBOL_REF_W",
+    "GMAX_SEED_MAX_RANK",
+    "GMAX_ANN",
+    "GMAX_ANN_NPROBES",
+    "GMAX_ANN_MAX_NPROBES",
+];
+const key = (r) => r.id || `${r.path}:${r.chunk_index}`;
+/** Request-local pointer trace. No content, vectors or additional database reads. */
+class SearchDiagnosticCollector {
+    constructor() {
+        this.ranks = new Map();
+        this.cohort = [];
+        this.total = 0;
+        this.fileLimited = new Set();
+    }
+    noteFileLimit(record) {
+        this.fileLimited.add(key(record));
+    }
+    outcome(record) {
+        var _a, _b, _c, _d, _e, _f;
+        const id = key(record);
+        if ((_a = this.ranks.get("final")) === null || _a === void 0 ? void 0 : _a.has(id))
+            return "returned";
+        if (!((_b = this.ranks.get("stage1")) === null || _b === void 0 ? void 0 : _b.has(id)))
+            return "stage1-cut";
+        if (!((_c = this.ranks.get("pooled")) === null || _c === void 0 ? void 0 : _c.has(id)) &&
+            !((_d = this.ranks.get("scored")) === null || _d === void 0 ? void 0 : _d.has(id)))
+            return "pooled-cut";
+        if (!((_e = this.ranks.get("scored")) === null || _e === void 0 ? void 0 : _e.has(id)))
+            return "not-scored";
+        if (!((_f = this.ranks.get("dedup")) === null || _f === void 0 ? void 0 : _f.has(id)))
+            return "deduplicated";
+        if (this.fileLimited.has(id))
+            return "per-file-limit";
+        // After the display window fills, remaining candidates are unexamined.
+        return "display-limit";
+    }
+    capture(stage, records) {
+        this.ranks.set(stage, new Map(records.map((r, i) => [key(r), i + 1])));
+        if (stage === "fusion") {
+            this.total = records.length;
+            this.cohort = records.slice(0, 200);
+        }
+    }
+    finish(details) {
+        return Object.assign(Object.assign({ schemaVersion: 1 }, details), { rankingEnvironment: Object.fromEntries(rankingKeys.map((name) => { var _a; return [name, (_a = process.env[name]) !== null && _a !== void 0 ? _a : null]; })), stages: Object.fromEntries(stages.map((s) => { var _a; var _b; return [s, (_b = (_a = this.ranks.get(s)) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0]; })), trace: {
+                cohort: "post-seed-fusion-head",
+                limit: 200,
+                total: this.total,
+                truncated: this.total > this.cohort.length,
+                candidates: this.cohort.map((r) => { var _a; return ({
+                    id: key(r),
+                    path: r.path,
+                    hash: r.hash,
+                    startLine: r.start_line + 1,
+                    endLine: r.end_line + 1,
+                    parentSymbol: (_a = r.parent_symbol) !== null && _a !== void 0 ? _a : "",
+                    outcome: this.outcome(r),
+                    ranks: Object.fromEntries(stages.map((s) => { var _a; var _b; return [s, (_b = (_a = this.ranks.get(s)) === null || _a === void 0 ? void 0 : _a.get(key(r))) !== null && _b !== void 0 ? _b : 0]; })),
+                }); }),
+            } });
+    }
+}
+exports.SearchDiagnosticCollector = SearchDiagnosticCollector;

package/dist/lib/search/per-file.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMaxPerFile = validateMaxPerFile;
+exports.parseCliPerFile = parseCliPerFile;
+/** Omitted requests retain the daemon's configured default. */
+function validateMaxPerFile(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+        throw new Error("maxPerFile must be a positive safe integer");
+    return value;
+}
+function parseCliPerFile(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value))
+        throw new Error("--per-file must be a positive safe integer");
+    try {
+        return validateMaxPerFile(Number(value));
+    }
+    catch (_a) {
+        throw new Error("--per-file must be a positive safe integer");
+    }
+}

package/dist/lib/search/searcher.js

@@ -18,8 +18,10 @@ const filter_builder_1 = require("../utils/filter-builder");
 const logger_1 = require("../utils/logger");
 const query_timeout_1 = require("../utils/query-timeout");
 const pool_1 = require("../workers/pool");
+const diagnostics_1 = require("./diagnostics");
 const intent_1 = require("./intent");
 const pagerank_1 = require("./pagerank");
+const per_file_1 = require("./per-file");
 const seed_weight_1 = require("./seed-weight");
 // Reads a defined_symbols / referenced_symbols column that may arrive as a plain
 // array or a LanceDB Arrow proxy (.toArray()).
@@ -396,6 +398,7 @@ class Searcher {
     search(query, top_k, _search_options, _filters, pathPrefix, intent, signal) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+            const requestedMaxPerFile = (0, per_file_1.validateMaxPerFile)(_search_options === null || _search_options === void 0 ? void 0 : _search_options.maxPerFile);
             const finalLimit = top_k !== null && top_k !== void 0 ? top_k : 10;
             // ColBERT rerank is opt-in as of v0.17.1. On the 97-case eval it
             // regresses MRR@10 by ~3% and doubles query latency; sweep across
@@ -403,6 +406,14 @@ class Searcher {
             // fused scores ~30:1 so blend tuning can't recover the loss.
             let doRerank = (_a = _search_options === null || _search_options === void 0 ? void 0 : _search_options.rerank) !== null && _a !== void 0 ? _a : false;
             const explain = (_b = _search_options === null || _search_options === void 0 ? void 0 : _search_options.explain) !== null && _b !== void 0 ? _b : false;
+            const diagnostics = (_search_options === null || _search_options === void 0 ? void 0 : _search_options.diagnostics)
+                ? new diagnostics_1.SearchDiagnosticCollector()
+                : undefined;
+            const requestedRerank = doRerank;
+            let gateEvaluated = false;
+            let gateShare = null;
+            let gateActivated = false;
+            let rerankInvoked = false;
             // Aider-style seeding (Phase 4): bias candidate generation toward the
             // agent's working context. Inert unless the caller supplied seed files or
             // symbols, so the default search path is unchanged.
@@ -569,6 +580,9 @@ class Searcher {
                 .sort((a, b) => b[1] - a[1])
                 .map(([key]) => docMap.get(key))
                 .filter(Boolean);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("vector", vectorResults);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("fts", ftsResults);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("rrf", fused);
             // Free raw search results — docMap holds the only needed references
             vectorResults.length = 0;
             ftsResults.length = 0;
@@ -618,16 +632,16 @@ class Searcher {
             // pools (express, platform) it regresses. So detect the concentrated regime
             // here and *add* rerank-on for it. This only ever flips doRerank false→true:
             // an explicit GMAX_RERANK=1 (doRerank already true) is never overridden off.
+            const envConcThreshold = Number.parseFloat((_f = process.env.GMAX_CONCENTRATION_THRESHOLD) !== null && _f !== void 0 ? _f : "");
+            // <= 0 (or NaN with the default) keeps the gate active at 0.7; a value > 1
+            // disables it (no possible share reaches it), giving a rerank-fully-off
+            // baseline for sweeps without touching the doRerank default. 0.7 is the
+            // sweep winner: highest threshold (least spurious firing) that still
+            // retains lodash's +0.15 MRR lift while leaving express/platform flat.
+            const CONCENTRATION_THRESHOLD = Number.isFinite(envConcThreshold) && envConcThreshold > 0
+                ? envConcThreshold
+                : 0.7;
             if (!doRerank) {
-                const envConcThreshold = Number.parseFloat((_f = process.env.GMAX_CONCENTRATION_THRESHOLD) !== null && _f !== void 0 ? _f : "");
-                // <= 0 (or NaN with the default) keeps the gate active at 0.7; a value > 1
-                // disables it (no possible share reaches it), giving a rerank-fully-off
-                // baseline for sweeps without touching the doRerank default. 0.7 is the
-                // sweep winner: highest threshold (least spurious firing) that still
-                // retains lodash's +0.15 MRR lift while leaving express/platform flat.
-                const CONCENTRATION_THRESHOLD = Number.isFinite(envConcThreshold) && envConcThreshold > 0
-                    ? envConcThreshold
-                    : 0.7;
                 // Histogram a fixed top-K window (not finalLimit) so the threshold stays
                 // calibrated across callers regardless of the result window they request.
                 const CONCENTRATION_K = 10;
@@ -643,16 +657,21 @@ class Searcher {
                             maxBucket = count;
                     }
                     const share = maxBucket / window.length;
+                    gateEvaluated = true;
+                    gateShare = share;
                     if (share >= CONCENTRATION_THRESHOLD) {
                         doRerank = true;
+                        gateActivated = true;
                     }
                 }
             }
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("fusion", fused);
             // Item 8: Widen PRE_RERANK_K
             // Retrieve a wide set for Stage 1 filtering
             const envStage1 = Number.parseInt((_h = process.env.GMAX_STAGE1_K) !== null && _h !== void 0 ? _h : "", 10);
             const STAGE1_K = Number.isFinite(envStage1) && envStage1 > 0 ? envStage1 : 200;
             const topCandidates = fused.slice(0, STAGE1_K);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("stage1", topCandidates);
             // Free docMap — topCandidates already holds record references
             docMap.clear();
             // Item 9: Two-stage rerank
@@ -694,11 +713,38 @@ class Searcher {
                 withScore.sort((a, b) => b.score - a.score);
                 stage2Candidates = withScore.slice(0, STAGE2_K).map((x) => x.doc);
             }
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("pooled", stage2Candidates);
+            const diagnosticDetails = () => ({
+                settings: {
+                    finalLimit,
+                    preK: PRE_RERANK_K,
+                    rrfK: RRF_K,
+                    stage1K: STAGE1_K,
+                    stage2K: STAGE2_K,
+                    rerankTop: RERANK_TOP,
+                    fusedWeight: FUSED_WEIGHT,
+                    pagerankEnabled,
+                    seedsActive: seedCtx.active,
+                    symbolQuery,
+                    pooledFilterApplied: !!queryPooled && topCandidates.length > STAGE2_K,
+                },
+                gate: {
+                    requestedRerank,
+                    threshold: CONCENTRATION_THRESHOLD,
+                    evaluated: gateEvaluated,
+                    share: gateShare,
+                    activated: gateActivated,
+                    rerankInvoked,
+                },
+                fts: { available: this.ftsAvailable, searchFailed: ftsSearchFailed },
+            });
             if (stage2Candidates.length === 0) {
-                return { data: [] };
+                return Object.assign({ data: [] }, (diagnostics
+                    ? { diagnostics: diagnostics.finish(diagnosticDetails()) }
+                    : {}));
             }
             const envMaxPerFile = Number.parseInt((_m = process.env.GMAX_MAX_PER_FILE) !== null && _m !== void 0 ? _m : "", 10);
-            const MAX_PER_FILE = Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3;
+            const MAX_PER_FILE = requestedMaxPerFile !== null && requestedMaxPerFile !== void 0 ? requestedMaxPerFile : (Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3);
             // Rank the entire bounded candidate pool before trimming the result count.
             // A limit-dependent cut here discarded contenders before structure boosts
             // and dedup, so requesting three results could hide the top match returned
@@ -735,6 +781,8 @@ class Searcher {
                     }
                 }
             }
+            // Selected rerank membership is separate from actual batch execution.
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("rerank", rerankCandidates);
             // Phase B: Lazy-load colbert data only for the ~20 rerank candidates
             if (doRerank && rerankCandidates.length > 0) {
                 const rerankIds = rerankCandidates
@@ -761,6 +809,7 @@ class Searcher {
             }
             const rerankScoreByKey = new Map();
             if (doRerank && rerankCandidates.length > 0) {
+                rerankInvoked = true;
                 const scores = yield pool.rerank({
                     query: queryMatrixRaw,
                     docs: rerankCandidates.map((doc) => { var _a; return ({
@@ -847,8 +896,10 @@ class Searcher {
             }
             // Note: "boosted" was not previously declared -- fix to use "scored"
             scored.sort((a, b) => b.score - a.score);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("scored", scored.map((item) => item.record));
             // Item 11: Intelligent Deduplication
             const uniqueScored = this.deduplicateResults(scored);
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("dedup", uniqueScored.map((item) => item.record));
             // Item 10: Per-file diversification
             const seenFiles = new Map();
             const diversified = [];
@@ -859,9 +910,13 @@ class Searcher {
                     diversified.push(item);
                     seenFiles.set(path, count + 1);
                 }
+                else {
+                    diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.noteFileLimit(item.record);
+                }
                 if (diversified.length >= finalLimit)
                     break;
             }
+            diagnostics === null || diagnostics === void 0 ? void 0 : diagnostics.capture("final", diversified.map((item) => item.record));
             // Phase C: Lazy-load display columns only for the final ~10 results
             const finalIds = diversified
                 .map((item) => item.record.id)
@@ -898,7 +953,7 @@ class Searcher {
             const finalResults = diversified.map((item) => (Object.assign(Object.assign({}, item.record), { _score: item.score, _breakdown: item.breakdown, vector: undefined, colbert: undefined })));
             // Item 12: Score Calibration
             const maxScore = finalResults.length > 0 ? finalResults[0]._score : 1.0;
-            return Object.assign({ data: finalResults.map((r) => {
+            return Object.assign(Object.assign({ data: finalResults.map((r) => {
                     const chunk = this.mapRecordToChunk(r, r._score || 0);
                     // Normalize score relative to top result
                     const normalized = maxScore > 0 ? r._score / maxScore : 0;
@@ -913,7 +968,11 @@ class Searcher {
                     }
                     chunk.confidence = confidence;
                     return chunk;
-                }) }, (!this.ftsAvailable || ftsSearchFailed
+                }) }, (diagnostics
+                ? {
+                    diagnostics: diagnostics.finish(Object.assign(Object.assign({}, diagnosticDetails()), { settings: Object.assign(Object.assign({}, diagnosticDetails().settings), { maxPerFile: MAX_PER_FILE, definitionBoost: DEF_MATCH_BOOST }) })),
+                }
+                : {})), (!this.ftsAvailable || ftsSearchFailed
                 ? {
                     warnings: [
                         "Full-text search unavailable — results may be less precise",

package/dist/lib/utils/daemon-search.js

@@ -0,0 +1,34 @@
+"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.sendSearchCommand = sendSearchCommand;
+const per_file_1 = require("../search/per-file");
+const daemon_client_1 = require("./daemon-client");
+/** An old live daemon must not silently ignore a request-scoped override. */
+function sendSearchCommand(command, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const maxPerFile = (0, per_file_1.validateMaxPerFile)(command.maxPerFile);
+        if (maxPerFile !== undefined) {
+            const ping = yield (0, daemon_client_1.sendDaemonCommand)({ cmd: "ping" }, options);
+            if (!ping.ok)
+                return ping;
+            if (((_a = ping.capabilities) === null || _a === void 0 ? void 0 : _a.perFileSearch) !== 1) {
+                return {
+                    ok: false,
+                    error: "unsupported per-file retrieval control",
+                    hint: "run gmax watch restart with the updated CLI",
+                };
+            }
+        }
+        return (0, daemon_client_1.sendDaemonCommand)(command, options);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.48",
+  "version": "0.26.50",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {
@@ -29,6 +29,7 @@
     "bench:recall:json": "GMAX_EVAL_JSON=1 npx tsx src/eval.ts",
     "bench:oss": "npx tsx src/eval-oss.ts all",
     "bench:oss:json": "GMAX_EVAL_JSON=1 npx tsx src/eval-oss.ts all",
+    "bench:relevance": "tsx src/eval-relevance.ts",
     "bench:tokens": "npx tsx src/eval-tokens.ts",
     "bench:tokens:json": "GMAX_EVAL_JSON=1 npx tsx src/eval-tokens.ts",
     "bench:surprises": "npx tsx src/eval-surprising-connections.ts",
@@ -76,7 +77,7 @@
     "NOTICE"
   ],
   "license": "Apache-2.0",
-  "description": "Semantic code search for coding agents. Local embeddings, LLM summaries, call graph tracing.",
+  "description": "Semantic code search for coding agents. Local embeddings, call graph tracing, compact code context.",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@huggingface/transformers": "^4.3.0",

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

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