grepmax 0.17.23 → 0.18.0

package/dist/lib/index/chunker.js

@@ -359,7 +359,13 @@ class TreeSitterChunker {
                 if (t !== "lexical_declaration" && t !== "variable_declaration")
                     return false;
                 const parentType = ((_a = node.parent) === null || _a === void 0 ? void 0 : _a.type) || "";
-                const allowedParents = ["program", "module", "source_file", "class_body", "export_statement"];
+                const allowedParents = [
+                    "program",
+                    "module",
+                    "source_file",
+                    "class_body",
+                    "export_statement",
+                ];
                 if (parentType && !allowedParents.includes(parentType))
                     return false;
                 // Exported declarations are part of the API surface, so always index
@@ -367,7 +373,8 @@ class TreeSitterChunker {
                 // is `export const typeDefs = gql\`...\`` (template literals, object
                 // literals, or non-PascalCase consts) had no defined_symbols entry
                 // and peek/extract returned "Symbol not found".
-                if (parentType === "export_statement" || parentType === "export_declaration") {
+                if (parentType === "export_statement" ||
+                    parentType === "export_declaration") {
                     return true;
                 }
                 const text = node.text || "";
@@ -553,6 +560,15 @@ class TreeSitterChunker {
                             referencedSymbols.push(name);
                         }
                     };
+                    // Type-position references go in a SEPARATE list so they never inflate
+                    // referencedSymbols.length (which drives role classification below and
+                    // the search structural boost). Navigation consumers union the two.
+                    const typeReferencedSymbols = [];
+                    const addTypeRef = (n) => {
+                        if (n && !typeReferencedSymbols.includes(n)) {
+                            typeReferencedSymbols.push(n);
+                        }
+                    };
                     // Leaf identifier node types across grammars (a bare name with no
                     // named children — `ErrorCodes`, not `a.ErrorCodes`).
                     const LEAF_ID_TYPES = new Set([
@@ -623,8 +639,33 @@ class TreeSitterChunker {
                         "struct_expression", // Rust
                         "instance_expression", // Scala
                     ]);
+                    // Harvest Capitalized type names out of an annotation subtree, for the
+                    // grammars whose type names are NOT `type_identifier` nodes (so Shape 4
+                    // can't see them): Python/C# spell them `identifier`, PHP spells them
+                    // `name`. We walk the WHOLE subtree and keep every Capitalized leaf of
+                    // those kinds — safe because we only ever enter from a type position (a
+                    // `type` / `return_type` / `returns` field, or a base/heritage list).
+                    // Excludes the chunk's own name; lowercase builtins (`list`, `int`,
+                    // `string`) and non-name leaves (`predefined_type`, `string_content`
+                    // in `Literal["x"]`) fall out via the kind + Capitalized gates.
+                    const TYPE_NAME_LEAF_TYPES = new Set(["identifier", "name"]);
+                    const harvestTypeLeaves = (node) => {
+                        var _a, _b, _c;
+                        if (!node)
+                            return;
+                        if (((_b = (_a = node.namedChildren) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) === 0) {
+                            if (TYPE_NAME_LEAF_TYPES.has(node.type) &&
+                                /^[A-Z]/.test(node.text) &&
+                                node.text !== name) {
+                                addTypeRef(node.text);
+                            }
+                            return;
+                        }
+                        for (const c of (_c = node.namedChildren) !== null && _c !== void 0 ? _c : [])
+                            harvestTypeLeaves(c);
+                    };
                     const extractRefs = (n) => {
-                        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+                        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1;
                         // Handle JS/TS (call_expression), Python (call), Lua (function_call)
                         if (n.type === "call_expression" ||
                             n.type === "call" ||
@@ -737,10 +778,110 @@ class TreeSitterChunker {
                                 addRef(head.text);
                             }
                         }
-                        for (const child of (_j = n.namedChildren) !== null && _j !== void 0 ? _j : []) {
+                        // Shape 4 — type-position reference (TS/TSX): `: T`, `<T>`, `T[]`,
+                        // `as T`, `interface X extends T`, type aliases. TS uses a distinct
+                        // `type_identifier` node for type names (primitives are
+                        // `predefined_type`, so they never reach here). Capture Capitalized
+                        // ones, skipping the chunk's own name and any locally-declared type
+                        // parameter (`<T>` and its uses `value: T`). Constraints
+                        // (`T extends Foo`) still yield `Foo`. Type list, never referencedSymbols.
+                        if (n.type === "type_identifier" &&
+                            /^[A-Z]/.test(n.text) &&
+                            n.text !== name &&
+                            !declaredTypeParams.has(n.text)) {
+                            addTypeRef(n.text);
+                        }
+                        // Shape 5 — class heritage `class A extends B`: the superclass is an
+                        // `identifier` (a runtime value), not a `type_identifier`, so Shape 4
+                        // misses it. `implements I` and `interface X extends Y` use
+                        // type_identifier and are already covered. Reduce `extends ns.Base`
+                        // to `Base`; skip type arguments (Shape 4 handles those).
+                        if (n.type === "extends_clause") {
+                            for (const c of (_j = n.namedChildren) !== null && _j !== void 0 ? _j : []) {
+                                if (c.type === "type_arguments")
+                                    continue;
+                                const sup = simpleRefName(c);
+                                if (sup && /^[A-Z]/.test(sup) && sup !== name)
+                                    addTypeRef(sup);
+                            }
+                        }
+                        // Shape 6 — type-position references for grammars whose type names
+                        // are plain `identifier` / `name` nodes (not `type_identifier`), so
+                        // Shape 4 can't reach them. Read the annotation off the carrier
+                        // node's type field and harvest from THAT subtree only — never the
+                        // node as a whole — so value expressions stay out of the type list.
+                        // Each grammar is gated by `lang` because the carrier node/field
+                        // names collide across grammars (`function_definition`,
+                        // `method_declaration`, `assignment`, …). The other typed grammars
+                        // (Go/Rust/Java/Kotlin/Scala/Swift) spell type names as
+                        // `type_identifier` and are already covered by Shape 4.
+                        if (lang === "python") {
+                            // `x: Foo`, `-> Bar`, `v: Baz = …`, and `class C(Base)` bases.
+                            if (n.type === "typed_parameter" ||
+                                n.type === "typed_default_parameter") {
+                                harvestTypeLeaves((_l = (_k = n.childForFieldName) === null || _k === void 0 ? void 0 : _k.call(n, "type")) !== null && _l !== void 0 ? _l : null);
+                            }
+                            else if (n.type === "function_definition") {
+                                harvestTypeLeaves((_o = (_m = n.childForFieldName) === null || _m === void 0 ? void 0 : _m.call(n, "return_type")) !== null && _o !== void 0 ? _o : null);
+                            }
+                            else if (n.type === "assignment") {
+                                harvestTypeLeaves((_q = (_p = n.childForFieldName) === null || _p === void 0 ? void 0 : _p.call(n, "type")) !== null && _q !== void 0 ? _q : null);
+                            }
+                            else if (n.type === "class_definition") {
+                                harvestTypeLeaves((_s = (_r = n.childForFieldName) === null || _r === void 0 ? void 0 : _r.call(n, "superclasses")) !== null && _s !== void 0 ? _s : null);
+                            }
+                        }
+                        else if (lang === "c_sharp") {
+                            // Method return (`returns`), parameter / property / variable
+                            // (`type`), and the base/interface list.
+                            if (n.type === "parameter" ||
+                                n.type === "property_declaration" ||
+                                n.type === "variable_declaration") {
+                                harvestTypeLeaves((_u = (_t = n.childForFieldName) === null || _t === void 0 ? void 0 : _t.call(n, "type")) !== null && _u !== void 0 ? _u : null);
+                            }
+                            else if (n.type === "method_declaration") {
+                                harvestTypeLeaves((_w = (_v = n.childForFieldName) === null || _v === void 0 ? void 0 : _v.call(n, "returns")) !== null && _w !== void 0 ? _w : null);
+                            }
+                            else if (n.type === "base_list") {
+                                harvestTypeLeaves(n);
+                            }
+                        }
+                        else if (lang === "php") {
+                            // Types are `name` inside `named_type` / `optional_type`.
+                            // Parameter / property (`type`), function & method return
+                            // (`return_type`), and the extends / implements clauses.
+                            if (n.type === "simple_parameter" ||
+                                n.type === "property_declaration") {
+                                harvestTypeLeaves((_y = (_x = n.childForFieldName) === null || _x === void 0 ? void 0 : _x.call(n, "type")) !== null && _y !== void 0 ? _y : null);
+                            }
+                            else if (n.type === "function_definition" ||
+                                n.type === "method_declaration") {
+                                harvestTypeLeaves((_0 = (_z = n.childForFieldName) === null || _z === void 0 ? void 0 : _z.call(n, "return_type")) !== null && _0 !== void 0 ? _0 : null);
+                            }
+                            else if (n.type === "base_clause" ||
+                                n.type === "class_interface_clause") {
+                                harvestTypeLeaves(n);
+                            }
+                        }
+                        for (const child of (_1 = n.namedChildren) !== null && _1 !== void 0 ? _1 : []) {
                             extractRefs(child);
                         }
                     };
+                    // Collect locally-declared type-parameter names (`<T, K>`) so their
+                    // *uses* (`value: T`) are excluded from type refs, not just their
+                    // declarations. Chunk-scoped, which matches single-definition chunks.
+                    const declaredTypeParams = new Set();
+                    const collectTypeParams = (n) => {
+                        var _a;
+                        if (n.type === "type_parameter") {
+                            const nm = firstNamed(n);
+                            if ((nm === null || nm === void 0 ? void 0 : nm.type) === "type_identifier")
+                                declaredTypeParams.add(nm.text);
+                        }
+                        for (const child of (_a = n.namedChildren) !== null && _a !== void 0 ? _a : [])
+                            collectTypeParams(child);
+                    };
+                    collectTypeParams(effective);
                     extractRefs(effective);
                     // Classify role
                     let role = "IMPLEMENTATION";
@@ -761,6 +902,7 @@ class TreeSitterChunker {
                         isExported,
                         definedSymbols,
                         referencedSymbols,
+                        typeReferencedSymbols,
                         role,
                         parentSymbol: stack.length > 1
                             ? stack[stack.length - 1].replace(/^(Class|Method|Function|Interface|Type): /, "")
@@ -843,6 +985,9 @@ class TreeSitterChunker {
         if (sub.referencedSymbols) {
             sub.referencedSymbols = sub.referencedSymbols.filter(occurs);
         }
+        if (sub.typeReferencedSymbols) {
+            sub.typeReferencedSymbols = sub.typeReferencedSymbols.filter(occurs);
+        }
         return sub;
     }
     splitIfTooBig(chunk) {

package/dist/lib/llm/tools.js

@@ -61,10 +61,22 @@ exports.TOOLS = [
             parameters: {
                 type: "object",
                 properties: {
-                    query: { type: "string", description: "Natural language search query" },
-                    max_count: { type: "integer", description: "Max results (default 5)" },
-                    lang: { type: "string", description: "Filter by extension (e.g. 'ts', 'py')" },
-                    file: { type: "string", description: "Filter to files matching this name" },
+                    query: {
+                        type: "string",
+                        description: "Natural language search query",
+                    },
+                    max_count: {
+                        type: "integer",
+                        description: "Max results (default 5)",
+                    },
+                    lang: {
+                        type: "string",
+                        description: "Filter by extension (e.g. 'ts', 'py')",
+                    },
+                    file: {
+                        type: "string",
+                        description: "Filter to files matching this name",
+                    },
                 },
                 required: ["query"],
             },
@@ -79,7 +91,10 @@ exports.TOOLS = [
                 type: "object",
                 properties: {
                     symbol: { type: "string", description: "Symbol name to trace" },
-                    depth: { type: "integer", description: "Caller depth 1-3 (default 1)" },
+                    depth: {
+                        type: "integer",
+                        description: "Caller depth 1-3 (default 1)",
+                    },
                 },
                 required: ["symbol"],
             },
@@ -94,7 +109,10 @@ exports.TOOLS = [
                 type: "object",
                 properties: {
                     symbol: { type: "string", description: "Symbol name to peek at" },
-                    depth: { type: "integer", description: "Caller depth 1-3 (default 1)" },
+                    depth: {
+                        type: "integer",
+                        description: "Caller depth 1-3 (default 1)",
+                    },
                 },
                 required: ["symbol"],
             },
@@ -109,7 +127,10 @@ exports.TOOLS = [
                 type: "object",
                 properties: {
                     target: { type: "string", description: "Symbol name or file path" },
-                    depth: { type: "integer", description: "Traversal depth 1-3 (default 1)" },
+                    depth: {
+                        type: "integer",
+                        description: "Traversal depth 1-3 (default 1)",
+                    },
                 },
                 required: ["target"],
             },
@@ -123,7 +144,10 @@ exports.TOOLS = [
             parameters: {
                 type: "object",
                 properties: {
-                    file: { type: "string", description: "File path relative to project root" },
+                    file: {
+                        type: "string",
+                        description: "File path relative to project root",
+                    },
                 },
                 required: ["file"],
             },
@@ -161,9 +185,13 @@ function executeSearch(args, ctx) {
             const rp = rel(absPath, ctx.projectRoot);
             const defs = (0, arrow_1.toArr)((_d = r.definedSymbols) !== null && _d !== void 0 ? _d : r.defined_symbols);
             const sym = defs[0] || "(anonymous)";
-            const role = String((_e = r.role) !== null && _e !== void 0 ? _e : "IMPL").slice(0, 4).toUpperCase();
+            const role = String((_e = r.role) !== null && _e !== void 0 ? _e : "IMPL")
+                .slice(0, 4)
+                .toUpperCase();
             const startLine = (_j = (_h = (_f = r.startLine) !== null && _f !== void 0 ? _f : (_g = r.generated_metadata) === null || _g === void 0 ? void 0 : _g.start_line) !== null && _h !== void 0 ? _h : r.start_line) !== null && _j !== void 0 ? _j : 0;
-            const hint = String((_l = (_k = r.text) !== null && _k !== void 0 ? _k : r.content) !== null && _l !== void 0 ? _l : "").split("\n")[0].slice(0, 100);
+            const hint = String((_l = (_k = r.text) !== null && _k !== void 0 ? _k : r.content) !== null && _l !== void 0 ? _l : "")
+                .split("\n")[0]
+                .slice(0, 100);
             return `${rp}:${startLine} ${sym} [${role}] — ${hint}`;
         });
         return lines.join("\n");
@@ -220,8 +248,12 @@ function executePeek(args, ctx) {
             .limit(1)
             .toArray();
         const exported = metaRows.length > 0 && Boolean(metaRows[0].is_exported);
-        const startLine = metaRows.length > 0 ? Number(metaRows[0].start_line || 0) : center.line;
-        const endLine = metaRows.length > 0 ? Number(metaRows[0].end_line || 0) : center.line;
+        const startLine = metaRows.length > 0
+            ? Number(metaRows[0].start_line || 0)
+            : center.line;
+        const endLine = metaRows.length > 0
+            ? Number(metaRows[0].end_line || 0)
+            : center.line;
         // Extract signature
         let sig = "(source not available)";
         try {
@@ -294,7 +326,11 @@ function executeRelated(args, ctx) {
         // Get file's symbols
         const fileChunks = yield table
             .query()
-            .select(["defined_symbols", "referenced_symbols"])
+            .select([
+            "defined_symbols",
+            "referenced_symbols",
+            "type_referenced_symbols",
+        ])
             .where(`path = '${(0, filter_builder_1.escapeSqlString)(absPath)}'`)
             .toArray();
         if (fileChunks.length === 0)
@@ -306,6 +342,8 @@ function executeRelated(args, ctx) {
                 definedHere.add(s);
             for (const s of (0, arrow_1.toArr)(chunk.referenced_symbols))
                 referencedHere.add(s);
+            for (const s of (0, arrow_1.toArr)(chunk.type_referenced_symbols))
+                referencedHere.add(s);
         }
         // Dependencies: files that DEFINE symbols this file REFERENCES
         const depCounts = new Map();
@@ -331,7 +369,7 @@ function executeRelated(args, ctx) {
             const rows = yield table
                 .query()
                 .select(["path"])
-                .where(`array_contains(referenced_symbols, '${(0, filter_builder_1.escapeSqlString)(sym)}')`)
+                .where(`(array_contains(referenced_symbols, '${(0, filter_builder_1.escapeSqlString)(sym)}') OR array_contains(type_referenced_symbols, '${(0, filter_builder_1.escapeSqlString)(sym)}'))`)
                 .limit(20)
                 .toArray();
             for (const row of rows) {
@@ -341,8 +379,12 @@ function executeRelated(args, ctx) {
                 revCounts.set(p, (revCounts.get(p) || 0) + 1);
             }
         }
-        const topDeps = [...depCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10);
-        const topRevs = [...revCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10);
+        const topDeps = [...depCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10);
+        const topRevs = [...revCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10);
         if (topDeps.length === 0 && topRevs.length === 0)
             return "(none)";
         const lines = [];

package/dist/lib/store/vector-db.js

@@ -48,9 +48,9 @@ const fs = __importStar(require("node:fs"));
 const lancedb = __importStar(require("@lancedb/lancedb"));
 const apache_arrow_1 = require("apache-arrow");
 const config_1 = require("../../config");
+const cleanup_1 = require("../utils/cleanup");
 const filter_builder_1 = require("../utils/filter-builder");
 const logger_1 = require("../utils/logger");
-const cleanup_1 = require("../utils/cleanup");
 class DiskPressureError extends Error {
     constructor(message = "Disk critically low — writes suspended") {
         super(message);
@@ -266,6 +266,7 @@ class VectorDB {
             doc_token_ids: [],
             defined_symbols: [],
             referenced_symbols: [],
+            type_referenced_symbols: [],
             imports: [],
             exports: [],
             role: "",
@@ -308,6 +309,7 @@ class VectorDB {
             new apache_arrow_1.Field("doc_token_ids", new apache_arrow_1.List(new apache_arrow_1.Field("item", new apache_arrow_1.Int32(), true)), true),
             new apache_arrow_1.Field("defined_symbols", new apache_arrow_1.List(new apache_arrow_1.Field("item", new apache_arrow_1.Utf8(), true)), true),
             new apache_arrow_1.Field("referenced_symbols", new apache_arrow_1.List(new apache_arrow_1.Field("item", new apache_arrow_1.Utf8(), true)), true),
+            new apache_arrow_1.Field("type_referenced_symbols", new apache_arrow_1.List(new apache_arrow_1.Field("item", new apache_arrow_1.Utf8(), true)), true),
             new apache_arrow_1.Field("imports", new apache_arrow_1.List(new apache_arrow_1.Field("item", new apache_arrow_1.Utf8(), true)), true),
             new apache_arrow_1.Field("exports", new apache_arrow_1.List(new apache_arrow_1.Field("item", new apache_arrow_1.Utf8(), true)), true),
             new apache_arrow_1.Field("role", new apache_arrow_1.Utf8(), true),
@@ -316,12 +318,38 @@ class VectorDB {
             new apache_arrow_1.Field("summary", new apache_arrow_1.Utf8(), true),
         ]);
     }
+    /**
+     * In-place, non-breaking schema evolution for additive list columns. Older
+     * tables predate `type_referenced_symbols`; adding it via `addColumns` (rather
+     * than forcing `gmax index --reset`) keeps a live daemon's incremental writes
+     * working — existing rows read back as empty until their file is reindexed,
+     * which is when the new edges would populate anyway. Idempotent: re-adding an
+     * existing column throws, which we swallow.
+     */
+    evolveSchema(table) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const schema = yield table.schema();
+            const fields = new Set(schema.fields.map((f) => f.name));
+            if (fields.has("type_referenced_symbols"))
+                return;
+            try {
+                yield table.addColumns(new apache_arrow_1.Field("type_referenced_symbols", new apache_arrow_1.List(new apache_arrow_1.Field("item", new apache_arrow_1.Utf8(), true)), true));
+                (0, logger_1.log)("db", "Added type_referenced_symbols column to existing table");
+            }
+            catch (err) {
+                // Lost a race with another writer that already added it, or a transient
+                // commit conflict — the next ensureTable() re-checks and no-ops.
+                (0, logger_1.debug)("vectordb", `evolveSchema skipped: ${err.message}`);
+            }
+        });
+    }
     ensureTable() {
         return __awaiter(this, void 0, void 0, function* () {
             const db = yield this.getDb();
             try {
                 const table = yield db.openTable(TABLE_NAME);
                 yield this.validateSchema(table);
+                yield this.evolveSchema(table);
                 return table;
             }
             catch (_err) {
@@ -337,7 +365,7 @@ class VectorDB {
     }
     insertBatch(records) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
             if (!records.length)
                 return;
             this.ensureDiskOk();
@@ -410,12 +438,13 @@ class VectorDB {
                     : null;
                 rec.defined_symbols = (_g = rec.defined_symbols) !== null && _g !== void 0 ? _g : [];
                 rec.referenced_symbols = (_h = rec.referenced_symbols) !== null && _h !== void 0 ? _h : [];
-                rec.imports = (_j = rec.imports) !== null && _j !== void 0 ? _j : [];
-                rec.exports = (_k = rec.exports) !== null && _k !== void 0 ? _k : [];
-                rec.role = (_l = rec.role) !== null && _l !== void 0 ? _l : "";
-                rec.parent_symbol = (_m = rec.parent_symbol) !== null && _m !== void 0 ? _m : "";
-                rec.file_skeleton = (_o = rec.file_skeleton) !== null && _o !== void 0 ? _o : "";
-                rec.summary = (_p = rec.summary) !== null && _p !== void 0 ? _p : null;
+                rec.type_referenced_symbols = (_j = rec.type_referenced_symbols) !== null && _j !== void 0 ? _j : [];
+                rec.imports = (_k = rec.imports) !== null && _k !== void 0 ? _k : [];
+                rec.exports = (_l = rec.exports) !== null && _l !== void 0 ? _l : [];
+                rec.role = (_m = rec.role) !== null && _m !== void 0 ? _m : "";
+                rec.parent_symbol = (_o = rec.parent_symbol) !== null && _o !== void 0 ? _o : "";
+                rec.file_skeleton = (_p = rec.file_skeleton) !== null && _p !== void 0 ? _p : "";
+                rec.summary = (_q = rec.summary) !== null && _q !== void 0 ? _q : null;
             }
             try {
                 yield this.withWriteGate(() => table.add(records));
@@ -488,7 +517,9 @@ class VectorDB {
             const table = yield this.ensureTable();
             const cutoff = new Date(Date.now() - retentionMs);
             let resolveCompacting;
-            this.compactingPromise = new Promise((r) => { resolveCompacting = r; });
+            this.compactingPromise = new Promise((r) => {
+                resolveCompacting = r;
+            });
             try {
                 for (let attempt = 1; attempt <= retries; attempt++) {
                     yield this.drainWrites();
@@ -519,7 +550,8 @@ class VectorDB {
                             return;
                         }
                         // ENOSPC: return immediately — retrying will only make things worse
-                        if (msg.includes("No space left on device") || msg.includes("os error 28")) {
+                        if (msg.includes("No space left on device") ||
+                            msg.includes("os error 28")) {
                             (0, logger_1.log)("vectordb", `Optimize failed (ENOSPC): disk full — skipping retries`);
                             return;
                         }
@@ -753,9 +785,7 @@ class VectorDB {
             yield this.withWriteGate(() => __awaiter(this, void 0, void 0, function* () {
                 for (let i = 0; i < unique.length; i += batchSize) {
                     const slice = unique.slice(i, i + batchSize);
-                    const values = slice
-                        .map((p) => `'${(0, filter_builder_1.escapeSqlString)(p)}'`)
-                        .join(",");
+                    const values = slice.map((p) => `'${(0, filter_builder_1.escapeSqlString)(p)}'`).join(",");
                     const where = `path IN (${values})${idExclusion}`;
                     const existing = yield table
                         .query()

package/dist/lib/utils/stale-hint.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetStaleHintForTests = _resetStaleHintForTests;
+exports.maybeWarnStaleChunker = maybeWarnStaleChunker;
+exports.maybeWarnStaleEmbedding = maybeWarnStaleEmbedding;
+exports.maybeWarnCrossProjectDim = maybeWarnCrossProjectDim;
+/**
+ * Query-time staleness nudges.
+ *
+ * When a graph/search command resolves a project whose index is out of date —
+ * built by an older chunker, or with a different embedding model/dim than the
+ * current config — emit a single concise line to STDERR. Writing to stderr
+ * (never stdout) keeps `--json` / `--agent` machine output byte-identical —
+ * agents parse stdout, so the hint never pollutes it. In `--agent` mode the line
+ * is rendered as a structured TSV record instead of prose so a tool that *does*
+ * capture stderr can parse it.
+ *
+ * Each concern fires at most once per process (independent latches, so a stale
+ * chunker does not mask a stale embedding). Suppress all with GMAX_NO_STALE_HINT=1.
+ */
+const config_1 = require("../../config");
+const index_config_1 = require("../index/index-config");
+const project_registry_1 = require("./project-registry");
+let chunkerEmitted = false;
+let embeddingEmitted = false;
+let crossDimEmitted = false;
+/** Reset the once-per-process latches. Test-only. */
+function _resetStaleHintForTests() {
+    chunkerEmitted = false;
+    embeddingEmitted = false;
+    crossDimEmitted = false;
+}
+function maybeWarnStaleChunker(projectRoot, opts) {
+    if (chunkerEmitted)
+        return;
+    if (!projectRoot)
+        return;
+    if (process.env.GMAX_NO_STALE_HINT === "1")
+        return;
+    const project = (0, project_registry_1.getProject)(projectRoot);
+    // Only nudge for an index that is supposed to be complete. A "pending"
+    // project is mid-index (will land current); "error" is ignored by the
+    // daemon; an unregistered root would already have errored upstream.
+    if (!project)
+        return;
+    if (project.status && project.status !== "indexed")
+        return;
+    const gap = (0, config_1.describeChunkerGap)(project.chunkerVersion);
+    if (!gap)
+        return;
+    // Latch only once we have something to say, so a suppressed-by-status call
+    // does not silence a later command in the same process (CLI is one command
+    // per process, but search resolves the root in two places).
+    chunkerEmitted = true;
+    const name = project.name || projectRoot;
+    if (opts === null || opts === void 0 ? void 0 : opts.agent) {
+        const fields = [
+            "stale_chunker",
+            `project=${name}`,
+            `indexed_v=${gap.fromVersion}`,
+            `current_v=${gap.toVersion}`,
+            `severity=${gap.severity}`,
+            `note=${gap.notes.join("; ")}`,
+            "fix=gmax index --reset",
+        ].join("\t");
+        process.stderr.write(`${fields}\n`);
+        return;
+    }
+    const label = gap.severity === "breaking" ? "WARN" : "hint";
+    process.stderr.write(`${label}  gmax: '${name}' indexed by chunker v${gap.fromVersion} (now v${gap.toVersion}) — ${gap.notes.join(" ")} Run 'gmax index --reset' to refresh. (silence: GMAX_NO_STALE_HINT=1)\n`);
+}
+/**
+ * Nudge when a project's stored embedding model/dim differs from the current
+ * global config. A dim change is `breaking` (search scores are invalid until a
+ * re-embed); a same-dim model swap is `additive` (results just mix models).
+ * Mirrors maybeWarnStaleChunker's discipline: stderr-only, once-per-process,
+ * `--agent` TSV, GMAX_NO_STALE_HINT-suppressible.
+ */
+function maybeWarnStaleEmbedding(projectRoot, opts) {
+    if (embeddingEmitted)
+        return;
+    if (!projectRoot)
+        return;
+    if (process.env.GMAX_NO_STALE_HINT === "1")
+        return;
+    const project = (0, project_registry_1.getProject)(projectRoot);
+    if (!project)
+        return;
+    if (project.status && project.status !== "indexed")
+        return;
+    const current = (0, index_config_1.readGlobalConfig)();
+    const gap = (0, config_1.describeEmbeddingGap)({ modelTier: project.modelTier, vectorDim: project.vectorDim }, { modelTier: current.modelTier, vectorDim: current.vectorDim });
+    if (!gap)
+        return;
+    embeddingEmitted = true;
+    const name = project.name || projectRoot;
+    if (opts === null || opts === void 0 ? void 0 : opts.agent) {
+        const fields = [
+            "stale_embedding",
+            `project=${name}`,
+            `indexed_model=${gap.fromModel}`,
+            `current_model=${gap.toModel}`,
+            `indexed_dim=${gap.fromDim}`,
+            `current_dim=${gap.toDim}`,
+            `dim_changed=${gap.dimChanged}`,
+            `severity=${gap.severity}`,
+            "fix=gmax index --reset",
+        ].join("\t");
+        process.stderr.write(`${fields}\n`);
+        return;
+    }
+    const label = gap.severity === "breaking" ? "WARN" : "hint";
+    const detail = gap.dimChanged
+        ? `vector dim ${gap.fromDim}→${gap.toDim} (incompatible — scores invalid until re-embed)`
+        : `model '${gap.fromModel}'→'${gap.toModel}' (same dim; results mix models until re-embed)`;
+    process.stderr.write(`${label}  gmax: '${name}' indexed with embedding ${detail}. Run 'gmax index --reset'. (silence: GMAX_NO_STALE_HINT=1)\n`);
+}
+/**
+ * Cross-project guard: when a `--all-projects` / `--projects` search spans
+ * projects whose stored vector widths disagree (with each other or with the
+ * current query width), the shared fixed-dim table cannot answer all of them
+ * correctly — mismatched vectors were padded/truncated at insert and score as
+ * noise. Warn (stderr) so the caller can re-embed or exclude them, rather than
+ * silently returning invalid cross-project rankings.
+ */
+function maybeWarnCrossProjectDim(roots, opts) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    if (crossDimEmitted)
+        return;
+    if (process.env.GMAX_NO_STALE_HINT === "1")
+        return;
+    if (!roots || roots.length === 0)
+        return;
+    const current = (0, index_config_1.readGlobalConfig)();
+    const currentDim = (_d = (_a = current.vectorDim) !== null && _a !== void 0 ? _a : (_c = config_1.MODEL_TIERS[(_b = current.modelTier) !== null && _b !== void 0 ? _b : config_1.DEFAULT_MODEL_TIER]) === null || _c === void 0 ? void 0 : _c.vectorDim) !== null && _d !== void 0 ? _d : config_1.CONFIG.VECTOR_DIM;
+    const byRoot = new Map((0, project_registry_1.listProjects)().map((p) => [p.root, p]));
+    const dims = new Set([currentDim]);
+    const mismatched = [];
+    for (const r of roots) {
+        const p = byRoot.get(r.root);
+        if (!p)
+            continue;
+        const dim = (_g = (_e = p.vectorDim) !== null && _e !== void 0 ? _e : (_f = config_1.MODEL_TIERS[p.modelTier]) === null || _f === void 0 ? void 0 : _f.vectorDim) !== null && _g !== void 0 ? _g : currentDim;
+        dims.add(dim);
+        if (dim !== currentDim)
+            mismatched.push({ name: p.name || r.name, dim });
+    }
+    // All in-scope projects share the query width → nothing to warn about.
+    if (dims.size <= 1)
+        return;
+    crossDimEmitted = true;
+    if (opts === null || opts === void 0 ? void 0 : opts.agent) {
+        const fields = [
+            "stale_embedding_crossdim",
+            `query_dim=${currentDim}`,
+            `mismatched=${mismatched.map((m) => `${m.name}:${m.dim}`).join(",")}`,
+            "fix=re-embed or --exclude-projects",
+        ].join("\t");
+        process.stderr.write(`${fields}\n`);
+        return;
+    }
+    const list = mismatched.map((m) => `${m.name} (${m.dim}d)`).join(", ");
+    process.stderr.write(`WARN  gmax: cross-project search mixes embedding dims (query ${currentDim}d) — ${list} return invalid scores. Re-embed them or drop with --exclude-projects. (silence: GMAX_NO_STALE_HINT=1)\n`);
+}