grepmax 0.18.1 → 0.19.0

package/README.md

@@ -2,6 +2,14 @@
   <h1>grepmax</h1>
   <p><em>Slash tokens. Save time. Semantic search for your coding agent.</em></p>
 
+  <a href="https://www.npmjs.com/package/grepmax">
+    <img src="https://img.shields.io/npm/v/grepmax.svg" alt="npm version" />
+  </a>
+
+  <a href="https://www.npmjs.com/package/grepmax">
+    <img src="https://img.shields.io/npm/dm/grepmax.svg" alt="npm downloads" />
+  </a>
+
   <a href="https://opensource.org/licenses/Apache-2.0">
     <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" />
   </a>
@@ -24,7 +32,7 @@ Natural-language search that works like `grep`. Fast, local, and built for codin
 - **Role Detection:** Distinguishes `ORCHESTRATION` (high-level logic) from `DEFINITION` (types/classes).
 - **Local & Private:** 100% local embeddings via ONNX (CPU) or MLX (Apple Silicon GPU).
 - **Centralized Index:** One database at `~/.gmax/` — index once, search from anywhere.
-- **Agent-Ready:** `--agent` flag returns compact one-line output — ~90% fewer tokens than default.
+- **Agent-Ready:** `--agent` flag returns compact one-line output — ~89% fewer tokens than default.
 
 ## Quick Start
 
@@ -124,7 +132,12 @@ Plugins auto-update when you run `npm install -g grepmax@latest` — no need to
 | `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. |
+| `audit` | Graph summary: god nodes, hub files, and dead-code candidates in one call. |
+| `get_neighbors` | Graph primitive: symbols reachable from a node along call edges within N hops. |
+| `find_paths` | Graph primitive: shortest call-graph path between two symbols. |
+| `subgraph_for_files` | Graph primitive: local dependency subgraph for a set of files. |
 | `list_symbols` | Indexed symbols with role and export status. |
+| `list_projects` | List every indexed project (name, root, status, chunks) to pick a search scope. |
 | `index_status` | Index health: chunks, files, projects, watcher status. |
 | `summarize_project` | Project overview: languages, structure, key symbols, entry points. |
 | `summarize_directory` | Generate LLM summaries for indexed chunks. |
@@ -138,6 +151,7 @@ Plugins auto-update when you run `npm install -g grepmax@latest` — no need to
 | `investigate` | Agentic codebase Q&A using local LLM + gmax tools. |
 | `review_commit` | Review a git commit for bugs, security issues, and breaking changes. |
 | `review_report` | Get accumulated code review findings for the current project. |
+| `review_risk` | Deterministic risk ranking of symbols a commit touches (blast radius × tests × churn). No LLM. |
 
 ## Search Options
 
@@ -157,11 +171,19 @@ gmax "query" [options]
 | `--symbol` | Append call graph after results. | `false` |
 | `--imports` | Prepend file imports per result. | `false` |
 | `--name <regex>` | Filter by symbol name. | — |
+| `--in <subpath>` | Restrict to a sub-path of the project (repeatable). | — |
+| `--seed-file <path>` | Bias results toward files in your working context (repeatable). | — |
+| `--seed-symbol <name>` | Bias results toward an identifier you're working with (repeatable). | — |
 | `--skeleton` | Show file skeletons for top matches. | `false` |
 | `--context-for-llm` | Full function bodies + imports per result. | `false` |
 | `--budget <tokens>` | Cap output tokens (for `--context-for-llm`). | `8000` |
 | `--explain` | Show scoring breakdown per result. | `false` |
+| `--scores` | Show relevance scores. | `false` |
+| `--compact` | Compact hits view (paths + line ranges + role/preview). | `false` |
+| `--plain` | Disable ANSI colors and use simpler formatting. | `false` |
+| `-c, --content` | Show full chunk content instead of snippets. | `false` |
 | `-C <n>` | Context lines before/after. | `0` |
+| `-s, --sync` | Sync local files to the store before searching. | `false` |
 | `--root <dir>` | Search a different project. | cwd |
 | `--all-projects` | Search every indexed project; results grouped by project. | `false` |
 | `--projects <list>` | Search only these projects (comma-separated names). | — |
@@ -251,7 +273,10 @@ All data lives in `~/.gmax/`:
 
 **Pipeline:** Walk (gitignore-aware) → Chunk (Tree-sitter) → Embed (384-dim Granite via ONNX/MLX) → Store (LanceDB + LMDB) → Search (vector + FTS + RRF fusion + ColBERT rerank)
 
-**Supported Languages:** TypeScript, JavaScript, Python, Go, Rust, Java, C#, C++, C, Ruby, PHP, Swift, Kotlin, JSON, YAML, Markdown, SQL, Shell.
+**Supported Languages:**
+
+- *Structure-aware* (Tree-sitter chunking + call graph): TypeScript, JavaScript/JSX, Python, Go, Rust, Java, C#, C++, C, Ruby, PHP, Swift, Kotlin, Scala, Lua, Bash, JSON.
+- *Text-indexed* (semantic search only, no call graph): Markdown, YAML, CSS, HTML, SQL, TOML, XML, and other common formats.
 
 ## Configuration
 

package/dist/commands/add.js

@@ -147,7 +147,7 @@ Examples:
             }
             const names = children.map((c) => c.name).join(", ");
             console.log(`Absorbing ${children.length} sub-project(s): ${names}`);
-            const { ensureDaemonRunning: checkDaemon, sendStreamingCommand: sendCmd } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
+            const { ensureDaemonRunning: checkDaemon, sendStreamingCommand: sendCmd, } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
             const daemonUp = yield checkDaemon();
             for (const child of children) {
                 if (daemonUp) {
@@ -158,7 +158,9 @@ Examples:
                     // Direct mode: delete vectors and MetaCache entries
                     const childPaths = (0, project_root_1.ensureProjectPaths)(child.root);
                     const db = new vector_db_1.VectorDB(childPaths.lancedbDir);
-                    const childPrefix = child.root.endsWith("/") ? child.root : `${child.root}/`;
+                    const childPrefix = child.root.endsWith("/")
+                        ? child.root
+                        : `${child.root}/`;
                     yield db.deletePathsWithPrefix(childPrefix);
                     const { MetaCache } = yield Promise.resolve().then(() => __importStar(require("../lib/store/meta-cache")));
                     const mc = new MetaCache(childPaths.lmdbPath);

package/dist/commands/claude-code.js

@@ -43,9 +43,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installClaudeCode = void 0;
+const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-const node_child_process_1 = require("node:child_process");
 const commander_1 = require("commander");
 function runClaudeCommand(args) {
     return new Promise((resolve, reject) => {

package/dist/commands/codex.js

@@ -57,7 +57,9 @@ function writeSkillToAgents(skill) {
         const markerRe = new RegExp(`\n?${SKILL_START}[\\s\\S]*?${SKILL_END}\n?`, "g");
         const cleaned = content.replace(markerRe, "");
         // Remove legacy content (everything between --- blocks mentioning gmax)
-        const withoutLegacy = cleaned.replace(/---[\s\S]*?(?:gmax|--compact)[\s\S]*?(?=\n<!-- |$)/, "").trim();
+        const withoutLegacy = cleaned
+            .replace(/---[\s\S]*?(?:gmax|--compact)[\s\S]*?(?=\n<!-- |$)/, "")
+            .trim();
         node_fs_1.default.writeFileSync(AGENTS_PATH, withoutLegacy ? `${withoutLegacy}\n\n${block}` : block);
     }
     else {

package/dist/commands/dead.js

@@ -50,8 +50,8 @@ const agent_errors_1 = require("../lib/utils/agent-errors");
 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 stale_hint_1 = require("../lib/utils/stale-hint");
 const project_root_1 = require("../lib/utils/project-root");
+const stale_hint_1 = require("../lib/utils/stale-hint");
 const useColors = process.stdout.isTTY && !process.env.NO_COLOR;
 const style = {
     bold: (s) => (useColors ? `\x1b[1m${s}\x1b[22m` : s),
@@ -148,11 +148,7 @@ exports.dead = new commander_1.Command("dead")
         const isExported = Boolean(defRow.is_exported);
         const builder = new graph_builder_1.GraphBuilder(vectorDb, scope.pathPrefix, scope.excludePrefixes);
         const callers = yield builder.getCallers(symbol);
-        const status = callers.length === 0
-            ? isExported
-                ? "PUBLIC_EXPORT"
-                : "DEAD"
-            : "LIVE";
+        const status = callers.length === 0 ? (isExported ? "PUBLIC_EXPORT" : "DEAD") : "LIVE";
         const topCallers = callers
             .slice(0, TOP_CALLERS)
             .map((c) => ({ file: c.file, line: c.line }));

package/dist/commands/doctor.js

@@ -135,7 +135,10 @@ exports.doctor = new commander_1.Command("doctor")
             embedUp = res.ok;
         }
         catch (err) {
-            embedError = err.code === "ECONNREFUSED" ? "connection refused" : (err.message || String(err));
+            embedError =
+                err.code === "ECONNREFUSED"
+                    ? "connection refused"
+                    : err.message || String(err);
         }
         console.log(`${embedUp ? "ok" : "WARN"}  MLX Embed: ${embedUp ? "running (port 8100)" : `not running${embedError ? ` (${embedError})` : ""}`}`);
         if (embedUp) {
@@ -234,7 +237,12 @@ exports.doctor = new commander_1.Command("doctor")
         try {
             const diskStats = fs.statfsSync(config_1.PATHS.lancedbDir);
             availBytes = diskStats.bavail * diskStats.bsize;
-            diskLevel = availBytes < config_1.DISK_CRITICAL_BYTES ? "CRITICAL" : availBytes < config_1.DISK_LOW_BYTES ? "LOW" : "ok";
+            diskLevel =
+                availBytes < config_1.DISK_CRITICAL_BYTES
+                    ? "CRITICAL"
+                    : availBytes < config_1.DISK_LOW_BYTES
+                        ? "LOW"
+                        : "ok";
         }
         catch (_g) { }
         const staleChunkerProjects = projects.filter((p) => {
@@ -247,7 +255,10 @@ exports.doctor = new commander_1.Command("doctor")
         // (a dim change can't be auto-fixed in the shared fixed-dim table; that's
         // the deferred Phase 1B re-embed work).
         const staleEmbeddingProjects = projects.filter((p) => p.status === "indexed" &&
-            (0, config_1.describeEmbeddingGap)({ modelTier: p.modelTier, vectorDim: p.vectorDim }, { modelTier: globalConfig.modelTier, vectorDim: globalConfig.vectorDim }) !== null);
+            (0, config_1.describeEmbeddingGap)({ modelTier: p.modelTier, vectorDim: p.vectorDim }, {
+                modelTier: globalConfig.modelTier,
+                vectorDim: globalConfig.vectorDim,
+            }) !== null);
         if (opts.agent) {
             const fields = [
                 "index_health",
@@ -281,7 +292,10 @@ exports.doctor = new commander_1.Command("doctor")
                 ].join("\t"));
             }
             for (const p of staleEmbeddingProjects) {
-                const gap = (0, config_1.describeEmbeddingGap)({ modelTier: p.modelTier, vectorDim: p.vectorDim }, { modelTier: globalConfig.modelTier, vectorDim: globalConfig.vectorDim });
+                const gap = (0, config_1.describeEmbeddingGap)({ modelTier: p.modelTier, vectorDim: p.vectorDim }, {
+                    modelTier: globalConfig.modelTier,
+                    vectorDim: globalConfig.vectorDim,
+                });
                 if (!gap)
                     continue;
                 console.log([
@@ -361,7 +375,10 @@ exports.doctor = new commander_1.Command("doctor")
             // the shared fixed-dim table (deferred Phase 1B), so we point at the
             // manual reset instead.
             if (staleEmbeddingProjects.length > 0) {
-                const gaps = staleEmbeddingProjects.map((p) => (0, config_1.describeEmbeddingGap)({ modelTier: p.modelTier, vectorDim: p.vectorDim }, { modelTier: globalConfig.modelTier, vectorDim: globalConfig.vectorDim }));
+                const gaps = staleEmbeddingProjects.map((p) => (0, config_1.describeEmbeddingGap)({ modelTier: p.modelTier, vectorDim: p.vectorDim }, {
+                    modelTier: globalConfig.modelTier,
+                    vectorDim: globalConfig.vectorDim,
+                }));
                 const anyBreaking = gaps.some((g) => (g === null || g === void 0 ? void 0 : g.severity) === "breaking");
                 console.log(`${anyBreaking ? "WARN" : "INFO"}  Stale embedding: ${staleEmbeddingProjects.length} project(s) indexed with a different embedding model/dim — run 'gmax index --reset' per project`);
                 staleEmbeddingProjects.forEach((p, i) => {
@@ -391,8 +408,10 @@ exports.doctor = new commander_1.Command("doctor")
                 try {
                     const { MetaCache } = yield Promise.resolve().then(() => __importStar(require("../lib/store/meta-cache")));
                     const mc = new MetaCache(config_1.PATHS.lmdbPath);
-                    for (const project of projects.filter(p => p.status === "indexed")) {
-                        const prefix = project.root.endsWith("/") ? project.root : `${project.root}/`;
+                    for (const project of projects.filter((p) => p.status === "indexed")) {
+                        const prefix = project.root.endsWith("/")
+                            ? project.root
+                            : `${project.root}/`;
                         const cachedCount = (yield mc.getKeysWithPrefix(prefix)).size;
                         const vectorCount = yield db.countDistinctFilesForPath(prefix);
                         if (cachedCount > 0) {

package/dist/commands/extract.js

@@ -107,8 +107,8 @@ exports.extract = new commander_1.Command("extract")
     .description("Extract full function/class body by symbol name")
     .argument("<symbol>", "The symbol to extract")
     .option("--root <dir>", "Project root directory")
-    .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("--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("--imports", "Prepend file imports", false)
     .option("--no-tests", "Suppress the tests footer")
@@ -146,9 +146,7 @@ exports.extract = new commander_1.Command("extract")
         const byLang = (0, language_1.groupByLanguage)(chunks);
         if (byLang.size >= 2) {
             const rel = (p) => p.startsWith(projectRoot) ? p.slice(projectRoot.length + 1) : p;
-            const lines = [
-                `Symbol '${symbol}' is defined in multiple languages:`,
-            ];
+            const lines = [`Symbol '${symbol}' is defined in multiple languages:`];
             for (const [lang, group] of byLang) {
                 const c = group[0];
                 lines.push(`  ${lang.padEnd(6)} ${rel(c.path)}:${c.startLine + 1}`);

package/dist/commands/impact.js

@@ -51,15 +51,15 @@ const vector_db_1 = require("../lib/store/vector-db");
 const agent_errors_1 = require("../lib/utils/agent-errors");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
-const stale_hint_1 = require("../lib/utils/stale-hint");
 const project_root_1 = require("../lib/utils/project-root");
+const stale_hint_1 = require("../lib/utils/stale-hint");
 exports.impact = new commander_1.Command("impact")
     .description("Analyze change impact: dependents and affected tests")
     .argument("<target>", "Symbol name or file path")
     .option("-d, --depth <n>", "Caller traversal depth (default 1, max 3)", "1")
     .option("--root <dir>", "Project root directory")
-    .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("--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("--no-tests", "Skip affected-test analysis; show production blast radius only")
     .option("--agent", "Compact output for AI agents", false)
     .action((target, opts) => __awaiter(void 0, void 0, void 0, function* () {
@@ -87,7 +87,9 @@ exports.impact = new commander_1.Command("impact")
         }
         // Resolve the target's own file path for exclusion
         const targetPath = resolvedAsFile
-            ? (target.startsWith("/") ? target : path.resolve(projectRoot, target))
+            ? target.startsWith("/")
+                ? target
+                : path.resolve(projectRoot, target)
             : undefined;
         const excludePaths = targetPath ? new Set([targetPath]) : undefined;
         const { resolveScope } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/scope-filter")));

package/dist/commands/index.js

@@ -46,8 +46,8 @@ exports.index = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const config_1 = require("../config");
-const index_config_1 = require("../lib/index/index-config");
 const grammar_loader_1 = require("../lib/index/grammar-loader");
+const index_config_1 = require("../lib/index/index-config");
 const sync_helpers_1 = require("../lib/index/sync-helpers");
 const syncer_1 = require("../lib/index/syncer");
 const setup_helpers_1 = require("../lib/setup/setup-helpers");
@@ -113,7 +113,12 @@ Examples:
             // Daemon mode: IPC streaming — daemon handles watcher pause/resume internally
             const { spinner, onProgress } = (0, sync_helpers_1.createIndexingSpinner)(projectRoot, "Indexing...", { verbose: options.verbose });
             try {
-                const done = yield sendStreamingCommand({ cmd: "index", root: projectRoot, reset: options.reset, dryRun: options.dryRun }, (msg) => {
+                const done = yield sendStreamingCommand({
+                    cmd: "index",
+                    root: projectRoot,
+                    reset: options.reset,
+                    dryRun: options.dryRun,
+                }, (msg) => {
                     var _a, _b, _c;
                     onProgress({
                         processed: (_a = msg.processed) !== null && _a !== void 0 ? _a : 0,

package/dist/commands/log.js

@@ -97,7 +97,8 @@ function printHuman(commits, projectRoot, targetPaths) {
         if (targetPaths && targetPaths.length > 1) {
             const targetSet = new Set(targetPaths);
             const touched = c.numstatLines
-                .filter((n) => targetSet.has(n.path) || targetSet.has(path.resolve(projectRoot, n.path)))
+                .filter((n) => targetSet.has(n.path) ||
+                targetSet.has(path.resolve(projectRoot, n.path)))
                 .map((n) => relativize(n.path, projectRoot));
             if (touched.length > 0) {
                 console.log(`  ${style.dim(`via: ${touched.join(", ")}`)}`);
@@ -112,7 +113,8 @@ function printAgent(commits, projectRoot, targetPaths) {
         let touched = "";
         if (targetSet) {
             const touchedPaths = c.numstatLines
-                .filter((n) => targetSet.has(n.path) || targetSet.has(path.resolve(projectRoot, n.path)))
+                .filter((n) => targetSet.has(n.path) ||
+                targetSet.has(path.resolve(projectRoot, n.path)))
                 .map((n) => relativize(n.path, projectRoot));
             touched = touchedPaths.join(",");
         }