grepmax 0.17.22 → 0.17.24

package/dist/commands/peek.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.peek = void 0;
 const fs = __importStar(require("node:fs"));
 const commander_1 = require("commander");
+const callsites_1 = require("../lib/graph/callsites");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const vector_db_1 = require("../lib/store/vector-db");
 const agent_errors_1 = require("../lib/utils/agent-errors");
@@ -52,6 +53,7 @@ const exit_1 = require("../lib/utils/exit");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const language_1 = require("../lib/utils/language");
 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 useColors = process.stdout.isTTY && !process.env.NO_COLOR;
 const style = {
@@ -69,26 +71,45 @@ function extractSignature(filePath, startLine, endLine) {
         const lines = content.split("\n");
         const chunk = lines.slice(startLine, endLine + 1);
         const bodyLines = chunk.length;
-        // Find the signature: everything up to and including the opening brace
+        // Find the signature: everything up to and including the opening brace.
+        // Only treat `{` / `=>` as the body boundary once the parameter list's
+        // parens are balanced — object-literal param types (`cached: { … }`)
+        // contain braces mid-signature and must not end it.
         const sigLines = [];
+        let parenDepth = 0;
         for (const line of chunk) {
             sigLines.push(line);
-            if (line.includes("{") || line.includes("=>"))
+            for (const ch of line) {
+                if (ch === "(")
+                    parenDepth++;
+                else if (ch === ")")
+                    parenDepth--;
+            }
+            if (parenDepth <= 0 && (line.includes("{") || line.includes("=>"))) {
                 break;
+            }
+            if (sigLines.length >= 12)
+                break; // degenerate input — bail
         }
         // If we only got one line and it's the whole function, collapse it
         if (sigLines.length >= bodyLines) {
-            return { signature: chunk.join("\n"), bodyLines: 0 };
+            const whole = chunk.join("\n");
+            return { signature: whole, signatureOnly: whole, bodyLines: 0 };
         }
         const sig = sigLines.join("\n");
         const remaining = bodyLines - sigLines.length;
         return {
             signature: `${sig}\n    // ... (${remaining} lines)\n  }`,
+            signatureOnly: sig,
             bodyLines,
         };
     }
     catch (_a) {
-        return { signature: "(source not available)", bodyLines: 0 };
+        return {
+            signature: "(source not available)",
+            signatureOnly: "(source not available)",
+            bodyLines: 0,
+        };
     }
 }
 exports.peek = new commander_1.Command("peek")
@@ -109,6 +130,7 @@ exports.peek = new commander_1.Command("peek")
     const depth = Math.min(Math.max(Number.parseInt(opts.depth || "1", 10), 1), 3);
     try {
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
+        (0, stale_hint_1.maybeWarnStaleChunker)(projectRoot, { agent: opts.agent });
         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")));
@@ -122,6 +144,9 @@ exports.peek = new commander_1.Command("peek")
         // languages, refuse to silently pick one. The graph builder otherwise
         // picks one chunk arbitrarily and lists callers from a different
         // language — verified failure mode.
+        // Same-language multi-definition is reported as a note instead (below):
+        // the first definition still wins, but the agent learns it guessed.
+        let otherDefs = [];
         {
             const tableForCheck = yield vectorDb.ensureTable();
             const allDefs = yield tableForCheck
@@ -134,6 +159,14 @@ exports.peek = new commander_1.Command("peek")
                 path: String(row.path || ""),
                 startLine: Number(row.start_line || 0),
             }));
+            // Dedupe by file: split sub-chunks of one definition share a path,
+            // while genuine ambiguity (same name defined elsewhere) crosses files.
+            const distinct = new Map();
+            for (const c of chunks) {
+                if (!distinct.has(c.path))
+                    distinct.set(c.path, c);
+            }
+            otherDefs = [...distinct.values()];
             const byLang = (0, language_1.groupByLanguage)(chunks);
             if (byLang.size >= 2) {
                 const rel = (p) => p.startsWith(projectRoot) ? p.slice(projectRoot.length + 1) : p;
@@ -198,7 +231,30 @@ exports.peek = new commander_1.Command("peek")
                 line: c.line,
             }));
         }
-        const calleeList = graph.callees.map((c) => ({
+        // Re-anchor chunk-level caller rows to actual call sites and dedupe —
+        // getCallers() returns one row per chunk, which multiplies callers for
+        // classes split across many chunks (verified: 3 real call sites → 66).
+        const resolvedCallers = (0, callsites_1.resolveCallSites)(callerList, symbol).map((c) => {
+            var _a;
+            return ({
+                symbol: c.symbol,
+                file: c.file,
+                line: (_a = c.snippetLine) !== null && _a !== void 0 ? _a : c.line,
+            });
+        });
+        // Builtins listed as "(not indexed)" callees (trunc, now, filter, …)
+        // are noise; project symbols always resolve so they're unaffected.
+        // Dedupe by symbol — repeated references arrive once per chunk.
+        const seenCallees = new Set();
+        const calleeList = graph.callees
+            .filter((c) => c.file || !(0, callsites_1.isBuiltinCallee)(c.symbol))
+            .filter((c) => {
+            if (seenCallees.has(c.symbol))
+                return false;
+            seenCallees.add(c.symbol);
+            return true;
+        })
+            .map((c) => ({
             symbol: c.symbol,
             file: c.file,
             line: c.line,
@@ -207,16 +263,30 @@ exports.peek = new commander_1.Command("peek")
             // Compact TSV output
             const exportedStr = exported ? "exported" : "";
             console.log(`${center.symbol}\t${rel(center.file)}:${center.line + 1}\t${center.role}\t${exportedStr}`);
-            // Signature (first line only)
-            const { signature } = extractSignature(center.file, startLine, endLine);
-            const firstLine = signature.split("\n")[0].trim();
-            console.log(`sig: ${firstLine}`);
+            if (otherDefs.length > 1) {
+                const others = otherDefs
+                    .filter((d) => d.path !== center.file)
+                    .slice(0, 4)
+                    .map((d) => `${rel(d.path)}:${d.startLine + 1}`);
+                if (others.length > 0) {
+                    console.log(`also-defined: ${others.join(", ")} — showing the first; pin with --in <subpath>`);
+                }
+            }
+            // Signature — all lines up to the opening brace, collapsed to one
+            // line so parameters survive (first-line-only loses them).
+            const { signatureOnly } = extractSignature(center.file, startLine, endLine);
+            const sigOnly = signatureOnly
+                .split("\n")
+                .map((l) => l.trim())
+                .join(" ")
+                .replace(/\s+/g, " ");
+            console.log(`sig: ${sigOnly}`);
             // Callers
-            for (const c of callerList.slice(0, MAX_CALLERS)) {
+            for (const c of resolvedCallers.slice(0, MAX_CALLERS)) {
                 console.log(`<- ${c.symbol}\t${c.file ? `${rel(c.file)}:${c.line + 1}` : "(not indexed)"}`);
             }
-            if (callerList.length > MAX_CALLERS) {
-                console.log(`<- ... ${callerList.length - MAX_CALLERS} more`);
+            if (resolvedCallers.length > MAX_CALLERS) {
+                console.log(`<- ... ${resolvedCallers.length - MAX_CALLERS} more`);
             }
             // Callees
             for (const c of calleeList.slice(0, MAX_CALLEES)) {
@@ -239,6 +309,15 @@ exports.peek = new commander_1.Command("peek")
             // Rich output
             const exportedStr = exported ? ", exported" : "";
             console.log(`${style.bold(`peek: ${center.symbol}`)}  ${style.dim(`${rel(center.file)}:${center.line + 1}`)}  ${style.dim(`[${center.role}${exportedStr}]`)}`);
+            if (otherDefs.length > 1) {
+                const others = otherDefs
+                    .filter((d) => d.path !== center.file)
+                    .slice(0, 4)
+                    .map((d) => `${rel(d.path)}:${d.startLine + 1}`);
+                if (others.length > 0) {
+                    console.log(style.dim(`  also defined in: ${others.join(", ")} — showing the first; pin with --in <subpath>`));
+                }
+            }
             console.log();
             // Signature with collapsed body
             const { signature } = extractSignature(center.file, startLine, endLine);
@@ -247,9 +326,9 @@ exports.peek = new commander_1.Command("peek")
             }
             console.log();
             // Callers
-            if (callerList.length > 0) {
-                const shown = callerList.slice(0, MAX_CALLERS);
-                console.log(style.bold(`callers (${callerList.length}):`));
+            if (resolvedCallers.length > 0) {
+                const shown = resolvedCallers.slice(0, MAX_CALLERS);
+                console.log(style.bold(`callers (${resolvedCallers.length}):`));
                 for (const c of shown) {
                     if (c.file) {
                         console.log(`  ${style.blue("\u2190")} ${style.green(c.symbol.padEnd(25))} ${style.dim(`${rel(c.file)}:${c.line + 1}`)}`);
@@ -258,8 +337,8 @@ exports.peek = new commander_1.Command("peek")
                         console.log(`  ${style.blue("\u2190")} ${c.symbol.padEnd(25)} ${style.dim("(not indexed)")}`);
                     }
                 }
-                if (callerList.length > MAX_CALLERS) {
-                    console.log(style.dim(`  ... and ${callerList.length - MAX_CALLERS} more`));
+                if (resolvedCallers.length > MAX_CALLERS) {
+                    console.log(style.dim(`  ... and ${resolvedCallers.length - MAX_CALLERS} more`));
                 }
             }
             else {

package/dist/commands/project.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.project = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
+const callsites_1 = require("../lib/graph/callsites");
 const vector_db_1 = require("../lib/store/vector-db");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const exit_1 = require("../lib/utils/exit");
@@ -91,7 +92,9 @@ exports.project = new commander_1.Command("project")
         const dirCounts = new Map();
         const roleCounts = new Map();
         const symbolRefs = new Map();
+        const definedInProject = new Set();
         const entryPoints = [];
+        const seenEntryPoints = new Set();
         for (const row of rows) {
             const p = String(row.path || "");
             const role = String(row.role || "IMPLEMENTATION");
@@ -115,13 +118,19 @@ exports.project = new commander_1.Command("project")
             dc.files.add(p);
             dc.chunks++;
             roleCounts.set(role, (roleCounts.get(role) || 0) + 1);
+            for (const d of defs)
+                definedInProject.add(d);
             for (const ref of refs)
                 symbolRefs.set(ref, (symbolRefs.get(ref) || 0) + 1);
             if (exported && role === "ORCHESTRATION" && complexity >= 5 && defs.length > 0) {
-                entryPoints.push({
-                    symbol: defs[0],
-                    path: p.startsWith(prefix) ? p.slice(prefix.length) : p,
-                });
+                const epKey = `${defs[0]}:${p}`;
+                if (!seenEntryPoints.has(epKey)) {
+                    seenEntryPoints.add(epKey);
+                    entryPoints.push({
+                        symbol: defs[0],
+                        path: p.startsWith(prefix) ? p.slice(prefix.length) : p,
+                    });
+                }
             }
         }
         const projects = (0, project_registry_1.listProjects)();
@@ -129,7 +138,11 @@ exports.project = new commander_1.Command("project")
         const extEntries = Array.from(extCounts.entries())
             .sort((a, b) => b[1] - a[1])
             .slice(0, 8);
+        // Key symbols must be the project's own: raw referenced_symbols counts
+        // are dominated by JS builtins (push, slice, map, …) which say nothing
+        // about the codebase.
         const topSymbols = Array.from(symbolRefs.entries())
+            .filter(([s]) => definedInProject.has(s) && !(0, callsites_1.isBuiltinCallee)(s))
             .sort((a, b) => b[1] - a[1])
             .slice(0, 8);
         if (opts.agent) {

package/dist/commands/related.js

@@ -51,6 +51,8 @@ const filter_builder_1 = require("../lib/utils/filter-builder");
 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 query_timeout_1 = require("../lib/utils/query-timeout");
+const stale_hint_1 = require("../lib/utils/stale-hint");
 const arrow_1 = require("../lib/utils/arrow");
 exports.related = new commander_1.Command("related")
     .description("Find files related by shared symbol references")
@@ -69,6 +71,7 @@ exports.related = new commander_1.Command("related")
         if (root === null)
             return;
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
+        (0, stale_hint_1.maybeWarnStaleChunker)(projectRoot, { agent: opts.agent });
         const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
         const absPath = path.resolve(projectRoot, file);
@@ -164,12 +167,13 @@ exports.related = new commander_1.Command("related")
                 basenameRejected = true;
             }
             else {
-                const rows = yield table
+                // No .limit() here: LIKE + limit deadlocks in @lancedb 0.27.x when
+                // more rows match than the limit (verified). The loop below caps.
+                const rows = yield (0, query_timeout_1.withQueryTimeout)(table
                     .query()
                     .select(["path"])
                     .where(`content LIKE '%${(0, filter_builder_1.escapeSqlString)(basename)}%' AND ${pathScope}`)
-                    .limit(limit * 4)
-                    .toArray();
+                    .toArray(), `content LIKE %${basename}% (related mentions)`);
                 const seen = new Set();
                 for (const row of rows) {
                     const p = String(row.path || "");

package/dist/commands/search.js

@@ -56,6 +56,7 @@ const import_extractor_1 = require("../lib/utils/import-extractor");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 const server_registry_1 = require("../lib/utils/server-registry");
+const stale_hint_1 = require("../lib/utils/stale-hint");
 const search_run_1 = require("./search-run");
 const search_skeletons_1 = require("./search-skeletons");
 exports.search = new commander_1.Command("search")
@@ -217,6 +218,7 @@ Examples:
                     };
                     console.log((0, agent_search_formatter_1.formatAgentSearchResults)(filteredData, projectRootForServer, {
                         includeImports: options.imports,
+                        query: pattern,
                         getImportsForFile,
                         explain: options.explain,
                     }));
@@ -284,6 +286,7 @@ Examples:
         if (project.status === "pending") {
             console.warn("This project is still being indexed. Results may be incomplete.\n");
         }
+        (0, stale_hint_1.maybeWarnStaleChunker)(checkRoot, { agent: options.agent });
         // Compute effective paths + filters early — both the daemon-mediated
         // and in-process search paths need them. Reuse the resolved checkRoot
         // so --root <name> only resolves once per invocation.
@@ -444,6 +447,7 @@ Examples:
                 if (options.agent) {
                     body = (0, agent_search_formatter_1.formatAgentSearchResults)(g.items, g.root, {
                         includeImports: options.imports,
+                        query: pattern,
                         getImportsForFile,
                         explain: options.explain,
                     });
@@ -487,6 +491,7 @@ Examples:
             else {
                 console.log((0, agent_search_formatter_1.formatAgentSearchResults)(filteredData, effectiveRoot, {
                     includeImports: options.imports,
+                    query: pattern,
                     getImportsForFile,
                     explain: options.explain,
                 }));

package/dist/commands/similar.js

@@ -51,6 +51,7 @@ const filter_builder_1 = require("../lib/utils/filter-builder");
 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 stale_hint_1 = require("../lib/utils/stale-hint");
 const arrow_1 = require("../lib/utils/arrow");
 exports.similar = new commander_1.Command("similar")
     .description("Find semantically similar code to a symbol or file")
@@ -71,6 +72,7 @@ exports.similar = new commander_1.Command("similar")
         if (root === null)
             return;
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
+        (0, stale_hint_1.maybeWarnStaleChunker)(projectRoot, { agent: opts.agent });
         const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
         const table = yield vectorDb.ensureTable();

package/dist/commands/test-find.js

@@ -45,10 +45,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.testFind = void 0;
 const commander_1 = require("commander");
 const impact_1 = require("../lib/graph/impact");
+const test_hits_1 = require("../lib/graph/test-hits");
 const vector_db_1 = require("../lib/store/vector-db");
 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 stale_hint_1 = require("../lib/utils/stale-hint");
 exports.testFind = new commander_1.Command("test")
     .description("Find tests that exercise a symbol or file")
     .argument("<target>", "Symbol name or file path")
@@ -66,6 +68,7 @@ exports.testFind = new commander_1.Command("test")
         if (root === null)
             return;
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
+        (0, stale_hint_1.maybeWarnStaleChunker)(projectRoot, { agent: opts.agent });
         const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
         const { symbols, resolvedAsFile } = yield (0, impact_1.resolveTargetSymbols)(target, vectorDb, projectRoot);
@@ -91,25 +94,18 @@ exports.testFind = new commander_1.Command("test")
             return;
         }
         const rel = (p) => p.startsWith(`${projectRoot}/`) ? p.slice(projectRoot.length + 1) : p;
+        // One line per test file: the file is what the reader runs; caller
+        // symbols inside it (often internal helpers) are detail, not the lead.
+        const grouped = (0, test_hits_1.groupTestHitsByFile)(tests);
         if (opts.agent) {
-            for (const t of tests) {
-                const hopLabel = t.hops === -1
-                    ? "via-import"
-                    : t.hops === 0
-                        ? "direct"
-                        : `${t.hops}-hop`;
-                console.log(`${rel(t.file)}:${t.line + 1}\t${t.symbol}\t${hopLabel}`);
+            for (const t of grouped) {
+                console.log(`${rel(t.file)}:${t.line + 1}\t${(0, test_hits_1.hopLabelAgent)(t.hops)}${(0, test_hits_1.formatViaAgent)(t.via)}`);
             }
         }
         else {
             console.log(`Tests for ${target}:\n`);
-            for (const t of tests) {
-                const hopLabel = t.hops === -1
-                    ? "via import"
-                    : t.hops === 0
-                        ? "calls directly"
-                        : `${t.hops} hop${t.hops > 1 ? "s" : ""} away`;
-                console.log(`  ${rel(t.file)}:${t.line + 1}  ${t.symbol}  (${hopLabel})`);
+            for (const t of grouped) {
+                console.log(`  ${rel(t.file)}:${t.line + 1}  (${(0, test_hits_1.hopLabelHuman)(t.hops)}${(0, test_hits_1.formatViaHuman)(t.via)})`);
             }
         }
     }

package/dist/commands/trace.js

@@ -43,14 +43,15 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.trace = void 0;
-const fs = __importStar(require("node:fs"));
 const commander_1 = require("commander");
+const callsites_1 = require("../lib/graph/callsites");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const formatter_1 = require("../lib/output/formatter");
 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 useColors = process.stdout.isTTY && !process.env.NO_COLOR;
 const dim = (s) => (useColors ? `\x1b[2m${s}\x1b[22m` : s);
@@ -78,33 +79,6 @@ function formatTraceAgent(graph, projectRoot) {
     }
     return lines.join("\n");
 }
-function findCallSiteSnippet(fileCache, callerFile, callerLine, targetSymbol) {
-    if (!callerFile)
-        return null;
-    let lines = fileCache.get(callerFile);
-    if (!lines) {
-        try {
-            lines = fs.readFileSync(callerFile, "utf-8").split("\n");
-        }
-        catch (_a) {
-            return null;
-        }
-        fileCache.set(callerFile, lines);
-    }
-    // Search a bounded window starting at the caller's definition line.
-    const start = Math.max(0, callerLine);
-    const end = Math.min(lines.length, callerLine + 200);
-    const wordRe = new RegExp(`\\b${targetSymbol.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
-    for (let i = start; i < end; i++) {
-        if (wordRe.test(lines[i])) {
-            return { snippet: lines[i].trim(), snippetLine: i };
-        }
-    }
-    // Window didn't contain the symbol — chunker rolled the reference up to a
-    // parent scope. Skip the snippet rather than showing a misleading default;
-    // the caller's file:line is still emitted.
-    return null;
-}
 function buildInboundTree(callerTree, targetSymbol, fileCache, withSnippets, limit) {
     var _a, _b, _c;
     const out = [];
@@ -114,7 +88,7 @@ function buildInboundTree(callerTree, targetSymbol, fileCache, withSnippets, lim
     const seen = new Set();
     for (const t of callerTree) {
         const snippet = withSnippets
-            ? findCallSiteSnippet(fileCache, t.node.file, t.node.line, targetSymbol)
+            ? (0, callsites_1.findCallSiteSnippet)(fileCache, t.node.file, t.node.line, targetSymbol)
             : null;
         const dedupeKey = `${t.node.file}:${(_a = snippet === null || snippet === void 0 ? void 0 : snippet.snippetLine) !== null && _a !== void 0 ? _a : t.node.line}`;
         if (seen.has(dedupeKey))
@@ -210,6 +184,7 @@ exports.trace = new commander_1.Command("trace")
     let vectorDb = null;
     try {
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
+        (0, stale_hint_1.maybeWarnStaleChunker)(projectRoot, { agent: opts.agent });
         const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
         const { resolveScope } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/scope-filter")));

package/dist/config.js

@@ -33,7 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INDEXABLE_EXTENSIONS = exports.FRAGMENT_COMPACT_THRESHOLD = exports.DISK_LOW_BYTES = exports.DISK_CRITICAL_BYTES = exports.MAX_FILE_SIZE_BYTES = exports.PATHS = exports.MAX_WORKER_MEMORY_MB = exports.WORKER_BOOT_TIMEOUT_MS = exports.WORKER_TIMEOUT_MS = exports.CONFIG = exports.MODEL_IDS = exports.DEFAULT_MODEL_TIER = exports.MODEL_TIERS = void 0;
+exports.INDEXABLE_EXTENSIONS = exports.FRAGMENT_COMPACT_THRESHOLD = exports.DISK_LOW_BYTES = exports.DISK_CRITICAL_BYTES = exports.MAX_FILE_SIZE_BYTES = exports.PATHS = exports.MAX_WORKER_MEMORY_MB = exports.WORKER_BOOT_TIMEOUT_MS = exports.WORKER_TIMEOUT_MS = exports.CHUNKER_VERSION_HISTORY = exports.CONFIG = exports.MODEL_IDS = exports.DEFAULT_MODEL_TIER = exports.MODEL_TIERS = void 0;
+exports.describeChunkerGap = describeChunkerGap;
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 exports.MODEL_TIERS = {
@@ -76,7 +77,52 @@ exports.CONFIG = {
     EMBED_BATCH_SIZE: 24,
     WORKER_THREADS: DEFAULT_WORKER_THREADS,
     QUERY_PREFIX: "",
+    // Bump when chunk metadata semantics change in a way that requires a full
+    // reindex to take effect. Must equal the latest entry's `v` in
+    // CHUNKER_VERSION_HISTORY below — see that list for per-version severity and
+    // the user-facing note rendered by `gmax doctor` and the staleness hint.
+    CHUNKER_VERSION: 3,
 };
+/**
+ * Per-version record of what changed in the chunker and how much it matters to
+ * an already-built index. `severity` drives tone: an "additive" change only
+ * adds new metadata (older indexes under-cover but aren't wrong), while a
+ * "breaking" change means older indexes carry incorrect metadata until a
+ * reindex. The `note` is shown verbatim to the user for the versions their
+ * index is missing. CONFIG.CHUNKER_VERSION must equal the highest `v` here.
+ */
+exports.CHUNKER_VERSION_HISTORY = [
+    {
+        v: 2,
+        severity: "breaking",
+        note: "sub-chunk symbol scoping; graph overcounted callers before this.",
+    },
+    {
+        v: 3,
+        severity: "additive",
+        note: "type-position edges; dead/trace miss type-only callers until reindex.",
+    },
+];
+/**
+ * Describe the gap between an index's stamped chunker version and the current
+ * one, or null when the index is already current. Shared by `gmax doctor` and
+ * the query-time staleness hint so both render the same severity + notes.
+ */
+function describeChunkerGap(indexedVersion) {
+    const fromVersion = indexedVersion !== null && indexedVersion !== void 0 ? indexedVersion : 1;
+    if (fromVersion >= exports.CONFIG.CHUNKER_VERSION)
+        return null;
+    const missed = exports.CHUNKER_VERSION_HISTORY.filter((h) => h.v > fromVersion && h.v <= exports.CONFIG.CHUNKER_VERSION);
+    const severity = missed.some((h) => h.severity === "breaking")
+        ? "breaking"
+        : "additive";
+    return {
+        fromVersion,
+        toVersion: exports.CONFIG.CHUNKER_VERSION,
+        severity,
+        notes: missed.map((h) => h.note),
+    };
+}
 exports.WORKER_TIMEOUT_MS = Number.parseInt(process.env.GMAX_WORKER_TIMEOUT_MS || "60000", 10);
 exports.WORKER_BOOT_TIMEOUT_MS = Number.parseInt(process.env.GMAX_WORKER_BOOT_TIMEOUT_MS || "300000", 10);
 exports.MAX_WORKER_MEMORY_MB = (() => {