grepmax 0.23.0 → 0.25.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.23.0",
+      "version": "0.25.0",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/README.md

@@ -73,6 +73,7 @@ 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
@@ -134,6 +135,7 @@ Plugins auto-update when you run `npm install -g grepmax@latest` — no need to
 | `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, 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. |
@@ -177,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` |
@@ -318,16 +332,21 @@ worker RAM, and dense-vector storage while *lowering* recall on code search.
 Unless you have a measured reason to switch (e.g. a recall complaint on a very
 large repo — benchmark it first), stay on 384d.
 
-To change tiers:
+The model tier is part of the persisted embedding generation. You can change the desired
+configuration, but existing indexes remain on their built generation until you explicitly run the
+guarded whole-corpus rebuild:
 
 ```bash
-gmax config --model-tier standard   # a dim change needs a full re-embed
-gmax repair --rebuild               # drops the shared table, re-embeds every project at the new dim
+gmax config --model-tier standard   # changes desired configuration only
+gmax config                         # shows configured vs built identity
+gmax status                         # reports current / legacy / stale / unbuilt per project
+gmax repair --rebuild               # guarded whole-corpus rebuild through the daemon
 ```
 
-A vector-dimension change can't be applied by a per-project `gmax index --reset`
-— the shared `chunks` table is fixed-width, so `gmax repair --rebuild` is the
-sanctioned path.
+A model change cannot be applied by a per-project `gmax index --reset`, even when vector widths
+match: one query embedding cannot safely search rows from another embedding space. Stale-generation
+search and sync fail before mutation, preserving the existing index. Run `gmax repair --rebuild` to
+replace the whole corpus, or restore the prior model tier as the non-destructive alternative.
 
 ### Ignoring Files
 

package/dist/commands/add.js

@@ -54,30 +54,12 @@ 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");
 const vector_db_1 = require("../lib/store/vector-db");
+const blocked_roots_1 = require("../lib/utils/blocked-roots");
 const exit_1 = require("../lib/utils/exit");
 const project_marker_1 = require("../lib/utils/project-marker");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 const watcher_launcher_1 = require("../lib/utils/watcher-launcher");
-function getBlockedRoots() {
-    const home = os.homedir();
-    return new Set([
-        home,
-        path.dirname(home),
-        "/",
-        "/tmp",
-        "/private",
-        "/private/tmp",
-        "/private/var",
-        "/var",
-        "/usr",
-        "/opt",
-        "/etc",
-        "/System",
-        "/Library",
-        "/Applications",
-    ].map((p) => path.resolve(p)));
-}
 function logBlockedAttempt(reason, attempted, extra) {
     var _a, _b;
     try {
@@ -101,17 +83,16 @@ Examples:
   gmax add . --no-index        Register only, index later with gmax index
 `)
     .action((dir, opts) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f;
     let vectorDb = null;
     try {
         const targetDir = dir ? path.resolve(dir) : process.cwd();
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(targetDir)) !== null && _a !== void 0 ? _a : targetDir;
         const projectName = path.basename(projectRoot);
-        const blocked = getBlockedRoots();
-        if (blocked.has(path.resolve(projectRoot))) {
+        if ((0, blocked_roots_1.isBlockedProjectRoot)(projectRoot)) {
             logBlockedAttempt("blocked_root", projectRoot);
             console.error(`Refusing to add ${projectRoot}: this path is blocked from indexing.\n` +
-                `(Blocked: home, /, /Users, /tmp, /private, /var, /usr, /opt, /etc, /System, /Library, /Applications.)\n` +
+                `(Blocked: ${blocked_roots_1.BLOCKED_ROOTS_DESCRIPTION}.)\n` +
                 `Pick a specific project subdirectory instead.\n` +
                 `Diagnostic logged to ~/.gmax/logs/blocked-add.log (cwd=${process.cwd()} ppid=${process.ppid}).`);
             process.exitCode = 1;
@@ -221,14 +202,18 @@ Examples:
                 if (!done.ok) {
                     throw new Error((_c = done.error) !== null && _c !== void 0 ? _c : "daemon add failed");
                 }
-                (0, project_registry_1.registerProject)(Object.assign(Object.assign({}, pendingEntry), { lastIndexed: new Date().toISOString(), chunkCount: (_d = done.indexed) !== null && _d !== void 0 ? _d : 0, status: "indexed", chunkerVersion: config_1.CONFIG.CHUNKER_VERSION }));
-                const failedFiles = (_e = done.failedFiles) !== null && _e !== void 0 ? _e : 0;
+                if (done.degraded === true) {
+                    (0, project_registry_1.registerProject)(Object.assign(Object.assign({}, pendingEntry), { status: "pending" }));
+                    spinner.warn(`Added ${projectName}, but indexing is incomplete (${(_d = done.scanErrors) !== null && _d !== void 0 ? _d : 0} scan errors, ${(_e = done.failedFiles) !== null && _e !== void 0 ? _e : 0} failed)`);
+                    process.exitCode = 1;
+                    return;
+                }
+                const failedFiles = (_f = done.failedFiles) !== null && _f !== void 0 ? _f : 0;
                 const failedSuffix = failedFiles > 0 ? ` · ${failedFiles} failed` : "";
                 spinner.succeed(`Added ${projectName} (${done.total} files, ${done.indexed} chunks${failedSuffix})`);
                 // Watcher already started by daemon's addProject
             }
             catch (e) {
-                (0, project_registry_1.registerProject)(pendingEntry);
                 spinner.fail(`Failed to index ${projectName}`);
                 throw e;
             }
@@ -242,12 +227,34 @@ Examples:
                     projectRoot,
                     onProgress,
                 });
-                (0, project_registry_1.registerProject)(Object.assign(Object.assign({}, pendingEntry), { lastIndexed: new Date().toISOString(), chunkCount: result.indexed, status: "indexed", chunkerVersion: config_1.CONFIG.CHUNKER_VERSION }));
-                const failedSuffix = result.failedFiles > 0 ? ` · ${result.failedFiles} failed` : "";
-                spinner.succeed(`Added ${projectName} (${result.total} files, ${result.indexed} chunks${failedSuffix})`);
+                if (result.degraded) {
+                    (0, project_registry_1.registerProject)(Object.assign(Object.assign({}, pendingEntry), { status: "pending" }));
+                    spinner.warn(`Added ${projectName}, but indexing is incomplete (${result.scanErrors} scan errors, ${result.failedFiles} failed)`);
+                    process.exitCode = 1;
+                }
+                else {
+                    const prefix = projectRoot.endsWith("/")
+                        ? projectRoot
+                        : `${projectRoot}/`;
+                    const chunkCount = yield vectorDb.countRowsForPath(prefix);
+                    (0, project_registry_1.stampProjectFullSync)({
+                        root: projectRoot,
+                        name: projectName,
+                        generation: result.generation,
+                        embedMode: result.embedMode,
+                        chunkCount,
+                        chunkerVersion: config_1.CONFIG.CHUNKER_VERSION,
+                        expectedFingerprint: result.registryExpectation.embeddingFingerprint,
+                        expectedRebuildId: result.registryExpectation.rebuildId,
+                    });
+                    const failedSuffix = result.failedFiles > 0 ? ` · ${result.failedFiles} failed` : "";
+                    spinner.succeed(`Added ${projectName} (${result.total} files, ${result.indexed} chunks${failedSuffix})`);
+                }
             }
             catch (e) {
-                (0, project_registry_1.registerProject)(pendingEntry);
+                if (!(e instanceof project_registry_1.ProjectRegistryConflictError)) {
+                    (0, project_registry_1.registerProject)(pendingEntry);
+                }
                 spinner.fail(`Failed to index ${projectName}`);
                 throw e;
             }
@@ -271,7 +278,7 @@ Examples:
             try {
                 yield vectorDb.close();
             }
-            catch (_f) { }
+            catch (_g) { }
         }
         yield (0, exit_1.gracefulExit)();
     }

package/dist/commands/config.js

@@ -12,8 +12,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.config = void 0;
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const embedding_status_1 = require("../lib/index/embedding-status");
 const index_config_1 = require("../lib/index/index-config");
 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");
 exports.config = new commander_1.Command("config")
     .description("View or update gmax configuration")
@@ -28,24 +30,29 @@ Examples:
   gmax config --query-log on           Enable query logging
 `)
     .action((_opts, cmd) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     const options = cmd.optsWithGlobals();
     const globalConfig = (0, index_config_1.readGlobalConfig)();
     const paths = (0, project_root_1.ensureProjectPaths)(process.cwd());
-    const indexConfig = (0, index_config_1.readIndexConfig)(paths.configPath);
+    const project = (0, project_registry_1.getProject)((_a = (0, project_root_1.findProjectRoot)(process.cwd())) !== null && _a !== void 0 ? _a : process.cwd());
     const hasUpdates = options.embedMode !== undefined ||
         options.modelTier !== undefined ||
         options.queryLog !== undefined;
     if (!hasUpdates) {
         // Show current config
-        const tier = (_a = config_1.MODEL_TIERS[globalConfig.modelTier]) !== null && _a !== void 0 ? _a : config_1.MODEL_TIERS.small;
+        const tier = (_b = config_1.MODEL_TIERS[globalConfig.modelTier]) !== null && _b !== void 0 ? _b : config_1.MODEL_TIERS.small;
         console.log("gmax configuration (~/.gmax/config.json)\n");
         console.log(`  Model tier:  ${globalConfig.modelTier} (${tier.vectorDim}d, ${tier.params})`);
         console.log(`  Embed mode:  ${globalConfig.embedMode}`);
         console.log(`  Embed model: ${globalConfig.embedMode === "gpu" ? tier.mlxModel : tier.onnxModel}`);
+        const identity = (0, embedding_status_1.projectEmbeddingStatus)(project, globalConfig);
+        console.log(`  Configured:  ${identity.configured.tier} ${identity.configured.vectorDim}d [${(0, embedding_status_1.embeddingFingerprintLabel)(identity.configured.fingerprint)}]`);
+        if (identity.built) {
+            console.log(`  Built:       ${identity.built.tier} ${identity.built.vectorDim}d [${(0, embedding_status_1.embeddingFingerprintLabel)(identity.built.fingerprint)}] (${identity.state})`);
+        }
         console.log(`  Query log:   ${globalConfig.queryLog ? "on" : "off"}`);
-        if (indexConfig === null || indexConfig === void 0 ? void 0 : indexConfig.indexedAt) {
-            console.log(`  Last indexed: ${indexConfig.indexedAt}`);
+        if (project === null || project === void 0 ? void 0 : project.lastIndexed) {
+            console.log(`  Last indexed: ${project.lastIndexed}`);
         }
         console.log(`\nTo change: gmax config --embed-mode <cpu|gpu> --model-tier <small|standard> --query-log <on|off>`);
         yield (0, exit_1.gracefulExit)();
@@ -80,11 +87,10 @@ Examples:
         // Reload config after queryLog write
         Object.assign(globalConfig, (0, index_config_1.readGlobalConfig)());
     }
-    const newTier = (_b = options.modelTier) !== null && _b !== void 0 ? _b : globalConfig.modelTier;
-    const newMode = (_c = options.embedMode) !== null && _c !== void 0 ? _c : globalConfig.embedMode;
-    const tier = (_d = config_1.MODEL_TIERS[newTier]) !== null && _d !== void 0 ? _d : config_1.MODEL_TIERS.small;
+    const newTier = (_c = options.modelTier) !== null && _c !== void 0 ? _c : globalConfig.modelTier;
+    const newMode = (_d = options.embedMode) !== null && _d !== void 0 ? _d : globalConfig.embedMode;
+    const tier = (_e = config_1.MODEL_TIERS[newTier]) !== null && _e !== void 0 ? _e : config_1.MODEL_TIERS.small;
     const tierChanged = newTier !== globalConfig.modelTier;
-    const dimChanged = tier.vectorDim !== globalConfig.vectorDim;
     (0, index_config_1.writeGlobalConfig)({
         modelTier: newTier,
         vectorDim: tier.vectorDim,
@@ -99,12 +105,7 @@ Examples:
     });
     console.log(`Updated: embed-mode=${newMode}, model-tier=${newTier} (${tier.vectorDim}d)`);
     if (tierChanged) {
-        // A dimension change can't be fixed by a per-project `gmax index --reset`:
-        // the shared `chunks` table is fixed-width, so it must be dropped and
-        // rebuilt. A same-dim model swap (future tiers) can use a per-project reset.
-        console.log(dimChanged
-            ? `⚠️  Model tier changed (${globalConfig.vectorDim}d → ${tier.vectorDim}d). The shared vector table is fixed-width — run \`${config_1.REBUILD_COMMAND}\` to drop it and re-embed every project at the new dim.`
-            : "⚠️  Model tier changed — run `gmax index --reset` per project to re-embed with the new model.");
+        console.log(`Model tier changed (${globalConfig.vectorDim}d → ${tier.vectorDim}d). Existing indexes are preserved and search is blocked until you run 'gmax repair --rebuild'.`);
     }
     yield (0, exit_1.gracefulExit)();
 }));

package/dist/commands/context.js

@@ -53,7 +53,9 @@ const vector_db_1 = require("../lib/store/vector-db");
 const arrow_1 = require("../lib/utils/arrow");
 const budget_pack_1 = require("../lib/utils/budget-pack");
 const exit_1 = require("../lib/utils/exit");
+const file_utils_1 = require("../lib/utils/file-utils");
 const filter_builder_1 = require("../lib/utils/filter-builder");
+const path_containment_1 = require("../lib/utils/path-containment");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 function estimateTokens(text) {
@@ -106,8 +108,11 @@ function resolveExistingPath(target, root, projectRoot) {
         path.resolve(projectRoot, target),
     ];
     for (const candidate of candidates) {
-        if (fs.existsSync(candidate))
-            return candidate;
+        if (!fs.existsSync(candidate))
+            continue;
+        return (0, path_containment_1.resolveContainedPath)(projectRoot, candidate, {
+            verifyExistingTarget: true,
+        });
     }
     return null;
 }
@@ -137,7 +142,7 @@ function renderPathContext(target, absPath, projectRoot, budget) {
             }
             return state;
         }
-        const content = fs.readFileSync(absPath, "utf-8");
+        const content = (0, file_utils_1.readContainedTextFileSync)(projectRoot, absPath);
         const skeletonizer = new skeleton_1.Skeletonizer();
         yield skeletonizer.init();
         if (skeletonizer.isSupported(absPath).supported) {
@@ -196,8 +201,9 @@ exports.context = new commander_1.Command("context")
         }
         const searcher = new searcher_1.Searcher(vectorDb);
         // Phase 1: Semantic search
-        const response = yield searcher.search(topic, maxResults, { rerank: true }, {}, projectRoot);
-        if (response.data.length === 0) {
+        const response = yield searcher.search(topic, maxResults, { rerank: true }, {}, `${projectRoot}/`);
+        const scopedData = response.data.filter((result) => (0, path_containment_1.isPathWithin)(projectRoot, chunkPath(result)));
+        if (scopedData.length === 0) {
             console.log(`No results found for "${topic}".`);
             return;
         }
@@ -208,8 +214,8 @@ exports.context = new commander_1.Command("context")
         sections.push(header);
         tokensUsed += estimateTokens(header);
         // Phase 2: Entry points (ORCHESTRATION role results)
-        const orchestrators = response.data.filter((r) => r.role === "ORCHESTRATION");
-        const entryPoints = orchestrators.length > 0 ? orchestrators : response.data.slice(0, 3);
+        const orchestrators = scopedData.filter((r) => r.role === "ORCHESTRATION");
+        const entryPoints = orchestrators.length > 0 ? orchestrators : scopedData.slice(0, 3);
         const epSection = ["\n## Entry Points"];
         for (const r of entryPoints.slice(0, 5)) {
             const p = chunkPath(r);
@@ -230,13 +236,21 @@ exports.context = new commander_1.Command("context")
         const topChunks = entryPoints.slice(0, 3);
         const bodyBlobs = topChunks.map((r) => {
             var _a, _b;
-            const absP = chunkPath(r);
+            let absP;
+            try {
+                absP = (0, path_containment_1.resolveContainedPath)(projectRoot, chunkPath(r), {
+                    verifyExistingTarget: true,
+                });
+            }
+            catch (_c) {
+                return null;
+            }
             const startLine = chunkStartLine(r);
             const endLine = chunkEndLine(r);
             const sym = (_b = (_a = (0, arrow_1.toArr)(r.defined_symbols)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : "";
             const parentSym = String(r.parent_symbol || "");
             try {
-                const content = fs.readFileSync(absP, "utf-8");
+                const content = (0, file_utils_1.readContainedTextFileSync)(projectRoot, absP);
                 const allLines = content.split("\n");
                 const body = allLines
                     .slice(startLine, Math.min(endLine + 1, allLines.length))
@@ -255,7 +269,7 @@ exports.context = new commander_1.Command("context")
                 }
                 return `\n--- ${relPath(projectRoot, absP)}:${startLine + 1} ${label} ---\n${enclosing}${body}`;
             }
-            catch (_c) {
+            catch (_d) {
                 return null; // File not readable — drop
             }
         });
@@ -279,7 +293,18 @@ exports.context = new commander_1.Command("context")
         }
         // Phase 4: File skeletons for unique files
         const uniqueFiles = [
-            ...new Set(response.data.map((r) => chunkPath(r)).filter(Boolean)),
+            ...new Set(scopedData
+                .map((r) => {
+                try {
+                    return (0, path_containment_1.resolveContainedPath)(projectRoot, chunkPath(r), {
+                        verifyExistingTarget: true,
+                    });
+                }
+                catch (_a) {
+                    return "";
+                }
+            })
+                .filter(Boolean)),
         ].slice(0, 5);
         const skelSection = ["\n## File Structure"];
         const skeletonizer = new skeleton_1.Skeletonizer();
@@ -288,7 +313,7 @@ exports.context = new commander_1.Command("context")
             if (!skeletonizer.isSupported(absP).supported)
                 continue;
             try {
-                const content = fs.readFileSync(absP, "utf-8");
+                const content = (0, file_utils_1.readContainedTextFileSync)(projectRoot, absP);
                 const result = yield skeletonizer.skeletonizeFile(absP, content);
                 if (!result.success)
                     continue;
@@ -311,7 +336,7 @@ exports.context = new commander_1.Command("context")
         // Phase 5: Related files summary
         const table = yield vectorDb.ensureTable();
         const allSymbols = new Set();
-        for (const r of response.data) {
+        for (const r of scopedData) {
             for (const s of (0, arrow_1.toArr)(r.defined_symbols))
                 allSymbols.add(s);
         }