codesearch-mcp 0.2.3-alpha → 0.3.0-alpha

package/dist/src/eval-results.js

@@ -33,20 +33,109 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.degradedNotices = degradedNotices;
+exports.renderSummary = renderSummary;
+exports.renderComparison = renderComparison;
+exports.renderProgress = renderProgress;
 exports.timestampSlug = timestampSlug;
 exports.writeResultFiles = writeResultFiles;
+exports.normaliseResultFile = normaliseResultFile;
 exports.readResultFile = readResultFile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const CATEGORIES = ['identifier', 'behaviour', 'concept'];
+const STAGE_LABEL = {
+    vector: 'vector (reranker input order, not a rerank-off search)',
+    reranked: 'reranked',
+};
 function pct(n) {
     return `${(n * 100).toFixed(1)}%`;
 }
+function signed(n, digits = 4) {
+    return (n >= 0 ? '+' : '') + n.toFixed(digits);
+}
+function oneCase(count) {
+    return count > 0 ? pct(1 / count) : '—';
+}
 function metricsRow(label, m) {
-    return `| ${label} | ${m.count} | ${pct(m.hit1)} | ${pct(m.hit5)} | ${m.mrr10.toFixed(4)} |`;
+    return `| ${label} | ${m.count} | ${oneCase(m.count)} | ${pct(m.hit1)} | ${pct(m.hit5)} | ${m.mrr10.toFixed(4)} |`;
 }
 function deltaRow(label, d) {
-    const sign = (n) => (n >= 0 ? '+' : '') + n.toFixed(4);
-    return `| ${label} | ${d.count.current} | ${pct(d.hit1.current)} (${sign(d.hit1.delta)}) | ${pct(d.hit5.current)} (${sign(d.hit5.delta)}) | ${d.mrr10.current.toFixed(4)} (${sign(d.mrr10.delta)}) |`;
+    return `| ${label} | ${d.count.current} | ${pct(d.hit1.current)} (${signed(d.hit1.delta)}) | ${pct(d.hit5.current)} (${signed(d.hit5.delta)}) | ${d.mrr10.current.toFixed(4)} (${signed(d.mrr10.delta)}) |`;
+}
+function poolRow(label, p) {
+    return `| ${label} | ${p.count} | ${oneCase(p.count)} | ${pct(p.recall)} | ${p.short} |`;
+}
+function pairRow(label, p, count) {
+    return `| ${label} | ${p.improved} | ${p.worsened} | ${p.unchanged} | ${p.signTestP.toFixed(4)} | ${oneCase(count)} |`;
+}
+function poolValue(v, format, digits) {
+    if (v.baseline === null || v.delta === null)
+        return `no pool data → ${format(v.current)}`;
+    return `${format(v.baseline)} → ${format(v.current)} (${signed(v.delta, digits)})`;
+}
+function poolDeltaRow(label, d) {
+    return `| ${label} | ${poolValue(d.recall, pct, 4)} | ${poolValue(d.short, String, 0)} |`;
+}
+function degradedNotices(run) {
+    if (run.rerankFailures === 0 || !run.stages.includes('reranked'))
+        return [];
+    return [`reranked stage degraded: ${run.rerankFailures} rerank failure(s) scored on the vector-order fallback`];
+}
+function caseCount(change) {
+    const o = change.overall;
+    return o.improved + o.worsened + o.unchanged;
+}
+function categoryCount(change, category) {
+    const p = change.byCategory[category];
+    return p ? p.improved + p.worsened + p.unchanged : 0;
+}
+function pairTable(change) {
+    const lines = ['| Category | Improved | Worsened | Unchanged | Sign-test p | 1 case |', '|---|---|---|---|---|---|'];
+    lines.push(pairRow('Overall', change.overall, caseCount(change)));
+    for (const category of CATEGORIES) {
+        const p = change.byCategory[category];
+        if (p)
+            lines.push(pairRow(category, p, categoryCount(change, category)));
+    }
+    if (change.hit5Lost.length > 0)
+        lines.push('', `**Lost hit@5:** ${change.hit5Lost.join(', ')}`);
+    if (change.hit5Gained.length > 0)
+        lines.push('', `**Gained hit@5:** ${change.hit5Gained.join(', ')}`);
+    return lines;
+}
+function formatList(values) {
+    return values.map(v => (v === null ? 'not sent' : String(v))).join(', ') || '—';
+}
+function corpusLines(metadata) {
+    const lines = metadata.corpora.map(c => `${c.root} @ ${c.commit} — ${c.projects.length} project(s), ${c.chunks} chunks, fingerprint ${c.fingerprint}`);
+    if (metadata.liveCases > 0)
+        lines.push(`${metadata.liveCases} live-corpus case(s) — not comparable over time`);
+    return lines.length > 0 ? lines : ['none recorded'];
+}
+function groupLabel(key, group) {
+    return `${key === 'live' ? 'live cases' : key} (${group.cases} case(s))`;
+}
+function corpusTable(stages, group) {
+    const lines = ['| Stage | Category | Cases | 1 case | hit@5 | MRR@10 |', '|---|---|---|---|---|---|'];
+    for (const stage of stages) {
+        const m = group.metrics[stage];
+        if (!m)
+            continue;
+        const row = (label, x) => `| ${stage} | ${label} | ${x.count} | ${oneCase(x.count)} | ${pct(x.hit5)} | ${x.mrr10.toFixed(4)} |`;
+        lines.push(row('Overall', m.overall));
+        for (const category of CATEGORIES) {
+            const cm = m.byCategory[category];
+            if (cm)
+                lines.push(row(category, cm));
+        }
+    }
+    lines.push('', `Pool recall ${pct(group.pool.overall.recall)}, short pools ${group.pool.overall.short}.`);
+    for (const sc of group.stageChanges) {
+        const o = sc.change.overall;
+        lines.push('', `${sc.from} → ${sc.to}: improved ${o.improved}, worsened ${o.worsened}, unchanged ${o.unchanged}, p=${o.signTestP.toFixed(4)}.`);
+    }
+    return lines;
 }
 function renderMarkdown(result, comparison) {
     const { metadata, run } = result;
@@ -58,17 +147,50 @@ function renderMarkdown(result, comparison) {
     if (metadata.indexMeta) {
         lines.push(`**Index:** ${metadata.indexMeta.provider}/${metadata.indexMeta.model} (${metadata.indexMeta.dimensions} dims)`);
     }
-    lines.push('', '## Metrics', '', '| Category | Cases | hit@1 | hit@5 | MRR@10 |', '|---|---|---|---|---|');
-    lines.push(metricsRow('Overall', run.metrics.overall));
-    for (const category of ['identifier', 'behaviour', 'concept']) {
-        const m = run.metrics.byCategory[category];
-        if (m)
-            lines.push(metricsRow(category, m));
+    const corpora = corpusLines(metadata);
+    lines.push(corpora.length === 1 ? `**Corpus:** ${corpora[0]}` : `**Corpora:** ${corpora.join('; ')}`);
+    const c = metadata.conditions;
+    if (c) {
+        lines.push(`**Search conditions:** threshold ${c.similarityThreshold} | overfetch ${c.overfetch} | candidateFloor ${c.candidateFloor} | fetchLimit ${formatList(c.fetchLimit)} | ef_search ${formatList(c.efSearch)} | iterative scan ${formatList(c.iterativeScan)}`);
+    }
+    else {
+        lines.push('**Search conditions:** not recorded');
+    }
+    for (const stage of run.stages) {
+        const m = run.metrics[stage];
+        if (!m)
+            continue;
+        lines.push('', `## Metrics — ${STAGE_LABEL[stage]}`, '', '| Category | Cases | 1 case | hit@1 | hit@5 | MRR@10 |', '|---|---|---|---|---|---|');
+        lines.push(metricsRow('Overall', m.overall));
+        for (const category of CATEGORIES) {
+            const cm = m.byCategory[category];
+            if (cm)
+                lines.push(metricsRow(category, cm));
+        }
     }
+    lines.push('', '## Candidate pool', '', '| Category | Cases | 1 case | Pool recall | Short pools |', '|---|---|---|---|---|');
+    lines.push(poolRow('Overall', run.pool.overall));
+    for (const category of CATEGORIES) {
+        const p = run.pool.byCategory[category];
+        if (p)
+            lines.push(poolRow(category, p));
+    }
+    for (const sc of run.stageChanges) {
+        lines.push('', `## Stage change — ${sc.from} → ${sc.to}`, '', ...pairTable(sc.change));
+    }
+    const groups = Object.entries(run.byCorpus);
+    if (groups.length > 0) {
+        lines.push('', '## Per corpus');
+        for (const [key, group] of groups)
+            lines.push('', `### ${groupLabel(key, group)}`, '', ...corpusTable(run.stages, group));
+    }
+    const degraded = degradedNotices(run);
+    if (degraded.length > 0)
+        lines.push('', ...degraded.map(d => `> ⚠ ${d}`));
     if (run.invalid.length > 0) {
         lines.push('', '## Invalid cases', '', '| Case | Reason |', '|---|---|');
-        for (const c of run.invalid)
-            lines.push(`| ${c.id} | ${c.reason}: ${c.invalidExpects.map(e => e.file).join(', ')} |`);
+        for (const ic of run.invalid)
+            lines.push(`| ${ic.id} | ${ic.reason}: ${ic.invalidExpects.map(e => e.file).join(', ')} |`);
     }
     if (run.warnings.length > 0) {
         lines.push('', '## Warnings (partially invalid)', '', '| Case | Dropped |', '|---|---|');
@@ -76,39 +198,200 @@ function renderMarkdown(result, comparison) {
             lines.push(`| ${w.id} | ${w.droppedExpects.map(e => e.file).join(', ')} |`);
     }
     if (comparison) {
+        const cmp = comparison.result;
         lines.push('', `## Comparison against ${comparison.baselinePath}`, '');
-        if (comparison.result.conditionWarnings.length > 0) {
-            lines.push('> ⚠ ' + comparison.result.conditionWarnings.join('; '), '');
+        if (cmp.conditionWarnings.length > 0) {
+            lines.push('> ⚠ ' + cmp.conditionWarnings.join('; '), '');
+        }
+        for (const sc of cmp.stages) {
+            lines.push(`### ${sc.stage}`, '', '| Category | Cases | hit@1 (Δ) | hit@5 (Δ) | MRR@10 (Δ) |', '|---|---|---|---|---|');
+            lines.push(deltaRow('Overall', sc.overall));
+            for (const category of CATEGORIES) {
+                const d = sc.byCategory[category];
+                if (d)
+                    lines.push(deltaRow(category, d));
+            }
+            lines.push('', `Paired change, baseline → current (${sc.stage}):`, '', ...pairTable(sc.change), '');
+        }
+        for (const u of cmp.unmatchedStages) {
+            lines.push(`**Stage \`${u.stage}\`** is present only in the ${u.side === 'baseline' ? 'baseline' : 'current run'}; not compared.`, '');
         }
-        lines.push('| Category | Cases | hit@1 (Δ) | hit@5 (Δ) | MRR@10 (Δ) |', '|---|---|---|---|---|');
-        lines.push(deltaRow('Overall', comparison.result.overall));
-        for (const category of ['identifier', 'behaviour', 'concept']) {
-            const d = comparison.result.byCategory[category];
+        lines.push('### Candidate pool', '', '| Category | Pool recall | Short pools |', '|---|---|---|');
+        lines.push(poolDeltaRow('Overall', cmp.pool.overall));
+        for (const category of CATEGORIES) {
+            const d = cmp.pool.byCategory[category];
             if (d)
-                lines.push(deltaRow(category, d));
+                lines.push(poolDeltaRow(category, d));
         }
-        if (comparison.result.hit5Lost.length > 0)
-            lines.push('', `**Lost hit@5:** ${comparison.result.hit5Lost.join(', ')}`);
-        if (comparison.result.hit5Gained.length > 0)
-            lines.push('', `**Gained hit@5:** ${comparison.result.hit5Gained.join(', ')}`);
     }
     return lines.join('\n') + '\n';
 }
-/** `yyyy-mm-dd_hh-mm` in local time, matching the existing `benchmarks/results/` naming. */
+function consoleMetrics(label, m) {
+    return `  ${label.padEnd(10)} — hit@1: ${pct(m.hit1)}  hit@5: ${pct(m.hit5)}  MRR@10: ${m.mrr10.toFixed(4)}  (${m.count}, 1 case = ${oneCase(m.count)})`;
+}
+function consolePairs(label, p) {
+    return `  ${label.padEnd(10)} — improved ${p.improved}  worsened ${p.worsened}  unchanged ${p.unchanged}  p=${p.signTestP.toFixed(4)}`;
+}
+function renderSummary(result) {
+    const { run, metadata } = result;
+    const lines = [];
+    lines.push('', `Evaluated ${run.cases.length} case(s) (${run.invalid.length} invalid) against ${metadata.embeddingProvider}/${metadata.embeddingModel}`);
+    for (const line of corpusLines(metadata))
+        lines.push(`  corpus: ${line}`);
+    for (const stage of run.stages) {
+        const m = run.metrics[stage];
+        if (!m)
+            continue;
+        lines.push(`\n[${STAGE_LABEL[stage]}]`);
+        lines.push(consoleMetrics('Overall', m.overall));
+        for (const category of CATEGORIES) {
+            const cm = m.byCategory[category];
+            if (cm)
+                lines.push(consoleMetrics(category, cm));
+        }
+    }
+    lines.push('\n[candidate pool]');
+    const poolLine = (label, p) => `  ${label.padEnd(10)} — recall: ${pct(p.recall)}  short: ${p.short}  (${p.count})`;
+    lines.push(poolLine('Overall', run.pool.overall));
+    for (const category of CATEGORIES) {
+        const p = run.pool.byCategory[category];
+        if (p)
+            lines.push(poolLine(category, p));
+    }
+    for (const sc of run.stageChanges) {
+        lines.push(`\n[${sc.from} → ${sc.to}]`);
+        lines.push(consolePairs('Overall', sc.change.overall));
+        for (const category of CATEGORIES) {
+            const p = sc.change.byCategory[category];
+            if (p)
+                lines.push(consolePairs(category, p));
+        }
+        if (sc.change.hit5Lost.length > 0)
+            lines.push(`  Lost hit@5: ${sc.change.hit5Lost.join(', ')}`);
+        if (sc.change.hit5Gained.length > 0)
+            lines.push(`  Gained hit@5: ${sc.change.hit5Gained.join(', ')}`);
+    }
+    for (const [key, group] of Object.entries(run.byCorpus)) {
+        lines.push(`\n[${groupLabel(key, group)}]`);
+        for (const stage of run.stages) {
+            const m = group.metrics[stage];
+            if (!m)
+                continue;
+            const cats = CATEGORIES.filter(cat => m.byCategory[cat]).map(cat => `${cat} ${m.byCategory[cat].mrr10.toFixed(4)}`).join('  ');
+            lines.push(`  ${stage.padEnd(10)} — MRR@10: ${m.overall.mrr10.toFixed(4)}  hit@5: ${pct(m.overall.hit5)}  (${cats})`);
+        }
+        lines.push(`  ${'pool'.padEnd(10)} — recall: ${pct(group.pool.overall.recall)}  short: ${group.pool.overall.short}`);
+        for (const sc of group.stageChanges)
+            lines.push(consolePairs(`${sc.from}→${sc.to}`, sc.change.overall));
+    }
+    for (const d of degradedNotices(run))
+        lines.push(`\n⚠ ${d}`);
+    if (run.invalid.length > 0) {
+        lines.push('\nInvalid cases:');
+        for (const c of run.invalid)
+            lines.push(`  ${c.id}: ${c.reason} — ${c.invalidExpects.map(e => e.file).join(', ')}`);
+    }
+    if (run.warnings.length > 0) {
+        lines.push('\nWarnings (scored on remaining valid answers):');
+        for (const w of run.warnings)
+            lines.push(`  ${w.id}: dropped ${w.droppedExpects.map(e => e.file).join(', ')}`);
+    }
+    return lines;
+}
+function renderComparison(baselinePath, cmp) {
+    const lines = [`\nComparison against ${baselinePath}:`];
+    for (const w of cmp.conditionWarnings)
+        lines.push(`  ⚠ ${w}`);
+    for (const sc of cmp.stages) {
+        lines.push(`  [${sc.stage}]`);
+        lines.push(`    MRR@10: ${sc.overall.mrr10.baseline.toFixed(4)} → ${sc.overall.mrr10.current.toFixed(4)} (${signed(sc.overall.mrr10.delta)})`);
+        lines.push(`    hit@5:  ${pct(sc.overall.hit5.baseline)} → ${pct(sc.overall.hit5.current)}`);
+        const o = sc.change.overall;
+        lines.push(`    paired: improved ${o.improved}  worsened ${o.worsened}  unchanged ${o.unchanged}  p=${o.signTestP.toFixed(4)}`);
+        if (sc.change.hit5Lost.length > 0)
+            lines.push(`    Lost hit@5: ${sc.change.hit5Lost.join(', ')}`);
+        if (sc.change.hit5Gained.length > 0)
+            lines.push(`    Gained hit@5: ${sc.change.hit5Gained.join(', ')}`);
+    }
+    for (const u of cmp.unmatchedStages) {
+        lines.push(`  [${u.stage}] only in the ${u.side === 'baseline' ? 'baseline' : 'current run'} — not compared`);
+    }
+    const p = cmp.pool.overall;
+    lines.push(`  pool recall: ${poolValue(p.recall, pct, 4)}`);
+    lines.push(`  short pools: ${poolValue(p.short, String, 0)}`);
+    for (const category of CATEGORIES) {
+        const d = cmp.pool.byCategory[category];
+        if (d)
+            lines.push(`    ${category.padEnd(10)} — recall ${poolValue(d.recall, pct, 4)}  short ${poolValue(d.short, String, 0)}`);
+    }
+    return lines;
+}
+function renderProgress(p) {
+    const head = `[${String(p.index).padStart(String(p.total).length)}/${p.total}] ${p.id}`;
+    const secs = `(${(p.ms / 1000).toFixed(1)}s)`;
+    if (p.invalid)
+        return `${head} invalid — ${p.invalid.reason} ${secs}`;
+    const ranks = Object.keys(p.result.stages)
+        .map(stage => `${stage} ${p.result.stages[stage]?.rank ?? '—'}`)
+        .join(' → ');
+    return `${head} ${ranks}${p.result.rerankFailed ? ' (rerank failed)' : ''} ${secs}`;
+}
 function timestampSlug(date) {
     const pad = (n) => String(n).padStart(2, '0');
     return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}_${pad(date.getHours())}-${pad(date.getMinutes())}`;
 }
-/** Writes the JSON + Markdown result files for one eval run; returns their paths. */
 function writeResultFiles(resultsDir, suiteLabel, result, now, comparison) {
     fs.mkdirSync(resultsDir, { recursive: true });
-    const base = `eval_${suiteLabel}_${timestampSlug(now)}`;
+    const stem = `eval_${suiteLabel}_${timestampSlug(now)}`;
+    const taken = (base) => fs.existsSync(path.join(resultsDir, `${base}.json`)) || fs.existsSync(path.join(resultsDir, `${base}.md`));
+    let base = stem;
+    for (let n = 2; taken(base); n++)
+        base = `${stem}-${n}`;
     const jsonPath = path.join(resultsDir, `${base}.json`);
     const mdPath = path.join(resultsDir, `${base}.md`);
     fs.writeFileSync(jsonPath, JSON.stringify(result, null, 2) + '\n', 'utf-8');
     fs.writeFileSync(mdPath, renderMarkdown(result, comparison), 'utf-8');
     return { jsonPath, mdPath };
 }
+const EMPTY_POOL = { count: 0, recall: 0, short: 0 };
+function normaliseResultFile(raw) {
+    const run = raw?.run;
+    if (!run || run.stages !== undefined || run.metrics?.overall === undefined)
+        return withCorpusMetadata(raw);
+    const stage = raw.metadata?.rerankerModel != null ? 'reranked' : 'vector';
+    const cases = run.cases.map(c => ({
+        id: c.id, project: c.project, category: c.category, query: c.query,
+        stages: { [stage]: { rank: c.rank, matched: c.matched } },
+        poolRank: null,
+        poolSize: 0,
+        rerankFailed: false,
+        corpus: null,
+    }));
+    return {
+        metadata: { ...raw.metadata, conditions: null, corpora: [], liveCases: cases.length },
+        run: {
+            cases,
+            invalid: run.invalid ?? [],
+            warnings: run.warnings ?? [],
+            stages: [stage],
+            metrics: { [stage]: run.metrics },
+            pool: { overall: EMPTY_POOL, byCategory: {} },
+            stageChanges: [],
+            rerankFailures: 0,
+            byCorpus: {},
+        },
+        legacy: true,
+    };
+}
+function withCorpusMetadata(file) {
+    if (!file?.metadata || file.metadata.corpora !== undefined)
+        return file;
+    return {
+        ...file,
+        metadata: { ...file.metadata, corpora: [], liveCases: file.run.cases.length },
+        run: { ...file.run, cases: file.run.cases.map(c => ({ ...c, corpus: c.corpus ?? null })), byCorpus: file.run.byCorpus ?? {} },
+    };
+}
 function readResultFile(filePath) {
-    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    return normaliseResultFile(JSON.parse(fs.readFileSync(filePath, 'utf-8')));
 }

package/dist/src/file-utils.d.ts

@@ -19,10 +19,5 @@ export type IndexingExclusion = {
 } | {
     kind: 'ragignore';
 };
-/**
- * Why `collectFiles` would skip the file at `relPath` (relative to the project
- * root, `/`-separated), or null when it would collect it. Checks mirror
- * `collectFiles`: file name, `IGNORE_DIRS` segments, `.ragignore` on every prefix.
- */
 export declare function indexingExclusion(relPath: string, ig: ReturnType<typeof ignore>): IndexingExclusion | null;
 export declare function collectFiles(dir: string, ig: ReturnType<typeof ignore>, rootDir: string): string[];

package/dist/src/file-utils.js

@@ -80,11 +80,6 @@ function loadIgnore(projectDir) {
 function isIndexableFileName(name) {
     return SOURCE_EXTENSIONS.test(name) && !IGNORE_EXTENSIONS.test(name);
 }
-/**
- * Why `collectFiles` would skip the file at `relPath` (relative to the project
- * root, `/`-separated), or null when it would collect it. Checks mirror
- * `collectFiles`: file name, `IGNORE_DIRS` segments, `.ragignore` on every prefix.
- */
 function indexingExclusion(relPath, ig) {
     const segments = relPath.split('/');
     if (!isIndexableFileName(segments[segments.length - 1]))

package/dist/src/graph.d.ts

@@ -12,33 +12,15 @@ export interface GraphData {
     nodes: ProjectNode[];
     edges: Edge[];
 }
-/** A single named graph tab (Workspace, or one per nested Nx repo). */
 export interface GraphView {
     name: string;
     nodes: ProjectNode[];
     edges: Edge[];
 }
-/**
- * Build the project graph data (nodes + relation edges) from a project list.
- * Pure apart from reading each project's `.ragmeta.json`. Shared by the console
- * graph, the graph views, and the web dashboard's `/api/graph`.
- */
 export declare function buildGraphData(projects: {
     name: string;
     path: string;
 }[]): GraphData;
-/**
- * Split a project list into graph tabs. A project whose name contains a `/`
- * belongs to a nested Nx repo (`<repo>/<sub-project>`); everything else is a
- * flat top-level project.
- *
- * - **Workspace** tab: flat projects + one node per Nx repo (collapsed to a
- *   single `nxRepo` node); edges from `.ragmeta.json` relations.
- * - **One tab per Nx repo**: its sub-projects as nodes, with edges between them
- *   taken from real import dependencies (`projectEdges`, from `code_dependency`).
- *
- * Returns the Workspace view first, then repo views sorted by name.
- */
 export declare function buildGraphViews(projects: {
     name: string;
     path: string;
@@ -46,13 +28,6 @@ export declare function buildGraphViews(projects: {
     from: string;
     to: string;
 }[], workspaceRoot: string): GraphView[];
-/**
- * Render the full interactive graph page (vis-network + inner tabs, edge-type
- * filters, legend, project toggle list). Used for the standalone
- * `project-graph.html` and served by the web dashboard at `GET /graph` (embedded
- * via iframe) so both share one implementation. Tab 0 is the Workspace view;
- * double-clicking an Nx-repo node opens that repo's tab.
- */
 export declare function buildHtml(views: GraphView[]): string;
 export declare function generateProjectGraph(projects: {
     name: string;

package/dist/src/graph.js

@@ -41,11 +41,6 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const file_utils_1 = require("./file-utils");
 const EMPTY_META = { description: null, stack: null, notes: null, relations: null };
-/**
- * Build the project graph data (nodes + relation edges) from a project list.
- * Pure apart from reading each project's `.ragmeta.json`. Shared by the console
- * graph, the graph views, and the web dashboard's `/api/graph`.
- */
 function buildGraphData(projects) {
     const nodes = projects.map(p => {
         const meta = (0, file_utils_1.readRagMeta)(p.path);
@@ -53,18 +48,6 @@ function buildGraphData(projects) {
     });
     return { nodes, edges: buildEdges(nodes) };
 }
-/**
- * Split a project list into graph tabs. A project whose name contains a `/`
- * belongs to a nested Nx repo (`<repo>/<sub-project>`); everything else is a
- * flat top-level project.
- *
- * - **Workspace** tab: flat projects + one node per Nx repo (collapsed to a
- *   single `nxRepo` node); edges from `.ragmeta.json` relations.
- * - **One tab per Nx repo**: its sub-projects as nodes, with edges between them
- *   taken from real import dependencies (`projectEdges`, from `code_dependency`).
- *
- * Returns the Workspace view first, then repo views sorted by name.
- */
 function buildGraphViews(projects, projectEdges, workspaceRoot) {
     const flat = [];
     const groups = new Map();
@@ -84,7 +67,6 @@ function buildGraphViews(projects, projectEdges, workspaceRoot) {
         }
     }
     const repoNames = [...groups.keys()].sort();
-    // Workspace: flat projects + one collapsed node per repo (reads repo-root ragmeta).
     const workspaceProjects = [
         ...flat,
         ...repoNames.map(repo => ({ name: repo, path: path.join(workspaceRoot, repo) })),
@@ -95,7 +77,6 @@ function buildGraphViews(projects, projectEdges, workspaceRoot) {
         if (repoSet.has(n.name))
             n.nxRepo = true;
     const workspace = { name: 'Workspace', nodes: ws.nodes, edges: ws.edges };
-    // Per-repo: sub-project nodes + intra-repo import edges.
     const repoViews = repoNames.map(repo => {
         const subs = groups.get(repo);
         const { nodes } = buildGraphData(subs);
@@ -151,7 +132,6 @@ function printConsole(views, workspacePath) {
         console.log(`\n  Full graph: file://${path.join(workspacePath, 'project-graph.html')}`);
     }
 }
-/** Prepare a view for vis-network: colored nodes (+ synthetic nodes for unknown edge targets) and indexed edges. */
 function viewToVis(view) {
     const nodes = view.nodes.map(n => ({
         id: n.name,
@@ -173,13 +153,6 @@ function viewToVis(view) {
     const labels = [...new Set(view.edges.map(e => e.label))].sort();
     return { name: view.name, nodes, edges, labels };
 }
-/**
- * Render the full interactive graph page (vis-network + inner tabs, edge-type
- * filters, legend, project toggle list). Used for the standalone
- * `project-graph.html` and served by the web dashboard at `GET /graph` (embedded
- * via iframe) so both share one implementation. Tab 0 is the Workspace view;
- * double-clicking an Nx-repo node opens that repo's tab.
- */
 function buildHtml(views) {
     const visViews = views.map(viewToVis);
     return `<!DOCTYPE html>
@@ -365,7 +338,6 @@ function buildHtml(views) {
 </body>
 </html>`;
 }
-// Single entry point — builds the tabbed views, prints a console summary, writes the HTML.
 function generateProjectGraph(projects, projectEdges, workspacePath) {
     const views = buildGraphViews(projects, projectEdges, workspacePath);
     printConsole(views, workspacePath);

package/dist/src/hnsw-settings.d.ts

@@ -0,0 +1,3 @@
+export declare const ITERATIVE_SCAN_MODE = "relaxed_order";
+export declare function hnswSettings(dbLimit: number, iterative: boolean): Record<string, string | number>;
+export declare function supportsIterativeScan(version: string): boolean;

package/dist/src/hnsw-settings.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ITERATIVE_SCAN_MODE = void 0;
+exports.hnswSettings = hnswSettings;
+exports.supportsIterativeScan = supportsIterativeScan;
+exports.ITERATIVE_SCAN_MODE = 'relaxed_order';
+const EF_SEARCH_DEFAULT = 40;
+const EF_SEARCH_MAX = 1000;
+const ITERATIVE_SCAN_MIN_VERSION = [0, 8, 0];
+function hnswSettings(dbLimit, iterative) {
+    return {
+        'hnsw.ef_search': Math.min(Math.max(dbLimit, EF_SEARCH_DEFAULT), EF_SEARCH_MAX),
+        ...(iterative ? { 'hnsw.iterative_scan': exports.ITERATIVE_SCAN_MODE } : {}),
+    };
+}
+function supportsIterativeScan(version) {
+    const segments = version.split('.').map(s => parseInt(s, 10) || 0);
+    for (let i = 0; i < ITERATIVE_SCAN_MIN_VERSION.length; i++) {
+        const diff = (segments[i] ?? 0) - ITERATIVE_SCAN_MIN_VERSION[i];
+        if (diff !== 0)
+            return diff > 0;
+    }
+    return true;
+}

package/dist/src/interfaces/IAstParser.d.ts

@@ -1,3 +1,4 @@
+import type { DeclarationTree } from '../declarations/DeclarationTree';
 export interface DepEdge {
     project: string;
     fromFile: string;
@@ -16,19 +17,9 @@ export interface SymbolEntry {
     line: number | null;
     endLine: number | null;
     col: number | null;
-    /** Dotted path of enclosing named scopes, outermost first; null for top-level declarations. */
     container: string | null;
     isStatic: boolean;
-    /**
-     * Qualified TypeScript name of the decorated declaration, set only on
-     * `graphql-symbols` rows (`graphqlNames`); null on every `symbols`/`members` entry.
-     */
     target?: string | null;
-    /**
-     * Whether this declaration node has a body (vs. an overload signature).
-     * Internal — used only to pick an overload set's representative row before
-     * writing to `code_symbol`; never persisted.
-     */
     hasBody?: boolean;
 }
 export interface CallEdge {
@@ -41,47 +32,19 @@ export interface CallEdge {
     line: number | null;
     col: number | null;
 }
-/**
- * Line range of a named scope used only to compute a chunk's owning declaration
- * (`ownerPath`). Method/constructor/accessor ranges carry their enclosing class
- * as `container`; top-level declarations use `container: null`. These are NOT
- * persisted to `code_symbol` — they exist only for chunk ownership.
- */
-export interface OwnerRange {
-    name: string;
-    container: string | null;
-    line: number;
-    endLine: number;
-}
 export interface FileAnalysis {
     edges: DepEdge[];
-    /** Top-level declarations only — feeds the chunker and the embedding prompt. */
     symbols: SymbolEntry[];
-    /** Members, namespace-level declarations and classes collected from the whole
-     * file. Written to `code_symbol` alongside `symbols`; never fed to the
-     * chunker or the prompt (see the `symbol-index-members` retrieval-invariance
-     * requirement). */
     members: SymbolEntry[];
     calls: CallEdge[];
-    /** Ownership ranges (decorator-inclusive) for every indexed declaration except `method_signature`. */
-    ownerRanges?: OwnerRange[];
-    /**
-     * GraphQL-named rows (`@Query`/`@Mutation`/`@Subscription`/`@ResolveField`/
-     * `@ObjectType`/`@InputType`/`@InterfaceType` of `@nestjs/graphql`). Written to
-     * `code_symbol` alongside `symbols`/`members`; never fed to the chunker, the
-     * prompt, `buildOwnerRanges` or `extractCalls` (see `graphql-symbols`).
-     */
+    declarations?: DeclarationTree;
     graphqlNames: SymbolEntry[];
 }
 export interface AnalyzeProjectOpts {
     skipDependencyResolution?: boolean;
-    /** Path to root tsconfig (e.g. tsconfig.base.json) for workspace-wide path aliases */
     rootTsConfigPath?: string;
 }
 export interface IAstParser {
-    /**
-     * @deprecated Use analyzeProject instead for project-wide context.
-     */
     analyzeFile(filePath: string, serviceName: string, projectRoot?: string): Promise<FileAnalysis>;
     analyzeProject(filePaths: string[], serviceName: string, projectRoot?: string, opts?: AnalyzeProjectOpts): Promise<Map<string, FileAnalysis>>;
     clearCache(projectRoot?: string): void;

package/dist/src/interfaces/IChunker.d.ts

@@ -1,24 +1,15 @@
-import type { SymbolEntry } from './IAstParser';
-/** One embeddable unit of source with its 1-based inclusive line range. */
+import type { DeclarationTree } from '../declarations/DeclarationTree';
 export interface ChunkPiece {
     content: string;
     startLine: number;
     endLine: number;
 }
 export interface ChunkOpts {
-    /** 'ast' = symbol-aligned boundaries; 'character' = fixed-size recursive splitter. */
     strategy: 'ast' | 'character';
-    /** Schema files (.prisma/.graphql/.gql) always use the schema separator splitter. */
     isSchemaFile: boolean;
-    /** Top-level symbol ranges for the file; may be empty (no analysis available). */
-    symbols: SymbolEntry[];
+    declarations?: DeclarationTree;
+    jsx?: boolean;
 }
 export interface IChunker {
-    /**
-     * Split source into embeddable pieces. AST strategy aligns boundaries to
-     * top-level declaration ranges and never emits a piece longer than the
-     * configured chunk size; falls back to the character splitter for schema
-     * files, empty-symbol files, or when strategy is 'character'.
-     */
     chunk(code: string, opts: ChunkOpts): Promise<ChunkPiece[]>;
 }