codesearch-mcp 0.3.0-alpha → 0.4.0-alpha

package/dist/src/retrieval-eval.js

@@ -8,8 +8,11 @@ exports.checkCaseCorpora = checkCaseCorpora;
 exports.mergeSuites = mergeSuites;
 exports.signTest = signTest;
 exports.pairedChange = pairedChange;
+exports.formatThresholdConditions = formatThresholdConditions;
 exports.compare = compare;
 const zod_1 = require("zod");
+const constants_1 = require("./constants");
+const eval_vector_index_1 = require("./eval-vector-index");
 const CATEGORIES = ['identifier', 'behaviour', 'concept'];
 exports.STAGE_ORDER = ['vector', 'reranked'];
 const STAGE_SOURCE = { reranked: 'vector' };
@@ -285,6 +288,13 @@ function runFigures(cases, stages, shortPool) {
         stageChanges: stageChangesOf(cases, stages),
     };
 }
+function distinctThresholds(pairs) {
+    const byKey = new Map(pairs.map(p => [`${p.value}|${p.source}`, p]));
+    return [...byKey.values()].sort((a, b) => b.value - a.value || a.source.localeCompare(b.source));
+}
+function formatThresholdConditions(pairs) {
+    return pairs.map(p => `${(0, constants_1.formatThreshold)(p.value)} (${p.source})`).join(', ') || '—';
+}
 class RetrievalEvaluator {
     async evaluate(suite, search, inspect, onCase) {
         await checkCaseCorpora(suite.cases, p => inspect.projectDir(p));
@@ -295,6 +305,7 @@ class RetrievalEvaluator {
         const fetchLimits = [];
         const efSearches = [];
         const iterativeScans = [];
+        const thresholds = [];
         let stages = null;
         const total = suite.cases.length;
         for (const [i, c] of suite.cases.entries()) {
@@ -334,6 +345,7 @@ class RetrievalEvaluator {
             fetchLimits.push(hits.fetchLimit);
             efSearches.push(hits.indexParams.efSearch);
             iterativeScans.push(hits.indexParams.iterativeScan);
+            thresholds.push(hits.threshold);
             report(result, null);
         }
         const runStages = stages ?? ['vector'];
@@ -347,6 +359,7 @@ class RetrievalEvaluator {
             fetchLimit: sortedDistinct(fetchLimits),
             efSearch: sortedDistinct(efSearches),
             iterativeScan: sortedDistinct(iterativeScans),
+            thresholds: distinctThresholds(thresholds),
         };
         return {
             run: {
@@ -393,8 +406,18 @@ function poolDelta(baseline, current) {
         short: poolValueDelta(baseline?.short ?? null, current.short),
     };
 }
+function isThresholdCondition(v) {
+    return typeof v === 'object' && v !== null && 'value' in v && 'source' in v;
+}
 function formatCondition(value) {
-    return Array.isArray(value) ? `[${value.map(v => (v === null ? 'not sent' : String(v))).join(', ')}]` : String(value);
+    if (!Array.isArray(value))
+        return String(value);
+    if (value.length > 0 && value.every(isThresholdCondition))
+        return `[${formatThresholdConditions(value)}]`;
+    return `[${value.map(v => (v === null ? 'not sent' : String(v))).join(', ')}]`;
+}
+function conditionKey(value) {
+    return JSON.stringify(Array.isArray(value) ? value.map(v => JSON.stringify(v)).sort() : value);
 }
 function corpusWarningsOf(b, cur) {
     const warnings = [];
@@ -426,6 +449,25 @@ function corpusWarningsOf(b, cur) {
         warnings.push(live('current run', cur.liveCases));
     return warnings;
 }
+function vectorIndexWarningsOf(b, cur) {
+    if (!b.vectorIndex || !cur.vectorIndex) {
+        return [...(b.vectorIndex ? [] : ['baseline records no vector index']), ...(cur.vectorIndex ? [] : ['current run records no vector index'])];
+    }
+    const warnings = [];
+    if (b.vectorIndex.pgvector !== cur.vectorIndex.pgvector) {
+        warnings.push(`pgvector differs: baseline ${b.vectorIndex.pgvector ?? 'not installed'} vs current ${cur.vectorIndex.pgvector ?? 'not installed'}`);
+    }
+    if (JSON.stringify(b.vectorIndex.indexes) !== JSON.stringify(cur.vectorIndex.indexes)) {
+        warnings.push(`vector index differs: baseline ${(0, eval_vector_index_1.formatIndexes)(b.vectorIndex)} vs current ${(0, eval_vector_index_1.formatIndexes)(cur.vectorIndex)}`);
+    }
+    const settings = [['hnsw.max_scan_tuples', 'maxScanTuples'], ['hnsw.scan_mem_multiplier', 'scanMemMultiplier']];
+    for (const [name, key] of settings) {
+        if (b.vectorIndex[key] !== cur.vectorIndex[key]) {
+            warnings.push(`${name} differs: baseline ${b.vectorIndex[key] ?? 'not defined'} vs current ${cur.vectorIndex[key] ?? 'not defined'}`);
+        }
+    }
+    return warnings;
+}
 function conditionWarningsOf(baseline, current) {
     const warnings = [];
     const b = baseline.metadata, cur = current.metadata;
@@ -450,11 +492,12 @@ function conditionWarningsOf(baseline, current) {
                 warnings.push(`search condition ${key} recorded only by the current run (${formatCondition(cc[key])})`);
             else if (!(key in cc))
                 warnings.push(`search condition ${key} recorded only by the baseline (${formatCondition(bc[key])})`);
-            else if (JSON.stringify(bc[key]) !== JSON.stringify(cc[key])) {
+            else if (conditionKey(bc[key]) !== conditionKey(cc[key])) {
                 warnings.push(`${key} differs: baseline ${formatCondition(bc[key])} vs current ${formatCondition(cc[key])}`);
             }
         }
     }
+    warnings.push(...vectorIndexWarningsOf(b, cur));
     warnings.push(...corpusWarningsOf(b, cur));
     if (baseline.run.rerankFailures > 0)
         warnings.push(`baseline has ${baseline.run.rerankFailures} rerank failure(s)`);

package/dist/src/search/CallGraph.d.ts

@@ -0,0 +1,9 @@
+import type { IDatabase, ILogger } from '../interfaces';
+import type { CallerRow, ICallGraph, NoCallersCause } from '../interfaces/ICallGraph';
+export declare class CallGraph implements ICallGraph {
+    private db;
+    private logger;
+    constructor(db: IDatabase, logger: ILogger);
+    getCallers(symbol: string, project: string, calleeFile?: string | null): Promise<CallerRow[]>;
+    explainNoCallers(symbol: string, project: string): Promise<NoCallersCause>;
+}

package/dist/src/search/CallGraph.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallGraph = void 0;
+const symbol_name_1 = require("../symbol-name");
+const symbol_sql_1 = require("./symbol-sql");
+const NO_CALLERS_LIST_LIMIT = 5;
+class CallGraph {
+    db;
+    logger;
+    constructor(db, logger) {
+        this.db = db;
+        this.logger = logger;
+    }
+    async getCallers(symbol, project, calleeFile = null) {
+        const t0 = Date.now();
+        this.logger.debug('CallGraph: getCallers', { symbol, project, calleeFile });
+        const parsed = (0, symbol_name_1.parseCallerSymbol)(symbol);
+        if (!parsed)
+            throw new Error('Invalid symbol name');
+        const params = [project];
+        let nameFilter;
+        if (parsed.form === 'bare') {
+            params.push(parsed.name);
+            nameFilter = `"calleeName" = $${params.length}`;
+        }
+        else {
+            params.push(`${parsed.container}.${parsed.name}`);
+            const exactParam = params.length;
+            params.push(`%.${(0, symbol_name_1.escapeLike)(parsed.container)}.${(0, symbol_name_1.escapeLike)(parsed.name)}`);
+            const suffixParam = params.length;
+            nameFilter = `("calleeSymbol" = $${exactParam} OR "calleeSymbol" LIKE $${suffixParam} ESCAPE '\\')`;
+        }
+        let fileFilter = '';
+        if (calleeFile) {
+            params.push(calleeFile);
+            fileFilter = `AND "calleeFile" = $${params.length}`;
+        }
+        const rows = await this.db.query(`SELECT "fromFile", "fromSymbol", "calleeName", "calleeFile", line
+       FROM code_call
+       WHERE project = $1 AND ${nameFilter}
+       ${fileFilter}
+       ORDER BY "fromFile", line
+       LIMIT 200`, params);
+        this.logger.debug('CallGraph: getCallers result', { count: rows.length, ms: Date.now() - t0 });
+        return rows;
+    }
+    async explainNoCallers(symbol, project) {
+        const t0 = Date.now();
+        const parsed = (0, symbol_name_1.parseCallerSymbol)(symbol);
+        if (!parsed)
+            throw new Error('Invalid symbol name');
+        const container = parsed.form === 'qualified' ? parsed.container : null;
+        try {
+            const calls = await this.db.query(`SELECT EXISTS (SELECT 1 FROM code_call WHERE project = $1) AS present`, [project]);
+            if (!calls[0]?.present)
+                return { kind: 'no-call-graph' };
+            const params = [project];
+            const match = (0, symbol_sql_1.symbolMatch)(parsed.name, container, params);
+            params.push(NO_CALLERS_LIST_LIMIT + 1);
+            const definitions = await this.db.query(`SELECT "filePath", line, qualified
+         FROM (
+           SELECT DISTINCT "filePath", line, ${symbol_sql_1.QUALIFIED_SQL} AS qualified${match.exactRank ? `, ${match.exactRank} AS exact_rank` : ''}
+           FROM code_symbol
+           WHERE project = $1 AND ${match.filter}
+         ) AS definitions
+         ORDER BY ${match.exactRank ? 'exact_rank, ' : ''}"filePath", line, qualified COLLATE "C"
+         LIMIT $${params.length}`, params);
+            if (definitions.length > 0) {
+                return {
+                    kind: 'no-recorded-calls',
+                    definitions: definitions.slice(0, NO_CALLERS_LIST_LIMIT).map(({ qualified, filePath, line }) => ({ qualified, filePath, line })),
+                    truncated: definitions.length > NO_CALLERS_LIST_LIMIT,
+                };
+            }
+            const { names, truncated } = await (0, symbol_sql_1.similarSymbolNames)(this.db, parsed.name, project, false);
+            return { kind: 'unknown-symbol', suggestions: names, truncated };
+        }
+        catch (err) {
+            this.logger.warn('CallGraph: explainNoCallers lookup failed', { err, symbol, project, ms: Date.now() - t0 });
+            return { kind: 'lookup-failed' };
+        }
+    }
+}
+exports.CallGraph = CallGraph;

package/dist/src/search/ChunkSearch.d.ts

@@ -0,0 +1,23 @@
+import type { Config } from '../config';
+import type { IDatabase, IEmbedder, ILogger } from '../interfaces';
+import type { IChunkSearch, NeighborResult, NoResultsCause, SearchResult, StagedSearchResult } from '../interfaces/IChunkSearch';
+import type { IndexIdentityGuard } from './IndexIdentityGuard';
+export declare class ChunkSearch implements IChunkSearch {
+    private db;
+    private embedder;
+    private identityGuard;
+    private config;
+    private logger;
+    private readonly gate;
+    private readonly fetcher;
+    private readonly rerankStage;
+    constructor(db: IDatabase, embedder: IEmbedder, identityGuard: IndexIdentityGuard, config: Config, logger: ILogger);
+    prepareQuery(raw: string): Promise<{
+        query: string;
+        translated: boolean;
+    }>;
+    searchChunks(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean, perFile?: number): Promise<SearchResult[]>;
+    searchChunksWithStages(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean, perFile?: number): Promise<StagedSearchResult>;
+    fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
+    explainNoResults(project: string | null): Promise<NoResultsCause>;
+}

package/dist/src/search/ChunkSearch.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChunkSearch = void 0;
+const result_shaping_1 = require("./result-shaping");
+const search_plan_1 = require("./chunks/search-plan");
+const IterativeScanGate_1 = require("./chunks/IterativeScanGate");
+const CandidateFetcher_1 = require("./chunks/CandidateFetcher");
+const RerankStage_1 = require("./chunks/RerankStage");
+const search_metrics_1 = require("./chunks/search-metrics");
+class ChunkSearch {
+    db;
+    embedder;
+    identityGuard;
+    config;
+    logger;
+    gate;
+    fetcher;
+    rerankStage;
+    constructor(db, embedder, identityGuard, config, logger) {
+        this.db = db;
+        this.embedder = embedder;
+        this.identityGuard = identityGuard;
+        this.config = config;
+        this.logger = logger;
+        this.gate = new IterativeScanGate_1.IterativeScanGate(db, logger);
+        this.fetcher = new CandidateFetcher_1.CandidateFetcher(db, this.gate);
+        this.rerankStage = new RerankStage_1.RerankStage(embedder, logger);
+    }
+    async prepareQuery(raw) {
+        return { query: raw, translated: false };
+    }
+    async searchChunks(query, limit, project, threshold, rerankOverride, perFile = result_shaping_1.DEFAULT_PER_FILE) {
+        const { stages } = await this.searchChunksWithStages(query, limit, project, threshold, rerankOverride, perFile);
+        return stages.reranked ?? stages.vector;
+    }
+    async searchChunksWithStages(query, limit, project, threshold, rerankOverride, perFile = result_shaping_1.DEFAULT_PER_FILE) {
+        const t0 = Date.now();
+        await this.identityGuard.assertIndexMatches();
+        const plan = (0, search_plan_1.planSearch)({ limit, perFile, threshold, rerankOverride, rerankAvailable: !!this.embedder.rerank }, this.config);
+        this.logger.debug('ChunkSearch: searchChunks', {
+            query: query.slice(0, 120), limit, fetchLimit: plan.fetchLimit, project, threshold: plan.threshold.value,
+        });
+        const tEmbed0 = Date.now();
+        const embedding = await this.embedder.embed(query, 'query');
+        const embedMs = Date.now() - tEmbed0;
+        const pool = await this.fetcher.fetch(embedding, plan, project);
+        this.logger.debug('ChunkSearch: searchChunks candidates', {
+            count: pool.candidates.length,
+            scores: pool.candidates.map(r => r.score),
+            files: pool.candidates.map(r => r.filePath),
+            ms: Date.now() - t0,
+        });
+        const vector = (0, result_shaping_1.limitPerFile)(pool.candidates, limit, perFile);
+        const rerank = plan.reranking ? await this.rerankStage.run(query, pool.candidates, vector, plan, t0) : undefined;
+        this.logger.info('search metrics', (0, search_metrics_1.searchMetrics)(query, {
+            fetchLimit: plan.fetchLimit, candidates: pool.candidates, results: rerank?.reranked ?? vector, poolSaturated: pool.poolSaturated, indexParams: pool.indexParams, threshold: plan.threshold,
+            embedMs, dbMs: pool.dbMs, rerankMs: rerank?.rerankMs ?? 0, totalMs: Date.now() - t0,
+        }));
+        return {
+            pool: pool.candidates,
+            stages: rerank ? { vector, reranked: rerank.reranked } : { vector },
+            rerankFailed: rerank?.rerankFailed ?? false,
+            fetchLimit: plan.fetchLimit,
+            indexParams: pool.indexParams,
+            threshold: plan.threshold,
+        };
+    }
+    async fetchNeighbors(results) {
+        const t0 = Date.now();
+        if (results.length === 0)
+            return [];
+        this.logger.debug('ChunkSearch: fetchNeighbors', { count: results.length });
+        const values = results.map((_, i) => `(${i}, $${i * 2 + 1}, $${i * 2 + 2}::int)`).join(',');
+        const params = results.flatMap(r => [r.filePath, r.startLine]);
+        const rows = await this.db.query(`SELECT r.idx,
+              prev."serviceName" AS prev_sn, prev."filePath" AS prev_fp, prev."startLine" AS prev_sl, prev.content AS prev_c, prev."ownerPath" AS prev_op,
+              next."serviceName" AS next_sn, next."filePath" AS next_fp, next."startLine" AS next_sl, next.content AS next_c, next."ownerPath" AS next_op
+       FROM (VALUES ${values}) r(idx, fp, sl)
+       LEFT JOIN LATERAL (
+         SELECT "serviceName", "filePath", "startLine", content, "ownerPath"
+         FROM code_chunk WHERE "filePath" = r.fp AND "startLine" < r.sl
+         ORDER BY "startLine" DESC LIMIT 1
+       ) prev ON true
+       LEFT JOIN LATERAL (
+         SELECT "serviceName", "filePath", "startLine", content, "ownerPath"
+         FROM code_chunk WHERE "filePath" = r.fp AND "startLine" > r.sl
+         ORDER BY "startLine" ASC LIMIT 1
+       ) next ON true
+       ORDER BY r.idx`, params);
+        const neighbors = rows.map((row, i) => ({
+            result: results[i],
+            prevChunk: row.prev_fp ? { serviceName: row.prev_sn, filePath: row.prev_fp, startLine: row.prev_sl, content: row.prev_c, ownerPath: row.prev_op ?? null } : null,
+            nextChunk: row.next_fp ? { serviceName: row.next_sn, filePath: row.next_fp, startLine: row.next_sl, content: row.next_c, ownerPath: row.next_op ?? null } : null,
+        }));
+        this.logger.debug('ChunkSearch: fetchNeighbors result', {
+            withPrev: neighbors.filter(n => n.prevChunk).length,
+            withNext: neighbors.filter(n => n.nextChunk).length,
+            ms: Date.now() - t0,
+        });
+        return neighbors;
+    }
+    async explainNoResults(project) {
+        try {
+            const rows = await this.db.query(project
+                ? `SELECT EXISTS (SELECT 1 FROM code_chunk WHERE "serviceName" = $1) AS present`
+                : `SELECT EXISTS (SELECT 1 FROM code_chunk) AS present`, project ? [project] : []);
+            return rows[0]?.present ? 'no-candidates' : 'empty-scope';
+        }
+        catch (err) {
+            this.logger.warn('ChunkSearch: explainNoResults lookup failed', { err, project });
+            return 'lookup-failed';
+        }
+    }
+}
+exports.ChunkSearch = ChunkSearch;

package/dist/src/search/DependencyGraph.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from '../config';
+import type { IDatabase, ILogger } from '../interfaces';
+import type { DependencyRow, GraphContext, IDependencyGraph } from '../interfaces/IDependencyGraph';
+import type { SearchResult } from '../interfaces/IChunkSearch';
+import type { ProjectRoots } from '../workspace/ProjectRoots';
+export declare class DependencyGraph implements IDependencyGraph {
+    private db;
+    private roots;
+    private config;
+    private logger;
+    constructor(db: IDatabase, roots: ProjectRoots, config: Config, logger: ILogger);
+    getProjectEdges(): Promise<{
+        from: string;
+        to: string;
+    }[]>;
+    fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
+    getDependencies(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependents(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+}

package/dist/src/search/DependencyGraph.js

@@ -0,0 +1,180 @@
+"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.DependencyGraph = void 0;
+const path = __importStar(require("path"));
+const dependency_traversal_1 = require("../dependency-traversal");
+const index_paths_1 = require("./index-paths");
+class DependencyGraph {
+    db;
+    roots;
+    config;
+    logger;
+    constructor(db, roots, config, logger) {
+        this.db = db;
+        this.roots = roots;
+        this.config = config;
+        this.logger = logger;
+    }
+    async getProjectEdges() {
+        const rows = await this.db.query(`SELECT DISTINCT project, "toFile" FROM code_dependency`);
+        const byRelPath = [...this.roots.entries()]
+            .map(([name, abs]) => ({ name, rel: path.relative(this.config.workspaceRoot, abs) }))
+            .sort((a, b) => b.rel.length - a.rel.length);
+        const ownerOf = (toFile) => {
+            for (const { name, rel } of byRelPath) {
+                if (toFile === rel || toFile.startsWith(rel + path.sep) || toFile.startsWith(rel + '/'))
+                    return name;
+            }
+            return null;
+        };
+        const seen = new Set();
+        const edges = [];
+        for (const { project, toFile } of rows) {
+            const to = ownerOf(toFile);
+            if (!to || to === project)
+                continue;
+            const key = project + ' ' + to;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            edges.push({ from: project, to });
+        }
+        return edges;
+    }
+    async fetchGraphContext(results) {
+        const t0 = Date.now();
+        const files = [...new Set(results.map(r => r.filePath))];
+        this.logger.debug('DependencyGraph: fetchGraphContext', { files: files.length });
+        if (files.length === 0)
+            return new Map();
+        const proportionalLimit = Math.max(2000, files.length * 100);
+        const values = files.map((_, i) => `($${i + 1}::text)`).join(', ');
+        const rows = await this.db.query(`SELECT r.fp AS "filePath", 'import' AS direction, d."toFile" AS related
+         FROM (VALUES ${values}) AS r(fp)
+         JOIN code_dependency d ON d."fromFile" = r.fp
+         WHERE NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('d."toFile"')}
+
+         UNION ALL
+
+         SELECT r.fp AS "filePath", 'usedby' AS direction, d."fromFile" AS related
+         FROM (VALUES ${values}) AS r(fp)
+         JOIN code_dependency d ON d."toFile" = r.fp
+         WHERE NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('d."fromFile"')}
+
+         LIMIT ${proportionalLimit}`, files);
+        const ctx = new Map();
+        for (const filePath of files)
+            ctx.set(filePath, { imports: new Set(), usedBy: new Set() });
+        for (const row of rows) {
+            const g = ctx.get(row.filePath);
+            if (row.direction === 'import')
+                g.imports.add(row.related);
+            else
+                g.usedBy.add(row.related);
+        }
+        this.logger.debug('DependencyGraph: fetchGraphContext result', { files: files.length, rows: rows.length, ms: Date.now() - t0 });
+        const result = new Map();
+        for (const [fp, g] of ctx)
+            result.set(fp, {
+                imports: [...g.imports].slice(0, 50),
+                usedBy: [...g.usedBy].slice(0, 50),
+            });
+        return result;
+    }
+    async getDependencies(filePath, symbol = null, transitive = false) {
+        const t0 = Date.now();
+        this.logger.debug('DependencyGraph: getDependencies', { filePath, symbol, transitive });
+        const params = [filePath];
+        let symbolFilter = '';
+        if (symbol) {
+            params.push(symbol);
+            symbolFilter = `AND "toSymbol" = $${params.length}`;
+        }
+        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType", min("id"::text) AS "id"
+       FROM code_dependency
+       WHERE "fromFile" = $1 AND NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('"toFile"')}
+       ${symbolFilter}
+       GROUP BY "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+       ORDER BY "toFile", min("id"::text)`, params);
+        if (!transitive) {
+            this.logger.debug('DependencyGraph: getDependencies result', { direct: direct.length, ms: Date.now() - t0 });
+            return direct;
+        }
+        const neighbours = async (frontier) => {
+            const rows = await this.db.query(`SELECT DISTINCT "fromFile", "toFile" FROM code_dependency
+         WHERE "fromFile" = ANY($1::text[]) AND NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('"toFile"')}`, [frontier]);
+            return rows.map(r => ({ from: r.fromFile, to: r.toFile }));
+        };
+        const indirect = (await (0, dependency_traversal_1.traverse)(filePath, neighbours)).map(r => ({
+            toFile: r.file, depth: r.depth, via: r.via,
+            fromFile: null, fromSymbol: null, toSymbol: null, depType: null,
+        }));
+        this.logger.debug('DependencyGraph: getDependencies result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
+        return [...direct, ...indirect];
+    }
+    async getDependents(filePath, symbol = null, transitive = false) {
+        const t0 = Date.now();
+        this.logger.debug('DependencyGraph: getDependents', { filePath, symbol, transitive });
+        const params = [filePath];
+        let symbolFilter = '';
+        if (symbol) {
+            params.push(symbol);
+            symbolFilter = `AND "toSymbol" = $${params.length}`;
+        }
+        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType", min("id"::text) AS "id"
+       FROM code_dependency
+       WHERE "toFile" = $1 AND NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('"fromFile"')}
+       ${symbolFilter}
+       GROUP BY "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+       ORDER BY "fromFile", min("id"::text)`, params);
+        if (!transitive) {
+            this.logger.debug('DependencyGraph: getDependents result', { direct: direct.length, ms: Date.now() - t0 });
+            return direct;
+        }
+        const neighbours = async (frontier) => {
+            const rows = await this.db.query(`SELECT DISTINCT "fromFile", "toFile" FROM code_dependency
+         WHERE "toFile" = ANY($1::text[]) AND NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('"fromFile"')}`, [frontier]);
+            return rows.map(r => ({ from: r.toFile, to: r.fromFile }));
+        };
+        const indirect = (await (0, dependency_traversal_1.traverse)(filePath, neighbours)).map(r => ({
+            fromFile: r.file, depth: r.depth, via: r.via,
+            toFile: null, fromSymbol: null, toSymbol: null, depType: null,
+        }));
+        this.logger.debug('DependencyGraph: getDependents result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
+        return [...direct, ...indirect];
+    }
+}
+exports.DependencyGraph = DependencyGraph;

package/dist/src/search/IndexIdentityGuard.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from '../config';
+import type { IDatabase, IEmbedder } from '../interfaces';
+import type { IIndexIdentityGuard } from '../interfaces/IIndexIdentityGuard';
+export declare class IndexIdentityGuard implements IIndexIdentityGuard {
+    private db;
+    private embedder;
+    private config;
+    constructor(db: IDatabase, embedder: IEmbedder, config: Config);
+    assertIndexMatches(): Promise<void>;
+    private compareIndexed;
+}

package/dist/src/search/IndexIdentityGuard.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexIdentityGuard = void 0;
+const legacy_ollama_index_1 = require("../services/legacy-ollama-index");
+class IndexIdentityGuard {
+    db;
+    embedder;
+    config;
+    constructor(db, embedder, config) {
+        this.db = db;
+        this.embedder = embedder;
+        this.config = config;
+    }
+    async assertIndexMatches() {
+        const meta = await this.db.readIndexMeta();
+        if (meta) {
+            this.compareIndexed(meta.provider, meta.model, meta.dimensions);
+            return;
+        }
+        if (await (0, legacy_ollama_index_1.hasIndexedChunks)(this.db)) {
+            this.compareIndexed(legacy_ollama_index_1.LEGACY_OLLAMA_IDENTITY.provider, legacy_ollama_index_1.LEGACY_OLLAMA_IDENTITY.model, null);
+        }
+    }
+    compareIndexed(indexedProvider, indexedModel, indexedDimensions) {
+        const { provider, model } = this.config.embedding;
+        if (indexedProvider !== provider || indexedModel !== model) {
+            throw new Error(`Index was built with ${indexedProvider}/${indexedModel} but the config selects ${provider}/${model}. ` +
+                `Run \`rag-index --reindex\` to rebuild the index for the new model.`);
+        }
+        const dim = this.embedder.dimensions;
+        if (indexedDimensions != null && dim > 0 && dim !== indexedDimensions) {
+            throw new Error(`Index was built at ${indexedDimensions} dimensions but ${provider}/${model} now resolves to ${dim}. ` +
+                `Run \`rag-index --reindex\` to rebuild the index at the new dimension.`);
+        }
+    }
+}
+exports.IndexIdentityGuard = IndexIdentityGuard;

package/dist/src/search/ProjectCatalog.d.ts

@@ -0,0 +1,11 @@
+import type { IDatabase } from '../interfaces';
+import type { IProjectCatalog, ProjectRow } from '../interfaces/IProjectCatalog';
+import { type WorkspaceFs } from '../workspace/fs-access';
+import type { ProjectRoots } from '../workspace/ProjectRoots';
+export declare class ProjectCatalog implements IProjectCatalog {
+    private db;
+    private roots;
+    private fs;
+    constructor(db: IDatabase, roots: ProjectRoots, fs: WorkspaceFs);
+    listProjects(): Promise<ProjectRow[]>;
+}

package/dist/src/search/ProjectCatalog.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectCatalog = void 0;
+const file_utils_1 = require("../file-utils");
+const fs_access_1 = require("../workspace/fs-access");
+const EMPTY_META = { description: null, stack: null, notes: null, relations: null };
+class ProjectCatalog {
+    db;
+    roots;
+    fs;
+    constructor(db, roots, fs) {
+        this.db = db;
+        this.roots = roots;
+        this.fs = fs;
+    }
+    async listProjects() {
+        const rows = await this.db.query(`SELECT "serviceName", COUNT(*)::int AS chunks
+       FROM code_chunk
+       GROUP BY "serviceName"
+       ORDER BY "serviceName"`);
+        return Promise.all(rows.map(async (r) => {
+            const projectRoot = this.roots.resolveProjectRoot(r.serviceName);
+            const meta = (0, file_utils_1.readRagMeta)(projectRoot);
+            let rootError = null;
+            try {
+                await this.fs.stat(projectRoot);
+            }
+            catch (err) {
+                rootError = (0, fs_access_1.errorCode)(err);
+            }
+            return {
+                ...r, path: projectRoot, relPath: this.roots.toRel(projectRoot), rootError,
+                ...(typeof meta === 'object' ? meta : EMPTY_META),
+            };
+        }));
+    }
+}
+exports.ProjectCatalog = ProjectCatalog;