grepmax 0.22.0 → 0.24.0

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.22.0",
+      "version": "0.24.0",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/README.md

@@ -72,6 +72,8 @@ gmax log src/lib/auth.ts                 # Git commit history for a path or symb
 gmax test handleAuth                     # Find tests via reverse call graph
 gmax impact handleAuth                   # Dependents + affected tests
 gmax similar handleAuth                  # Find similar code patterns
+gmax audit --top 10                      # God nodes, hub files, file cycles, dead candidates
+gmax surprises --experimental --agent    # Experimental: similar but graph-disconnected file pairs
 gmax dead handleAuth                     # Unused-symbol check via call graph (DEAD / PUBLIC EXPORT / LIVE)
 gmax context "auth system" --budget 4000 # Token-budgeted topic summary
 gmax context src/lib/auth.ts --budget 4000 # Deterministic file/path context
@@ -132,7 +134,8 @@ 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. |
+| `audit` | Graph summary: god nodes, hub files, symbol-derived file dependency cycles, and dead-code candidates. |
+| `surprising_connections` | Experimental orientation signal: embedding-similar file pairs with no direct indexed static file edge. Requires `experimental:true`. |
 | `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. |
@@ -176,6 +179,18 @@ gmax "query" [options]
 | `--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` |
+
+## Experimental Orientation
+
+`gmax surprises --experimental` finds file pairs that are semantically similar but not already connected by the indexed static graph. Use it for architecture orientation, duplicate-logic sweeps, and cross-package drift checks, not as proof that two files are unrelated.
+
+```bash
+gmax surprises --experimental --agent
+gmax surprises --experimental --in packages/app/src --dir-depth 4 --agent
+gmax surprises --experimental --exclude generated --top 10
+```
+
+The CLI and MCP output include score, max similarity, pair count, representative symbols, directory buckets, top similarities, applied penalties, and `gmax skeleton` follow-up hints. On large monorepos, prefer `--in`/`--exclude`; the default scan is capped at 50,000 rows and user-provided `--max-rows` is capped at 100,000. If a narrow `--in` scope returns no findings, increase `--dir-depth` so subdirectories are compared inside the scope.
 | `--budget <tokens>` | Cap output tokens (for `--context-for-llm`). | `8000` |
 | `--explain` | Show scoring breakdown per result. | `false` |
 | `--scores` | Show relevance scores. | `false` |

package/dist/commands/audit.js

@@ -64,6 +64,73 @@ const MIN_GOD_NAME_LEN = 3;
 function rel(p, prefix) {
     return p.startsWith(prefix) ? p.slice(prefix.length) : p;
 }
+function findFileCycles(deps, prefix, top) {
+    const indexByFile = new Map();
+    const lowlink = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const components = [];
+    let index = 0;
+    const strongConnect = (file) => {
+        var _a, _b, _c, _d, _e;
+        indexByFile.set(file, index);
+        lowlink.set(file, index);
+        index++;
+        stack.push(file);
+        onStack.add(file);
+        for (const dep of (_a = deps.get(file)) !== null && _a !== void 0 ? _a : []) {
+            if (!indexByFile.has(dep)) {
+                strongConnect(dep);
+                lowlink.set(file, Math.min((_b = lowlink.get(file)) !== null && _b !== void 0 ? _b : 0, (_c = lowlink.get(dep)) !== null && _c !== void 0 ? _c : 0));
+            }
+            else if (onStack.has(dep)) {
+                lowlink.set(file, Math.min((_d = lowlink.get(file)) !== null && _d !== void 0 ? _d : 0, (_e = indexByFile.get(dep)) !== null && _e !== void 0 ? _e : 0));
+            }
+        }
+        if (lowlink.get(file) !== indexByFile.get(file))
+            return;
+        const component = [];
+        while (stack.length > 0) {
+            const dep = stack.pop();
+            onStack.delete(dep);
+            component.push(dep);
+            if (dep === file)
+                break;
+        }
+        if (component.length > 1)
+            components.push(component);
+    };
+    const files = new Set();
+    for (const [file, targets] of deps) {
+        files.add(file);
+        for (const target of targets)
+            files.add(target);
+    }
+    for (const file of [...files].sort()) {
+        if (!indexByFile.has(file))
+            strongConnect(file);
+    }
+    return components
+        .map((component) => {
+        var _a;
+        const set = new Set(component);
+        let edgeCount = 0;
+        for (const file of component) {
+            for (const dep of (_a = deps.get(file)) !== null && _a !== void 0 ? _a : []) {
+                if (set.has(dep))
+                    edgeCount++;
+            }
+        }
+        return {
+            files: component.map((f) => rel(f, prefix)).sort(),
+            edgeCount,
+        };
+    })
+        .sort((a, b) => b.files.length - a.files.length ||
+        b.edgeCount - a.edgeCount ||
+        a.files.join("\0").localeCompare(b.files.join("\0")))
+        .slice(0, top);
+}
 /**
  * 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
@@ -170,6 +237,23 @@ function computeAudit(rows, prefix, top) {
         });
     }
     hubFiles.sort((a, b) => b.dependents - a.dependents || b.defines - a.defines);
+    const fileDeps = new Map();
+    for (const [file, refs] of fileOutRefs) {
+        for (const s of refs) {
+            if ((0, callsites_1.isBuiltinCallee)(s))
+                continue;
+            const defFiles = defFileCounts.get(s);
+            if (!defFiles || defFiles.size !== 1)
+                continue;
+            const [depFile] = defFiles;
+            if (!depFile || depFile === file)
+                continue;
+            if (!fileDeps.has(file))
+                fileDeps.set(file, new Set());
+            fileDeps.get(file).add(depFile);
+        }
+    }
+    const fileCycles = findFileCycles(fileDeps, prefix, top);
     // Dead candidates — non-exported in-project symbols with zero inbound
     // references anywhere (including their own file).
     const deadAll = [];
@@ -186,10 +270,17 @@ function computeAudit(rows, prefix, top) {
         scannedFiles: files.size,
         godNodes: godNodes.slice(0, top),
         hubFiles: hubFiles.filter((h) => h.dependents > 0).slice(0, top),
+        fileCycles,
         deadCandidates: deadAll.slice(0, top),
         deadTotal: deadAll.length,
     };
 }
+function formatCycle(files) {
+    const shown = files.length > 6
+        ? [...files.slice(0, 6), `... ${files.length - 6} more`]
+        : files;
+    return shown.join(", ");
+}
 function formatHuman(r) {
     const out = [];
     out.push(`${style.bold("Audit")} ${style.dim(`— ${r.scannedChunks} chunks across ${r.scannedFiles} files`)}`);
@@ -217,6 +308,17 @@ function formatHuman(r) {
         }
     }
     out.push("");
+    out.push(style.bold("File dependency cycles") +
+        style.dim(" (symbol-derived, bounded SCCs)"));
+    if (r.fileCycles.length === 0) {
+        out.push(style.dim("  none"));
+    }
+    else {
+        for (const c of r.fileCycles) {
+            out.push(`  ${formatCycle(c.files)}  ${style.dim(`${c.files.length} files, ${c.edgeCount} internal edges`)}`);
+        }
+    }
+    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) {
@@ -246,6 +348,9 @@ function formatAgent(r) {
     for (const h of r.hubFiles) {
         lines.push(`hub\t${h.file}\t${h.dependents}\t${h.defines}\t${h.fanOut}`);
     }
+    for (const c of r.fileCycles) {
+        lines.push(`cycle\t${c.files.join(",")}\t${c.files.length}\t${c.edgeCount}`);
+    }
     for (const d of r.deadCandidates) {
         lines.push(`dead\t${d.symbol}\t${d.file}:${d.line + 1}`);
     }
@@ -253,11 +358,12 @@ function formatAgent(r) {
     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.")
+    .description("Graph-summary of the indexed project: god nodes (most depended-upon " +
+    "symbols), hub files (most depended-upon files), symbol-derived file " +
+    "dependency cycles, and dead-code candidates (non-exported symbols with " +
+    "zero inbound references). One pass over the static reference 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])

package/dist/commands/impact.js

@@ -46,6 +46,7 @@ exports.impact = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const impact_1 = require("../lib/graph/impact");
+const impact_rollup_1 = require("../lib/graph/impact-rollup");
 const test_hits_1 = require("../lib/graph/test-hits");
 const vector_db_1 = require("../lib/store/vector-db");
 const agent_errors_1 = require("../lib/utils/agent-errors");
@@ -61,12 +62,16 @@ exports.impact = new commander_1.Command("impact")
     .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("--rollup", "Show export/package rollup (default for file targets in human output)", false)
+    .option("--flat", "Use the legacy flat dependent/test list", false)
+    .option("--top <n>", "Max rows per rollup section", "10")
     .option("--agent", "Compact output for AI agents", false)
     .action((target, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const depth = Math.min(Math.max(Number.parseInt(opts.depth || "1", 10), 1), 3);
     // commander maps --no-tests → opts.tests === false (defaults true).
     const includeTests = opts.tests !== false;
+    const top = Math.min(Math.max(Number.parseInt(opts.top || "10", 10) || 10, 1), 100);
     let vectorDb = null;
     try {
         const root = (0, project_registry_1.resolveRootOrExit)(opts.root);
@@ -105,15 +110,42 @@ exports.impact = new commander_1.Command("impact")
         const queryRoot = opts.in && opts.in.length > 0
             ? scope.pathPrefix.replace(/\/$/, "")
             : projectRoot;
+        const useRollup = !opts.flat && ((resolvedAsFile && !opts.agent) || opts.rollup === true);
+        const rollupLimit = Math.min(Math.max(top * 10, 100), 500);
         // Run dependents and tests in parallel. --no-tests skips the test
         // traversal entirely so the affected-tests section is omitted (not just
         // empty) below.
         const [dependents, tests] = yield Promise.all([
-            (0, impact_1.findDependents)(symbols, vectorDb, queryRoot, excludePaths, undefined, scope.excludePrefixes, symbolFamilies),
+            useRollup
+                ? (0, impact_1.findDependentsDetailed)(symbols, vectorDb, queryRoot, excludePaths, rollupLimit, scope.excludePrefixes, symbolFamilies)
+                : (0, impact_1.findDependents)(symbols, vectorDb, queryRoot, excludePaths, undefined, scope.excludePrefixes, symbolFamilies),
             includeTests
                 ? (0, impact_1.findTests)(symbols, vectorDb, queryRoot, depth, scope.excludePrefixes, symbolFamilies)
                 : Promise.resolve([]),
         ]);
+        if (useRollup) {
+            const detailedDependents = dependents;
+            const rollup = (0, impact_rollup_1.buildImpactRollup)({
+                targetSymbols: symbols,
+                dependents: detailedDependents,
+                tests,
+                projectRoot,
+                top,
+            });
+            const formatted = opts.agent
+                ? (0, impact_rollup_1.formatImpactRollupAgent)(rollup, {
+                    target,
+                    projectRoot,
+                    includeTests,
+                })
+                : (0, impact_rollup_1.formatImpactRollupHuman)(rollup, {
+                    target,
+                    projectRoot,
+                    includeTests,
+                });
+            console.log(formatted);
+            return;
+        }
         // Separate test files from non-test dependents
         const nonTestDeps = dependents.filter((d) => !(0, impact_1.isTestPath)(d.file));
         // One line per test file; caller symbols inside it become `via` detail.