codesearch-mcp 0.2.3-alpha → 0.4.0-alpha

package/dist/src/eval-results.js

@@ -33,20 +33,111 @@ 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 retrieval_eval_1 = require("./retrieval-eval");
+const eval_vector_index_1 = require("./eval-vector-index");
+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 +149,51 @@ 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));
+    lines.push(`**Vector index:** ${(0, eval_vector_index_1.formatVectorIndex)(metadata.vectorIndex)}`);
+    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 ${(0, retrieval_eval_1.formatThresholdConditions)(c.thresholds)} | 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 +201,211 @@ 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('; '), '');
         }
-        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];
+        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('### 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}`);
+    lines.push(`  vector index: ${(0, eval_vector_index_1.formatVectorIndex)(metadata.vectorIndex)}`);
+    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 withThresholdConditions(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 withThresholdConditions(file) {
+    const conditions = file?.metadata?.conditions;
+    if (conditions?.similarityThreshold === undefined)
+        return file;
+    const { similarityThreshold, ...rest } = conditions;
+    return {
+        ...file,
+        metadata: { ...file.metadata, conditions: { ...rest, thresholds: [{ value: similarityThreshold, source: 'not recorded' }] } },
+    };
+}
 function readResultFile(filePath) {
-    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    return normaliseResultFile(JSON.parse(fs.readFileSync(filePath, 'utf-8')));
 }

package/dist/src/eval-vector-index.d.ts

@@ -0,0 +1,5 @@
+import type { IDatabase } from './interfaces/IDatabase';
+import type { VectorIndexRecord } from './interfaces/IRetrievalEvaluator';
+export declare function describeVectorIndex(db: Pick<IDatabase, 'query' | 'pgvectorVersion'>): Promise<VectorIndexRecord>;
+export declare function formatIndexes(record: VectorIndexRecord): string;
+export declare function formatVectorIndex(record: VectorIndexRecord | null): string;

package/dist/src/eval-vector-index.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeVectorIndex = describeVectorIndex;
+exports.formatIndexes = formatIndexes;
+exports.formatVectorIndex = formatVectorIndex;
+const BUILD_DEFAULTS = {
+    hnsw: { m: '16', ef_construction: '64' },
+    ivfflat: { lists: '100' },
+};
+const INDEX_SQL = `
+  SELECT c.relname AS name, am.amname AS method, oc.opcname AS opclass, c.reloptions AS options
+  FROM pg_index i
+  JOIN pg_class c ON c.oid = i.indexrelid
+  JOIN pg_am am ON am.oid = c.relam
+  JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = i.indkey[0]
+  JOIN pg_opclass oc ON oc.oid = i.indclass[0]
+  WHERE i.indrelid = to_regclass('code_chunk') AND a.attname = 'embedding' AND i.indisvalid
+  ORDER BY c.relname`;
+const SCAN_SETTINGS_SQL = `
+  SELECT current_setting('hnsw.max_scan_tuples', true) AS max_scan_tuples,
+         current_setting('hnsw.scan_mem_multiplier', true) AS scan_mem_multiplier
+  FROM (SELECT '[1]'::vector) AS loaded`;
+function numericSetting(value) {
+    if (value == null || value === '')
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+function parseOptions(options) {
+    const params = {};
+    for (const option of options ?? []) {
+        const eq = option.indexOf('=');
+        if (eq > 0)
+            params[option.slice(0, eq)] = option.slice(eq + 1);
+    }
+    return params;
+}
+async function describeVectorIndex(db) {
+    const rows = await db.query(INDEX_SQL);
+    const [settings] = await db.query(SCAN_SETTINGS_SQL);
+    return {
+        pgvector: await db.pgvectorVersion(),
+        indexes: rows.map(r => ({
+            name: r.name,
+            method: r.method,
+            opclass: r.opclass,
+            params: { ...BUILD_DEFAULTS[r.method], ...parseOptions(r.options) },
+        })),
+        maxScanTuples: numericSetting(settings?.max_scan_tuples),
+        scanMemMultiplier: numericSetting(settings?.scan_mem_multiplier),
+    };
+}
+function formatIndexes(record) {
+    return record.indexes.map(i => `${i.name} ${i.method} (${[i.opclass, ...Object.entries(i.params).map(([k, v]) => `${k}=${v}`)].join(', ')})`).join('; ') || 'none';
+}
+function formatVectorIndex(record) {
+    if (!record)
+        return 'not recorded';
+    return `${formatIndexes(record)} | pgvector ${record.pgvector ?? 'not installed'} | hnsw.max_scan_tuples ${record.maxScanTuples ?? 'not defined'} | hnsw.scan_mem_multiplier ${record.scanMemMultiplier ?? 'not defined'}`;
+}

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/help.js

@@ -16,7 +16,15 @@ function printHelp(command) {
             console.log('  --project [name]  Scope this run to one discovered project or monorepo unit');
             console.log('                    by exact name, bypassing selection and pruning; omit the');
             console.log('                    name for an interactive single-choice prompt');
+            console.log('  --require-cwd     Needs --project <name>; the run is refused unless the current');
+            console.log('                    directory is that project\'s directory');
             console.log('  -h, --help        Show this help message');
+            console.log('');
+            console.log('Exit codes:');
+            console.log('  0  No file failed and nothing else failed; includes an interrupted run,');
+            console.log('     which may have left files unindexed');
+            console.log('  2  The run finished with failed files and the rest of the index is usable');
+            console.log('  1  Any other failure');
             break;
         case 'rag-mcp':
         case 'mcp':
@@ -75,7 +83,7 @@ function printHelp(command) {
             console.log('  -h, --help        Show this help message');
             break;
         default:
-            console.log('Usage: rag-index [--reindex] [--select] [--project [name]]');
+            console.log('Usage: rag-index [--reindex] [--select] [--project [name]] [--require-cwd]');
             console.log('       rag-mcp');
             console.log('       rag-setup');
             console.log('       rag-config <show|get|set|reset|edit>');

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;