codesearch-mcp 0.2.1-alpha → 0.2.3-alpha

package/CHANGELOG.md

@@ -5,6 +5,46 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [0.2.3-alpha] - 2026-10-21
+
+### Measured, no change
+
+- **Embedding prompt: members in `Symbols:` and an `Owner:` line both measured, neither shipped** — `prompt-owner-line` ran `rag-index eval` against two prompt variants (members overlapping the chunk added to `Symbols:`; a new `Owner: <ownerPath>` line) against the `retrieval-eval-set` reference baseline (41 cases). Members: overall MRR@10 +0.0192, short of the required ≥ 0.02. Owner line: overall MRR@10 -0.0112, with the `identifier` category dropping -0.0268 (over the -0.02 limit). Neither met the decision rule fixed in advance, so the embedding prompt is unchanged. Results: `benchmarks/results/prompt-owner-line-decision.md`. Separately, re-running the same suite with the reranker disabled scored far higher than with it enabled for both variants (+0.16 to +0.21 MRR@10) — unrelated to the prompt tested, but worth its own investigation into the configured reranker.
+
+### Added
+
+- **`rag-index --project [name]` scopes a run to one project or monorepo unit** — matched exactly against the same names `list_projects` prints; a unit name (e.g. `micros-learning`) expands to all of its children. Bypasses the `.ragprojects`/`.ragskip` selector and project pruning entirely, leaving every other indexed project untouched. Composes with `--reindex` to force a full reindex of just that project. Omitting the name opens a one-off interactive single-choice prompt (distinct from the `--select` multi-select checkbox). An unresolved name is reported with the full list of available projects and exits non-zero before any database or embedding-backend work. The post-index project graph (`project-graph.html`) now always reflects the full discovered workspace regardless of `--select`/`--project` scoping.
+- **`search_codebase` gains a per-call `rerank` override** — pass `rerank: false` to skip reranking regardless of `reranker.enabled` (uses `fetchLimit = limit`, no candidate floor), or `rerank: true` to force it on when a reranker is configured (no-op otherwise). A 41-case / 82-query benchmark across both projects' `benchmarks/eval/*.json` suites found `rerank: false` performs same-or-better in a strong majority of identifier/behaviour/concept cases at `threshold=0.6`/`limit=5`; guidance in `McpServer.ts` and `CLAUDE.md` recommends `false` for "what does X do" / "where is X" lookups described without an exact name, and points exact-name lookups at `find_symbol` instead of `search_codebase` (the rerank setting is moot there — `find_symbol` resolved every sampled identifier exactly at rank 1).
+- **`find_symbol` finds NestJS GraphQL operations, resolve fields and types by their GraphQL name** — `@Query`/`@Mutation`/`@Subscription`/`@ResolveField`/`@ObjectType`/`@InputType`/`@InterfaceType` decorators imported from `@nestjs/graphql` get an extra `code_symbol` row named by the GraphQL name (e.g. `adminPendingSubscriptionOrders`, not the method's TypeScript name), with new kinds `graphql_query`/`graphql_mutation`/`graphql_subscription`/`graphql_field`/`graphql_type` and a ` → \`<target>\`` in the output naming the TypeScript declaration. These rows never affect retrieval, chunk ownership or the call graph. Run `rag-index --reindex` to get the new rows for a project already indexed.
+
+### Changed (breaking)
+
+- **One path form for every MCP tool: workspace-relative** — the form `search_codebase`, `find_symbol` and `get_callers` already print (`my-app/src/index.ts`; for a nested-monorepo project the on-disk path, `micros-learning/apps/account/...`). `read_file` takes it instead of an absolute path; `list_files` takes a workspace directory (`.` for the root) and loses its `project` argument; `get_dependencies` / `get_dependents` lose their `project` argument (a passed `project` is ignored). An absolute path is refused with its workspace-relative equivalent, so update prompts or skills that pass absolute paths or `project` to these tools.
+
+### Changed
+
+- **A path that names nothing is an error, not an empty result** — every path-taking tool answers `Not found:` with the expected form (example `my-app/src` for `list_files`, `my-app/src/index.ts` elsewhere) and up to three `Did you mean:` candidates, `Not indexed:` (with the reason — excluded file type, ignored directory, `.ragignore`, unselected project, or not yet indexed), `Deleted from disk:`, `Not a file:` / `Not a directory:` or `Cannot read:`, all as MCP error responses. A database or discovery failure is an error response, never "not found".
+- **`Did you mean:` resolves nested-monorepo project names** — a path that starts with a project's name instead of its directory (`micros-learning/account/src/main.ts`) is offered at its on-disk location (`micros-learning/apps/account/src/main.ts`) first, when that file exists; `list_files` given a project name is pointed at the project's directory.
+- **Graph tools span projects** — `get_dependencies`, `get_dependents` and `include_graph_context` list edges into and out of other projects; an edge stored under two overlapping projects prints once; import targets outside the workspace (`../…`) are never printed.
+- **`read_file_range` reads unindexed files** — both read tools read any file under the workspace (symlinks resolved before the boundary check; a symlinked file already in the index stays readable). `start_line` past the end and `end_line` before `start_line` are errors; an unreadable file is `Cannot read:`.
+- **`list_projects` prints each project's directory** as a `path:` line, marked `(not on disk)` when it is gone. `list_files` prints a `**Directory:**` header and marks unreadable subdirectories `(unreadable)`.
+- **`get_dependents` text-search fallback** runs in the project owning the file and reports `failed` / `partial` when grep cannot search every file, instead of `No results.`
+- **Transitive `get_dependencies` / `get_dependents` traverse each reachable file once** — a breadth-first traversal replaces the recursive query, issuing one query per depth level instead of enumerating every import path. A file that is a direct dependency/dependent is no longer also listed under `**Transitive:**` at a larger depth; `via` on a tie is now the first predecessor in UTF-8 byte order, deterministic instead of arbitrary; indirect rows of equal depth are ordered by path in byte order instead of the database's default collation. Direct rows are unchanged.
+
+### Fixed
+
+- **Combined and side-effect imports no longer lose edges** — `import Layout, { NavItem } from './layout'` previously recorded only the named import (`NavItem`), losing the default; `import X, * as N from './m'` recorded only the default, losing the namespace import. Each part of an import declaration — default, namespace, each named import — now produces its own edge, in that order. A side-effect import (`import './x'`) now gets a new `depType` `import-side-effect`, where before it produced no edge at all, so `get_dependents` under-reported its target as unused. Default and namespace edges also get `fromSymbol` from the local name, the same rule named imports already use. The embedding prompt is unaffected — side-effect edges are excluded from it, and the other edges already deduped by file. Run `rag-index --reindex` to get the new edges for files already indexed.
+
+### Removed
+
+- **Per-project symbol-index version check** — `rag-index` no longer refuses to run with `Indexed before member indexing … run rag-index --reindex`, and `find_symbol`/`get_callers` no longer show that warning. Interrupting the first indexing of a project (ESC/Ctrl+C) used to trigger it on the next run even though every row was already in the current format. If you are upgrading from 0.2.0 or earlier with an existing index, run `rag-index --reindex` once yourself — it is no longer enforced. The `symbol_index_version` table is no longer created or read; an existing one is left in place, unused.
+
+## [0.2.2-alpha] - 2026-10-02
+
+### Fixed
+
+- **Global install crashed on startup with `Cannot find module 'typescript'`** — `AstParserService` imported `NodeFlags`/`SyntaxKind` as runtime values from `typescript`, a `devDependency` not installed by `npm install -g`. Now sourced from `ts-morph`, which already bundles its own copy of the compiler — no separate runtime dependency on `typescript`.
+
 ## [0.2.1-alpha] - 2026-10-02
 
 ### Added

package/README.md

@@ -73,8 +73,13 @@ rag-index
 rag-index --select          # re-run project selection
 rag-index --reindex         # force re-embed all files (use after model change)
 rag-index --select --reindex
+rag-index --project billing-service           # scope this run to one project, by exact name
+rag-index --reindex --project billing-service # force a full reindex of just that project
+rag-index --project                           # no name — pick one from an interactive prompt
 ```
 
+`--project` leaves every other indexed project untouched: it skips the `.ragprojects`/`.ragskip` selector entirely and never prunes projects outside the one(s) it resolves to. A name that doesn't match any discovered project or monorepo unit exits with an error before touching the database — matching exactly, no partial or fuzzy match.
+
 ## Monorepo support
 
 If `workspaceRoot` is an [Nx](https://nx.dev) workspace (detected by `nx.json`), `rag-index` discovers each project under `apps/`, `libs/`, and `packages/` as a **separate indexed project** rather than scanning the workspace as one blob. Cross-project imports like `@scope/shared` resolve through the workspace `tsconfig.base.json` path aliases, so `get_dependencies` / `get_dependents` report edges **across** projects.
@@ -97,16 +102,18 @@ See [docs/web-dashboard.md](docs/web-dashboard.md) for the full reference.
 
 ## MCP Tools
 
+Every file or directory argument is **workspace-relative** (relative to `workspaceRoot`, `/`-separated — e.g. `my-app/src/index.ts`, `.` for the root), exactly as `search_codebase` prints it, so a path copied from one tool works in every other. A path that names nothing is an error with the expected form and up to three `Did you mean:` candidates, never an empty result.
+
 | Tool | Description |
 |------|-------------|
-| `search_codebase` | Semantic search across all indexed projects. Accepts `include_graph_context` to append direct imports/dependents to each result, `include_neighbors` for surrounding chunks, and `threshold` to override the similarity threshold for that query |
-| `list_projects` | List projects with metadata and chunk counts |
-| `find_symbol` | Find a declaration or member by exact name — bare, qualified (`Class.method`), quoted, or computed — faster than semantic search |
-| `list_files` | Browse the directory tree of a project |
-| `read_file` | Read a complete file by absolute path |
-| `read_file_range` | Read a specific line range from an indexed file |
-| `get_dependencies` | Show what files a given file imports (direct or transitive) |
-| `get_dependents` | Show which files import a given file (direct or transitive) |
+| `search_codebase` | Semantic search across all indexed projects. Accepts `include_graph_context` to append direct imports/dependents to each result, `include_neighbors` for surrounding chunks, `threshold` to override the similarity threshold for that query, and `rerank` to force reranking on/off for that call regardless of `reranker.enabled` |
+| `list_projects` | List projects with metadata, chunk counts and each project's directory (`path:` line) |
+| `find_symbol` | Find a declaration or member by exact name — bare, qualified (`Class.method`), quoted, or computed — faster than semantic search. Also finds a NestJS GraphQL operation, resolve field or type by its GraphQL name (`kind: graphql_query`/`graphql_mutation`/`graphql_subscription`/`graphql_field`/`graphql_type`) |
+| `list_files` | Browse the directory tree of any workspace directory |
+| `read_file` | Read a complete file under the workspace, indexed or not |
+| `read_file_range` | Read a specific line range from any file under the workspace |
+| `get_dependencies` | Show what files a given file imports (direct or transitive), across projects |
+| `get_dependents` | Show which files import a given file (direct or transitive), across projects |
 | `get_callers` | Find all call sites of a function or method by exact name (bare or qualified) |
 
 ## Project metadata

package/dist/app.js

@@ -41,6 +41,7 @@ const container_1 = require("./src/container");
 const config_1 = require("./src/config");
 const config_store_1 = require("./src/config-store");
 const IndexCommand_1 = require("./src/commands/IndexCommand");
+const EvalCommand_1 = require("./src/commands/EvalCommand");
 const McpCommand_1 = require("./src/commands/McpCommand");
 const ConfigCommand_1 = require("./src/commands/ConfigCommand");
 const WebCommand_1 = require("./src/commands/WebCommand");
@@ -86,17 +87,53 @@ async function main() {
     const isSetup = argv1 === 'rag-setup' || process.argv[2] === 'setup' || process.argv[2] === 'rag-setup';
     const isConfig = argv1 === 'rag-config' || process.argv[2] === 'config' || process.argv[2] === 'rag-config';
     const isWeb = argv1 === 'rag-web' || process.argv[2] === 'web' || process.argv[2] === 'rag-web';
-    const mode = isIndex ? 'index' : isMcp ? 'mcp' : isSetup ? 'setup' : isConfig ? 'config' : isWeb ? 'web' : (process.argv[2] ?? '');
     const isBinary = ['rag-index', 'rag-mcp', 'rag-setup', 'rag-config', 'rag-web'].includes(argv1);
+    // `rag-index eval` — a sub-mode of index, not its own binary, so it sits one
+    // token deeper than the other modes (`rag-index eval` / `index eval`).
+    const evalSubArg = isBinary ? process.argv[2] : process.argv[3];
+    const isEval = isIndex && evalSubArg === 'eval';
+    const mode = isEval ? 'eval' : isIndex ? 'index' : isMcp ? 'mcp' : isSetup ? 'setup' : isConfig ? 'config' : isWeb ? 'web' : (process.argv[2] ?? '');
+    const helpKey = mode === 'eval' ? 'eval' : (isBinary ? argv1 : mode);
     if (process.argv.includes('--help') || process.argv.includes('-h')) {
-        (0, help_1.printHelp)(isBinary ? argv1 : mode);
+        (0, help_1.printHelp)(helpKey);
         process.exit(0);
     }
-    const effectiveArgs = process.argv.slice(isBinary ? 2 : 3);
+    const effectiveArgs = process.argv.slice(isEval ? (isBinary ? 3 : 4) : (isBinary ? 2 : 3));
     // Arg validation
-    if (mode === 'index') {
-        const knownFlags = new Set(['--reindex', '--select']);
-        const unknown = effectiveArgs.filter(a => !a.startsWith('-') || !knownFlags.has(a));
+    if (mode === 'eval') {
+        const valueFlags = new Set(['--suite', '--baseline', '--project']);
+        const unknown = [];
+        for (let i = 0; i < effectiveArgs.length; i++) {
+            const a = effectiveArgs[i];
+            if (valueFlags.has(a)) {
+                const next = effectiveArgs[i + 1];
+                if (next !== undefined && !next.startsWith('-'))
+                    i++; // consume the value
+                continue;
+            }
+            unknown.push(a);
+        }
+        if (unknown.length > 0) {
+            console.error(`Unexpected argument: ${unknown[0]}\n`);
+            (0, help_1.printHelp)(helpKey);
+            process.exit(1);
+        }
+    }
+    else if (mode === 'index') {
+        const boolFlags = new Set(['--reindex', '--select']);
+        const unknown = [];
+        for (let i = 0; i < effectiveArgs.length; i++) {
+            const a = effectiveArgs[i];
+            if (boolFlags.has(a))
+                continue;
+            if (a === '--project') {
+                const next = effectiveArgs[i + 1];
+                if (next !== undefined && !next.startsWith('-'))
+                    i++; // consume the name
+                continue;
+            }
+            unknown.push(a);
+        }
         if (unknown.length > 0) {
             console.error(`Unexpected argument: ${unknown[0]}\n`);
             (0, help_1.printHelp)(isBinary ? argv1 : 'rag-index');
@@ -137,7 +174,7 @@ async function main() {
         process.exit(0);
     }
     // All other modes require a valid config.json
-    const loggerName = mode === 'index' ? 'indexer' : mode === 'mcp' ? 'mcp' : mode === 'web' ? 'web' : undefined;
+    const loggerName = mode === 'index' || mode === 'eval' ? 'indexer' : mode === 'mcp' ? 'mcp' : mode === 'web' ? 'web' : undefined;
     let container;
     try {
         container = (0, container_1.createContainer)(loggerName);
@@ -161,6 +198,7 @@ async function main() {
     // never use it.
     const factories = {
         index: () => new IndexCommand_1.IndexCommand(container, argv1),
+        eval: () => new EvalCommand_1.EvalCommand(container, argv1),
         mcp: () => new McpCommand_1.McpCommand(container),
         web: () => new WebCommand_1.WebCommand(container, effectiveArgs),
     };

package/dist/src/commands/EvalCommand.d.ts

@@ -0,0 +1,10 @@
+import type { Container } from '../container';
+import type { ICommand } from './ICommand';
+export declare class EvalCommand implements ICommand {
+    private container;
+    private argv1;
+    constructor(container: Container, argv1: string);
+    execute(): Promise<void>;
+    private printSummary;
+    private printComparison;
+}

package/dist/src/commands/EvalCommand.js

@@ -0,0 +1,231 @@
+"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.EvalCommand = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const child_process_1 = require("child_process");
+const retrieval_eval_1 = require("../retrieval-eval");
+const eval_results_1 = require("../eval-results");
+const DEFAULT_SUITE_DIR = path.join('benchmarks', 'eval');
+const RESULTS_DIR_NAME = path.join('benchmarks', 'results');
+// Resolves to the repo root in both `ts-node app.ts` (one level above `src/`) and
+// the compiled `dist/` layout (two levels above `dist/src/commands/`).
+const _projectRoot = fs.existsSync(path.join(__dirname, '..', '..', 'package.json'))
+    ? path.join(__dirname, '..', '..')
+    : path.join(__dirname, '..', '..', '..');
+function gitCommit() {
+    try {
+        return (0, child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], { cwd: _projectRoot, encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function hashContent(text) {
+    return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/** `--suite <path>` — a file or a directory of `*.json` suite files (default: `benchmarks/eval/`). */
+function parseSuiteFlag(args) {
+    const i = args.indexOf('--suite');
+    if (i === -1)
+        return DEFAULT_SUITE_DIR;
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith('-'))
+        throw new Error('--suite requires a path');
+    return next;
+}
+function parseBaselineFlag(args) {
+    const i = args.indexOf('--baseline');
+    if (i === -1)
+        return null;
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith('-'))
+        throw new Error('--baseline requires a path');
+    return next;
+}
+function parseProjectFlag(args) {
+    const i = args.indexOf('--project');
+    if (i === -1)
+        return null;
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith('-'))
+        throw new Error('--project requires a name');
+    return next;
+}
+/** Loads one suite file, or every `*.json` file directly under a directory, merged into one. */
+function loadSuite(suitePath) {
+    const resolved = path.resolve(_projectRoot, suitePath);
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        const files = fs.readdirSync(resolved).filter(f => f.endsWith('.json')).sort();
+        const parts = files.map(f => fs.readFileSync(path.join(resolved, f), 'utf-8'));
+        const suites = parts.map(text => (0, retrieval_eval_1.parseSuite)(JSON.parse(text)));
+        return { suite: (0, retrieval_eval_1.mergeSuites)(suites), rawContent: parts.join('\n'), label: 'all' };
+    }
+    const text = fs.readFileSync(resolved, 'utf-8');
+    return { suite: (0, retrieval_eval_1.parseSuite)(JSON.parse(text)), rawContent: text, label: path.basename(resolved, '.json') };
+}
+class EvalCommand {
+    container;
+    argv1;
+    constructor(container, argv1) {
+        this.container = container;
+        this.argv1 = argv1;
+    }
+    async execute() {
+        const { db, searcher, config } = this.container;
+        const args = process.argv.slice(this.argv1 === 'rag-index' ? 3 : 4); // after `rag-index eval` / `index eval`
+        let suitePath, baselinePath, projectFilter;
+        try {
+            suitePath = parseSuiteFlag(args);
+            baselinePath = parseBaselineFlag(args);
+            projectFilter = parseProjectFlag(args);
+        }
+        catch (err) {
+            console.error(`\n${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        let suite, rawContent, label;
+        try {
+            ({ suite, rawContent, label } = loadSuite(suitePath));
+        }
+        catch (err) {
+            if (err instanceof retrieval_eval_1.EvalSuiteError) {
+                console.error(`\nInvalid suite: ${err.message}`);
+            }
+            else {
+                console.error(`\nFailed to load suite at '${suitePath}': ${err.message}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (projectFilter) {
+            suite = { version: 1, cases: suite.cases.filter(c => c.project === projectFilter) };
+        }
+        if (suite.cases.length === 0) {
+            console.error('\nNo cases to evaluate (suite is empty, or --project matched nothing).');
+            process.exitCode = 1;
+            return;
+        }
+        await db.initDbWithSchema();
+        const knownFilesCache = new Map();
+        const inspect = {
+            async isFileIndexed(project, file) {
+                if (!knownFilesCache.has(project))
+                    knownFilesCache.set(project, db.listKnownFiles(project));
+                const files = await knownFilesCache.get(project);
+                return files.includes(file);
+            },
+            async ownerPathsOfFile(project, file) {
+                const rows = await db.query(`SELECT DISTINCT "ownerPath" FROM code_chunk WHERE "serviceName" = $1 AND "filePath" = $2 AND "ownerPath" IS NOT NULL`, [project, file]);
+                return rows.map(r => r.ownerPath);
+            },
+        };
+        const search = async (query, limit, project, threshold) => {
+            const prepared = await searcher.prepareQuery(query);
+            const results = await searcher.searchChunks(prepared.query, limit, project, threshold);
+            return results.map(r => ({ filePath: r.filePath, ownerPath: r.ownerPath ?? null }));
+        };
+        const run = await new retrieval_eval_1.RetrievalEvaluator().evaluate(suite, search, inspect);
+        const indexMeta = await db.readIndexMeta();
+        const metadata = {
+            suitePath,
+            suiteHash: hashContent(rawContent),
+            embeddingProvider: config.embedding.provider,
+            embeddingModel: config.embedding.model,
+            rerankerModel: config.reranker.enabled ? config.reranker.model : null,
+            indexMeta: indexMeta ? { provider: indexMeta.provider, model: indexMeta.model, dimensions: indexMeta.dimensions } : null,
+            gitCommit: gitCommit(),
+            timestamp: new Date().toISOString(),
+        };
+        const resultFile = { metadata, run };
+        this.printSummary(resultFile);
+        let comparison;
+        if (baselinePath) {
+            try {
+                const baseline = (0, eval_results_1.readResultFile)(path.resolve(_projectRoot, baselinePath));
+                const cmp = (0, retrieval_eval_1.compare)(baseline, resultFile);
+                comparison = { baselinePath, result: cmp };
+                this.printComparison(baselinePath, cmp);
+            }
+            catch (err) {
+                console.error(`\nFailed to read baseline '${baselinePath}': ${err.message}`);
+                process.exitCode = 1;
+            }
+        }
+        const resultsDir = path.join(_projectRoot, RESULTS_DIR_NAME);
+        const { jsonPath, mdPath } = (0, eval_results_1.writeResultFiles)(resultsDir, label, resultFile, new Date(), comparison);
+        console.log(`\nResults written to:\n  ${path.relative(_projectRoot, jsonPath)}\n  ${path.relative(_projectRoot, mdPath)}`);
+    }
+    printSummary(result) {
+        const { run, metadata } = result;
+        console.log(`\nEvaluated ${run.cases.length} case(s) (${run.invalid.length} invalid) against ${metadata.embeddingProvider}/${metadata.embeddingModel}`);
+        const o = run.metrics.overall;
+        console.log(`  Overall — hit@1: ${(o.hit1 * 100).toFixed(1)}%  hit@5: ${(o.hit5 * 100).toFixed(1)}%  MRR@10: ${o.mrr10.toFixed(4)}`);
+        for (const category of ['identifier', 'behaviour', 'concept']) {
+            const m = run.metrics.byCategory[category];
+            if (m)
+                console.log(`  ${category.padEnd(10)} — hit@1: ${(m.hit1 * 100).toFixed(1)}%  hit@5: ${(m.hit5 * 100).toFixed(1)}%  MRR@10: ${m.mrr10.toFixed(4)}  (${m.count})`);
+        }
+        if (run.invalid.length > 0) {
+            console.log(`\nInvalid cases:`);
+            for (const c of run.invalid)
+                console.log(`  ${c.id}: ${c.reason} — ${c.invalidExpects.map(e => e.file).join(', ')}`);
+        }
+        if (run.warnings.length > 0) {
+            console.log(`\nWarnings (scored on remaining valid answers):`);
+            for (const w of run.warnings)
+                console.log(`  ${w.id}: dropped ${w.droppedExpects.map(e => e.file).join(', ')}`);
+        }
+    }
+    printComparison(baselinePath, cmp) {
+        console.log(`\nComparison against ${baselinePath}:`);
+        if (cmp.conditionWarnings.length > 0) {
+            for (const w of cmp.conditionWarnings)
+                console.log(`  ⚠ ${w}`);
+        }
+        const sign = (n) => (n >= 0 ? '+' : '') + n.toFixed(4);
+        console.log(`  MRR@10: ${cmp.overall.mrr10.baseline.toFixed(4)} → ${cmp.overall.mrr10.current.toFixed(4)} (${sign(cmp.overall.mrr10.delta)})`);
+        console.log(`  hit@5:  ${(cmp.overall.hit5.baseline * 100).toFixed(1)}% → ${(cmp.overall.hit5.current * 100).toFixed(1)}%`);
+        if (cmp.hit5Lost.length > 0)
+            console.log(`  Lost hit@5: ${cmp.hit5Lost.join(', ')}`);
+        if (cmp.hit5Gained.length > 0)
+            console.log(`  Gained hit@5: ${cmp.hit5Gained.join(', ')}`);
+    }
+}
+exports.EvalCommand = EvalCommand;

package/dist/src/commands/IndexCommand.js

@@ -5,8 +5,17 @@ const interrupt_1 = require("../interrupt");
 const project_selector_1 = require("../project-selector");
 const graph_1 = require("../graph");
 const MonorepoAwareDiscoveryService_1 = require("../services/MonorepoAwareDiscoveryService");
+const project_scope_1 = require("../project-scope");
 const file_utils_1 = require("../file-utils");
 const legacy_ollama_index_1 = require("../services/legacy-ollama-index");
+/** `--project`'s index in `args`; the following token is its name unless absent or itself a flag. */
+function parseProjectFlag(args) {
+    const i = args.indexOf('--project');
+    if (i === -1)
+        return { present: false };
+    const next = args[i + 1];
+    return next !== undefined && !next.startsWith('-') ? { present: true, name: next } : { present: true };
+}
 class IndexCommand {
     container;
     argv1;
@@ -19,6 +28,42 @@ class IndexCommand {
         const args = process.argv.slice(this.argv1 === 'rag-index' ? 2 : 3);
         const force = args.includes('--reindex');
         const forceSelect = args.includes('--select');
+        const projectFlag = parseProjectFlag(args);
+        let discovered;
+        try {
+            discovered = discovery.discover(config.workspaceRoot);
+        }
+        catch (err) {
+            console.error(`\n${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        // Resolve --project before any database or embedding work, so a bad name
+        // (or a cancelled no-name prompt) has zero side effects.
+        let scanTargets;
+        if (projectFlag.present) {
+            let name = projectFlag.name;
+            if (name === undefined) {
+                if (discovered.length === 0) {
+                    console.error('\nNo projects available to select.');
+                    process.exitCode = 1;
+                    return;
+                }
+                name = await (0, project_selector_1.selectSingleProject)(discovered);
+                if (name === undefined) {
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            const { targets, notFound } = (0, project_scope_1.resolveProjectNames)([name], discovered);
+            if (notFound.length > 0) {
+                const available = (0, project_scope_1.listAvailableNames)(discovered).join(', ');
+                console.error(`\nProject '${notFound[0]}' not found. Available projects: ${available}`);
+                process.exitCode = 1;
+                return;
+            }
+            scanTargets = targets;
+        }
         await db.initDbWithSchema();
         // A former Ollama installation the config layer cannot recognise (old
         // defaults, no `embedding`/`ollama` block) is protected here: without an
@@ -43,33 +88,21 @@ class IndexCommand {
                 return;
             }
         }
-        const discovered = discovery.discover(config.workspaceRoot);
-        const selected = await new project_selector_1.ProjectSelector(config.workspaceRoot).select(discovered, forceSelect);
-        if (selected.length === 0)
-            return;
-        // Expand any selected nested-monorepo unit (e.g. an Nx repo) into its
-        // sub-projects; ordinary projects pass through unchanged.
-        const projects = (0, MonorepoAwareDiscoveryService_1.toLeafProjects)(selected);
-        // A project indexed before member extraction mixes old-format rows (no
-        // members, bare calleeSymbol) with new ones if left to an incremental run.
-        // Refuse before any backend readiness check, Docker command, or schema
-        // work — the same pattern as the legacy-Ollama guard above.
-        if (!force) {
-            let outdated;
-            try {
-                outdated = await db.listOutdatedProjects(projects.map(p => p.name));
-            }
-            catch (err) {
-                console.error(`\n${err.message}`);
-                process.exitCode = 1;
-                return;
-            }
-            if (outdated.length > 0) {
-                console.error(`\nIndexed before member indexing: ${[...outdated].sort().join(', ')} — run \`rag-index --reindex\`.`);
-                process.exitCode = 1;
+        let projects;
+        if (scanTargets) {
+            projects = scanTargets;
+        }
+        else {
+            const selected = await new project_selector_1.ProjectSelector(config.workspaceRoot).select(discovered, forceSelect);
+            if (selected.length === 0)
                 return;
-            }
+            // Expand any selected nested-monorepo unit (e.g. an Nx repo) into its
+            // sub-projects; ordinary projects pass through unchanged.
+            projects = (0, MonorepoAwareDiscoveryService_1.toLeafProjects)(selected);
         }
+        // The post-index graph always reflects the full workspace, regardless of
+        // what this run actually scanned.
+        const fullLeafProjects = (0, MonorepoAwareDiscoveryService_1.toLeafProjects)(discovered);
         // Ensure the local model is served (Infinity only — no-op for cloud), then
         // resolve the active embedding dimension and reconcile it with index_meta
         // (recreate code_chunk on a dimension change, clear rows on a model change)
@@ -87,39 +120,32 @@ class IndexCommand {
         const controller = new AbortController();
         const teardown = (0, interrupt_1.setupInterrupt)(controller);
         try {
-            let pruneResult;
-            try {
-                pruneResult = await indexer.pruneProjects(projects.map(p => p.name));
-            }
-            catch (err) {
-                console.error(`\nPruning failed: ${err.message}`);
-                process.exitCode = 1;
-                return;
-            }
-            const { removed, failed } = pruneResult;
-            for (const name of removed) {
-                console.log(`Removed project ${name} (not selected)`);
-            }
-            if (failed.length > 0) {
-                process.exitCode = 1;
+            // --project bypasses pruning entirely — it promises "touch only this
+            // project," so nothing outside the resolved target(s) is ever removed.
+            if (!scanTargets) {
+                let pruneResult;
+                try {
+                    pruneResult = await indexer.pruneProjects(projects.map(p => p.name));
+                }
+                catch (err) {
+                    console.error(`\nPruning failed: ${err.message}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                const { removed, failed } = pruneResult;
+                for (const name of removed) {
+                    console.log(`Removed project ${name} (not selected)`);
+                }
+                if (failed.length > 0) {
+                    process.exitCode = 1;
+                }
             }
             const filesPerProject = projects.map(p => (0, file_utils_1.collectFiles)(p.path, (0, file_utils_1.loadIgnore)(p.path), p.path));
             const totalFiles = filesPerProject.reduce((sum, f) => sum + f.length, 0);
             console.log(`\n${projects.length} projects — ${totalFiles} files total`);
             if (force)
                 console.log('Reindex mode: all files will be re-indexed.');
-            const allStats = [];
-            for (let i = 0; i < projects.length; i++) {
-                if (controller.signal.aborted)
-                    break;
-                const stats = await indexer.scanAndIndex(projects[i].path, projects[i].name, force, controller.signal, filesPerProject[i], { rootTsConfigPath: projects[i].rootTsConfigPath ?? undefined });
-                allStats.push(stats);
-                const remaining = projects.length - allStats.length;
-                if (remaining > 0 && !controller.signal.aborted) {
-                    const leftFiles = filesPerProject.slice(allStats.length).reduce((sum, f) => sum + f.length, 0);
-                    console.log(`  ${allStats.length}/${projects.length} projects — done in ${stats.elapsedSec}s — ${leftFiles} files left`);
-                }
-            }
+            const allStats = await indexer.scanProjects(projects, force, controller.signal, filesPerProject);
             if (controller.signal.aborted)
                 console.log('\nIndexing interrupted.');
             this.printSummary(allStats);
@@ -130,7 +156,7 @@ class IndexCommand {
                 try {
                     // Real import edges (code_dependency, just written) → intra-repo graph links.
                     const projectEdges = await searcher.getProjectEdges();
-                    (0, graph_1.generateProjectGraph)(projects, projectEdges, config.workspaceRoot);
+                    (0, graph_1.generateProjectGraph)(fullLeafProjects, projectEdges, config.workspaceRoot);
                 }
                 catch (err) {
                     console.error(`  ⚠ Could not build project graph: ${err.message}`);

package/dist/src/db/index.d.ts

@@ -1,2 +1,2 @@
-export { codeChunk, codeDependency, codeSymbol, codeCall, indexMeta, symbolIndexVersion } from './schema';
+export { codeChunk, codeDependency, codeSymbol, codeCall, indexMeta } from './schema';
 export type { CodeChunkInsert } from './schema';

package/dist/src/db/index.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.symbolIndexVersion = exports.indexMeta = exports.codeCall = exports.codeSymbol = exports.codeDependency = exports.codeChunk = void 0;
+exports.indexMeta = exports.codeCall = exports.codeSymbol = exports.codeDependency = exports.codeChunk = void 0;
 var schema_1 = require("./schema");
 Object.defineProperty(exports, "codeChunk", { enumerable: true, get: function () { return schema_1.codeChunk; } });
 Object.defineProperty(exports, "codeDependency", { enumerable: true, get: function () { return schema_1.codeDependency; } });
 Object.defineProperty(exports, "codeSymbol", { enumerable: true, get: function () { return schema_1.codeSymbol; } });
 Object.defineProperty(exports, "codeCall", { enumerable: true, get: function () { return schema_1.codeCall; } });
 Object.defineProperty(exports, "indexMeta", { enumerable: true, get: function () { return schema_1.indexMeta; } });
-Object.defineProperty(exports, "symbolIndexVersion", { enumerable: true, get: function () { return schema_1.symbolIndexVersion; } });