@code-rag/core 0.1.6 → 0.1.8

package/dist/api-contracts/index.d.ts

@@ -0,0 +1,2 @@
+export { PaginationMetaSchema, ChunkSummarySchema, ChunkDetailSchema, GraphNodeSchema, GraphEdgeSchema, ViewerSearchResultSchema, EmbeddingPointSchema, ViewerStatsResponseSchema, ViewerChunksResponseSchema, ViewerChunkDetailResponseSchema, ViewerSearchResponseSchema, ViewerGraphResponseSchema, ViewerEmbeddingsResponseSchema, } from './viewer-contracts.js';
+export type { PaginationMeta as ViewerPaginationMeta, ChunkSummary as ViewerChunkSummary, ChunkDetail as ViewerChunkDetail, ViewerGraphNode, ViewerGraphEdge, ViewerSearchResult as ViewerSearchResultType, EmbeddingPoint as ViewerEmbeddingPoint, ViewerStatsResponse, ViewerChunksResponse, ViewerChunkDetailResponse, ViewerSearchResponse, ViewerGraphResponse, ViewerEmbeddingsResponse, } from './viewer-contracts.js';

package/dist/api-contracts/index.js

@@ -0,0 +1,5 @@
+export { 
+// Sub-schemas
+PaginationMetaSchema, ChunkSummarySchema, ChunkDetailSchema, GraphNodeSchema, GraphEdgeSchema, ViewerSearchResultSchema, EmbeddingPointSchema, 
+// Endpoint response schemas
+ViewerStatsResponseSchema, ViewerChunksResponseSchema, ViewerChunkDetailResponseSchema, ViewerSearchResponseSchema, ViewerGraphResponseSchema, ViewerEmbeddingsResponseSchema, } from './viewer-contracts.js';

package/dist/api-contracts/viewer-contracts.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Shared Zod schemas for the Viewer REST API contract.
+ *
+ * These schemas define the exact JSON shape that the api-server sends
+ * and the viewer client receives. Both packages import these schemas so
+ * that any drift between server responses and client expectations is
+ * caught at compile time (type mismatch) or runtime (schema.parse()).
+ *
+ * Every schema here models the **wire format** including the `{ data }` envelope.
+ */
+import { z } from 'zod';
+/** Pagination metadata returned alongside list endpoints. */
+export declare const PaginationMetaSchema: z.ZodObject<{
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+    total: z.ZodNumber;
+    totalPages: z.ZodNumber;
+}, z.core.$strip>;
+/** A single chunk summary as returned by GET /chunks. */
+export declare const ChunkSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    filePath: z.ZodString;
+    chunkType: z.ZodString;
+    name: z.ZodString;
+    language: z.ZodString;
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+    contentPreview: z.ZodString;
+}, z.core.$strip>;
+/** Full chunk detail as returned by GET /chunks/:id. */
+export declare const ChunkDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    filePath: z.ZodString;
+    chunkType: z.ZodString;
+    name: z.ZodString;
+    language: z.ZodString;
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+    content: z.ZodString;
+    nlSummary: z.ZodString;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    vector: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+/** Graph node as returned by the dependency-graph module.
+ *  Uses z.string() for `type` because the actual types in practice extend beyond
+ *  the core GraphNode union (e.g., 'interface' from AST chunker). TypeScript
+ *  constrains the allowed values at compile time; Zod validates the wire shape. */
+export declare const GraphNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    filePath: z.ZodString;
+    symbols: z.ZodArray<z.ZodString>;
+    type: z.ZodString;
+}, z.core.$strip>;
+/** Graph edge as returned by the dependency-graph module.
+ *  Uses z.string() for `type` for the same forward-compatibility reason. */
+export declare const GraphEdgeSchema: z.ZodObject<{
+    source: z.ZodString;
+    target: z.ZodString;
+    type: z.ZodString;
+}, z.core.$strip>;
+/** A single search result as returned by GET /search. */
+export declare const ViewerSearchResultSchema: z.ZodObject<{
+    chunkId: z.ZodString;
+    filePath: z.ZodString;
+    chunkType: z.ZodString;
+    name: z.ZodString;
+    content: z.ZodString;
+    nlSummary: z.ZodString;
+    score: z.ZodNumber;
+    method: z.ZodString;
+}, z.core.$strip>;
+/** A single embedding point as returned by GET /embeddings. */
+export declare const EmbeddingPointSchema: z.ZodObject<{
+    id: z.ZodString;
+    filePath: z.ZodString;
+    chunkType: z.ZodString;
+    language: z.ZodString;
+    vector: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+/** GET /api/v1/viewer/stats */
+export declare const ViewerStatsResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        chunkCount: z.ZodNumber;
+        fileCount: z.ZodNumber;
+        languages: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        storageBytes: z.ZodNullable<z.ZodNumber>;
+        lastIndexed: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** GET /api/v1/viewer/chunks */
+export declare const ViewerChunksResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        filePath: z.ZodString;
+        chunkType: z.ZodString;
+        name: z.ZodString;
+        language: z.ZodString;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        contentPreview: z.ZodString;
+    }, z.core.$strip>>;
+    meta: z.ZodObject<{
+        page: z.ZodNumber;
+        pageSize: z.ZodNumber;
+        total: z.ZodNumber;
+        totalPages: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** GET /api/v1/viewer/chunks/:id */
+export declare const ViewerChunkDetailResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        id: z.ZodString;
+        filePath: z.ZodString;
+        chunkType: z.ZodString;
+        name: z.ZodString;
+        language: z.ZodString;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        content: z.ZodString;
+        nlSummary: z.ZodString;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        vector: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** GET /api/v1/viewer/search */
+export declare const ViewerSearchResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        results: z.ZodArray<z.ZodObject<{
+            chunkId: z.ZodString;
+            filePath: z.ZodString;
+            chunkType: z.ZodString;
+            name: z.ZodString;
+            content: z.ZodString;
+            nlSummary: z.ZodString;
+            score: z.ZodNumber;
+            method: z.ZodString;
+        }, z.core.$strip>>;
+        timing: z.ZodObject<{
+            totalMs: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** GET /api/v1/viewer/graph */
+export declare const ViewerGraphResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        nodes: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            filePath: z.ZodString;
+            symbols: z.ZodArray<z.ZodString>;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+        edges: z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            target: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** GET /api/v1/viewer/embeddings */
+export declare const ViewerEmbeddingsResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        filePath: z.ZodString;
+        chunkType: z.ZodString;
+        language: z.ZodString;
+        vector: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PaginationMeta = z.infer<typeof PaginationMetaSchema>;
+export type ChunkSummary = z.infer<typeof ChunkSummarySchema>;
+export type ChunkDetail = z.infer<typeof ChunkDetailSchema>;
+export type ViewerGraphNode = z.infer<typeof GraphNodeSchema>;
+export type ViewerGraphEdge = z.infer<typeof GraphEdgeSchema>;
+export type ViewerSearchResult = z.infer<typeof ViewerSearchResultSchema>;
+export type EmbeddingPoint = z.infer<typeof EmbeddingPointSchema>;
+export type ViewerStatsResponse = z.infer<typeof ViewerStatsResponseSchema>;
+export type ViewerChunksResponse = z.infer<typeof ViewerChunksResponseSchema>;
+export type ViewerChunkDetailResponse = z.infer<typeof ViewerChunkDetailResponseSchema>;
+export type ViewerSearchResponse = z.infer<typeof ViewerSearchResponseSchema>;
+export type ViewerGraphResponse = z.infer<typeof ViewerGraphResponseSchema>;
+export type ViewerEmbeddingsResponse = z.infer<typeof ViewerEmbeddingsResponseSchema>;

package/dist/api-contracts/viewer-contracts.js

@@ -0,0 +1,124 @@
+/**
+ * Shared Zod schemas for the Viewer REST API contract.
+ *
+ * These schemas define the exact JSON shape that the api-server sends
+ * and the viewer client receives. Both packages import these schemas so
+ * that any drift between server responses and client expectations is
+ * caught at compile time (type mismatch) or runtime (schema.parse()).
+ *
+ * Every schema here models the **wire format** including the `{ data }` envelope.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Reusable sub-schemas
+// ---------------------------------------------------------------------------
+/** Pagination metadata returned alongside list endpoints. */
+export const PaginationMetaSchema = z.object({
+    page: z.number().int(),
+    pageSize: z.number().int(),
+    total: z.number().int(),
+    totalPages: z.number().int(),
+});
+/** A single chunk summary as returned by GET /chunks. */
+export const ChunkSummarySchema = z.object({
+    id: z.string(),
+    filePath: z.string(),
+    chunkType: z.string(),
+    name: z.string(),
+    language: z.string(),
+    startLine: z.number().int(),
+    endLine: z.number().int(),
+    contentPreview: z.string(),
+});
+/** Full chunk detail as returned by GET /chunks/:id. */
+export const ChunkDetailSchema = z.object({
+    id: z.string(),
+    filePath: z.string(),
+    chunkType: z.string(),
+    name: z.string(),
+    language: z.string(),
+    startLine: z.number().int(),
+    endLine: z.number().int(),
+    content: z.string(),
+    nlSummary: z.string(),
+    metadata: z.record(z.string(), z.unknown()),
+    vector: z.array(z.number()).optional(),
+});
+/** Graph node as returned by the dependency-graph module.
+ *  Uses z.string() for `type` because the actual types in practice extend beyond
+ *  the core GraphNode union (e.g., 'interface' from AST chunker). TypeScript
+ *  constrains the allowed values at compile time; Zod validates the wire shape. */
+export const GraphNodeSchema = z.object({
+    id: z.string(),
+    filePath: z.string(),
+    symbols: z.array(z.string()),
+    type: z.string(),
+});
+/** Graph edge as returned by the dependency-graph module.
+ *  Uses z.string() for `type` for the same forward-compatibility reason. */
+export const GraphEdgeSchema = z.object({
+    source: z.string(),
+    target: z.string(),
+    type: z.string(),
+});
+/** A single search result as returned by GET /search. */
+export const ViewerSearchResultSchema = z.object({
+    chunkId: z.string(),
+    filePath: z.string(),
+    chunkType: z.string(),
+    name: z.string(),
+    content: z.string(),
+    nlSummary: z.string(),
+    score: z.number(),
+    method: z.string(),
+});
+/** A single embedding point as returned by GET /embeddings. */
+export const EmbeddingPointSchema = z.object({
+    id: z.string(),
+    filePath: z.string(),
+    chunkType: z.string(),
+    language: z.string(),
+    vector: z.array(z.number()),
+});
+// ---------------------------------------------------------------------------
+// Endpoint response schemas (full wire shape including envelope)
+// ---------------------------------------------------------------------------
+/** GET /api/v1/viewer/stats */
+export const ViewerStatsResponseSchema = z.object({
+    data: z.object({
+        chunkCount: z.number().int(),
+        fileCount: z.number().int(),
+        languages: z.record(z.string(), z.number()),
+        storageBytes: z.number().nullable(),
+        lastIndexed: z.string().nullable(),
+    }),
+});
+/** GET /api/v1/viewer/chunks */
+export const ViewerChunksResponseSchema = z.object({
+    data: z.array(ChunkSummarySchema),
+    meta: PaginationMetaSchema,
+});
+/** GET /api/v1/viewer/chunks/:id */
+export const ViewerChunkDetailResponseSchema = z.object({
+    data: ChunkDetailSchema,
+});
+/** GET /api/v1/viewer/search */
+export const ViewerSearchResponseSchema = z.object({
+    data: z.object({
+        results: z.array(ViewerSearchResultSchema),
+        timing: z.object({
+            totalMs: z.number(),
+        }),
+    }),
+});
+/** GET /api/v1/viewer/graph */
+export const ViewerGraphResponseSchema = z.object({
+    data: z.object({
+        nodes: z.array(GraphNodeSchema),
+        edges: z.array(GraphEdgeSchema),
+    }),
+});
+/** GET /api/v1/viewer/embeddings */
+export const ViewerEmbeddingsResponseSchema = z.object({
+    data: z.array(EmbeddingPointSchema),
+});

package/dist/benchmarks/benchmark-evaluator.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Benchmark evaluator that runs auto-generated queries through CodeRAG search
+ * and computes IR metrics by comparing results to ground truth.
+ *
+ * Uses the portable IR metrics from @code-rag/benchmarks where possible,
+ * but also includes a standalone implementation to avoid cross-package
+ * dependency (core should not depend on benchmarks).
+ */
+import { type Result } from 'neverthrow';
+import type { GeneratedQuery, BenchmarkQueryType } from './query-generator.js';
+/** Result of evaluating a single query. */
+export interface QueryEvalResult {
+    readonly query: string;
+    readonly queryType: BenchmarkQueryType;
+    readonly retrievedIds: readonly string[];
+    readonly expectedIds: readonly string[];
+    readonly metrics: QueryMetrics;
+}
+/** Metrics for a single query. */
+export interface QueryMetrics {
+    readonly precisionAt5: number;
+    readonly precisionAt10: number;
+    readonly recallAt10: number;
+    readonly mrr: number;
+    readonly ndcgAt10: number;
+}
+/** Aggregate metrics across all queries. */
+export interface AggregateEvalMetrics {
+    readonly precisionAt5: number;
+    readonly precisionAt10: number;
+    readonly recallAt10: number;
+    readonly mrr: number;
+    readonly ndcgAt10: number;
+    readonly queryCount: number;
+}
+/** Breakdown of metrics per query type. */
+export interface QueryTypeBreakdown {
+    readonly queryType: BenchmarkQueryType;
+    readonly metrics: AggregateEvalMetrics;
+}
+/** Full benchmark report. */
+export interface BenchmarkReport {
+    readonly aggregate: AggregateEvalMetrics;
+    readonly byQueryType: readonly QueryTypeBreakdown[];
+    readonly perQuery: readonly QueryEvalResult[];
+    readonly metadata: BenchmarkMetadata;
+}
+/** Metadata about the benchmark run. */
+export interface BenchmarkMetadata {
+    readonly timestamp: string;
+    readonly totalQueries: number;
+    readonly totalChunksInIndex: number;
+    readonly durationMs: number;
+}
+export declare class BenchmarkEvalError extends Error {
+    constructor(message: string);
+}
+/** A function that performs search and returns ordered chunk IDs. */
+export type SearchFn = (query: string) => Promise<readonly string[]>;
+/**
+ * Compute metrics for a single query result.
+ */
+export declare function computeQueryMetrics(retrieved: readonly string[], expected: readonly string[]): QueryMetrics;
+/**
+ * Compute aggregate metrics by averaging per-query metrics.
+ */
+export declare function computeAggregateMetrics(results: readonly QueryEvalResult[]): AggregateEvalMetrics;
+/**
+ * Group results by query type and compute per-type aggregates.
+ */
+export declare function computeQueryTypeBreakdown(results: readonly QueryEvalResult[]): readonly QueryTypeBreakdown[];
+/** Progress callback for benchmark evaluation. */
+export type BenchmarkProgressFn = (completed: number, total: number) => void;
+/**
+ * Run the full benchmark evaluation.
+ *
+ * For each generated query, calls the search function and computes metrics
+ * by comparing retrieved chunk IDs to the ground-truth expected IDs.
+ */
+export declare function runBenchmark(queries: readonly GeneratedQuery[], searchFn: SearchFn, totalChunksInIndex: number, onProgress?: BenchmarkProgressFn): Promise<Result<BenchmarkReport, BenchmarkEvalError>>;
+/**
+ * Format a BenchmarkReport as a human-readable summary table string.
+ */
+export declare function formatBenchmarkSummary(report: BenchmarkReport): string;

package/dist/benchmarks/benchmark-evaluator.js

@@ -0,0 +1,220 @@
+/**
+ * Benchmark evaluator that runs auto-generated queries through CodeRAG search
+ * and computes IR metrics by comparing results to ground truth.
+ *
+ * Uses the portable IR metrics from @code-rag/benchmarks where possible,
+ * but also includes a standalone implementation to avoid cross-package
+ * dependency (core should not depend on benchmarks).
+ */
+import { ok, err } from 'neverthrow';
+export class BenchmarkEvalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BenchmarkEvalError';
+    }
+}
+// --- Standalone IR metric functions (no external dependency) ---
+function precisionAtK(retrieved, relevant, k) {
+    if (k <= 0 || retrieved.length === 0)
+        return 0;
+    const topK = retrieved.slice(0, k);
+    let hits = 0;
+    for (const item of topK) {
+        if (relevant.has(item))
+            hits++;
+    }
+    return hits / k;
+}
+function recallAtK(retrieved, relevant, k) {
+    if (k <= 0 || relevant.size === 0)
+        return 0;
+    const topK = retrieved.slice(0, k);
+    let hits = 0;
+    for (const item of topK) {
+        if (relevant.has(item))
+            hits++;
+    }
+    return hits / relevant.size;
+}
+function mrr(retrieved, relevant) {
+    for (let i = 0; i < retrieved.length; i++) {
+        const item = retrieved[i];
+        if (item !== undefined && relevant.has(item)) {
+            return 1 / (i + 1);
+        }
+    }
+    return 0;
+}
+function ndcgAtK(retrieved, relevant, k) {
+    if (k <= 0 || relevant.size === 0)
+        return 0;
+    const topK = retrieved.slice(0, k);
+    let dcg = 0;
+    for (let i = 0; i < topK.length; i++) {
+        const item = topK[i];
+        if (item !== undefined && relevant.has(item)) {
+            dcg += 1 / Math.log2(i + 2);
+        }
+    }
+    const idealCount = Math.min(relevant.size, k);
+    let idcg = 0;
+    for (let i = 0; i < idealCount; i++) {
+        idcg += 1 / Math.log2(i + 2);
+    }
+    if (idcg === 0)
+        return 0;
+    return dcg / idcg;
+}
+/**
+ * Compute metrics for a single query result.
+ */
+export function computeQueryMetrics(retrieved, expected) {
+    const relevantSet = new Set(expected);
+    return {
+        precisionAt5: precisionAtK(retrieved, relevantSet, 5),
+        precisionAt10: precisionAtK(retrieved, relevantSet, 10),
+        recallAt10: recallAtK(retrieved, relevantSet, 10),
+        mrr: mrr(retrieved, relevantSet),
+        ndcgAt10: ndcgAtK(retrieved, relevantSet, 10),
+    };
+}
+/**
+ * Compute aggregate metrics by averaging per-query metrics.
+ */
+export function computeAggregateMetrics(results) {
+    if (results.length === 0) {
+        return {
+            precisionAt5: 0,
+            precisionAt10: 0,
+            recallAt10: 0,
+            mrr: 0,
+            ndcgAt10: 0,
+            queryCount: 0,
+        };
+    }
+    let sumP5 = 0;
+    let sumP10 = 0;
+    let sumR10 = 0;
+    let sumMrr = 0;
+    let sumNdcg = 0;
+    for (const result of results) {
+        sumP5 += result.metrics.precisionAt5;
+        sumP10 += result.metrics.precisionAt10;
+        sumR10 += result.metrics.recallAt10;
+        sumMrr += result.metrics.mrr;
+        sumNdcg += result.metrics.ndcgAt10;
+    }
+    const count = results.length;
+    return {
+        precisionAt5: sumP5 / count,
+        precisionAt10: sumP10 / count,
+        recallAt10: sumR10 / count,
+        mrr: sumMrr / count,
+        ndcgAt10: sumNdcg / count,
+        queryCount: count,
+    };
+}
+/**
+ * Group results by query type and compute per-type aggregates.
+ */
+export function computeQueryTypeBreakdown(results) {
+    const groups = new Map();
+    for (const result of results) {
+        const existing = groups.get(result.queryType);
+        if (existing) {
+            existing.push(result);
+        }
+        else {
+            groups.set(result.queryType, [result]);
+        }
+    }
+    const breakdowns = [];
+    for (const [queryType, groupResults] of groups) {
+        breakdowns.push({
+            queryType,
+            metrics: computeAggregateMetrics(groupResults),
+        });
+    }
+    // Sort by query type for consistent output
+    breakdowns.sort((a, b) => a.queryType.localeCompare(b.queryType));
+    return breakdowns;
+}
+/**
+ * Run the full benchmark evaluation.
+ *
+ * For each generated query, calls the search function and computes metrics
+ * by comparing retrieved chunk IDs to the ground-truth expected IDs.
+ */
+export async function runBenchmark(queries, searchFn, totalChunksInIndex, onProgress) {
+    try {
+        const startTime = Date.now();
+        const perQuery = [];
+        for (let i = 0; i < queries.length; i++) {
+            const query = queries[i];
+            const retrievedIds = await searchFn(query.query);
+            const metrics = computeQueryMetrics(retrievedIds, query.expectedChunkIds);
+            perQuery.push({
+                query: query.query,
+                queryType: query.queryType,
+                retrievedIds,
+                expectedIds: query.expectedChunkIds,
+                metrics,
+            });
+            if (onProgress) {
+                onProgress(i + 1, queries.length);
+            }
+        }
+        const durationMs = Date.now() - startTime;
+        const aggregate = computeAggregateMetrics(perQuery);
+        const byQueryType = computeQueryTypeBreakdown(perQuery);
+        return ok({
+            aggregate,
+            byQueryType,
+            perQuery,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                totalQueries: queries.length,
+                totalChunksInIndex,
+                durationMs,
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return err(new BenchmarkEvalError(`Benchmark evaluation failed: ${message}`));
+    }
+}
+/**
+ * Format a BenchmarkReport as a human-readable summary table string.
+ */
+export function formatBenchmarkSummary(report) {
+    const lines = [];
+    const a = report.aggregate;
+    lines.push('Benchmark Results');
+    lines.push('=================');
+    lines.push(`Queries: ${report.metadata.totalQueries}`);
+    lines.push(`Index size: ${report.metadata.totalChunksInIndex} chunks`);
+    lines.push(`Duration: ${(report.metadata.durationMs / 1000).toFixed(1)}s`);
+    lines.push('');
+    lines.push('Aggregate Metrics:');
+    lines.push(`  P@5:       ${fmt(a.precisionAt5)}`);
+    lines.push(`  P@10:      ${fmt(a.precisionAt10)}`);
+    lines.push(`  Recall@10: ${fmt(a.recallAt10)}`);
+    lines.push(`  MRR:       ${fmt(a.mrr)}`);
+    lines.push(`  nDCG@10:   ${fmt(a.ndcgAt10)}`);
+    if (report.byQueryType.length > 0) {
+        lines.push('');
+        lines.push('By Query Type:');
+        lines.push('  Type                 | Count |  P@5  | P@10  | R@10  |  MRR  | nDCG@10');
+        lines.push('  ---------------------|-------|-------|-------|-------|-------|--------');
+        for (const bt of report.byQueryType) {
+            const m = bt.metrics;
+            const type = bt.queryType.padEnd(20);
+            lines.push(`  ${type} | ${String(m.queryCount).padStart(5)} | ${fmt(m.precisionAt5)} | ${fmt(m.precisionAt10)} | ${fmt(m.recallAt10)} | ${fmt(m.mrr)} | ${fmt(m.ndcgAt10)}`);
+        }
+    }
+    return lines.join('\n');
+}
+function fmt(value) {
+    return value.toFixed(4).padStart(6);
+}

package/dist/benchmarks/index-scanner.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Scans an existing CodeRAG index (LanceDB) to extract entity information
+ * used for auto-generating benchmark queries with ground truth.
+ *
+ * All functions are pure where possible, taking data as input rather than
+ * connecting to stores directly.
+ */
+import { type Result } from 'neverthrow';
+import type { ChunkType } from '../types/chunk.js';
+import type { GraphEdge } from '../graph/dependency-graph.js';
+/** A scanned entity extracted from the index. */
+export interface ScannedEntity {
+    readonly chunkId: string;
+    readonly name: string;
+    readonly chunkType: ChunkType;
+    readonly filePath: string;
+    readonly language: string;
+    readonly nlSummary: string;
+    readonly imports: readonly string[];
+    readonly exports: readonly string[];
+    readonly declarations: readonly string[];
+}
+/** Result of scanning the full index. */
+export interface IndexScanResult {
+    readonly entities: readonly ScannedEntity[];
+    readonly totalChunks: number;
+    /** Map from chunkId to ScannedEntity for quick lookup. */
+    readonly entityMap: ReadonlyMap<string, ScannedEntity>;
+    /** Map from entity name to chunk IDs that declare it. */
+    readonly nameToChunkIds: ReadonlyMap<string, readonly string[]>;
+    /** Map from file path to chunk IDs in that file. */
+    readonly fileToChunkIds: ReadonlyMap<string, readonly string[]>;
+}
+export declare class IndexScanError extends Error {
+    constructor(message: string);
+}
+/**
+ * Convert raw index rows (from LanceDBStore.getAll()) into ScannedEntity objects.
+ * This is a pure function that operates on already-fetched data.
+ */
+export declare function parseIndexRows(rows: readonly {
+    id: string;
+    metadata: Record<string, unknown>;
+}[]): Result<IndexScanResult, IndexScanError>;
+/**
+ * Build a caller map from graph edges.
+ * Maps target chunkId to source chunkIds that reference it.
+ */
+export declare function buildCallerMap(edges: readonly GraphEdge[]): ReadonlyMap<string, readonly string[]>;
+/**
+ * Build a test file map: maps source file paths to test file chunk IDs.
+ * Heuristic: a file at `foo.test.ts` or `foo.spec.ts` is the test for `foo.ts`.
+ */
+export declare function buildTestMap(fileToChunkIds: ReadonlyMap<string, readonly string[]>): ReadonlyMap<string, readonly string[]>;