grepmax 0.21.0 → 0.21.2

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "grepmax",
       "source": "./plugins/grepmax",
       "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
-      "version": "0.21.0",
+      "version": "0.21.2",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/README.md

@@ -289,6 +289,45 @@ All data lives in `~/.gmax/`:
 }
 ```
 
+### Model Tier
+
+gmax embeds with IBM's Granite r2 code-embedding models. Two tiers are available:
+
+| Tier | Model | Dim | Params |
+| --- | --- | --- | --- |
+| `small` (default) | `granite-embedding-small-english-r2` | 384 | 47M |
+| `standard` | `granite-embedding-english-r2` | 768 | 149M |
+
+**384d is the default — and benchmarking says keep it.** On gmax's own 97-case
+retrieval eval (`pnpm bench:recall`), the larger 768d model scored **~10 points
+*worse* on Recall@10** than 384d, consistently on both the MLX GPU and ONNX CPU
+embedding paths, with and without ColBERT rerank:
+
+| Model | Recall@10 | MRR@10 |
+| --- | --- | --- |
+| `small` / 384d | **0.72** | **0.51** |
+| `standard` / 768d | 0.62 | 0.44 |
+
+<sub>gmax repo, 97 cases, MLX GPU, rerank off (the shipped default). The CPU/q4
+path and the rerank-on path show the same ~0.10 Recall@10 gap, so it isn't a
+quantization artifact — the bigger model just retrieves worse on code here.</sub>
+
+Bigger isn't better for this workload: 768d roughly doubles embedding compute,
+worker RAM, and dense-vector storage while *lowering* recall on code search.
+Unless you have a measured reason to switch (e.g. a recall complaint on a very
+large repo — benchmark it first), stay on 384d.
+
+To change tiers:
+
+```bash
+gmax config --model-tier standard   # a dim change needs a full re-embed
+gmax repair --rebuild               # drops the shared table, re-embeds every project at the new dim
+```
+
+A vector-dimension change can't be applied by a per-project `gmax index --reset`
+— the shared `chunks` table is fixed-width, so `gmax repair --rebuild` is the
+sanctioned path.
+
 ### Ignoring Files
 
 gmax respects `.gitignore` and `.gmaxignore`:
@@ -339,6 +378,8 @@ 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.
 
+`pnpm bench:recall` also drives the model-tier comparison behind the 384d default — see [Model Tier](#model-tier) for why the larger 768d model is *not* the default.
+
 ## 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/config.js

@@ -84,6 +84,7 @@ Examples:
     const newMode = (_c = options.embedMode) !== null && _c !== void 0 ? _c : globalConfig.embedMode;
     const tier = (_d = config_1.MODEL_TIERS[newTier]) !== null && _d !== void 0 ? _d : config_1.MODEL_TIERS.small;
     const tierChanged = newTier !== globalConfig.modelTier;
+    const dimChanged = tier.vectorDim !== globalConfig.vectorDim;
     (0, index_config_1.writeGlobalConfig)({
         modelTier: newTier,
         vectorDim: tier.vectorDim,
@@ -98,7 +99,12 @@ Examples:
     });
     console.log(`Updated: embed-mode=${newMode}, model-tier=${newTier} (${tier.vectorDim}d)`);
     if (tierChanged) {
-        console.log("⚠️  Model tier changed — run `gmax index --reset` to rebuild with new dimensions.");
+        // A dimension change can't be fixed by a per-project `gmax index --reset`:
+        // the shared `chunks` table is fixed-width, so it must be dropped and
+        // rebuilt. A same-dim model swap (future tiers) can use a per-project reset.
+        console.log(dimChanged
+            ? `⚠️  Model tier changed (${globalConfig.vectorDim}d → ${tier.vectorDim}d). The shared vector table is fixed-width — run \`${config_1.REBUILD_COMMAND}\` to drop it and re-embed every project at the new dim.`
+            : "⚠️  Model tier changed — run `gmax index --reset` per project to re-embed with the new model.");
     }
     yield (0, exit_1.gracefulExit)();
 }));

package/dist/eval-tokens.js

@@ -0,0 +1,220 @@
+"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());
+    });
+};
+var _a;
+var _b;
+Object.defineProperty(exports, "__esModule", { value: true });
+// Reduce worker pool fan-out during eval to avoid ONNX concurrency issues.
+// Must run before importing modules that read GMAX_WORKER_COUNT (mirrors eval.ts).
+(_a = (_b = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_b.GMAX_WORKER_COUNT = "1");
+// Token-savings benchmark — sibling to eval.ts.
+//
+// eval.ts measures Recall@10/MRR only; it never measures the "fewer tokens"
+// value prop. This harness does, over the SAME 98 `cases` (imported from
+// eval.ts), with an honest, conservative methodology:
+//
+//   Baseline (no gmax — what a grep-then-Read agent pays): read the WHOLE first
+//     `expectedPath` file → estTokens(content). One file UNDER-counts (after a
+//     grep an agent typically reads several), so every reported ratio is a
+//     conservative FLOOR, not a best case.
+//
+//   gmax pointer: searcher.search(query, 20, {rerank}) rendered through
+//     formatMcpPointerSearchResults(..., { query }) — the REAL bytes the
+//     `semantic_search detail:pointer` view returns, not an idealized chunk.
+//
+//   gmax pointer+symbol: pointer bytes PLUS the top hit's symbol body, obtained
+//     by slicing the top result's file on its [startLine..endLine] range. That
+//     is what `extract_symbol` fundamentally returns (the symbol's line span),
+//     with zero dependency on non-importable MCP handler internals.
+//
+// We deliberately REJECT graphify's "70×/100×" methodology: it compares one
+// query to reading the ENTIRE corpus (corpus_words = nodes*50, benchmark.py:113),
+// which no agent ever does. Whole-file Read is the baseline an agent actually pays.
+//
+// estTokens is a chars/4 proxy (mirrors mcp.ts:2216), NOT a real tokenizer. Both
+// sides use the same estimator, so the RATIO is largely estimator-invariant — no
+// tokenizer dependency is warranted.
+//
+// Preconditions (identical to eval.ts): an indexed store for cwd AND query
+// embeddings available (MLX :8100 or the ONNX CPU fallback).
+//
+// Output: dual-mode like eval.ts — GMAX_EVAL_JSON=1 / --json emits a single JSON
+// object on stdout (human preamble routed to stderr); otherwise human-readable.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const mcp_1 = require("./commands/mcp");
+const eval_1 = require("./eval");
+const searcher_1 = require("./lib/search/searcher");
+const vector_db_1 = require("./lib/store/vector-db");
+const exit_1 = require("./lib/utils/exit");
+const project_root_1 = require("./lib/utils/project-root");
+const topK = 20;
+// chars/4 proxy — mirrors the estimator in mcp.ts:2216. Not a tokenizer; fine
+// here because BOTH sides use it, so the ratio is largely estimator-invariant.
+const estTokens = (s) => Math.ceil(s.length / 4);
+// Linear-interpolation quantile over an ascending-sorted array.
+function quantile(sortedAsc, q) {
+    if (sortedAsc.length === 0)
+        return 0;
+    const pos = (sortedAsc.length - 1) * q;
+    const base = Math.floor(pos);
+    const rest = pos - base;
+    const next = sortedAsc[base + 1];
+    return next !== undefined
+        ? sortedAsc[base] + rest * (next - sortedAsc[base])
+        : sortedAsc[base];
+}
+function mean(xs) {
+    return xs.length === 0 ? 0 : xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+function aggregate(ratios) {
+    const sorted = [...ratios].sort((a, b) => a - b);
+    return {
+        medianRatio: Number(quantile(sorted, 0.5).toFixed(2)),
+        p25: Number(quantile(sorted, 0.25).toFixed(2)),
+        p75: Number(quantile(sorted, 0.75).toFixed(2)),
+        meanRatio: Number(mean(sorted).toFixed(2)),
+    };
+}
+function run() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const root = process.cwd();
+        const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
+        const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
+        const vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
+        const searcher = new searcher_1.Searcher(vectorDb);
+        const jsonMode = process.env.GMAX_EVAL_JSON === "1" || process.argv.includes("--json");
+        // In JSON mode all human preamble goes to stderr so stdout stays one object.
+        const log = jsonMode ? console.error : console.log;
+        // Same precondition as eval.ts: bail loudly if the store is empty.
+        if (!(yield vectorDb.hasAnyRows())) {
+            console.error("❌ Store appears to be empty!");
+            console.error('   Run "gmax index" to populate the store with data.');
+            process.exit(1);
+        }
+        // Rerank OFF by default (matches eval.ts) — set GMAX_EVAL_RERANK=1 to measure
+        // the full production pipeline. Rendered bytes barely move with rerank; the
+        // flag is here so token numbers line up with whichever recall run they sit next to.
+        const rerank = process.env.GMAX_EVAL_RERANK === "1";
+        log("Starting token-savings benchmark...\n");
+        const results = [];
+        for (const c of eval_1.cases) {
+            // Baseline: a grep-then-Read agent reads the whole first expectedPath file.
+            // Pipe-split mirrors evaluateCase's path handling (eval.ts:552-555).
+            const firstExpected = c.expectedPath.split("|")[0].trim();
+            let baselineTokens = 0;
+            let baselineOk = false;
+            try {
+                const content = (0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, firstExpected), "utf8");
+                baselineTokens = estTokens(content);
+                baselineOk = true;
+            }
+            catch (_d) {
+                // Fixture path not present in this checkout — excluded from aggregation.
+            }
+            // gmax pointer: the real rendered bytes of the detail:pointer view.
+            const res = yield searcher.search(c.query, topK, { rerank });
+            const pointerText = (0, mcp_1.formatMcpPointerSearchResults)(res.data, projectRoot, {
+                query: c.query,
+            });
+            const pointerTokens = estTokens(pointerText);
+            // gmax pointer+symbol: pointer bytes plus the top hit's symbol body, sliced
+            // by its [startLine..endLine] range (0-based; mcp.ts:482 adds 1 for display).
+            let symbolTokens = 0;
+            let symbolLabel = "";
+            let topHitPath = "";
+            const top = res.data[0];
+            if (top) {
+                const absPath = (0, mcp_1.searchResultPath)(top);
+                topHitPath = absPath;
+                const start = (0, mcp_1.searchResultStartLine)(top);
+                const end = (0, mcp_1.searchResultEndLine)(top, start);
+                try {
+                    const lines = (0, node_fs_1.readFileSync)(absPath, "utf8").split("\n");
+                    symbolTokens = estTokens(lines.slice(start, end + 1).join("\n"));
+                    symbolLabel =
+                        (_c = (_b = top.defined_symbols) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : "";
+                }
+                catch (_e) {
+                    // Top-hit file unreadable — symbol cost stays 0 (pointer-only).
+                }
+            }
+            const pointerSymbolTokens = pointerTokens + symbolTokens;
+            const skipped = !baselineOk;
+            results.push({
+                query: c.query,
+                expectedPath: c.expectedPath,
+                baselineTokens,
+                pointerTokens,
+                symbolTokens,
+                pointerSymbolTokens,
+                symbolLabel,
+                topHitPath,
+                ratioPointer: skipped || pointerTokens === 0 ? 0 : baselineTokens / pointerTokens,
+                ratioPointerSymbol: skipped || pointerSymbolTokens === 0
+                    ? 0
+                    : baselineTokens / pointerSymbolTokens,
+                skipped,
+                note: skipped ? "baseline file missing" : undefined,
+            });
+        }
+        const evaluated = results.filter((r) => !r.skipped);
+        const pointerAgg = aggregate(evaluated.map((r) => r.ratioPointer));
+        const pointerSymbolAgg = aggregate(evaluated.map((r) => r.ratioPointerSymbol));
+        const summary = {
+            cases: results.length,
+            evaluated: evaluated.length,
+            skipped: results.length - evaluated.length,
+            rerank,
+            estimator: "chars/4 proxy (mirrors mcp.ts:2216)",
+            baseline: "whole-file Read of first expectedPath — conservative floor (agents read several files after a grep)",
+            pointer: pointerAgg,
+            pointerSymbol: pointerSymbolAgg,
+            storePath: paths.lancedbDir,
+        };
+        if (jsonMode) {
+            process.stdout.write(`${JSON.stringify({ summary, results }, null, 2)}\n`);
+        }
+        else {
+            const fmt = (n) => `${n.toFixed(1)}×`;
+            console.log("=".repeat(80));
+            console.log(`Token-savings benchmark — store: ${paths.lancedbDir}`);
+            console.log("Baseline = whole-file Read of first expectedPath (chars/4, conservative floor)");
+            console.log("=".repeat(80));
+            for (const r of results) {
+                if (r.skipped) {
+                    console.log(`⏭  ${r.query}`);
+                    console.log(`   => skipped (${r.note}: ${r.expectedPath})`);
+                    continue;
+                }
+                console.log(r.query);
+                console.log(`   baseline ${r.baselineTokens} tok  |  pointer ${r.pointerTokens} tok (${fmt(r.ratioPointer)})  |  +symbol ${r.pointerSymbolTokens} tok (${fmt(r.ratioPointerSymbol)})`);
+            }
+            console.log("=".repeat(80));
+            console.log(`gmax pointer        median ${fmt(pointerAgg.medianRatio)}  (p25 ${fmt(pointerAgg.p25)} · p75 ${fmt(pointerAgg.p75)} · mean ${fmt(pointerAgg.meanRatio)})`);
+            console.log(`gmax pointer+symbol median ${fmt(pointerSymbolAgg.medianRatio)}  (p25 ${fmt(pointerSymbolAgg.p25)} · p75 ${fmt(pointerSymbolAgg.p75)} · mean ${fmt(pointerSymbolAgg.meanRatio)})`);
+            console.log(`Evaluated ${evaluated.length}/${results.length} cases` +
+                (summary.skipped ? ` (${summary.skipped} skipped: file missing)` : ""));
+            console.log("Estimator: chars/4 proxy — ratio is estimator-invariant. Single-file baseline under-counts → floor.");
+            console.log("=".repeat(80));
+        }
+        yield (0, exit_1.gracefulExit)(0);
+    });
+}
+if (
+// Only auto-run when executed directly (not when imported for experiments/tests)
+require.main === module &&
+    process.env.GMAX_EVAL_AUTORUN !== "0") {
+    run().catch((err) => {
+        console.error("Token benchmark failed:", err);
+        (0, exit_1.gracefulExit)(1);
+    });
+}

package/dist/lib/core/languages.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LANGUAGES = void 0;
 exports.getLanguageByExtension = getLanguageByExtension;
+exports.languageFamily = languageFamily;
+exports.languageFamilyForPath = languageFamilyForPath;
 exports.getGrammarUrl = getGrammarUrl;
+const node_path_1 = require("node:path");
 exports.LANGUAGES = [
     {
         id: "typescript",
@@ -258,6 +261,43 @@ function getLanguageByExtension(ext) {
     const normalized = ext.toLowerCase();
     return exports.LANGUAGES.find((lang) => lang.extensions.includes(normalized));
 }
+// ---------------------------------------------------------------------------
+// Language families — for cross-language phantom-edge suppression
+// ---------------------------------------------------------------------------
+// The shared LanceDB table holds every language's chunks, scoped only by path.
+// A bare-name call-graph match (`array_contains(referenced_symbols, 'render')`)
+// therefore cross-connects a `render` defined in Python to a `render` referenced
+// in TSX. To suppress those phantom edges we collapse languages that genuinely
+// share a call namespace into one "family" and only keep edges within it.
+// Languages absent from this map are their own family (their `id`). The grouping
+// is deliberately conservative: only languages that directly call across one
+// another are merged, so a real cross-file edge is never dropped.
+const LANGUAGE_FAMILIES = {
+    // JS/TS ecosystem — these freely import and call across one another.
+    typescript: "js_ts",
+    tsx: "js_ts",
+    javascript: "js_ts",
+    // C and C++ share headers and C++ calls into C.
+    c: "c_cpp",
+    cpp: "c_cpp",
+};
+/** The call-namespace family for a language id (defaults to the id itself). */
+function languageFamily(langId) {
+    var _a;
+    return (_a = LANGUAGE_FAMILIES[langId]) !== null && _a !== void 0 ? _a : langId;
+}
+/**
+ * The language family for a file path, or null when the extension is unknown or
+ * absent. Null means "unclassifiable, do not filter" — callers must keep edges
+ * they can't classify and only drop edges whose family is known *and* differs.
+ */
+function languageFamilyForPath(path) {
+    const ext = (0, node_path_1.extname)(path).toLowerCase();
+    if (!ext)
+        return null;
+    const lang = getLanguageByExtension(ext);
+    return lang ? languageFamily(lang.id) : null;
+}
 function getGrammarUrl(grammarName) {
     var _a;
     const lang = exports.LANGUAGES.find((l) => { var _a; return ((_a = l.grammar) === null || _a === void 0 ? void 0 : _a.name) === grammarName; });

package/dist/lib/daemon/watcher-manager.js

@@ -382,9 +382,9 @@ class WatcherManager {
                             // Fast path: if only mtime changed but size is identical and we have a hash,
                             // just verify the hash in-process instead of sending to a worker.
                             if ((cached === null || cached === void 0 ? void 0 : cached.hash) && cached.size === stats.size) {
-                                const { computeBufferHash } = yield Promise.resolve().then(() => __importStar(require("../utils/file-utils")));
+                                const { computeContentHash } = yield Promise.resolve().then(() => __importStar(require("../utils/file-utils")));
                                 const buf = yield fs.promises.readFile(absPath);
-                                const hash = computeBufferHash(buf);
+                                const hash = computeContentHash(buf, absPath);
                                 if (hash === cached.hash) {
                                     // Content unchanged — update mtime in cache and skip worker
                                     metaCache.put(absPath, Object.assign(Object.assign({}, cached), { mtimeMs: stats.mtimeMs }));

package/dist/lib/graph/graph-builder.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GraphBuilder = void 0;
+const languages_1 = require("../core/languages");
 const filter_builder_1 = require("../utils/filter-builder");
 const query_timeout_1 = require("../utils/query-timeout");
 const graph_traversal_1 = require("./graph-traversal");
@@ -36,8 +37,13 @@ class GraphBuilder {
     }
     /**
      * Find all chunks that call the given symbol.
+     *
+     * `anchorFamily` (the language family of the symbol's definition) enables the
+     * cross-language phantom-edge guard: the shared table matches a bare symbol
+     * name across every language, so without it a `render` defined in one language
+     * picks up callers that merely reference an unrelated `render` in another.
      */
-    getCallers(symbol) {
+    getCallers(symbol, anchorFamily) {
         return __awaiter(this, void 0, void 0, function* () {
             const table = yield this.db.ensureTable();
             const escaped = (0, filter_builder_1.escapeSqlString)(symbol);
@@ -59,7 +65,17 @@ class GraphBuilder {
                 .where(this.scopeWhere(`(array_contains(referenced_symbols, '${escaped}') OR array_contains(type_referenced_symbols, '${escaped}'))`))
                 .limit(100)
                 .toArray();
-            return rows.map((row) => this.mapRowToNode(row, symbol, "caller"));
+            // Cross-language phantom-edge guard. When the anchor family is known, drop
+            // callers from a *different known* family; callers we can't classify (unknown
+            // extension) are kept so a real edge is never lost. No anchor → no filter.
+            const guarded = anchorFamily == null
+                ? rows
+                : rows.filter((row) => {
+                    var _a;
+                    const fam = (0, languages_1.languageFamilyForPath)(String((_a = row.path) !== null && _a !== void 0 ? _a : ""));
+                    return fam == null || fam === anchorFamily;
+                });
+            return guarded.map((row) => this.mapRowToNode(row, symbol, "caller"));
         });
     }
     /**
@@ -108,8 +124,10 @@ class GraphBuilder {
             const center = centerRows.length > 0
                 ? this.mapRowToNode(centerRows[0], symbol, "center")
                 : null;
-            // 2. Get Callers
-            const callers = yield this.getCallers(symbol);
+            // 2. Get Callers — anchored to the center definition's language family so a
+            // bare name shared across languages doesn't pull in cross-language callers.
+            const anchorFamily = center ? (0, languages_1.languageFamilyForPath)(center.file) : null;
+            const callers = yield this.getCallers(symbol, anchorFamily);
             // 3. Get Callees — resolve each to a GraphNode with file:line
             const calleeNames = center ? center.calls.slice(0, 15) : [];
             const calleeNodes = [];
@@ -204,7 +222,7 @@ class GraphBuilder {
                 visited.add(caller.symbol);
                 let subCallers = [];
                 if (remainingDepth > 0) {
-                    const upstreamCallers = yield this.getCallers(caller.symbol);
+                    const upstreamCallers = yield this.getCallers(caller.symbol, (0, languages_1.languageFamilyForPath)(caller.file));
                     subCallers = yield this.expandCallers(upstreamCallers, remainingDepth - 1, visited);
                 }
                 trees.push({ node: caller, callers: subCallers });
@@ -222,7 +240,10 @@ class GraphBuilder {
     /** Distinct symbols that reference the given symbol (inbound edges). */
     callersOf(symbol) {
         return __awaiter(this, void 0, void 0, function* () {
-            const nodes = yield this.getCallers(symbol);
+            // Anchor the guard to this symbol's own definition language family so the
+            // bare name doesn't pull in callers from an unrelated language.
+            const loc = yield this.resolveLocation(symbol);
+            const nodes = yield this.getCallers(symbol, loc ? (0, languages_1.languageFamilyForPath)(loc.file) : null);
             const out = [];
             for (const n of nodes) {
                 if (n.symbol && n.symbol !== "unknown" && !out.includes(n.symbol)) {
@@ -246,9 +267,13 @@ class GraphBuilder {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
             const hits = yield (0, graph_traversal_1.bfsNeighbors)(symbol, this.neighborFn(direction), maxHops);
+            // Resolve the origin once to anchor every neighbor's location lookup to the
+            // same language family, so a shared name doesn't resolve to a foreign file.
+            const origin = yield this.resolveLocation(symbol);
+            const anchorFamily = origin ? (0, languages_1.languageFamilyForPath)(origin.file) : null;
             const out = [];
             for (const h of hits) {
-                const loc = yield this.resolveLocation(h.symbol);
+                const loc = yield this.resolveLocation(h.symbol, anchorFamily);
                 out.push(Object.assign(Object.assign({}, h), { file: (_a = loc === null || loc === void 0 ? void 0 : loc.file) !== null && _a !== void 0 ? _a : "", line: (_b = loc === null || loc === void 0 ? void 0 : loc.line) !== null && _b !== void 0 ? _b : 0 }));
             }
             return out;
@@ -260,8 +285,13 @@ class GraphBuilder {
             return (0, graph_traversal_1.findPath)(from, to, this.neighborFn(direction), maxHops);
         });
     }
-    /** Resolve a symbol to its first defining chunk's file:line, if indexed. */
-    resolveLocation(symbol) {
+    /**
+     * Resolve a symbol to a defining chunk's file:line, if indexed. With
+     * `anchorFamily` set, prefer the definition in that language family rather than
+     * an arbitrary cross-language match (the shared table can hold the same name in
+     * several languages); falls back to the first definition when none match.
+     */
+    resolveLocation(symbol, anchorFamily) {
         return __awaiter(this, void 0, void 0, function* () {
             const table = yield this.db.ensureTable();
             const escaped = (0, filter_builder_1.escapeSqlString)(symbol);
@@ -269,11 +299,22 @@ class GraphBuilder {
                 .query()
                 .select(["path", "start_line"])
                 .where(this.scopeWhere(`array_contains(defined_symbols, '${escaped}')`))
-                .limit(1)
+                // No anchor → keep the cheap single-row fetch. With one, pull a few
+                // candidates so we can pick the same-family definition instead of guessing.
+                .limit(anchorFamily ? 25 : 1)
                 .toArray();
             if (rows.length === 0)
                 return null;
-            const r = rows[0];
+            let r = rows[0];
+            if (anchorFamily) {
+                const match = rows.find((row) => {
+                    var _a;
+                    return (0, languages_1.languageFamilyForPath)(String((_a = row.path) !== null && _a !== void 0 ? _a : "")) ===
+                        anchorFamily;
+                });
+                if (match)
+                    r = match;
+            }
             return { file: String(r.path || ""), line: Number(r.start_line || 0) };
         });
     }

package/dist/lib/index/batch-processor.js

@@ -196,7 +196,7 @@ class ProjectBatchProcessor {
                         // verify in-process instead of dispatching to a worker (~220ms saved).
                         if ((cached === null || cached === void 0 ? void 0 : cached.hash) && cached.size === stats.size) {
                             const buf = yield fs.promises.readFile(absPath);
-                            const hash = (0, file_utils_1.computeBufferHash)(buf);
+                            const hash = (0, file_utils_1.computeContentHash)(buf, absPath);
                             if (hash === cached.hash) {
                                 metaUpdates.set(absPath, Object.assign(Object.assign({}, cached), { mtimeMs: stats.mtimeMs }));
                                 continue;

package/dist/lib/utils/file-utils.js

@@ -43,6 +43,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeBufferHash = computeBufferHash;
+exports.stripMarkdownFrontmatter = stripMarkdownFrontmatter;
+exports.computeContentHash = computeContentHash;
 exports.hasNullByte = hasNullByte;
 exports.readFileSnapshot = readFileSnapshot;
 exports.isIndexableFile = isIndexableFile;
@@ -58,6 +60,37 @@ const config_1 = require("../../config");
 function computeBufferHash(buffer) {
     return (0, node_crypto_1.createHash)("sha256").update(buffer).digest("hex");
 }
+// Files whose leading YAML frontmatter is metadata, not content. A status:/tags:
+// edit bumps mtime and changes the bytes, but the embedding ignores frontmatter —
+// so hashing it would force a needless GPU re-embed on every metadata touch.
+const FRONTMATTER_EXTENSIONS = new Set([".md", ".mdx"]);
+// Leading YAML frontmatter: a whole `---` line at the very top (NOT a bare
+// `startsWith("---")`, which would also match a `---` thematic break or `--- x`),
+// through the next whole `---`/`...` line. Anchored at string start (no `m` flag)
+// with an optional BOM, so only true file-leading frontmatter matches; a doc that
+// opens with a thematic break and no closing fence is left untouched.
+const FRONTMATTER_BLOCK = /^\uFEFF?---[ \t]*\r?\n[\s\S]*?\r?\n(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/;
+/** Strip leading YAML frontmatter from markdown bytes; returns input unchanged otherwise. */
+function stripMarkdownFrontmatter(buffer) {
+    const text = buffer.toString("utf8");
+    const match = text.match(FRONTMATTER_BLOCK);
+    if (!match)
+        return buffer;
+    return Buffer.from(text.slice(match[0].length), "utf8");
+}
+/**
+ * Hash file content for change detection. For markdown, YAML frontmatter is
+ * stripped first so a metadata-only edit doesn't bust `isFileCached` and trigger
+ * a re-embed; every other file hashes its exact bytes. Must be used identically
+ * across the catchup, watcher, and worker hash paths or they will disagree and
+ * re-index in a loop.
+ */
+function computeContentHash(buffer, filePath) {
+    if (FRONTMATTER_EXTENSIONS.has((0, node_path_1.extname)(filePath).toLowerCase())) {
+        return computeBufferHash(stripMarkdownFrontmatter(buffer));
+    }
+    return computeBufferHash(buffer);
+}
 function hasNullByte(buffer, sampleLength = 1024) {
     const length = Math.min(buffer.length, sampleLength);
     for (let i = 0; i < length; i++) {

package/dist/lib/utils/stale-hint.js

@@ -104,7 +104,9 @@ function maybeWarnStaleEmbedding(projectRoot, opts) {
             `current_dim=${gap.toDim}`,
             `dim_changed=${gap.dimChanged}`,
             `severity=${gap.severity}`,
-            "fix=gmax index --reset",
+            // A dim change needs the global rebuild (shared table is fixed-width); a
+            // same-dim model swap can use a per-project reset.
+            `fix=${gap.dimChanged ? config_1.REBUILD_COMMAND : "gmax index --reset"}`,
         ].join("\t");
         process.stderr.write(`${fields}\n`);
         return;
@@ -113,7 +115,10 @@ function maybeWarnStaleEmbedding(projectRoot, opts) {
     const detail = gap.dimChanged
         ? `vector dim ${gap.fromDim}→${gap.toDim} (incompatible — scores invalid until re-embed)`
         : `model '${gap.fromModel}'→'${gap.toModel}' (same dim; results mix models until re-embed)`;
-    process.stderr.write(`${label}  gmax: '${name}' indexed with embedding ${detail}. Run 'gmax index --reset'. (silence: GMAX_NO_STALE_HINT=1)\n`);
+    const fix = gap.dimChanged
+        ? `Run '${config_1.REBUILD_COMMAND}'`
+        : "Run 'gmax index --reset'";
+    process.stderr.write(`${label}  gmax: '${name}' indexed with embedding ${detail}. ${fix}. (silence: GMAX_NO_STALE_HINT=1)\n`);
 }
 /**
  * Cross-project guard: when a `--all-projects` / `--projects` search spans

package/dist/lib/workers/orchestrator.js

@@ -244,7 +244,7 @@ class WorkerOrchestrator {
                     : path.join(PROJECT_ROOT, input.path);
             (0, logger_1.debug)("orch", `processFile start: ${input.path}`);
             const { buffer, mtimeMs, size } = yield (0, file_utils_1.readFileSnapshot)(absolutePath);
-            const hash = (0, file_utils_1.computeBufferHash)(buffer);
+            const hash = (0, file_utils_1.computeContentHash)(buffer, absolutePath);
             if (!(0, file_utils_1.isIndexableFile)(absolutePath, size)) {
                 (0, logger_1.debug)("orch", `skip ${input.path} (non-indexable, size=${size})`);
                 return { vectors: [], hash, mtimeMs, size, shouldDelete: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {
@@ -25,14 +25,12 @@
     "dev": "npx tsc && node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "benchmark": "./run-benchmark.sh",
-    "benchmark:index": "./run-benchmark.sh $HOME/gmax-benchmarks --index",
-    "benchmark:agent": "npx tsx src/bench/benchmark-agent.ts",
-    "benchmark:chart": "npx tsx src/bench/generate-benchmark-chart.ts",
     "bench:recall": "npx tsx src/eval.ts",
     "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:tokens": "npx tsx src/eval-tokens.ts",
+    "bench:tokens:json": "GMAX_EVAL_JSON=1 npx tsx src/eval-tokens.ts",
     "format": "biome format --write .",
     "format:check": "biome check .",
     "lint": "biome lint .",

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

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