grepmax 0.17.10 → 0.17.12

package/dist/commands/audit.js

@@ -0,0 +1,314 @@
+"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.audit = void 0;
+exports.computeAudit = computeAudit;
+const commander_1 = require("commander");
+const arrow_1 = require("../lib/utils/arrow");
+const exit_1 = require("../lib/utils/exit");
+const project_registry_1 = require("../lib/utils/project-registry");
+const project_root_1 = require("../lib/utils/project-root");
+const vector_db_1 = require("../lib/store/vector-db");
+const useColors = process.stdout.isTTY && !process.env.NO_COLOR;
+const style = {
+    bold: (s) => (useColors ? `\x1b[1m${s}\x1b[22m` : s),
+    dim: (s) => (useColors ? `\x1b[2m${s}\x1b[39m` : s),
+    red: (s) => (useColors ? `\x1b[31m${s}\x1b[39m` : s),
+    yellow: (s) => (useColors ? `\x1b[33m${s}\x1b[39m` : s),
+    cyan: (s) => (useColors ? `\x1b[36m${s}\x1b[39m` : s),
+};
+// Names too generic to be useful as god-node signal (`id`, `el`, `fn`, …).
+const MIN_GOD_NAME_LEN = 3;
+function rel(p, prefix) {
+    return p.startsWith(prefix) ? p.slice(prefix.length) : p;
+}
+/**
+ * Pure aggregation over chunk rows — no DB, no I/O. Builds the symbol→def map,
+ * cross-file inbound edges, and per-file fan-in/out, then derives god nodes
+ * (most depended-upon symbols), hub files (most depended-upon files), and
+ * dead-code candidates (non-exported symbols with zero inbound references).
+ * `top` caps each list; `deadTotal` reports the full pre-cap dead count.
+ */
+function computeAudit(rows, prefix, top) {
+    // First definition of a symbol wins (matches GraphBuilder semantics).
+    const defs = new Map();
+    // Distinct files that reference a symbol (cross-file inbound edges).
+    const inboundFiles = new Map();
+    const inboundTotal = new Map();
+    // Per-file aggregates.
+    const fileDefs = new Map();
+    const fileOutRefs = new Map();
+    const files = new Set();
+    for (const row of rows) {
+        const file = String(row.path || "");
+        const line = Number(row.start_line || 0);
+        const exported = Boolean(row.is_exported);
+        const defSyms = (0, arrow_1.toArr)(row.defined_symbols);
+        const refSyms = (0, arrow_1.toArr)(row.referenced_symbols);
+        files.add(file);
+        for (const s of defSyms) {
+            if (!defs.has(s)) {
+                defs.set(s, { file, line, exported, complexity: 0 });
+            }
+            if (!fileDefs.has(file))
+                fileDefs.set(file, new Set());
+            fileDefs.get(file).add(s);
+        }
+        for (const s of refSyms) {
+            if (!inboundFiles.has(s))
+                inboundFiles.set(s, new Set());
+            inboundFiles.get(s).add(file);
+            inboundTotal.set(s, (inboundTotal.get(s) || 0) + 1);
+            if (!fileOutRefs.has(file))
+                fileOutRefs.set(file, new Set());
+            fileOutRefs.get(file).add(s);
+        }
+    }
+    // God nodes — in-project symbols by distinct external inbound files.
+    const godNodes = [];
+    for (const [symbol, info] of defs) {
+        if (symbol.length < MIN_GOD_NAME_LEN)
+            continue;
+        const refFiles = inboundFiles.get(symbol);
+        if (!refFiles)
+            continue;
+        let external = 0;
+        for (const f of refFiles)
+            if (f !== info.file)
+                external++;
+        if (external === 0)
+            continue;
+        godNodes.push({
+            symbol,
+            file: rel(info.file, prefix),
+            line: info.line,
+            inboundFiles: external,
+            totalRefs: inboundTotal.get(symbol) || 0,
+        });
+    }
+    godNodes.sort((a, b) => b.inboundFiles - a.inboundFiles || b.totalRefs - a.totalRefs);
+    // Hub files — distinct external files depending on each file (a file G
+    // depends on F if G references any symbol F defines).
+    const hubFiles = [];
+    for (const [file, syms] of fileDefs) {
+        const dependents = new Set();
+        for (const s of syms) {
+            const refFiles = inboundFiles.get(s);
+            if (!refFiles)
+                continue;
+            for (const f of refFiles)
+                if (f !== file)
+                    dependents.add(f);
+        }
+        // Fan-out: distinct referenced symbols that are defined somewhere
+        // in-project (external-library calls don't count as coupling).
+        let fanOut = 0;
+        const out = fileOutRefs.get(file);
+        if (out)
+            for (const s of out)
+                if (defs.has(s))
+                    fanOut++;
+        hubFiles.push({
+            file: rel(file, prefix),
+            dependents: dependents.size,
+            defines: syms.size,
+            fanOut,
+        });
+    }
+    hubFiles.sort((a, b) => b.dependents - a.dependents || b.defines - a.defines);
+    // Dead candidates — non-exported in-project symbols with zero inbound
+    // references anywhere (including their own file).
+    const deadAll = [];
+    for (const [symbol, info] of defs) {
+        if (info.exported)
+            continue;
+        if ((inboundTotal.get(symbol) || 0) > 0)
+            continue;
+        deadAll.push({ symbol, file: rel(info.file, prefix), line: info.line });
+    }
+    deadAll.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    return {
+        scannedChunks: rows.length,
+        scannedFiles: files.size,
+        godNodes: godNodes.slice(0, top),
+        hubFiles: hubFiles.filter((h) => h.dependents > 0).slice(0, top),
+        deadCandidates: deadAll.slice(0, top),
+        deadTotal: deadAll.length,
+    };
+}
+function formatHuman(r) {
+    const out = [];
+    out.push(`${style.bold("Audit")} ${style.dim(`— ${r.scannedChunks} chunks across ${r.scannedFiles} files`)}`);
+    out.push("");
+    out.push(style.bold("God nodes") + style.dim(" (most depended-upon symbols)"));
+    if (r.godNodes.length === 0) {
+        out.push(style.dim("  none"));
+    }
+    else {
+        for (const g of r.godNodes) {
+            out.push(`  ${style.cyan(g.symbol.padEnd(28))} ${style.dim(`${g.inboundFiles} files`)}, ${g.totalRefs} refs  ${style.dim(`${g.file}:${g.line + 1}`)}`);
+        }
+    }
+    out.push("");
+    out.push(style.bold("Hub files") + style.dim(" (most depended-upon files)"));
+    if (r.hubFiles.length === 0) {
+        out.push(style.dim("  none"));
+    }
+    else {
+        for (const h of r.hubFiles) {
+            out.push(`  ${h.file.padEnd(44)} ${style.dim(`${h.dependents} dependents, ${h.defines} defs, fan-out ${h.fanOut}`)}`);
+        }
+    }
+    out.push("");
+    out.push(style.bold("Dead-code candidates") +
+        style.dim(` (${r.deadTotal} non-exported symbols with zero inbound refs)`));
+    if (r.deadCandidates.length === 0) {
+        out.push(style.dim("  none"));
+    }
+    else {
+        for (const d of r.deadCandidates) {
+            out.push(`  ${style.red(d.symbol.padEnd(28))} ${style.dim(`${d.file}:${d.line + 1}`)}`);
+        }
+        if (r.deadTotal > r.deadCandidates.length) {
+            out.push(style.dim(`  … and ${r.deadTotal - r.deadCandidates.length} more`));
+        }
+    }
+    out.push("");
+    out.push(style.dim("Static call graph: dynamic dispatch, reflection, eval, and string-built " +
+        "call sites are invisible. Dead candidates are hypotheses — verify with " +
+        "`gmax dead <symbol>` and `grep` before removing."));
+    return out.join("\n");
+}
+function formatAgent(r) {
+    const lines = [];
+    lines.push(`scanned\t${r.scannedChunks}\t${r.scannedFiles}`);
+    for (const g of r.godNodes) {
+        lines.push(`god\t${g.symbol}\t${g.file}:${g.line + 1}\t${g.inboundFiles}\t${g.totalRefs}`);
+    }
+    for (const h of r.hubFiles) {
+        lines.push(`hub\t${h.file}\t${h.dependents}\t${h.defines}\t${h.fanOut}`);
+    }
+    for (const d of r.deadCandidates) {
+        lines.push(`dead\t${d.symbol}\t${d.file}:${d.line + 1}`);
+    }
+    lines.push(`dead_total\t${r.deadTotal}`);
+    return lines.join("\n");
+}
+exports.audit = new commander_1.Command("audit")
+    .description("Graph-summary of the indexed project — god nodes (most depended-upon " +
+    "symbols), hub files (most depended-upon files), and dead-code candidates " +
+    "(non-exported symbols with zero inbound references). One pass over the " +
+    "static call graph; dynamic dispatch / reflection / eval are invisible, so " +
+    "dead candidates are hypotheses, not proof.")
+    .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("--top <n>", "How many of each category to show", "10")
+    .option("--agent", "Compact TSV output for AI agents", false)
+    .action((opts) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const root = (0, project_registry_1.resolveRootOrExit)(opts.root);
+    if (root === null)
+        return;
+    let vectorDb = null;
+    try {
+        const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
+        const prefix = projectRoot.endsWith("/")
+            ? projectRoot
+            : `${projectRoot}/`;
+        const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
+        vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
+        const { resolveScope, buildScopeWhere } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/scope-filter")));
+        const scope = resolveScope({
+            projectRoot,
+            in: opts.in,
+            exclude: opts.exclude,
+        });
+        const top = Math.max(1, Number.parseInt(opts.top, 10) || 10);
+        const table = yield vectorDb.ensureTable();
+        const rows = yield table
+            .query()
+            .select([
+            "path",
+            "start_line",
+            "defined_symbols",
+            "referenced_symbols",
+            "is_exported",
+        ])
+            .where(buildScopeWhere(scope))
+            .limit(500000)
+            .toArray();
+        if (rows.length === 0) {
+            console.log(opts.agent
+                ? "(no indexed data)"
+                : `No indexed data for ${projectRoot}. Run: gmax index --path ${projectRoot}`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = computeAudit(rows.map((r) => ({
+            path: String(r.path || ""),
+            start_line: Number(r.start_line || 0),
+            is_exported: Boolean(r.is_exported),
+            defined_symbols: (0, arrow_1.toArr)(r.defined_symbols),
+            referenced_symbols: (0, arrow_1.toArr)(r.referenced_symbols),
+        })), prefix, top);
+        console.log(opts.agent ? formatAgent(result) : formatHuman(result));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error("Audit failed:", message);
+        process.exitCode = 1;
+    }
+    finally {
+        if (vectorDb) {
+            try {
+                yield vectorDb.close();
+            }
+            catch (err) {
+                console.error("Failed to close VectorDB:", err);
+            }
+        }
+        yield (0, exit_1.gracefulExit)();
+    }
+}));

package/dist/commands/mcp.js

@@ -62,6 +62,7 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const audit_1 = require("./audit");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const index_config_1 = require("../lib/index/index-config");
 const syncer_1 = require("../lib/index/syncer");
@@ -239,6 +240,82 @@ const TOOLS = [
             required: ["symbol"],
         },
     },
+    {
+        name: "audit",
+        description: "Graph-summary of the indexed project in one call: god nodes (most depended-upon symbols), hub files (most depended-upon files), and dead-code candidates (non-exported symbols with zero inbound references). Built from the static call graph — dynamic dispatch, reflection, eval, and type-position-only references are invisible, so dead candidates are hypotheses; verify with the `dead` tool before acting.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                root: {
+                    type: "string",
+                    description: "Project root (default: current)",
+                },
+                top: {
+                    type: "number",
+                    description: "How many of each category to return (default 10)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_neighbors",
+        description: "Graph primitive: symbols reachable from a node along call edges within N hops. direction 'callees' = what it calls (outbound), 'callers' = what calls it (inbound). Each result carries its hop distance and definition location. Static call graph — same caveats as `dead`/`audit`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                symbol: { type: "string", description: "Starting symbol" },
+                direction: {
+                    type: "string",
+                    enum: ["callers", "callees"],
+                    description: "Edge direction (default callees)",
+                },
+                max_hops: {
+                    type: "number",
+                    description: "Max hops (default 2, max 5)",
+                },
+                root: { type: "string", description: "Project root (absolute path)" },
+            },
+            required: ["symbol"],
+        },
+    },
+    {
+        name: "find_paths",
+        description: "Graph primitive: shortest call-graph path between two symbols, as a symbol sequence. direction 'callees' searches outward from `from` (does `from` transitively call `to`?), 'callers' searches inward. Returns 'no path' if unreachable within max_hops.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                from: { type: "string", description: "Start symbol" },
+                to: { type: "string", description: "Target symbol" },
+                direction: {
+                    type: "string",
+                    enum: ["callers", "callees"],
+                    description: "Search direction (default callees)",
+                },
+                max_hops: {
+                    type: "number",
+                    description: "Max hops (default 6, max 10)",
+                },
+                root: { type: "string", description: "Project root (absolute path)" },
+            },
+            required: ["from", "to"],
+        },
+    },
+    {
+        name: "subgraph_for_files",
+        description: "Graph primitive: the local dependency subgraph for a set of files — symbols they define, the call edges among those symbols, and their outbound external dependencies. Paths may be absolute or project-root-relative.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                files: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "File paths (absolute or root-relative)",
+                },
+                root: { type: "string", description: "Project root (absolute path)" },
+            },
+            required: ["files"],
+        },
+    },
     {
         name: "list_symbols",
         description: "List indexed symbols with role and export status.",
@@ -1338,6 +1415,181 @@ exports.mcp = new commander_1.Command("mcp")
             }
         });
     }
+    function handleAudit(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            ensureWatcher();
+            const root = typeof args.root === "string" && args.root
+                ? path.resolve(args.root)
+                : projectRoot;
+            const prefix = root.endsWith("/") ? root : `${root}/`;
+            const top = Math.min(Math.max(Number(args.top) || 10, 1), 50);
+            try {
+                const db = getVectorDb();
+                const table = yield db.ensureTable();
+                const rows = yield table
+                    .query()
+                    .select([
+                    "path",
+                    "start_line",
+                    "defined_symbols",
+                    "referenced_symbols",
+                    "is_exported",
+                ])
+                    .where(`path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+                    .limit(500000)
+                    .toArray();
+                if (rows.length === 0) {
+                    return ok(`No indexed data found for ${root}. Run: gmax index --path ${root}`);
+                }
+                const audit = (0, audit_1.computeAudit)(rows.map((r) => ({
+                    path: String(r.path || ""),
+                    start_line: Number(r.start_line || 0),
+                    is_exported: Boolean(r.is_exported),
+                    defined_symbols: toStringArray(r.defined_symbols),
+                    referenced_symbols: toStringArray(r.referenced_symbols),
+                })), prefix, top);
+                const lines = [];
+                lines.push(`Audit — ${audit.scannedChunks} chunks across ${audit.scannedFiles} files`);
+                lines.push("");
+                lines.push("God nodes (most depended-upon symbols):");
+                for (const g of audit.godNodes) {
+                    lines.push(`  ${g.symbol} — ${g.inboundFiles} files, ${g.totalRefs} refs (${g.file}:${g.line + 1})`);
+                }
+                if (audit.godNodes.length === 0)
+                    lines.push("  none");
+                lines.push("");
+                lines.push("Hub files (most depended-upon files):");
+                for (const h of audit.hubFiles) {
+                    lines.push(`  ${h.file} — ${h.dependents} dependents, ${h.defines} defs, fan-out ${h.fanOut}`);
+                }
+                if (audit.hubFiles.length === 0)
+                    lines.push("  none");
+                lines.push("");
+                lines.push(`Dead-code candidates (${audit.deadTotal} non-exported symbols with zero inbound refs):`);
+                for (const d of audit.deadCandidates) {
+                    lines.push(`  ${d.symbol} (${d.file}:${d.line + 1})`);
+                }
+                if (audit.deadCandidates.length === 0)
+                    lines.push("  none");
+                if (audit.deadTotal > audit.deadCandidates.length) {
+                    lines.push(`  … and ${audit.deadTotal - audit.deadCandidates.length} more`);
+                }
+                lines.push("");
+                lines.push("Static call graph: dynamic dispatch, reflection, eval, and type-position-only references are invisible. Dead candidates are hypotheses — verify with the `dead` tool before removing.");
+                return ok(lines.join("\n"));
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return err(`Audit failed: ${msg}`);
+            }
+        });
+    }
+    function handleGetNeighbors(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            ensureWatcher();
+            const symbol = String(args.symbol || "");
+            if (!symbol)
+                return err("Missing required parameter: symbol");
+            const direction = args.direction === "callers" ? "callers" : "callees";
+            const maxHops = Math.min(Math.max(Number(args.max_hops) || 2, 1), 5);
+            try {
+                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
+                const builder = new graph_builder_1.GraphBuilder(getVectorDb(), root);
+                const hits = yield builder.getNeighbors(symbol, direction, maxHops);
+                if (hits.length === 0) {
+                    return ok(`No ${direction} found for '${symbol}' within ${maxHops} hop(s). Check it is indexed (\`gmax status\`) or try the \`dead\` tool.`);
+                }
+                const rel = (p) => p.startsWith(root) ? p.slice(root.length + 1) : p;
+                const lines = [
+                    `${direction} of ${symbol} (≤${maxHops} hops, ${hits.length} found):`,
+                ];
+                for (const h of hits.slice(0, 100)) {
+                    const loc = h.file ? ` ${rel(h.file)}:${h.line + 1}` : " (external)";
+                    lines.push(`  [${h.hops}h] ${h.symbol}${loc}`);
+                }
+                if (hits.length > 100)
+                    lines.push(`  … and ${hits.length - 100} more`);
+                return ok(lines.join("\n"));
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return err(`get_neighbors failed: ${msg}`);
+            }
+        });
+    }
+    function handleFindPaths(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            ensureWatcher();
+            const from = String(args.from || "");
+            const to = String(args.to || "");
+            if (!from || !to) {
+                return err("Missing required parameters: from and to");
+            }
+            const direction = args.direction === "callers" ? "callers" : "callees";
+            const maxHops = Math.min(Math.max(Number(args.max_hops) || 6, 1), 10);
+            try {
+                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
+                const builder = new graph_builder_1.GraphBuilder(getVectorDb(), root);
+                const pathSyms = yield builder.findPaths(from, to, direction, maxHops);
+                if (!pathSyms) {
+                    return ok(`No ${direction} path from '${from}' to '${to}' within ${maxHops} hops.`);
+                }
+                const arrow = direction === "callees" ? " → " : " ← ";
+                const hops = pathSyms.length - 1;
+                return ok(`Path (${hops} hop${hops === 1 ? "" : "s"}): ${pathSyms.join(arrow)}`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return err(`find_paths failed: ${msg}`);
+            }
+        });
+    }
+    function handleSubgraphForFiles(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            ensureWatcher();
+            const filesIn = Array.isArray(args.files)
+                ? args.files.map((f) => String(f)).filter(Boolean)
+                : [];
+            if (filesIn.length === 0) {
+                return err("Missing required parameter: files (non-empty array)");
+            }
+            try {
+                const root = typeof args.root === "string" && args.root ? args.root : projectRoot;
+                const abs = filesIn.map((f) => path.isAbsolute(f) ? f : path.resolve(root, f));
+                const builder = new graph_builder_1.GraphBuilder(getVectorDb(), root);
+                const sg = yield builder.subgraphForFiles(abs);
+                if (sg.symbols.length === 0) {
+                    return ok(`No indexed symbols found in: ${filesIn.join(", ")}. Check the paths and \`gmax status\`.`);
+                }
+                const rel = (p) => p.startsWith(root) ? p.slice(root.length + 1) : p;
+                const cap = (arr, n) => arr.length > n
+                    ? `${arr.slice(0, n).join(", ")} … (+${arr.length - n})`
+                    : arr.join(", ");
+                const lines = [];
+                lines.push(`Subgraph for ${sg.files.length} file(s): ${sg.symbols.length} symbols, ${sg.internalEdges.length} internal edges, ${sg.externalDeps.length} external deps`);
+                lines.push(`Files: ${sg.files.map(rel).join(", ")}`);
+                lines.push("");
+                lines.push(`Symbols: ${cap(sg.symbols, 50)}`);
+                lines.push("");
+                lines.push("Internal edges:");
+                for (const e of sg.internalEdges.slice(0, 80)) {
+                    lines.push(`  ${e.from} → ${e.to}`);
+                }
+                if (sg.internalEdges.length === 0)
+                    lines.push("  none");
+                if (sg.internalEdges.length > 80) {
+                    lines.push(`  … and ${sg.internalEdges.length - 80} more`);
+                }
+                lines.push("");
+                lines.push(`External deps: ${cap(sg.externalDeps, 50) || "none"}`);
+                return ok(lines.join("\n"));
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return err(`subgraph_for_files failed: ${msg}`);
+            }
+        });
+    }
     function handleListSymbols(args) {
         return __awaiter(this, void 0, void 0, function* () {
             ensureWatcher();
@@ -2080,6 +2332,18 @@ exports.mcp = new commander_1.Command("mcp")
             case "dead":
                 result = yield handleDead(toolArgs);
                 break;
+            case "audit":
+                result = yield handleAudit(toolArgs);
+                break;
+            case "get_neighbors":
+                result = yield handleGetNeighbors(toolArgs);
+                break;
+            case "find_paths":
+                result = yield handleFindPaths(toolArgs);
+                break;
+            case "subgraph_for_files":
+                result = yield handleSubgraphForFiles(toolArgs);
+                break;
             case "list_symbols":
                 result = yield handleListSymbols(toolArgs);
                 break;

package/dist/index.js

@@ -39,6 +39,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const add_1 = require("./commands/add");
+const audit_1 = require("./commands/audit");
 const context_1 = require("./commands/context");
 const dead_1 = require("./commands/dead");
 const diff_1 = require("./commands/diff");
@@ -116,6 +117,7 @@ commander_1.program.addCommand(trace_1.trace);
 commander_1.program.addCommand(extract_1.extract);
 commander_1.program.addCommand(peek_1.peek);
 commander_1.program.addCommand(dead_1.dead);
+commander_1.program.addCommand(audit_1.audit);
 commander_1.program.addCommand(project_1.project);
 commander_1.program.addCommand(related_1.related);
 commander_1.program.addCommand(log_1.log);

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

@@ -11,6 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GraphBuilder = void 0;
 const filter_builder_1 = require("../utils/filter-builder");
+const graph_traversal_1 = require("./graph-traversal");
 class GraphBuilder {
     constructor(db, pathPrefix, excludePrefixes) {
         this.db = db;
@@ -185,6 +186,102 @@ class GraphBuilder {
             return trees;
         });
     }
+    // --- MCP graph primitives (Phase 7) -----------------------------------
+    /** Symbols the given symbol references (outbound edges). */
+    calleesOf(symbol) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.getCallees(symbol);
+        });
+    }
+    /** 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);
+            const out = [];
+            for (const n of nodes) {
+                if (n.symbol && n.symbol !== "unknown" && !out.includes(n.symbol)) {
+                    out.push(n.symbol);
+                }
+            }
+            return out;
+        });
+    }
+    neighborFn(direction) {
+        return direction === "callers"
+            ? (s) => this.callersOf(s)
+            : (s) => this.calleesOf(s);
+    }
+    /**
+     * Symbols reachable from `symbol` along `direction` within `maxHops`, each
+     * annotated with hop distance and resolved to a definition location when one
+     * is indexed.
+     */
+    getNeighbors(symbol, direction, maxHops) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const hits = yield (0, graph_traversal_1.bfsNeighbors)(symbol, this.neighborFn(direction), maxHops);
+            const out = [];
+            for (const h of hits) {
+                const loc = yield this.resolveLocation(h.symbol);
+                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;
+        });
+    }
+    /** Shortest path `[from, …, to]` along `direction`, or null. */
+    findPaths(from_1, to_1, direction_1) {
+        return __awaiter(this, arguments, void 0, function* (from, to, direction, maxHops = 6) {
+            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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const table = yield this.db.ensureTable();
+            const escaped = (0, filter_builder_1.escapeSqlString)(symbol);
+            const rows = yield table
+                .query()
+                .select(["path", "start_line"])
+                .where(this.scopeWhere(`array_contains(defined_symbols, '${escaped}')`))
+                .limit(1)
+                .toArray();
+            if (rows.length === 0)
+                return null;
+            const r = rows[0];
+            return { file: String(r.path || ""), line: Number(r.start_line || 0) };
+        });
+    }
+    /**
+     * Build the local dependency subgraph for a set of files: every symbol they
+     * define, the edges among those symbols, and their outbound external deps.
+     */
+    subgraphForFiles(files) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (files.length === 0) {
+                return { files: [], symbols: [], internalEdges: [], externalDeps: [] };
+            }
+            const table = yield this.db.ensureTable();
+            const orClause = files
+                .map((f) => `path = '${(0, filter_builder_1.escapeSqlString)(f)}'`)
+                .join(" OR ");
+            const rows = yield table
+                .query()
+                .select(["path", "defined_symbols", "referenced_symbols"])
+                .where(this.scopeWhere(`(${orClause})`))
+                .limit(100000)
+                .toArray();
+            const toArray = (val) => {
+                if (val && typeof val.toArray === "function")
+                    return val.toArray();
+                return Array.isArray(val) ? val : [];
+            };
+            return (0, graph_traversal_1.buildFileSubgraph)(rows.map((r) => ({
+                path: String(r.path || ""),
+                defined_symbols: toArray(r.defined_symbols),
+                referenced_symbols: toArray(r.referenced_symbols),
+            })));
+        });
+    }
     mapRowToNode(row, targetSymbol, type) {
         // Helper to convert Arrow Vector to array if needed
         const toArray = (val) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.17.10",
+  "version": "0.17.12",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {
@@ -37,7 +37,7 @@
     "prepublishOnly": "pnpm build",
     "preversion": "pnpm test && pnpm typecheck",
     "version": "bash scripts/sync-versions.sh && git add -A",
-    "postversion": "git push origin main && git push origin v$npm_package_version && gh release create v$npm_package_version --generate-notes --title v$npm_package_version && sleep 5 && gh run watch $(gh run list --workflow=release.yml --branch v$npm_package_version --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status && sleep 30 && npm cache clean --force && npm install -g grepmax@$npm_package_version"
+    "postversion": "bash scripts/postrelease.sh"
   },
   "keywords": [
     "grepmax",

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

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