grepmax 0.17.2 → 0.17.4

package/dist/lib/search/pagerank.js

@@ -0,0 +1,267 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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.computePageRank = computePageRank;
+exports.buildGraphFromDb = buildGraphFromDb;
+exports.writeDiskCache = writeDiskCache;
+exports.loadOrComputePageRank = loadOrComputePageRank;
+exports.pageRankBoostForSymbols = pageRankBoostForSymbols;
+exports._clearMemoryCacheForTests = _clearMemoryCacheForTests;
+exports._cachePathForTests = _cachePathForTests;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("../../config");
+const filter_builder_1 = require("../utils/filter-builder");
+const DEFAULT_DAMPING = 0.85;
+const DEFAULT_MAX_ITER = 50;
+const DEFAULT_TOL = 1e-6;
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const memoryCache = new Map();
+function computePageRank(graph, damping = DEFAULT_DAMPING, maxIter = DEFAULT_MAX_ITER, tol = DEFAULT_TOL) {
+    const N = graph.nodes.length;
+    const result = new Map();
+    if (N === 0)
+        return result;
+    const idx = new Map();
+    for (let i = 0; i < N; i++)
+        idx.set(graph.nodes[i], i);
+    const outNeighbors = Array.from({ length: N }, () => []);
+    for (const [src, targets] of graph.edges) {
+        const si = idx.get(src);
+        if (si === undefined)
+            continue;
+        const seen = new Set();
+        for (const tgt of targets) {
+            const ti = idx.get(tgt);
+            if (ti === undefined || ti === si || seen.has(ti))
+                continue;
+            seen.add(ti);
+            outNeighbors[si].push(ti);
+        }
+    }
+    const outDegree = new Int32Array(N);
+    for (let i = 0; i < N; i++)
+        outDegree[i] = outNeighbors[i].length;
+    const inNeighbors = Array.from({ length: N }, () => []);
+    for (let i = 0; i < N; i++) {
+        for (const j of outNeighbors[i])
+            inNeighbors[j].push(i);
+    }
+    let pr = new Float64Array(N).fill(1 / N);
+    let next = new Float64Array(N);
+    const teleport = (1 - damping) / N;
+    for (let iter = 0; iter < maxIter; iter++) {
+        let dangling = 0;
+        for (let i = 0; i < N; i++) {
+            if (outDegree[i] === 0)
+                dangling += pr[i];
+        }
+        const danglingShare = (damping * dangling) / N;
+        for (let i = 0; i < N; i++) {
+            let sum = 0;
+            const ins = inNeighbors[i];
+            for (let k = 0; k < ins.length; k++) {
+                const j = ins[k];
+                sum += pr[j] / outDegree[j];
+            }
+            next[i] = teleport + danglingShare + damping * sum;
+        }
+        let delta = 0;
+        for (let i = 0; i < N; i++)
+            delta += Math.abs(next[i] - pr[i]);
+        const tmp = pr;
+        pr = next;
+        next = tmp;
+        if (delta < tol)
+            break;
+    }
+    for (let i = 0; i < N; i++)
+        result.set(graph.nodes[i], pr[i]);
+    return result;
+}
+function toStringArray(val) {
+    if (!val)
+        return [];
+    if (Array.isArray(val))
+        return val.filter((v) => typeof v === "string");
+    const maybe = val;
+    if (typeof maybe.toArray === "function") {
+        try {
+            const arr = maybe.toArray();
+            return Array.isArray(arr)
+                ? arr.filter((v) => typeof v === "string")
+                : [];
+        }
+        catch (_a) {
+            return [];
+        }
+    }
+    return [];
+}
+function buildGraphFromDb(db, pathPrefix) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const table = yield db.ensureTable();
+        const prefix = pathPrefix.endsWith("/") ? pathPrefix : `${pathPrefix}/`;
+        const rows = yield table
+            .query()
+            .select(["defined_symbols", "referenced_symbols"])
+            .where(`path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+            .toArray();
+        const nodes = new Set();
+        const edges = new Map();
+        for (const row of rows) {
+            const defs = toStringArray(row.defined_symbols);
+            const refs = toStringArray(row.referenced_symbols);
+            for (const d of defs)
+                nodes.add(d);
+            if (refs.length === 0)
+                continue;
+            for (const d of defs) {
+                let set = edges.get(d);
+                if (!set) {
+                    set = new Set();
+                    edges.set(d, set);
+                }
+                for (const r of refs)
+                    set.add(r);
+            }
+        }
+        return { nodes: Array.from(nodes), edges };
+    });
+}
+function cachePathFor(pathPrefix) {
+    const hash = crypto
+        .createHash("sha1")
+        .update(pathPrefix)
+        .digest("hex")
+        .slice(0, 16);
+    return path.join(config_1.PATHS.globalRoot, "pagerank", `${hash}.json`);
+}
+function getTtlMs() {
+    var _a;
+    const env = Number.parseInt((_a = process.env.GMAX_PAGERANK_TTL_MS) !== null && _a !== void 0 ? _a : "", 10);
+    return Number.isFinite(env) && env > 0 ? env : DEFAULT_TTL_MS;
+}
+function readDiskCache(pathPrefix) {
+    const file = cachePathFor(pathPrefix);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        const computedAt = Date.parse(data.computedAt);
+        if (!Number.isFinite(computedAt))
+            return null;
+        if (Date.now() - computedAt > getTtlMs())
+            return null;
+        const scores = new Map();
+        let max = 0;
+        for (const [k, v] of Object.entries(data.scores)) {
+            const n = Number(v);
+            if (!Number.isFinite(n))
+                continue;
+            scores.set(k, n);
+            if (n > max)
+                max = n;
+        }
+        return { scores, max, computedAt };
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function writeDiskCache(pathPrefix, scores) {
+    const file = cachePathFor(pathPrefix);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const obj = {
+        pathPrefix,
+        computedAt: new Date().toISOString(),
+        nodeCount: scores.size,
+        scores: Object.fromEntries(scores),
+    };
+    fs.writeFileSync(file, JSON.stringify(obj), "utf8");
+}
+function loadOrComputePageRank(db, pathPrefix) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const mem = memoryCache.get(pathPrefix);
+        if (mem && Date.now() - mem.computedAt < getTtlMs()) {
+            return { scores: mem.scores, max: mem.max };
+        }
+        const disk = readDiskCache(pathPrefix);
+        if (disk) {
+            memoryCache.set(pathPrefix, disk);
+            return { scores: disk.scores, max: disk.max };
+        }
+        const graph = yield buildGraphFromDb(db, pathPrefix);
+        const scores = computePageRank(graph);
+        let max = 0;
+        for (const v of scores.values())
+            if (v > max)
+                max = v;
+        const entry = { scores, max, computedAt: Date.now() };
+        memoryCache.set(pathPrefix, entry);
+        try {
+            writeDiskCache(pathPrefix, scores);
+        }
+        catch (_a) { }
+        return { scores, max };
+    });
+}
+function pageRankBoostForSymbols(symbols, scores, max) {
+    if (!symbols || symbols.length === 0 || max <= 0)
+        return 0;
+    let best = 0;
+    for (const s of symbols) {
+        const v = scores.get(s);
+        if (v !== undefined && v > best)
+            best = v;
+    }
+    return best / max;
+}
+function _clearMemoryCacheForTests() {
+    memoryCache.clear();
+}
+function _cachePathForTests(pathPrefix) {
+    return cachePathFor(pathPrefix);
+}

package/dist/lib/search/searcher.js

@@ -15,6 +15,7 @@ const config_1 = require("../../config");
 const filter_builder_1 = require("../utils/filter-builder");
 const pool_1 = require("../workers/pool");
 const intent_1 = require("./intent");
+const pagerank_1 = require("./pagerank");
 function buildWhereClause(pathPrefix, filters, searchIntent) {
     var _a;
     const parts = [];
@@ -338,7 +339,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;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
             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
@@ -371,7 +372,7 @@ class Searcher {
             try {
                 table = yield this.db.ensureTable();
             }
-            catch (_j) {
+            catch (_k) {
                 return { data: [] };
             }
             // Ensure FTS index exists (lazy init, retry periodically on failure)
@@ -391,10 +392,15 @@ class Searcher {
                 }
             }
             // Phase A: Lightweight retrieval — only columns needed for RRF, cosine, boost, dedup
+            // PageRank tiebreaker needs defined_symbols for the per-chunk lookup; include
+            // it in the lightweight path only when the flag is on so we don't bloat the
+            // default query path.
+            const pagerankEnabled = process.env.GMAX_PAGERANK === "1" && !!pathPrefix;
             const LIGHTWEIGHT_COLUMNS = [
                 "id", "path", "hash", "chunk_index", "start_line", "end_line",
                 "is_anchor", "chunk_type", "role", "complexity", "is_exported",
                 "content", "parent_symbol", "referenced_symbols", "pooled_colbert_48d",
+                ...(pagerankEnabled ? ["defined_symbols"] : []),
             ];
             // _distance is auto-added by vectorSearch, _score by FTS — include each
             // in the respective query to suppress LanceDB deprecation warnings
@@ -432,7 +438,7 @@ class Searcher {
                             this.ftsAvailable = true;
                             console.warn("[Searcher] Rebuilt FTS index with position support — retry search");
                         }
-                        catch (_k) { }
+                        catch (_l) { }
                     }
                     else {
                         console.warn(`[Searcher] FTS search failed (will retry later): ${msg}`);
@@ -571,6 +577,40 @@ class Searcher {
                         : undefined,
                 };
             });
+            // PageRank tiebreaker (opt-in via GMAX_PAGERANK=1). Small additive delta on
+            // top of the post-boost score, sourced from the per-project call graph. Read
+            // docs/plans/2026-05-25-semantic-search-landscape.md (Bundle B / G1) for the
+            // measurement criterion that decides whether this flag becomes default-on.
+            if (pagerankEnabled && pathPrefix) {
+                try {
+                    const { scores: prScores, max: prMax } = yield (0, pagerank_1.loadOrComputePageRank)(this.db, pathPrefix);
+                    if (prMax > 0) {
+                        const envWeight = Number.parseFloat((_h = process.env.GMAX_PR_WEIGHT) !== null && _h !== void 0 ? _h : "");
+                        const PR_WEIGHT = Number.isFinite(envWeight) && envWeight >= 0 ? envWeight : 0.05;
+                        for (const item of scored) {
+                            const raw = item.record.defined_symbols;
+                            let defs = [];
+                            if (Array.isArray(raw)) {
+                                defs = raw.filter((v) => typeof v === "string");
+                            }
+                            else if (raw && typeof raw.toArray === "function") {
+                                try {
+                                    const arr = raw.toArray();
+                                    if (Array.isArray(arr)) {
+                                        defs = arr.filter((v) => typeof v === "string");
+                                    }
+                                }
+                                catch (_m) { }
+                            }
+                            const norm = (0, pagerank_1.pageRankBoostForSymbols)(defs, prScores, prMax);
+                            item.score += PR_WEIGHT * norm;
+                        }
+                    }
+                }
+                catch (e) {
+                    console.warn(`[Searcher] PageRank tiebreaker failed: ${e}`);
+                }
+            }
             // Note: "boosted" was not previously declared -- fix to use "scored"
             scored.sort((a, b) => b.score - a.score);
             // Item 11: Intelligent Deduplication
@@ -578,7 +618,7 @@ class Searcher {
             // Item 10: Per-file diversification
             const seenFiles = new Map();
             const diversified = [];
-            const envMaxPerFile = Number.parseInt((_h = process.env.GMAX_MAX_PER_FILE) !== null && _h !== void 0 ? _h : "", 10);
+            const envMaxPerFile = Number.parseInt((_j = process.env.GMAX_MAX_PER_FILE) !== null && _j !== void 0 ? _j : "", 10);
             const MAX_PER_FILE = Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3;
             for (const item of uniqueScored) {
                 const path = item.record.path || "";

package/mlx-embed-server/server.py

@@ -25,6 +25,30 @@ os.environ["HF_HUB_DISABLE_IMPLICIT_TOKEN"] = "1"
 os.environ["HF_HUB_VERBOSITY"] = "error"
 os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+# Auto-enable offline mode when the model is already cached, so steady-state
+# startups don't HEAD-check huggingface.co (annoying firewall prompts, slow
+# starts on flaky networks). First run with an empty cache stays online so
+# the model can be fetched. Force one or the other with GMAX_HF_ONLINE=1
+# or GMAX_HF_OFFLINE=1.
+def _hf_cache_has_model(model_id: str) -> bool:
+    hf_home = os.environ.get("HF_HOME") or os.path.expanduser(
+        os.path.join("~", ".cache", "huggingface")
+    )
+    cache_dir = os.path.join(
+        hf_home, "hub", "models--" + model_id.replace("/", "--")
+    )
+    return os.path.isdir(cache_dir) and bool(os.listdir(cache_dir))
+
+_model_id_for_cache_check = os.environ.get(
+    "MLX_EMBED_MODEL", "ibm-granite/granite-embedding-small-english-r2"
+)
+if os.environ.get("GMAX_HF_OFFLINE") == "1" or (
+    os.environ.get("GMAX_HF_ONLINE") != "1"
+    and _hf_cache_has_model(_model_id_for_cache_check)
+):
+    os.environ["HF_HUB_OFFLINE"] = "1"
+    os.environ["TRANSFORMERS_OFFLINE"] = "1"
 warnings.filterwarnings("ignore", message=".*PyTorch.*")
 warnings.filterwarnings("ignore", message=".*resource_tracker.*")
 logging.getLogger("huggingface_hub").setLevel(logging.ERROR)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {
@@ -28,6 +28,8 @@
     "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",
     "format": "biome check --write .",
     "format:check": "biome check .",
     "lint": "biome lint .",

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

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

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

@@ -13,6 +13,7 @@ allowed-tools: "Bash(gmax:*), Read"
 - **Quick symbol overview?** → `Bash(gmax peek <symbol>)` (signature + callers + callees)
 - **Need file structure?** → `Bash(gmax skeleton <path>)`
 - **Need call flow?** → `Bash(gmax trace <symbol>)`
+- **Is a symbol unused?** → `Bash(gmax dead <symbol>)` (call-graph check — hypothesis, not proof)
 
 ## Quick start
 
@@ -40,7 +41,7 @@ If search returns "This project hasn't been added to gmax yet", run `Bash(gmax a
 
 ### Search — `gmax "query" --agent`
 
-The `--agent` flag produces compact, token-efficient output for AI agents. It works on most commands — `search`, `peek`, `extract`, `trace`, `test`, `impact`, `similar`, `log`, `related`, `symbols`, `status`, `project`, `context`, `skeleton`, and `doctor`.
+The `--agent` flag produces compact, token-efficient output for AI agents. It works on most commands — `search`, `peek`, `extract`, `trace`, `test`, `impact`, `similar`, `dead`, `log`, `related`, `symbols`, `status`, `project`, `context`, `skeleton`, and `doctor`.
 
 ```
 gmax "where do we handle authentication" --agent
@@ -177,6 +178,14 @@ gmax similar src/lib/auth.ts           # files with similar structure
 gmax similar handleAuth -m 5 --agent   # top 5, compact output
 ```
 
+### Dead — `gmax dead <symbol>`
+```
+gmax dead handleAuth                   # zero-inbound-callers check via the call graph
+gmax dead handleAuth --agent           # TSV: status\tdef:line\tcaller_count\tcallers_top3
+gmax dead handleAuth --in src/         # restrict to a sub-path
+```
+Status is `DEAD` (no callers, not exported), `PUBLIC EXPORT` (no internal callers but the defining chunk is exported — check external usage), or `LIVE` (with caller count + top-3 file:line). The call graph reflects what tree-sitter chunked: dynamic dispatch, reflection, eval, and string-built call sites won't show up — `DEAD` is a hypothesis, not a proof.
+
 ### Context — `gmax context <topic> --budget <tokens>`
 ```
 gmax context "authentication system" --budget 4000
@@ -219,13 +228,14 @@ gmax llm on/off/start/stop/status          # manage local LLM server
 10. **Test** — `Bash(gmax test <symbol>)` to find tests covering a symbol before editing
 11. **Impact** — `Bash(gmax impact <symbol>)` for blast radius before significant changes
 12. **Similar** — `Bash(gmax similar <symbol>)` to find similar patterns for DRY analysis
-13. **Context** — `Bash(gmax context "topic" --budget 4000)` for a token-budgeted topic summary
-14. **Related** — `Bash(gmax related <file>)` to see what else to look at
-15. **Status** — `Bash(gmax status)` to check index state across all projects
+13. **Dead** — `Bash(gmax dead <symbol>)` to check if a symbol has zero inbound callers (hypothesis, not proof)
+14. **Context** — `Bash(gmax context "topic" --budget 4000)` for a token-budgeted topic summary
+15. **Related** — `Bash(gmax related <file>)` to see what else to look at
+16. **Status** — `Bash(gmax status)` to check index state across all projects
 
 ## Tips
 
-- **Use `--agent` for compact output** — works on most commands: search, peek, extract, trace, log, test, impact, similar, related, status, project, doctor.
+- **Use `--agent` for compact output** — works on most commands: search, peek, extract, trace, log, test, impact, similar, dead, related, status, project, doctor.
 - **Be specific.** 5+ words. "auth" returns noise. "where does the server validate JWT tokens" is specific.
 - **Use `--role ORCHESTRATION`** to skip type definitions and find the actual logic.
 - **Use `--symbol`** when the query is a function/class name — gets search + trace in one call.