codesearch-mcp 0.2.2-alpha → 0.3.0-alpha

package/dist/src/eval-results.js

@@ -0,0 +1,397 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.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} | ${oneCase(m.count)} | ${pct(m.hit1)} | ${pct(m.hit5)} | ${m.mrr10.toFixed(4)} |`;
+}
+function deltaRow(label, d) {
+    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;
+    const lines = [];
+    lines.push('# Retrieval Evaluation Report', '');
+    lines.push(`**Suite:** ${metadata.suitePath} (hash \`${metadata.suiteHash}\`)`);
+    lines.push(`**Model:** ${metadata.embeddingProvider}/${metadata.embeddingModel} | **Reranker:** ${metadata.rerankerModel ?? 'none'}`);
+    lines.push(`**Commit:** ${metadata.gitCommit} | **Timestamp:** ${metadata.timestamp}`);
+    if (metadata.indexMeta) {
+        lines.push(`**Index:** ${metadata.indexMeta.provider}/${metadata.indexMeta.model} (${metadata.indexMeta.dimensions} dims)`);
+    }
+    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 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 |', '|---|---|');
+        for (const w of run.warnings)
+            lines.push(`| ${w.id} | ${w.droppedExpects.map(e => e.file).join(', ')} |`);
+    }
+    if (comparison) {
+        const cmp = comparison.result;
+        lines.push('', `## Comparison against ${comparison.baselinePath}`, '');
+        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('### 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(poolDeltaRow(category, d));
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+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())}`;
+}
+function writeResultFiles(resultsDir, suiteLabel, result, now, comparison) {
+    fs.mkdirSync(resultsDir, { recursive: true });
+    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 normaliseResultFile(JSON.parse(fs.readFileSync(filePath, 'utf-8')));
+}

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

@@ -10,4 +10,14 @@ export type RagMetaResult = ProjectMeta | 'missing' | 'invalid';
 export declare function readRagMeta(projectDir: string): RagMetaResult;
 export declare const IGNORE_DIRS: Set<string>;
 export declare function loadIgnore(projectDir: string): ReturnType<typeof ignore>;
+export declare function isIndexableFileName(name: string): boolean;
+export type IndexingExclusion = {
+    kind: 'type';
+} | {
+    kind: 'ignored_dir';
+    segment: string;
+} | {
+    kind: 'ragignore';
+};
+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

@@ -39,6 +39,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.IGNORE_DIRS = void 0;
 exports.readRagMeta = readRagMeta;
 exports.loadIgnore = loadIgnore;
+exports.isIndexableFileName = isIndexableFileName;
+exports.indexingExclusion = indexingExclusion;
 exports.collectFiles = collectFiles;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -75,6 +77,22 @@ function loadIgnore(projectDir) {
     }
     return ig;
 }
+function isIndexableFileName(name) {
+    return SOURCE_EXTENSIONS.test(name) && !IGNORE_EXTENSIONS.test(name);
+}
+function indexingExclusion(relPath, ig) {
+    const segments = relPath.split('/');
+    if (!isIndexableFileName(segments[segments.length - 1]))
+        return { kind: 'type' };
+    const ignoredDir = segments.slice(0, -1).find(s => exports.IGNORE_DIRS.has(s));
+    if (ignoredDir)
+        return { kind: 'ignored_dir', segment: ignoredDir };
+    for (let i = 1; i <= segments.length; i++) {
+        if (ig.ignores(segments.slice(0, i).join('/')))
+            return { kind: 'ragignore' };
+    }
+    return null;
+}
 function collectFiles(dir, ig, rootDir) {
     const result = [];
     let entries;
@@ -94,7 +112,7 @@ function collectFiles(dir, ig, rootDir) {
             if (!exports.IGNORE_DIRS.has(file))
                 result.push(...collectFiles(fullPath, ig, rootDir));
         }
-        else if (SOURCE_EXTENSIONS.test(file) && !IGNORE_EXTENSIONS.test(file)) {
+        else if (isIndexableFileName(file)) {
             result.push(fullPath);
         }
     }

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

@@ -13,6 +13,9 @@ function printHelp(command) {
             console.log('Options:');
             console.log('  --reindex         Force re-index all files (ignores cached mtimes)');
             console.log('  --select          Interactively select which projects to index');
+            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('  -h, --help        Show this help message');
             break;
         case 'rag-mcp':
@@ -72,7 +75,7 @@ function printHelp(command) {
             console.log('  -h, --help        Show this help message');
             break;
         default:
-            console.log('Usage: rag-index [--reindex] [--select]');
+            console.log('Usage: rag-index [--reindex] [--select] [--project [name]]');
             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;

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;
+}