grepmax 0.17.2 → 0.17.4

package/dist/eval-graph-totals.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Diagnostic counterpart to eval-graph-sanity.ts.
+ *
+ * Phase 0 found that 0/200 fusion-pool chunks reference any of the 4
+ * hard-miss targets via `referenced_symbols`. That can mean either:
+ *   (a) chunker isn't extracting these refs (upstream miss), OR
+ *   (b) refs exist but live outside the fusion top-200.
+ *
+ * This script measures the *total* `array_contains(referenced_symbols, X)`
+ * count across the whole platform index for each target. If those counts
+ * are also ~0, the graph is empty at the data-extraction layer, not the
+ * retrieval layer.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a, _b;
+var _c;
+Object.defineProperty(exports, "__esModule", { value: true });
+(_a = (_c = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_c.GMAX_WORKER_COUNT = "1");
+const path = __importStar(require("node:path"));
+const config_1 = require("./config");
+const vector_db_1 = require("./lib/store/vector-db");
+const exit_1 = require("./lib/utils/exit");
+const filter_builder_1 = require("./lib/utils/filter-builder");
+const PLATFORM_ROOT = path.join((_b = process.env.HOME) !== null && _b !== void 0 ? _b : "", "Development/beyond/platform");
+const TARGETS = ["BeyondError", "ErrorCodes", "resolveActor", "errorHandler"];
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const db = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir);
+        const table = yield db.ensureTable();
+        const pathPrefix = PLATFORM_ROOT.endsWith("/") ? PLATFORM_ROOT : `${PLATFORM_ROOT}/`;
+        const scope = `path LIKE '${(0, filter_builder_1.escapeSqlString)(pathPrefix)}%'`;
+        console.log(`Platform graph density check — pathPrefix=${PLATFORM_ROOT}\n`);
+        for (const sym of TARGETS) {
+            const esc = (0, filter_builder_1.escapeSqlString)(sym);
+            const refRows = yield table
+                .query()
+                .select(["path"])
+                .where(`${scope} AND array_contains(referenced_symbols, '${esc}')`)
+                .limit(2000)
+                .toArray();
+            const defRows = yield table
+                .query()
+                .select(["path"])
+                .where(`${scope} AND array_contains(defined_symbols, '${esc}')`)
+                .limit(2000)
+                .toArray();
+            console.log(`${sym.padEnd(16)}  def-chunks=${String(defRows.length).padStart(3)}  ref-chunks=${String(refRows.length).padStart(4)}`);
+        }
+        // Also count chunks with non-empty referenced_symbols overall to baseline
+        // graph density.
+        const allRows = yield table
+            .query()
+            .select(["referenced_symbols"])
+            .where(scope)
+            .limit(20000)
+            .toArray();
+        let nonEmpty = 0;
+        let totalRefs = 0;
+        for (const row of allRows) {
+            const raw = row.referenced_symbols;
+            let arr = [];
+            if (Array.isArray(raw))
+                arr = raw.filter((v) => typeof v === "string");
+            else if (raw && typeof raw.toArray === "function") {
+                try {
+                    const a = raw.toArray();
+                    if (Array.isArray(a))
+                        arr = a.filter((v) => typeof v === "string");
+                }
+                catch (_a) { }
+            }
+            if (arr.length > 0) {
+                nonEmpty++;
+                totalRefs += arr.length;
+            }
+        }
+        console.log(`\nPlatform corpus: ${allRows.length} chunks sampled (cap 20k), ` +
+            `${nonEmpty} with non-empty referenced_symbols (${((nonEmpty / allRows.length) * 100).toFixed(1)}%), ` +
+            `avg refs/chunk = ${(totalRefs / Math.max(1, nonEmpty)).toFixed(1)}`);
+        yield db.close();
+        yield (0, exit_1.gracefulExit)(0);
+    });
+}
+if (require.main === module) {
+    main().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/eval-oss.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * OSS-fixture evaluation harness — runs the search pipeline against
+ * sverklo-bench P1 (definition lookup) fixtures ported from
+ * github.com/sverklo/sverklo-bench (tasks/express.gen.ts,
+ * tasks/lodash.gen.ts). Used to answer "does ColBERT rerank help on a
+ * third-party fixture set, or are our 97 internal cases biased?"
+ *
+ * Usage:
+ *   pnpm tsx src/eval-oss.ts express                  # rerank off (default)
+ *   GMAX_EVAL_RERANK=1 pnpm tsx src/eval-oss.ts express
+ *   pnpm tsx src/eval-oss.ts lodash --json
+ *   pnpm tsx src/eval-oss.ts all                      # all datasets
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a, _b, _c, _d;
+var _e;
+Object.defineProperty(exports, "__esModule", { value: true });
+// Same precaution as src/eval.ts — pin worker pool to 1 to avoid ONNX
+// concurrency issues during the back-to-back search runs.
+(_a = (_e = process.env).GMAX_WORKER_COUNT) !== null && _a !== void 0 ? _a : (_e.GMAX_WORKER_COUNT = "1");
+const path = __importStar(require("node:path"));
+const searcher_1 = require("./lib/search/searcher");
+const vector_db_1 = require("./lib/store/vector-db");
+const exit_1 = require("./lib/utils/exit");
+const config_1 = require("./config");
+// ─── express 4.21.1 P1 — sverklo-bench/tasks/express.gen.ts resolved against
+//     a fresh checkout. `merge` dropped: it's the utils-merge package, not
+//     an in-tree definition, so the sverklo resolver returns no location.
+const EXPRESS_CASES = [
+    { id: "ex-p1-01", query: "createApplication", expectedFile: "lib/express.js", expectedLine: 37 },
+    { id: "ex-p1-02", query: "Route", expectedFile: "lib/router/route.js", expectedLine: 43 },
+    { id: "ex-p1-03", query: "Layer", expectedFile: "lib/router/layer.js", expectedLine: 33 },
+    { id: "ex-p1-04", query: "View", expectedFile: "lib/view.js", expectedLine: 52 },
+    { id: "ex-p1-05", query: "query", expectedFile: "lib/express.js", expectedLine: 79, note: "re-export site — middleware/query.js doesn't match the function-decl patterns" },
+    { id: "ex-p1-06", query: "init", expectedFile: "lib/middleware/init.js", expectedLine: 28 },
+    { id: "ex-p1-07", query: "acceptParams", expectedFile: "lib/utils.js", expectedLine: 126 },
+    { id: "ex-p1-08", query: "stringify", expectedFile: "lib/response.js", expectedLine: 1155 },
+    { id: "ex-p1-09", query: "compileETag", expectedFile: "lib/utils.js", expectedLine: 150 },
+];
+// ─── lodash 4.17.21 P1 — hand-verified line numbers in lodash.js, copied
+//     verbatim from sverklo-bench/tasks/lodash.gen.ts. All 10 live in the
+//     same 17K-line UMD file, so line-window matching (NOT path-only match)
+//     is what makes this fixture set discriminating.
+const LODASH_CASES = [
+    { id: "ld-p1-01", query: "map", expectedFile: "lodash.js", expectedLine: 9620 },
+    { id: "ld-p1-02", query: "filter", expectedFile: "lodash.js", expectedLine: 9239 },
+    { id: "ld-p1-03", query: "reduce", expectedFile: "lodash.js", expectedLine: 9745 },
+    { id: "ld-p1-04", query: "debounce", expectedFile: "lodash.js", expectedLine: 10372 },
+    { id: "ld-p1-05", query: "throttle", expectedFile: "lodash.js", expectedLine: 10965 },
+    { id: "ld-p1-06", query: "merge", expectedFile: "lodash.js", expectedLine: 13505, note: "var merge = createAssigner(...) binding site, not the re-export at 16689" },
+    { id: "ld-p1-07", query: "cloneDeep", expectedFile: "lodash.js", expectedLine: 11155 },
+    { id: "ld-p1-08", query: "get", expectedFile: "lodash.js", expectedLine: 13194 },
+    { id: "ld-p1-09", query: "set", expectedFile: "lodash.js", expectedLine: 13741 },
+    { id: "ld-p1-10", query: "chunk", expectedFile: "lodash.js", expectedLine: 6903 },
+];
+// ─── platform monorepo (private) — 15 hand-curated P1 cases across packages
+//     to test the "modular monorepo" shape that neither express nor lodash
+//     covers. Symbols resolved against the live checkout. Bare-symbol
+//     queries match sverklo's P1 methodology so results are comparable.
+const PLATFORM_CASES = [
+    { id: "pf-p1-01", query: "formatCents", expectedFile: "packages/shared/src/format.ts", expectedLine: 8 },
+    { id: "pf-p1-02", query: "formatTimeAgo", expectedFile: "packages/shared/src/format.ts", expectedLine: 44 },
+    { id: "pf-p1-03", query: "BeyondError", expectedFile: "packages/shared/src/errors.ts", expectedLine: 37 },
+    { id: "pf-p1-04", query: "ErrorCodes", expectedFile: "packages/shared/src/errors.ts", expectedLine: 5 },
+    { id: "pf-p1-05", query: "createDb", expectedFile: "packages/db/src/index.ts", expectedLine: 42 },
+    { id: "pf-p1-06", query: "createDbAsync", expectedFile: "packages/db/src/index.ts", expectedLine: 50 },
+    { id: "pf-p1-07", query: "authMiddleware", expectedFile: "packages/api/src/middleware/auth.ts", expectedLine: 39 },
+    { id: "pf-p1-08", query: "requireAuth", expectedFile: "packages/api/src/middleware/auth.ts", expectedLine: 45 },
+    { id: "pf-p1-09", query: "resolveActor", expectedFile: "packages/api/src/middleware/auth.ts", expectedLine: 71 },
+    { id: "pf-p1-10", query: "getActor", expectedFile: "packages/api/src/middleware/auth.ts", expectedLine: 1136 },
+    { id: "pf-p1-11", query: "rateLimit", expectedFile: "packages/api/src/middleware/rate-limit.ts", expectedLine: 94 },
+    { id: "pf-p1-12", query: "checkRateLimitKey", expectedFile: "packages/api/src/middleware/rate-limit.ts", expectedLine: 158 },
+    { id: "pf-p1-13", query: "errorHandler", expectedFile: "packages/api/src/middleware/error.ts", expectedLine: 128 },
+    { id: "pf-p1-14", query: "activityTracker", expectedFile: "packages/api/src/middleware/activity-tracker.ts", expectedLine: 17 },
+    { id: "pf-p1-15", query: "initializeApp", expectedFile: "packages/api/src/app.ts", expectedLine: 68 },
+];
+const DATASETS = {
+    express: {
+        name: "express",
+        projectRoot: path.join((_b = process.env.HOME) !== null && _b !== void 0 ? _b : "", "Development/sandbox/bench-fixtures/express"),
+        cases: EXPRESS_CASES,
+    },
+    lodash: {
+        name: "lodash",
+        projectRoot: path.join((_c = process.env.HOME) !== null && _c !== void 0 ? _c : "", "Development/sandbox/bench-fixtures/lodash"),
+        cases: LODASH_CASES,
+    },
+    platform: {
+        name: "platform",
+        projectRoot: path.join((_d = process.env.HOME) !== null && _d !== void 0 ? _d : "", "Development/beyond/platform"),
+        cases: PLATFORM_CASES,
+    },
+};
+// A chunk matches when its file path ends with the expected file AND the
+// expected line falls within [start_line, end_line]. end_line falls back
+// to start_line + 200 when missing (lodash's mega-IIFE chunks are
+// typically much smaller than this, but the guard avoids false negatives
+// from short tail chunks).
+function chunkMatches(chunk, expectedFile, expectedLine) {
+    var _a, _b, _c, _d, _e, _f;
+    const path = String(((_a = chunk.metadata) === null || _a === void 0 ? void 0 : _a.path) || "").toLowerCase();
+    if (!path.endsWith(`/${expectedFile.toLowerCase()}`) && !path.endsWith(expectedFile.toLowerCase())) {
+        return false;
+    }
+    const start = Number((_d = (_c = (_b = chunk.generated_metadata) === null || _b === void 0 ? void 0 : _b.start_line) !== null && _c !== void 0 ? _c : chunk.start_line) !== null && _d !== void 0 ? _d : 0);
+    const numLines = Number((_f = (_e = chunk.generated_metadata) === null || _e === void 0 ? void 0 : _e.num_lines) !== null && _f !== void 0 ? _f : 0);
+    const end = numLines > 0 ? start + numLines : start + 200;
+    // chunks are 0-indexed start_line; expected line is 1-indexed
+    return expectedLine - 1 >= start && expectedLine - 1 <= end;
+}
+function evaluateOss(response, c, timeMs) {
+    const idx = response.data.findIndex((chunk) => chunkMatches(chunk, c.expectedFile, c.expectedLine));
+    const rank = idx + 1; // 0 = miss
+    const rr = rank > 0 ? 1 / rank : 0;
+    const recall10 = rank > 0 && rank <= 10 ? 1 : 0;
+    return {
+        id: c.id,
+        query: c.query,
+        expectedFile: c.expectedFile,
+        expectedLine: c.expectedLine,
+        rank,
+        rr,
+        recall10,
+        timeMs,
+        note: c.note,
+    };
+}
+function runDataset(ds, rerank, topK) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const vectorDb = new vector_db_1.VectorDB(config_1.PATHS.lancedbDir);
+        const searcher = new searcher_1.Searcher(vectorDb);
+        const pathPrefix = ds.projectRoot.endsWith("/") ? ds.projectRoot : `${ds.projectRoot}/`;
+        const results = [];
+        for (const c of ds.cases) {
+            const t0 = performance.now();
+            const res = yield searcher.search(c.query, topK, { rerank }, undefined, pathPrefix);
+            const timeMs = performance.now() - t0;
+            results.push(evaluateOss(res, c, timeMs));
+        }
+        yield vectorDb.close();
+        const hits = results.filter((r) => r.rank > 0).length;
+        const hitsAt1 = results.filter((r) => r.rank === 1).length;
+        const mrr = results.reduce((s, r) => s + r.rr, 0) / results.length;
+        const recall10 = results.reduce((s, r) => s + r.recall10, 0) / results.length;
+        const avgTime = results.reduce((s, r) => s + r.timeMs, 0) / results.length;
+        return {
+            summary: {
+                dataset: ds.name,
+                rerank,
+                cases: results.length,
+                hits,
+                hitsAt1,
+                mrrAt10: Number(mrr.toFixed(4)),
+                recallAt10: Number(recall10.toFixed(4)),
+                avgTimeMs: Math.round(avgTime),
+            },
+            results,
+        };
+    });
+}
+function run() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const args = process.argv.slice(2);
+        const datasetArg = (_a = args.find((a) => !a.startsWith("--"))) !== null && _a !== void 0 ? _a : "all";
+        const jsonMode = args.includes("--json") || process.env.GMAX_EVAL_JSON === "1";
+        const rerank = process.env.GMAX_EVAL_RERANK === "1";
+        const topK = 20;
+        const wanted = datasetArg === "all" ? Object.keys(DATASETS) : [datasetArg];
+        const out = [];
+        const log = jsonMode ? console.error : console.log;
+        log(`OSS eval (rerank=${rerank ? "on" : "off"})`);
+        for (const name of wanted) {
+            const ds = DATASETS[name];
+            if (!ds) {
+                console.error(`Unknown dataset: ${name}. Known: ${Object.keys(DATASETS).join(", ")}`);
+                process.exit(1);
+            }
+            log(`\n── ${ds.name} (${ds.cases.length} cases, ${ds.projectRoot})`);
+            const r = yield runDataset(ds, rerank, topK);
+            out.push(r);
+            if (!jsonMode) {
+                for (const res of r.results) {
+                    const status = res.rank > 0 ? `rank ${res.rank}` : "miss";
+                    console.log(`  ${res.id}  ${res.query.padEnd(20)} → ${status.padEnd(8)} ${res.expectedFile}:${res.expectedLine} [${res.timeMs.toFixed(0)}ms]`);
+                }
+                const s = r.summary;
+                console.log(`  → MRR@10=${s.mrrAt10}  Recall@10=${s.recallAt10}  hits@1=${s.hitsAt1}/${s.cases}  avg=${s.avgTimeMs}ms`);
+            }
+        }
+        if (jsonMode) {
+            process.stdout.write(`${JSON.stringify({ rerank, datasets: out }, null, 2)}\n`);
+        }
+        yield (0, exit_1.gracefulExit)(0);
+    });
+}
+if (require.main === module && process.env.GMAX_EVAL_AUTORUN !== "0") {
+    run().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/eval.js

@@ -582,9 +582,14 @@ function run() {
         // changes show up clearly. Set GMAX_EVAL_RERANK=1 to measure the full
         // production pipeline (slower, but more representative).
         const rerank = process.env.GMAX_EVAL_RERANK === "1";
+        // Optional pathPrefix scoping — needed by PageRank tiebreaker (which is
+        // per-project) and to isolate this bench from cross-project chunks indexed
+        // by the same daemon. Defaults to unscoped so historical numbers stay
+        // comparable.
+        const evalPathPrefix = process.env.GMAX_EVAL_PATH_PREFIX || undefined;
         for (const c of exports.cases) {
             const queryStart = performance.now();
-            const res = yield searcher.search(c.query, topK, { rerank });
+            const res = yield searcher.search(c.query, topK, { rerank }, undefined, evalPathPrefix);
             const queryEnd = performance.now();
             const timeMs = queryEnd - queryStart;
             results.push(evaluateCase(res, c, timeMs));

package/dist/lib/output/agent-search-formatter.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAgentSearchResults = formatAgentSearchResults;
+const path = __importStar(require("node:path"));
+function chunkPath(chunk) {
+    const metadata = chunk.metadata;
+    return String(chunk.path || (metadata === null || metadata === void 0 ? void 0 : metadata.path) || "");
+}
+function chunkStartLine(chunk) {
+    var _a, _b, _c, _d;
+    return Math.max(1, Number((_d = (_b = (_a = chunk.startLine) !== null && _a !== void 0 ? _a : chunk.start_line) !== null && _b !== void 0 ? _b : (_c = chunk.generated_metadata) === null || _c === void 0 ? void 0 : _c.start_line) !== null && _d !== void 0 ? _d : 0) + 1);
+}
+function definedSymbols(chunk) {
+    var _a;
+    const raw = (_a = chunk.defined_symbols) !== null && _a !== void 0 ? _a : chunk.definedSymbols;
+    if (Array.isArray(raw))
+        return raw.filter((v) => typeof v === "string");
+    if (raw && typeof raw.toArray === "function") {
+        try {
+            const arr = raw.toArray();
+            if (Array.isArray(arr)) {
+                return arr.filter((v) => typeof v === "string");
+            }
+        }
+        catch (_b) { }
+    }
+    return [];
+}
+function relativePath(projectRoot, absPath) {
+    if (!absPath)
+        return "";
+    return path.isAbsolute(absPath)
+        ? path.relative(projectRoot, absPath)
+        : absPath;
+}
+function firstSignatureLine(chunk) {
+    var _a, _b;
+    const raw = (_b = (_a = chunk.content) !== null && _a !== void 0 ? _a : chunk.text) !== null && _b !== void 0 ? _b : "";
+    const lines = String(raw).split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.length < 5)
+            continue;
+        if (trimmed.startsWith("//") ||
+            trimmed.startsWith("/*") ||
+            trimmed.startsWith("*")) {
+            continue;
+        }
+        if (trimmed.startsWith("import ") ||
+            trimmed.startsWith("#") ||
+            trimmed.startsWith("File:")) {
+            continue;
+        }
+        if (trimmed === "{" || trimmed === "}")
+            continue;
+        if (/^[.),;:}\]|&(+`'"!~]/.test(trimmed))
+            continue;
+        if (trimmed.startsWith("} ") ||
+            trimmed.startsWith("- ") ||
+            trimmed.startsWith("...")) {
+            continue;
+        }
+        if (/^[a-z]/.test(trimmed) &&
+            !/^(export|function|class|interface|type|const|let|var|async|return|if|for|while|switch|enum|struct|pub |fn |def |impl |mod |use )/.test(trimmed)) {
+            continue;
+        }
+        return trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed;
+    }
+    return "";
+}
+function hintFor(chunk) {
+    if (typeof chunk.summary === "string" && chunk.summary) {
+        return chunk.summary;
+    }
+    return firstSignatureLine(chunk);
+}
+function explainSuffix(chunk, enabled) {
+    if (!enabled || !chunk.scoreBreakdown)
+        return "";
+    const b = chunk.scoreBreakdown;
+    return `\texplain:rerank=${b.rerank.toFixed(3)},fused=${b.fused.toFixed(3)},boost=${b.boost.toFixed(2)}x,score=${b.normalized.toFixed(3)}`;
+}
+function formatAgentSearchResults(results, projectRoot, options = {}) {
+    var _a, _b;
+    if (!results.length)
+        return "(none)";
+    const groups = new Map();
+    for (const result of results) {
+        const absPath = chunkPath(result);
+        const group = groups.get(absPath);
+        if (group)
+            group.push(result);
+        else
+            groups.set(absPath, [result]);
+    }
+    const lines = [];
+    const seenImportFiles = new Set();
+    for (const [absPath, members] of groups) {
+        const rel = relativePath(projectRoot, absPath);
+        if (options.includeImports &&
+            absPath &&
+            options.getImportsForFile &&
+            !seenImportFiles.has(absPath)) {
+            seenImportFiles.add(absPath);
+            const imports = options.getImportsForFile(absPath);
+            if (imports) {
+                lines.push(`[imports ${rel}] ${imports.split("\n").join(" | ")}`);
+            }
+        }
+        const grouped = members.length > 1;
+        if (grouped) {
+            lines.push(`${rel} (${members.length} hits):`);
+        }
+        for (const result of members) {
+            const symbol = (_a = definedSymbols(result)[0]) !== null && _a !== void 0 ? _a : "";
+            const role = String((_b = result.role) !== null && _b !== void 0 ? _b : "")
+                .slice(0, 4)
+                .toUpperCase();
+            const score = typeof result.score === "number"
+                ? `\ts=${result.score.toFixed(3)}`
+                : "";
+            const hint = hintFor(result);
+            const locator = grouped
+                ? `  :${chunkStartLine(result)}`
+                : `${rel}:${chunkStartLine(result)}`;
+            lines.push(`${locator}${score}${symbol ? ` ${symbol}` : ""}${role ? ` [${role}]` : ""}${hint ? ` — ${hint}` : ""}${explainSuffix(result, options.explain)}`);
+        }
+    }
+    return lines.join("\n");
+}