codesearch-mcp 0.2.1-alpha → 0.2.3-alpha

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

@@ -464,43 +464,19 @@ export declare const codeSymbol: import("drizzle-orm/pg-core").PgTableWithColumn
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-    };
-    dialect: "pg";
-}>;
-export declare const symbolIndexVersion: import("drizzle-orm/pg-core").PgTableWithColumns<{
-    name: "symbol_index_version";
-    schema: undefined;
-    columns: {
-        project: import("drizzle-orm/pg-core").PgColumn<{
-            name: "project";
-            tableName: "symbol_index_version";
+        target: import("drizzle-orm/pg-core").PgColumn<{
+            name: "target";
+            tableName: "code_symbol";
             dataType: "string";
             columnType: "PgText";
             data: string;
             driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        version: import("drizzle-orm/pg-core").PgColumn<{
-            name: "version";
-            tableName: "symbol_index_version";
-            dataType: "number";
-            columnType: "PgInteger";
-            data: number;
-            driverParam: string | number;
-            notNull: true;
+            notNull: false;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: undefined;
+            enumValues: [string, ...string[]];
             baseColumn: never;
             identity: undefined;
             generated: undefined;

package/dist/src/db/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.indexMeta = exports.codeCall = exports.symbolIndexVersion = exports.codeSymbol = exports.codeDependency = exports.codeChunk = void 0;
+exports.indexMeta = exports.codeCall = exports.codeSymbol = exports.codeDependency = exports.codeChunk = void 0;
 const pg_core_1 = require("drizzle-orm/pg-core");
 // NOTE: the `dimensions` literal below is nominal only. `dataType()` is invoked
 // solely by drizzle-kit DDL generation, which this project does not use — the
@@ -40,13 +40,7 @@ exports.codeSymbol = (0, pg_core_1.pgTable)('code_symbol', {
     col: (0, pg_core_1.integer)('col'),
     container: (0, pg_core_1.text)('container'),
     isStatic: (0, pg_core_1.boolean)('isStatic').notNull().default(false),
-});
-// Per-project marker of the symbol/call-graph row format. Not one of the four
-// index tables (see the `index-consistency` pruning requirement) — a project
-// with only a marker row is not "indexed" and is never pruned for it.
-exports.symbolIndexVersion = (0, pg_core_1.pgTable)('symbol_index_version', {
-    project: (0, pg_core_1.text)('project').primaryKey(),
-    version: (0, pg_core_1.integer)('version').notNull(),
+    target: (0, pg_core_1.text)('target'),
 });
 exports.codeCall = (0, pg_core_1.pgTable)('code_call', {
     id: (0, pg_core_1.uuid)('id').primaryKey().defaultRandom(),

package/dist/src/dependency-traversal.d.ts

@@ -0,0 +1,16 @@
+/** One edge in the traversal direction: forward (fromFile → toFile) for dependencies, backward for dependents. */
+export interface Edge {
+    from: string;
+    to: string;
+}
+export interface IndirectRow {
+    file: string;
+    depth: number;
+    via: string;
+}
+/**
+ * Breadth-first, one `neighbours` call per depth level. Each reachable file is expanded
+ * at most once; `via` ties within a level are broken by byte order, not call order.
+ * Does not catch — a rejecting `neighbours` call rejects the whole traversal.
+ */
+export declare function traverse(root: string, neighbours: (frontier: string[]) => Promise<Edge[]>, maxDepth?: number): Promise<IndirectRow[]>;

package/dist/src/dependency-traversal.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traverse = traverse;
+/** UTF-8 byte order (`COLLATE "C"`), not the platform locale or UTF-16 code-unit order. */
+function byteCompare(a, b) {
+    return Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+}
+/**
+ * Breadth-first, one `neighbours` call per depth level. Each reachable file is expanded
+ * at most once; `via` ties within a level are broken by byte order, not call order.
+ * Does not catch — a rejecting `neighbours` call rejects the whole traversal.
+ */
+async function traverse(root, neighbours, maxDepth = 20) {
+    const visited = new Map();
+    visited.set(root, 0);
+    const via = new Map();
+    let frontier = [root];
+    let depth = 1;
+    while (frontier.length > 0 && depth <= maxDepth) {
+        const edges = await neighbours(frontier);
+        const bestVia = new Map();
+        for (const edge of edges) {
+            if (visited.has(edge.to))
+                continue;
+            const current = bestVia.get(edge.to);
+            if (current === undefined || byteCompare(edge.from, current) < 0)
+                bestVia.set(edge.to, edge.from);
+        }
+        const next = [];
+        for (const [to, from] of bestVia) {
+            visited.set(to, depth);
+            via.set(to, from);
+            next.push(to);
+        }
+        frontier = next;
+        depth += 1;
+    }
+    const rows = [];
+    for (const [file, d] of visited) {
+        if (d >= 2)
+            rows.push({ file, depth: d, via: via.get(file) });
+    }
+    rows.sort((a, b) => a.depth - b.depth || byteCompare(a.file, b.file));
+    return rows;
+}

package/dist/src/enriched-prompt.d.ts

@@ -2,7 +2,8 @@ import type { ChunkPiece } from './interfaces/IChunker';
 import type { DepEdge, SymbolEntry } from './interfaces/IAstParser';
 /**
  * Build the embedding-input prompt for one chunk. `symbols` is the file's
- * top-level declarations only (never members) — the prompt is unaffected by
- * this change (see the `symbol-index-members` non-goal).
+ * top-level declarations only (never members) — the prompt-owner-line
+ * experiment measured adding members and an owner line and found neither met
+ * the required MRR@10 gain, so this stays the shipped prompt.
  */
 export declare function getEnrichedPrompt(piece: ChunkPiece, relPath: string, serviceName: string, edges: DepEdge[], symbols: SymbolEntry[]): string;

package/dist/src/enriched-prompt.js

@@ -61,8 +61,9 @@ function inferRole(relPath) {
 }
 /**
  * Build the embedding-input prompt for one chunk. `symbols` is the file's
- * top-level declarations only (never members) — the prompt is unaffected by
- * this change (see the `symbol-index-members` non-goal).
+ * top-level declarations only (never members) — the prompt-owner-line
+ * experiment measured adding members and an owner line and found neither met
+ * the required MRR@10 gain, so this stays the shipped prompt.
  */
 function getEnrichedPrompt(piece, relPath, serviceName, edges, symbols) {
     const chunkStart = piece.startLine;

package/dist/src/eval-results.d.ts

@@ -0,0 +1,12 @@
+import type { EvalResultFile, CompareResult } from './interfaces/IRetrievalEvaluator';
+/** `yyyy-mm-dd_hh-mm` in local time, matching the existing `benchmarks/results/` naming. */
+export declare function timestampSlug(date: Date): string;
+/** Writes the JSON + Markdown result files for one eval run; returns their paths. */
+export declare function writeResultFiles(resultsDir: string, suiteLabel: string, result: EvalResultFile, now: Date, comparison?: {
+    baselinePath: string;
+    result: CompareResult;
+}): {
+    jsonPath: string;
+    mdPath: string;
+};
+export declare function readResultFile(filePath: string): EvalResultFile;

package/dist/src/eval-results.js

@@ -0,0 +1,114 @@
+"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.timestampSlug = timestampSlug;
+exports.writeResultFiles = writeResultFiles;
+exports.readResultFile = readResultFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function pct(n) {
+    return `${(n * 100).toFixed(1)}%`;
+}
+function metricsRow(label, m) {
+    return `| ${label} | ${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)}) |`;
+}
+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)`);
+    }
+    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));
+    }
+    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(', ')} |`);
+    }
+    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) {
+        lines.push('', `## Comparison against ${comparison.baselinePath}`, '');
+        if (comparison.result.conditionWarnings.length > 0) {
+            lines.push('> ⚠ ' + comparison.result.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];
+            if (d)
+                lines.push(deltaRow(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 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 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 };
+}
+function readResultFile(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}

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

@@ -10,4 +10,19 @@ 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';
+};
+/**
+ * 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

@@ -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,27 @@ function loadIgnore(projectDir) {
     }
     return ig;
 }
+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]))
+        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 +117,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/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/interfaces/IAstParser.d.ts

@@ -6,7 +6,7 @@ export interface DepEdge {
     toSymbol: string | null;
     depType: string;
 }
-export type SymbolKind = 'function' | 'class' | 'interface' | 'type' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature';
+export type SymbolKind = 'function' | 'class' | 'interface' | 'type' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature' | 'graphql_query' | 'graphql_mutation' | 'graphql_subscription' | 'graphql_field' | 'graphql_type';
 export interface SymbolEntry {
     project: string;
     filePath: string;
@@ -19,6 +19,11 @@ export interface SymbolEntry {
     /** Dotted path of enclosing named scopes, outermost first; null for top-level declarations. */
     container: string | null;
     isStatic: boolean;
+    /**
+     * Qualified TypeScript name of the decorated declaration, set only on
+     * `graphql-symbols` rows (`graphqlNames`); null on every `symbols`/`members` entry.
+     */
+    target?: string | null;
     /**
      * Whether this declaration node has a body (vs. an overload signature).
      * Internal — used only to pick an overload set's representative row before
@@ -60,6 +65,13 @@ export interface FileAnalysis {
     calls: CallEdge[];
     /** Ownership ranges (decorator-inclusive) for every indexed declaration except `method_signature`. */
     ownerRanges?: OwnerRange[];
+    /**
+     * GraphQL-named rows (`@Query`/`@Mutation`/`@Subscription`/`@ResolveField`/
+     * `@ObjectType`/`@InputType`/`@InterfaceType` of `@nestjs/graphql`). Written to
+     * `code_symbol` alongside `symbols`/`members`; never fed to the chunker, the
+     * prompt, `buildOwnerRanges` or `extractCalls` (see `graphql-symbols`).
+     */
+    graphqlNames: SymbolEntry[];
 }
 export interface AnalyzeProjectOpts {
     skipDependencyResolution?: boolean;

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

@@ -41,18 +41,4 @@ export interface IDatabase {
     listIndexedProjects(): Promise<string[]>;
     /** Delete all rows for `name` from the four index tables in one transaction. */
     deleteProject(name: string): Promise<void>;
-    /** Every project with at least one row in `code_chunk` or `code_symbol` — the
-     * symbol/call-graph lookup scope (distinct from `listIndexedProjects`, which
-     * also covers `code_call`/`code_dependency`). */
-    listProjectsWithIndexRows(): Promise<string[]>;
-    /**
-     * Among `projectNames` (or every project with rows when null), those that
-     * are outdated: at least one row in `code_chunk`/`code_symbol` and a
-     * `symbol_index_version` below the current format version (missing row = 1).
-     * A missing `symbol_index_version` table counts as "no marker rows" for every
-     * project. Any other database error propagates.
-     */
-    listOutdatedProjects(projectNames: string[] | null): Promise<string[]>;
-    /** Upsert a project's `symbol_index_version` marker to the current format version. */
-    upsertSymbolIndexVersion(project: string): Promise<void>;
 }

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

@@ -0,0 +1,94 @@
+export type EvalCategory = 'identifier' | 'behaviour' | 'concept';
+export interface ExpectedAnswer {
+    file: string;
+    owner?: string;
+}
+export interface EvalCase {
+    id: string;
+    project: string;
+    category: EvalCategory;
+    query: string;
+    expect: ExpectedAnswer[];
+    threshold?: number;
+}
+export interface EvalSuite {
+    version: 1;
+    cases: EvalCase[];
+}
+export interface SearchHit {
+    filePath: string;
+    ownerPath: string | null;
+}
+export type SearchFn = (query: string, limit: number, project: string | null, threshold?: number) => Promise<SearchHit[]>;
+/** Index-inspection callbacks used to validate a case's expected answers before scoring. */
+export interface IndexInspector {
+    isFileIndexed(project: string, file: string): Promise<boolean>;
+    ownerPathsOfFile(project: string, file: string): Promise<string[]>;
+}
+export interface Metrics {
+    count: number;
+    hit1: number;
+    hit5: number;
+    mrr10: number;
+}
+export interface CaseResult {
+    id: string;
+    project: string;
+    category: EvalCategory;
+    query: string;
+    /** 1-based position of the first matching result within the top 10, null when unranked. */
+    rank: number | null;
+    matched: SearchHit | null;
+}
+export interface InvalidCase {
+    id: string;
+    reason: string;
+    invalidExpects: ExpectedAnswer[];
+}
+export interface PartialWarning {
+    id: string;
+    droppedExpects: ExpectedAnswer[];
+}
+export interface EvalRunResult {
+    cases: CaseResult[];
+    invalid: InvalidCase[];
+    warnings: PartialWarning[];
+    metrics: {
+        overall: Metrics;
+        byCategory: Partial<Record<EvalCategory, Metrics>>;
+    };
+}
+export interface IRetrievalEvaluator {
+    evaluate(suite: EvalSuite, search: SearchFn, inspect: IndexInspector): Promise<EvalRunResult>;
+}
+export interface ResultMetadata {
+    suitePath: string;
+    suiteHash: string;
+    embeddingProvider: string;
+    embeddingModel: string;
+    rerankerModel: string | null;
+    indexMeta: {
+        provider: string;
+        model: string;
+        dimensions: number;
+    } | null;
+    gitCommit: string;
+    timestamp: string;
+}
+export interface EvalResultFile {
+    metadata: ResultMetadata;
+    run: EvalRunResult;
+}
+export interface MetricDelta {
+    baseline: number;
+    current: number;
+    delta: number;
+}
+export type MetricsDelta = Record<keyof Metrics, MetricDelta>;
+export interface CompareResult {
+    overall: MetricsDelta;
+    byCategory: Partial<Record<EvalCategory, MetricsDelta>>;
+    hit5Gained: string[];
+    hit5Lost: string[];
+    conditionWarnings: string[];
+}

package/dist/src/interfaces/IRetrievalEvaluator.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,4 +1,4 @@
-import type { SearchResult, NeighborResult, GraphContext, DependencyRow, ProjectRow, GrepMatch, SymbolKind, SymbolHit, CallerRow, FileRangeResult } from '../services/SearcherService';
+import type { SearchResult, NeighborResult, GraphContext, DependencyRow, ProjectRow, SymbolKind, SymbolHit, CallerRow, FileRangeResult, ListFilesResult, GrepSymbolResult, ResolvedToolPath, PathFailure } from '../services/SearcherService';
 /**
  * Searcher abstraction — McpServer depends on this interface
  * rather than the concrete SearcherService.
@@ -14,27 +14,22 @@ export interface ISearcher {
         from: string;
         to: string;
     }[]>;
-    searchChunks(query: string, limit: number, project: string | null, threshold?: number): Promise<SearchResult[]>;
+    searchChunks(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean): Promise<SearchResult[]>;
     fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
     fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
-    getDependencies(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
-    getDependents(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependencies(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependents(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
     getCallers(symbol: string, project: string, calleeFile?: string | null): Promise<CallerRow[]>;
-    grepSymbol(symbol: string, project: string, excludeFile: string): Promise<{
-        matches: GrepMatch[];
-        truncated: boolean;
-    }>;
+    grepSymbol(symbol: string, rootDir: string, excludeFile: string): Promise<GrepSymbolResult>;
     findSymbol(name: string, project: string | null, kind: SymbolKind): Promise<{
         hits: SymbolHit[];
         truncated: boolean;
         grepFailed: boolean;
     }>;
-    /** One-line warning when a project in scope is outdated (see `SearcherService.outdatedNotice`), else null. */
-    outdatedNotice(project: string | null): Promise<string | null>;
-    listFiles(relativePath: string, project: string, depth: number, pattern: string | null): {
-        tree: string;
-        error?: string;
-    };
-    readFileAbsolute(absPath: string, maxLines: number): Promise<FileRangeResult>;
-    readFileRange(filePath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
+    listFiles(relPath: string, depth: number, pattern: string | null): Promise<ListFilesResult>;
+    readFile(relPath: string, maxLines: number): Promise<FileRangeResult>;
+    readFileRange(relPath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
+    resolveToolPath(input: string | null | undefined): Promise<ResolvedToolPath>;
+    checkGraphPath(relPath: string): Promise<PathFailure | null>;
+    fallbackRoot(relPath: string): string | null;
 }

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

@@ -6,3 +6,4 @@ export type { IDatabase } from './IDatabase';
 export type { ISearcher } from './ISearcher';
 export type { IProjectDiscovery, DiscoveredProject } from './IProjectDiscovery';
 export type { IMcpToolHandler, ToolDefinition, ToolResponse } from './IMcpToolHandler';
+export type { EvalCategory, ExpectedAnswer, EvalCase, EvalSuite, SearchHit, SearchFn, IndexInspector, Metrics, CaseResult, InvalidCase, PartialWarning, EvalRunResult, IRetrievalEvaluator, ResultMetadata, EvalResultFile, MetricDelta, MetricsDelta, CompareResult, } from './IRetrievalEvaluator';

package/dist/src/project-scope.d.ts

@@ -0,0 +1,19 @@
+import type { DiscoveredProject } from './interfaces';
+export interface ResolveProjectNamesResult {
+    targets: DiscoveredProject[];
+    notFound: string[];
+}
+/**
+ * Resolve one or more `--project`-style names against discovered units: a
+ * unit name expands to all of its children, a leaf name resolves to itself.
+ * Units are tried before leaves so a top-level project named the same as a
+ * nested-monorepo child's bare name can never shadow it. Targets are
+ * deduplicated by leaf name and ordered by first-resolving input name.
+ */
+export declare function resolveProjectNames(names: string[], units: DiscoveredProject[]): ResolveProjectNamesResult;
+/**
+ * Every name `--project` would accept as a match, in discovery order: each
+ * unit's own name, immediately followed by its expanded leaf names (an
+ * ordinary project — no children — contributes only its own name once).
+ */
+export declare function listAvailableNames(units: DiscoveredProject[]): string[];

package/dist/src/project-scope.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjectNames = resolveProjectNames;
+exports.listAvailableNames = listAvailableNames;
+const MonorepoAwareDiscoveryService_1 = require("./services/MonorepoAwareDiscoveryService");
+/**
+ * Resolve one or more `--project`-style names against discovered units: a
+ * unit name expands to all of its children, a leaf name resolves to itself.
+ * Units are tried before leaves so a top-level project named the same as a
+ * nested-monorepo child's bare name can never shadow it. Targets are
+ * deduplicated by leaf name and ordered by first-resolving input name.
+ */
+function resolveProjectNames(names, units) {
+    const leaves = (0, MonorepoAwareDiscoveryService_1.toLeafProjects)(units);
+    const targets = [];
+    const seen = new Set();
+    const notFound = [];
+    for (const name of names) {
+        const unit = units.find(u => u.name === name);
+        const matches = unit ? (0, MonorepoAwareDiscoveryService_1.toLeafProjects)([unit]) : [leaves.find(l => l.name === name)].filter((p) => p !== undefined);
+        if (matches.length === 0) {
+            notFound.push(name);
+            continue;
+        }
+        for (const leaf of matches) {
+            if (seen.has(leaf.name))
+                continue;
+            seen.add(leaf.name);
+            targets.push(leaf);
+        }
+    }
+    return { targets, notFound };
+}
+/**
+ * Every name `--project` would accept as a match, in discovery order: each
+ * unit's own name, immediately followed by its expanded leaf names (an
+ * ordinary project — no children — contributes only its own name once).
+ */
+function listAvailableNames(units) {
+    const names = [];
+    for (const unit of units) {
+        names.push(unit.name);
+        if (unit.children && unit.children.length > 0) {
+            for (const child of unit.children)
+                names.push(child.name);
+        }
+    }
+    return names;
+}