@monoes/monograph 2.24.0 → 2.25.0

package/dist/src/pipeline/phases/summaries.js

@@ -0,0 +1,176 @@
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { CODE_SCOPE_LABELS } from '../../search/hybrid-query.js';
+import { definitionText } from './agent-registry.js';
+const MAX_COMMENT_CHARS = 300;
+const HEADER_SCAN_LINES = 40;
+/** "pickAgents" / "pick_agents" / "pick-agents.ts" → "pick Agents" words. */
+export function splitWords(identifier) {
+    return identifier
+        .replace(/\.[A-Za-z0-9]+$/, '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/[_\-./\\]+/g, ' ')
+        .trim();
+}
+function cleanCommentLine(line) {
+    return line
+        .trim()
+        .replace(/^\/\*\*?|\*\/$/g, '')
+        .replace(/^\/\/\/?!?|^#+|^\*+/g, '')
+        .replace(/@\w+\s*(\{[^}]*\})?/g, ' ')
+        .trim();
+}
+const isCommentLine = (l) => /^(\/\/|\/\*|\*|#(?!\[)|--|""")/.test(l.trim());
+/**
+ * The comment block directly above a 1-based `startLine` (JSDoc, `//`, `///`,
+ * `#`), skipping decorator/attribute lines; for a Python-style `def ...:` with
+ * no comment above, the docstring that follows it.
+ */
+export function extractLeadingComment(lines, startLine) {
+    let i = startLine - 2;
+    while (i >= 0 && /^\s*(@|#\[)/.test(lines[i]))
+        i--;
+    const block = [];
+    while (i >= 0 && lines[i].trim() !== '' && isCommentLine(lines[i])) {
+        block.unshift(lines[i]);
+        i--;
+    }
+    let text = block.map(cleanCommentLine).filter(Boolean).join(' ');
+    if (!text) {
+        const def = lines[startLine - 1] ?? '';
+        const next = (lines[startLine] ?? '').trim();
+        const m = def.trimEnd().endsWith(':') && /^[rRuU]?("""|''')/.exec(next);
+        if (m) {
+            const quote = m[1];
+            const parts = [];
+            for (let j = startLine; j < Math.min(lines.length, startLine + 8); j++) {
+                const part = lines[j].trim().replace(/^[rRuU]?("""|''')/, '');
+                const end = part.indexOf(quote);
+                parts.push(end === -1 ? part : part.slice(0, end));
+                if (end !== -1)
+                    break;
+            }
+            text = parts.join(' ');
+        }
+    }
+    return text.replace(/\s+/g, ' ').trim().slice(0, MAX_COMMENT_CHARS);
+}
+/** The first comment block near the top of a file (its stated purpose). */
+export function extractFileHeader(lines) {
+    const head = lines.slice(0, HEADER_SCAN_LINES);
+    let i = 0;
+    while (i < head.length && (head[i].trim() === '' || head[i].startsWith('#!')))
+        i++;
+    const block = [];
+    while (i < head.length && isCommentLine(head[i]))
+        block.push(head[i++]);
+    return block
+        .map(cleanCommentLine)
+        .filter(Boolean)
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, MAX_COMMENT_CHARS);
+}
+const stripMarkdown = (s) => s
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/[`*_>#|]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+/** A markdown document's title and opening paragraph — what it says it is about. */
+export function extractMarkdownLead(lines) {
+    let i = 0;
+    if (lines[0]?.trim() === '---') {
+        i = lines.findIndex((l, n) => n > 0 && l.trim() === '---') + 1 || 0;
+    }
+    let title = '';
+    while (i < lines.length && !title) {
+        const m = /^#{1,3}\s+(.+)/.exec(lines[i]);
+        if (m)
+            title = m[1];
+        i++;
+    }
+    const para = [];
+    for (; i < lines.length && para.length < 6; i++) {
+        const l = lines[i].trim();
+        if (/^#{1,6}\s/.test(l) || l.startsWith('```') || l.startsWith('|')) {
+            if (para.length)
+                break;
+            continue;
+        }
+        if (l)
+            para.push(l);
+        else if (para.length)
+            break;
+    }
+    return stripMarkdown(`${title}. ${para.join(' ')}`).slice(0, MAX_COMMENT_CHARS);
+}
+/** Words a person would use to describe a symbol: its name, location and comment. */
+export function buildSummaryText(name, filePath, comment) {
+    const where = filePath
+        ? `${splitWords(basename(filePath))} ${splitWords(basename(dirname(filePath)))}`
+        : '';
+    return `${splitWords(name)} ${comment} ${where}`.replace(/\s+/g, ' ').trim();
+}
+/** Rebuilds `node_summaries_fts` for every code symbol and file in the graph. */
+export const summariesPhase = {
+    name: 'summaries',
+    deps: ['stale-sweep', 'agent-registry'],
+    async execute(ctx) {
+        const db = ctx.db;
+        const labels = [...CODE_SCOPE_LABELS, 'Document'];
+        const placeholders = labels.map(() => '?').join(',');
+        const rows = db
+            .prepare(`SELECT id, label, name, file_path, start_line FROM nodes
+         WHERE label IN (${placeholders}) AND file_path IS NOT NULL ORDER BY file_path`)
+            .all(...labels);
+        db.exec('DELETE FROM node_summaries_fts');
+        const insert = db.prepare('INSERT INTO node_summaries_fts (node_id, text) VALUES (?, ?)');
+        let summarized = 0;
+        // Agent and skill definitions describe themselves in frontmatter.
+        const defs = db
+            .prepare("SELECT id, name, properties FROM nodes WHERE label IN ('Agent', 'Skill')")
+            .all();
+        for (const d of defs) {
+            let props = {};
+            try {
+                props = d.properties ? JSON.parse(d.properties) : {};
+            }
+            catch {
+                /* malformed properties: index the name alone */
+            }
+            insert.run(d.id, definitionText(props, splitWords(d.name)));
+            summarized++;
+        }
+        let currentFile = '';
+        let lines = [];
+        for (const r of rows) {
+            if (r.file_path !== currentFile) {
+                currentFile = r.file_path;
+                try {
+                    lines = readFileSync(join(ctx.repoPath, r.file_path), 'utf8').split('\n');
+                }
+                catch {
+                    lines = [];
+                }
+            }
+            const isDoc = r.label === 'Document' || /\.(md|mdx)$/i.test(r.file_path);
+            const comment = isDoc
+                ? extractMarkdownLead(lines)
+                : r.label === 'File'
+                    ? extractFileHeader(lines)
+                    : r.start_line
+                        ? extractLeadingComment(lines, r.start_line)
+                        : '';
+            const text = buildSummaryText(r.label === 'File' || r.label === 'Document' ? basename(r.file_path) : r.name, r.file_path, comment);
+            if (text) {
+                insert.run(r.id, text);
+                summarized++;
+            }
+        }
+        return { summarized };
+    },
+};
+//# sourceMappingURL=summaries.js.map

package/dist/src/pipeline/phases/summaries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summaries.js","sourceRoot":"","sources":["../../../../src/pipeline/phases/summaries.ts"],"names":[],"mappings":"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"}

package/dist/src/pipeline/phases/tests-edges.d.ts

@@ -0,0 +1,16 @@
+import type { PipelinePhase } from '../types.js';
+/** SQL predicate: `col` is the path of a test file. */
+export declare function testPathSql(col: string): string;
+/**
+ * Derives `TESTS` edges — test File → the source it exercises — so an agent can
+ * ask "what covers this?" and "what should I run after changing it?":
+ *  - a test file that IMPORTS a non-test file tests that file (INFERRED: an
+ *    import shows the test touches the file, not that it asserts anything);
+ *  - a test-file function that CALLS a non-test symbol tests that symbol.
+ * Always rebuilt from scratch from the committed IMPORTS/CALLS edges, so it can
+ * never drift from them.
+ */
+export declare const testsEdgesPhase: PipelinePhase<{
+    edges: number;
+}>;
+//# sourceMappingURL=tests-edges.d.ts.map

package/dist/src/pipeline/phases/tests-edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tests-edges.d.ts","sourceRoot":"","sources":["../../../../src/pipeline/phases/tests-edges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAkC5D,CAAC"}

package/dist/src/pipeline/phases/tests-edges.js

@@ -0,0 +1,44 @@
+/** SQL predicate: `col` is the path of a test file. */
+export function testPathSql(col) {
+    return `(${col} LIKE '%.test.%' OR ${col} LIKE '%.spec.%' OR ${col} LIKE '%/__tests__/%' OR ${col} LIKE '%/tests/%' OR ${col} LIKE '%/test/%' OR ${col} LIKE '%\\_test.%' ESCAPE '\\' OR ${col} LIKE 'test\\_%' ESCAPE '\\')`;
+}
+/**
+ * Derives `TESTS` edges — test File → the source it exercises — so an agent can
+ * ask "what covers this?" and "what should I run after changing it?":
+ *  - a test file that IMPORTS a non-test file tests that file (INFERRED: an
+ *    import shows the test touches the file, not that it asserts anything);
+ *  - a test-file function that CALLS a non-test symbol tests that symbol.
+ * Always rebuilt from scratch from the committed IMPORTS/CALLS edges, so it can
+ * never drift from them.
+ */
+export const testsEdgesPhase = {
+    name: 'tests-edges',
+    deps: ['stale-sweep'],
+    async execute(ctx) {
+        const db = ctx.db;
+        db.exec("DELETE FROM edges WHERE relation = 'TESTS'");
+        db.exec(`
+      INSERT OR IGNORE INTO edges (id, source_id, target_id, relation, confidence, confidence_score, reason)
+      SELECT 'tests:' || s.id || '>' || t.id, s.id, t.id, 'TESTS', 'INFERRED', 0.7,
+             'test file imports this file'
+      FROM edges e
+      JOIN nodes s ON s.id = e.source_id AND s.label = 'File'
+      JOIN nodes t ON t.id = e.target_id AND t.label = 'File'
+      WHERE e.relation = 'IMPORTS'
+        AND ${testPathSql('s.file_path')} AND NOT ${testPathSql('t.file_path')}`);
+        // Resolves the calling function to its test File node by path.
+        db.exec(`
+      INSERT OR IGNORE INTO edges (id, source_id, target_id, relation, confidence, confidence_score, reason)
+      SELECT 'tests:' || f.id || '>' || t.id, f.id, t.id, 'TESTS', 'INFERRED', 0.9,
+             'test code calls this symbol'
+      FROM edges e
+      JOIN nodes s ON s.id = e.source_id
+      JOIN nodes f ON f.label = 'File' AND f.file_path = s.file_path
+      JOIN nodes t ON t.id = e.target_id
+      WHERE e.relation = 'CALLS' AND t.label != 'File'
+        AND ${testPathSql('s.file_path')} AND NOT ${testPathSql('t.file_path')}`);
+        const { n } = db.prepare("SELECT COUNT(*) AS n FROM edges WHERE relation = 'TESTS'").get();
+        return { edges: n };
+    },
+};
+//# sourceMappingURL=tests-edges.js.map

package/dist/src/pipeline/phases/tests-edges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tests-edges.js","sourceRoot":"","sources":["../../../../src/pipeline/phases/tests-edges.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,IAAI,GAAG,uBAAuB,GAAG,uBAAuB,GAAG,4BAA4B,GAAG,wBAAwB,GAAG,uBAAuB,GAAG,qCAAqC,GAAG,+BAA+B,CAAC;AAChO,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqC;IAC/D,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,CAAC,aAAa,CAAC;IACrB,KAAK,CAAC,OAAO,CAAC,GAAG;QACf,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC;QAClB,EAAE,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;QAEtD,EAAE,CAAC,IAAI,CAAC;;;;;;;;cAQE,WAAW,CAAC,aAAa,CAAC,YAAY,WAAW,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;QAE9E,+DAA+D;QAC/D,EAAE,CAAC,IAAI,CAAC;;;;;;;;;cASE,WAAW,CAAC,aAAa,CAAC,YAAY,WAAW,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;QAE9E,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,0DAA0D,CAAC,CAAC,GAAG,EAEvF,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACtB,CAAC;CACF,CAAC"}

package/dist/src/pipeline/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/pipeline/runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjE,qBAAa,cAAc;IACzB,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,iCAAiC;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAE/D,YAAY,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,EAG3C;IAEK,GAAG,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAoC7D;CACF"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/pipeline/runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjE,qBAAa,cAAc;IACzB,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,iCAAiC;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAE/D,YAAY,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,EAG3C;IAEK,GAAG,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAyC7D;CACF"}

package/dist/src/pipeline/runner.js

@@ -20,9 +20,14 @@ export class PipelineRunner {
                 // Wait for all dep phases to finish
                 await Promise.all(phase.deps.map((dep) => getOrCreatePromise(dep)));
                 ctx.onProgress?.({ phase: phase.name });
+                const startedAt = Date.now();
                 try {
                     const output = await phase.execute(ctx, outputs);
                     outputs.set(phase.name, output);
+                    ctx.onProgress?.({
+                        phase: phase.name,
+                        message: `done in ${((Date.now() - startedAt) / 1000).toFixed(1)}s`,
+                    });
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);

package/dist/src/pipeline/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../src/pipeline/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../src/pipeline/runner.ts"],"names":[],"mappings":"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"}

package/dist/src/search/eval.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Retrieval evaluation: run gold queries through {@link searchGraph} and report
+ * how often, and how high, the expected node shows up.
+ *
+ * A case passes at rank r when any hit's name or file path contains one of its
+ * `expect` strings (case-insensitive). Substring matching keeps gold files
+ * stable across line-number and id-scheme changes.
+ */
+import type Database from 'better-sqlite3';
+import type { Embedder } from '../embeddings/store.js';
+import type { GraphSearchOptions } from './hybrid-query.js';
+export interface EvalCase {
+    query: string;
+    /** Any hit whose name or filePath contains one of these counts as found. */
+    expect: string[];
+    /** Free-form bucket for the report: exact, ambiguous, natural, doc, dependency. */
+    kind?: string;
+    scope?: GraphSearchOptions['scope'];
+}
+export interface EvalCaseResult {
+    query: string;
+    kind: string;
+    /** 1-based rank of the first expected hit, or null when absent from the top k. */
+    rank: number | null;
+}
+export interface EvalReport {
+    k: number;
+    cases: number;
+    recallAtK: number;
+    /** Mean reciprocal rank: 1/rank per case, 0 when absent. */
+    mrr: number;
+    byKind: Record<string, {
+        cases: number;
+        recallAtK: number;
+        mrr: number;
+    }>;
+    results: EvalCaseResult[];
+}
+export declare function evaluateRetrieval(db: Database.Database, cases: EvalCase[], options?: {
+    k?: number;
+    search?: Partial<GraphSearchOptions>;
+    embedder?: Embedder | null;
+}): Promise<EvalReport>;
+//# sourceMappingURL=eval.d.ts.map

package/dist/src/search/eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../../src/search/eval.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1E,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,GAAE;IAAE,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAO,GAC7F,OAAO,CAAC,UAAU,CAAC,CA6BrB"}

package/dist/src/search/eval.js

@@ -0,0 +1,35 @@
+/**
+ * Retrieval evaluation: run gold queries through {@link searchGraph} and report
+ * how often, and how high, the expected node shows up.
+ *
+ * A case passes at rank r when any hit's name or file path contains one of its
+ * `expect` strings (case-insensitive). Substring matching keeps gold files
+ * stable across line-number and id-scheme changes.
+ */
+import { searchGraphFused } from './fused-search.js';
+export async function evaluateRetrieval(db, cases, options = {}) {
+    const k = options.k ?? 10;
+    const results = [];
+    for (const c of cases) {
+        const hits = await searchGraphFused(db, c.query, {
+            ...options.search,
+            scope: c.scope ?? options.search?.scope,
+            limit: k,
+            embedder: options.embedder,
+        });
+        const wanted = c.expect.map((e) => e.toLowerCase());
+        const idx = hits.findIndex((h) => wanted.some((w) => h.name.toLowerCase().includes(w) || (h.filePath ?? '').toLowerCase().includes(w)));
+        results.push({ query: c.query, kind: c.kind ?? 'general', rank: idx === -1 ? null : idx + 1 });
+    }
+    const summarize = (rs) => ({
+        cases: rs.length,
+        recallAtK: rs.length ? rs.filter((r) => r.rank !== null).length / rs.length : 0,
+        mrr: rs.length ? rs.reduce((sum, r) => sum + (r.rank ? 1 / r.rank : 0), 0) / rs.length : 0,
+    });
+    const byKind = {};
+    for (const kind of new Set(results.map((r) => r.kind))) {
+        byKind[kind] = summarize(results.filter((r) => r.kind === kind));
+    }
+    return { k, ...summarize(results), byKind, results };
+}
+//# sourceMappingURL=eval.js.map

package/dist/src/search/eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sourceRoot":"","sources":["../../../src/search/eval.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AA6BrD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAqB,EACrB,KAAiB,EACjB,OAAO,GAAqF,EAAE;IAE9F,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1B,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE;YAC/C,GAAG,OAAO,CAAC,MAAM;YACjB,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,KAAK;YACvC,KAAK,EAAE,CAAC;YACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAC/B,MAAM,CAAC,IAAI,CACT,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CACxF,CACF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,SAAS,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC;IACjG,CAAC;IAED,MAAM,SAAS,GAAG,CAAC,EAAoB,EAAE,EAAE,CAAC,CAAC;QAC3C,KAAK,EAAE,EAAE,CAAC,MAAM;QAChB,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/E,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;KAC3F,CAAC,CAAC;IACH,MAAM,MAAM,GAAyB,EAAE,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACvD,CAAC"}

package/dist/src/search/fused-search.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Lexical + semantic retrieval, fused.
+ *
+ * Lexical search (names, stemmed summaries) is exact and fast but only finds
+ * what shares words with the query. Embeddings find "which agent should handle
+ * a task" -> `pickAgents` but blur exact identifiers. Reciprocal-rank fusion
+ * keeps the strengths of both; the weights follow the query's style, and an
+ * exact name match is always pinned first.
+ *
+ * Degrades to plain lexical search when no embedder is supplied, nothing has
+ * been embedded yet, or the query only concerns documentation.
+ */
+import type Database from 'better-sqlite3';
+import { type Embedder } from '../embeddings/store.js';
+import { type GraphSearchOptions, type GraphSearchResult } from './hybrid-query.js';
+export interface FusedSearchOptions extends GraphSearchOptions {
+    embedder?: Embedder | null;
+}
+/** A single token (`UserService`, `agent-pick`, `fts-store.ts`) is a name, not a question. */
+export declare function isIdentifierQuery(query: string): boolean;
+export declare function searchGraphFused(db: Database.Database, query: string, options?: FusedSearchOptions): Promise<GraphSearchResult[]>;
+//# sourceMappingURL=fused-search.d.ts.map

package/dist/src/search/fused-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fused-search.d.ts","sourceRoot":"","sources":["../../../src/search/fused-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,KAAK,QAAQ,EAAoC,MAAM,wBAAwB,CAAC;AACzF,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EAKvB,MAAM,mBAAmB,CAAC;AAS3B,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AAUD,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA0E9B"}

package/dist/src/search/fused-search.js

@@ -0,0 +1,103 @@
+/**
+ * Lexical + semantic retrieval, fused.
+ *
+ * Lexical search (names, stemmed summaries) is exact and fast but only finds
+ * what shares words with the query. Embeddings find "which agent should handle
+ * a task" -> `pickAgents` but blur exact identifiers. Reciprocal-rank fusion
+ * keeps the strengths of both; the weights follow the query's style, and an
+ * exact name match is always pinned first.
+ *
+ * Degrades to plain lexical search when no embedder is supplied, nothing has
+ * been embedded yet, or the query only concerns documentation.
+ */
+import { semanticSearch } from '../embeddings/store.js';
+import { AGENT_SCOPE_LABELS, CODE_SCOPE_LABELS, searchGraph, TEST_FACTOR, TEST_INTENT, TEST_PATH, } from './hybrid-query.js';
+const RRF_K = 60;
+/** How many of keyword search's top hits are never dropped by fusion. */
+const PROTECTED_LEXICAL = 2;
+/** [lexical, semantic] weights. */
+const WEIGHTS_IDENTIFIER = [2, 1];
+const WEIGHTS_NATURAL = [1, 2];
+/** A single token (`UserService`, `agent-pick`, `fts-store.ts`) is a name, not a question. */
+export function isIdentifierQuery(query) {
+    return !/\s/.test(query.trim());
+}
+function semanticLabels(options) {
+    if (options.label)
+        return options.label;
+    if (options.scope === 'code')
+        return CODE_SCOPE_LABELS;
+    if (options.scope === 'agents')
+        return AGENT_SCOPE_LABELS;
+    if (options.scope === 'docs')
+        return ['Document'];
+    return undefined;
+}
+export async function searchGraphFused(db, query, options = {}) {
+    const { embedder, ...base } = options;
+    const limit = base.limit ?? 20;
+    const q = (query ?? '').trim();
+    if (limit <= 0 || !q)
+        return [];
+    const pool = Math.max(limit * 5, 50);
+    const lexical = searchGraph(db, q, { ...base, limit: pool });
+    if (!embedder)
+        return lexical.slice(0, limit);
+    let sem = [];
+    try {
+        sem = semanticSearch(db, await embedder.embedQuery(q), pool, semanticLabels(base));
+    }
+    catch {
+        return lexical.slice(0, limit);
+    }
+    if (sem.length === 0)
+        return lexical.slice(0, limit);
+    const [wl, ws] = isIdentifierQuery(q) ? WEIGHTS_IDENTIFIER : WEIGHTS_NATURAL;
+    const wantsTests = TEST_INTENT.test(q);
+    const fused = new Map();
+    const add = (hit, rank, weight) => {
+        const penalty = !wantsTests && hit.filePath && TEST_PATH.test(hit.filePath) ? TEST_FACTOR : 1;
+        const entry = fused.get(hit.id) ?? { hit, score: 0 };
+        entry.score += (weight * penalty) / (RRF_K + rank + 1);
+        fused.set(hit.id, entry);
+    };
+    lexical.forEach((hit, i) => add(hit, i, wl));
+    sem.forEach((s, i) => add({
+        id: s.id,
+        name: s.name,
+        normLabel: s.normLabel,
+        filePath: s.filePath,
+        label: s.label,
+        relevance: 0,
+        startLine: s.startLine,
+        endLine: s.endLine,
+        matchStrategy: 'semantic',
+    }, i, ws));
+    const ceiling = (wl + ws) / (RRF_K + 1);
+    const ranked = [...fused.values()]
+        .sort((a, b) => b.score - a.score)
+        .map(({ hit, score }) => ({ ...hit, relevance: score / ceiling }));
+    // An exact name match is what the caller typed; nothing the fusion adds outranks it.
+    const lower = q.toLowerCase();
+    const exact = ranked.filter((r) => r.name.toLowerCase() === lower);
+    const rest = ranked.filter((r) => r.name.toLowerCase() !== lower);
+    const final = [...exact, ...rest].slice(0, limit);
+    // Keyword search's two best hits stay in the results even when the semantic lane crowds
+    // them out (a sentence that contains a real name — "share a meeting" -> shareRoutes —
+    // is exactly where a keyword hit is right and the embedding is only roughly so).
+    const present = new Set(final.map((r) => r.id));
+    const protectedHits = lexical.slice(0, PROTECTED_LEXICAL).filter((h) => !present.has(h.id));
+    for (const hit of protectedHits) {
+        if (final.length >= limit) {
+            if (final.length <= exact.length)
+                break; // never evict an exact name match
+            final.pop();
+        }
+        final.push({
+            ...(ranked.find((r) => r.id === hit.id) ?? hit),
+            relevance: final.at(-1)?.relevance ?? 0,
+        });
+    }
+    return final;
+}
+//# sourceMappingURL=fused-search.js.map

package/dist/src/search/fused-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fused-search.js","sourceRoot":"","sources":["../../../src/search/fused-search.ts"],"names":[],"mappings":"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"}

package/dist/src/search/hybrid-query.d.ts

@@ -30,9 +30,32 @@ import type { RankedResult } from './rrf.js';
  *   wants pure lexical ranking with no heuristic bonuses.
  */
 export type RetrievalMode = 'bm25' | 'hybrid';
+/**
+ * Which part of the graph a search covers.
+ *
+ * - `code` — symbols, files, routes and tools.
+ * - `docs` — markdown sections, documents and concepts.
+ * - `agents` — agent and skill definitions.
+ * - `all` — everything, ranked purely by relevance.
+ * - `auto` (default) — code first, with documentation filling any slots the
+ *   code left empty; a query that is plainly about documentation flips that
+ *   order. Doc sections outnumber code symbols roughly 1:2 in this repo, so
+ *   without this an abstract task query is answered entirely by headings.
+ */
+export type SearchScope = 'code' | 'docs' | 'agents' | 'all' | 'auto';
+export declare const CODE_SCOPE_LABELS: readonly string[];
+export declare const DOC_SCOPE_LABELS: readonly string[];
+export declare const AGENT_SCOPE_LABELS: readonly string[];
+/** True when the query is asking which agent or skill to use. */
+export declare function hasAgentIntent(query: string): boolean;
+/** True when the query is plainly asking about documentation rather than code. */
+export declare function hasDocIntent(query: string): boolean;
 export interface GraphSearchOptions {
     limit?: number;
-    label?: string;
+    /** Exact node label (or labels). Overrides `scope`. */
+    label?: string | readonly string[];
+    /** Part of the graph to search (default: `auto`). */
+    scope?: SearchScope;
     /** Retrieval strategy (default: `hybrid`). */
     mode?: RetrievalMode;
 }
@@ -49,7 +72,7 @@ export interface GraphSearchResult {
     /** Last line of the symbol in its source file (1-based, null if unknown). */
     endLine: number | null;
     /** Which retrieval strategy surfaced this row. */
-    matchStrategy: 'fts' | 'like' | 'fuzzy';
+    matchStrategy: 'fts' | 'like' | 'fuzzy' | 'semantic';
 }
 /**
  * Run a lexical search over the graph and return results under the
@@ -68,6 +91,10 @@ export interface GraphSearchResult {
  * would break the LIKE fallback against a capitalized name.
  */
 export declare function searchGraph(db: Database.Database, query: string, options?: GraphSearchOptions): GraphSearchResult[];
+/** Tests restate the code they exercise; they rank below it unless asked for. */
+export declare const TEST_PATH: RegExp;
+export declare const TEST_INTENT: RegExp;
+export declare const TEST_FACTOR = 0.6;
 export interface BM25QueryOptions {
     limit?: number;
     label?: string;

package/dist/src/search/hybrid-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-query.d.ts","sourceRoot":"","sources":["../../../src/search/hybrid-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kDAAkD;IAClD,aAAa,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;CACzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,EAAE,CAqCrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uIAAuI;IACvI,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,yGAAyG;AACzG,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAElD,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wGAAwG;AACxG,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,UAAU,EAAE,CAAC,CAYvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,kBAAY,CAAC"}
+{"version":3,"file":"hybrid-query.d.ts","sourceRoot":"","sources":["../../../src/search/hybrid-query.ts"],"names":[],"mappings":"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"}