codesearch-mcp 0.0.17-alpha.1 → 0.1.0-alpha

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

@@ -0,0 +1,33 @@
+/**
+ * Represents a discovered project within a monorepo workspace.
+ */
+export interface MonorepoProject {
+    /** Project name (e.g. "my-app", "shared-utils") */
+    name: string;
+    /** Absolute path to the project root */
+    path: string;
+    /** npm scope + package name (e.g. "@scope/my-app") — null if no package.json or no name */
+    packageName: string | null;
+    /** "app" | "lib" — derived from project.json or directory convention */
+    type: 'app' | 'lib';
+}
+/**
+ * Monorepo resolver — detects and resolves workspace structure.
+ * Implementations handle specific monorepo tooling (Nx, Turborepo, etc.)
+ */
+export interface IMonorepoResolver {
+    /**
+     * Detect whether the given root directory is a monorepo workspace.
+     */
+    isMonorepo(rootDir: string): boolean;
+    /**
+     * Discover all projects (apps + libs) in the monorepo.
+     */
+    discoverProjects(rootDir: string): MonorepoProject[];
+    /**
+     * Get the root tsconfig path that contains workspace-wide path aliases.
+     * For Nx this is typically tsconfig.base.json at the workspace root.
+     * The AST parser uses this to resolve cross-project imports (@scope/*).
+     */
+    getRootTsConfigPath(rootDir: string): string | null;
+}

package/dist/src/interfaces/IMonorepoResolver.js

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

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

@@ -0,0 +1,28 @@
+export interface DiscoveredProject {
+    name: string;
+    path: string;
+    /** npm scope + package name (e.g. "@scope/my-app") — only set for monorepo projects */
+    packageName?: string | null;
+    /** "app" | "lib" — only set for monorepo projects */
+    type?: 'app' | 'lib';
+    /**
+     * Path to the workspace-wide tsconfig (e.g. tsconfig.base.json) that holds
+     * cross-project path aliases. Set for monorepo projects; undefined for flat
+     * workspaces (where each project uses its own local tsconfig.json).
+     */
+    rootTsConfigPath?: string | null;
+    /**
+     * When a top-level directory is itself a nested monorepo (e.g. an Nx repo
+     * under a flat workspaceRoot), this holds its expanded sub-projects. The
+     * repo stays a single selectable unit; `toLeafProjects` expands `children`
+     * into the actual projects to index. Absent/undefined for ordinary projects.
+     */
+    children?: DiscoveredProject[];
+}
+/**
+ * Project discovery abstraction — decouples project enumeration
+ * from the indexing service (Single Responsibility Principle).
+ */
+export interface IProjectDiscovery {
+    discover(rootDir: string): DiscoveredProject[];
+}

package/dist/src/interfaces/IProjectDiscovery.js

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

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

@@ -0,0 +1,37 @@
+import type { SearchResult, NeighborResult, GraphContext, DependencyRow, ProjectRow, GrepMatch, SymbolKind, SymbolHit, CallerRow, FileRangeResult } from '../services/SearcherService';
+/**
+ * Searcher abstraction — McpServer depends on this interface
+ * rather than the concrete SearcherService.
+ */
+export interface ISearcher {
+    prepareQuery(raw: string): Promise<{
+        query: string;
+        translated: boolean;
+    }>;
+    assertIndexMatches(): Promise<void>;
+    listProjects(): Promise<ProjectRow[]>;
+    getProjectEdges(): Promise<{
+        from: string;
+        to: string;
+    }[]>;
+    searchChunks(query: string, limit: number, project: string | null, threshold?: number): 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[]>;
+    getCallers(symbol: string, project: string, calleeFile?: string | null): Promise<CallerRow[]>;
+    grepSymbol(symbol: string, project: string, excludeFile: string): Promise<{
+        matches: GrepMatch[];
+        truncated: boolean;
+    }>;
+    findSymbol(name: string, project: string | null, kind: SymbolKind): Promise<{
+        hits: SymbolHit[];
+        truncated: boolean;
+    }>;
+    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>;
+}

package/dist/src/interfaces/ISearcher.js

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

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

@@ -0,0 +1,8 @@
+export type { IEmbedder, InputType } from './IEmbedder';
+export type { IAstParser, DepEdge, SymbolEntry, CallEdge, FileAnalysis } from './IAstParser';
+export type { IChunker, ChunkPiece, ChunkOpts } from './IChunker';
+export type { ILogger } from './ILogger';
+export type { IDatabase } from './IDatabase';
+export type { ISearcher } from './ISearcher';
+export type { IProjectDiscovery, DiscoveredProject } from './IProjectDiscovery';
+export type { IMcpToolHandler, ToolDefinition, ToolResponse } from './IMcpToolHandler';

package/dist/src/interfaces/index.js

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

package/dist/src/owner-path.d.ts

@@ -0,0 +1,10 @@
+import type { OwnerRange } from './interfaces/IAstParser';
+/**
+ * Resolve the owning declaration for a chunk given its 1-based start line and a
+ * flat list of candidate ranges (top-level symbols + method ranges). The
+ * deepest range containing the start line wins (smallest `endLine - line` span),
+ * so a method beats its enclosing class. Returns `Container.name` for methods
+ * (via `container`) or `name` for top-level declarations, and `null` when the
+ * start line lies outside every range (imports / module-scope gaps).
+ */
+export declare function resolveOwnerPath(startLine: number, ranges: OwnerRange[]): string | null;

package/dist/src/owner-path.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOwnerPath = resolveOwnerPath;
+/**
+ * Resolve the owning declaration for a chunk given its 1-based start line and a
+ * flat list of candidate ranges (top-level symbols + method ranges). The
+ * deepest range containing the start line wins (smallest `endLine - line` span),
+ * so a method beats its enclosing class. Returns `Container.name` for methods
+ * (via `container`) or `name` for top-level declarations, and `null` when the
+ * start line lies outside every range (imports / module-scope gaps).
+ */
+function resolveOwnerPath(startLine, ranges) {
+    let best = null;
+    let bestSpan = Infinity;
+    for (const r of ranges) {
+        if (r.line <= startLine && startLine <= r.endLine) {
+            const span = r.endLine - r.line;
+            if (span < bestSpan) {
+                bestSpan = span;
+                best = r;
+            }
+        }
+    }
+    if (!best)
+        return null;
+    return best.container ? `${best.container}.${best.name}` : best.name;
+}

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

@@ -7,7 +7,7 @@ export declare class ProjectSelector {
     private included;
     private skipped;
     constructor(workspaceDir: string);
-    select(allProjects: Project[], forceSelect: boolean): Promise<Project[]>;
+    select<T extends Project>(allProjects: T[], forceSelect: boolean): Promise<T[]>;
     private printAlreadySelected;
     private promptForSelection;
     private promptForSkip;

package/dist/src/services/AstChunker.d.ts

@@ -0,0 +1,31 @@
+import type { Config } from '../config';
+import type { IChunker, ChunkPiece, ChunkOpts } from '../interfaces/IChunker';
+/**
+ * Splits TS/JS source into embeddable pieces aligned to top-level declaration
+ * ranges (AST strategy). Falls back to the character-based recursive splitter
+ * for schema files, files without symbol analysis, or when strategy is
+ * 'character' — that path is byte-for-byte the previous behavior.
+ */
+export declare class AstChunker implements IChunker {
+    private config;
+    private readonly jsSplitter;
+    private readonly schemaSplitter;
+    private readonly chunkSize;
+    constructor(config: Config);
+    chunk(code: string, opts: ChunkOpts): Promise<ChunkPiece[]>;
+    /** Character-splitter path for a whole file; line numbers from splitter metadata. */
+    private splitWholeFile;
+    private chunkByAst;
+    /**
+     * Build disjoint, sorted line intervals from symbol ranges. Overlapping /
+     * nested ranges merge into the outermost (a merged region covers any symbol
+     * inside it). Ranges are clamped to the file's line count.
+     */
+    private static buildIntervals;
+    /**
+     * Emit pieces for a 1-based inclusive line region. Whitespace-only gaps are
+     * dropped; regions longer than chunkSize are sub-split with the char splitter,
+     * with sub-piece line numbers offset back to absolute file lines.
+     */
+    private regionPieces;
+}

package/dist/src/services/AstChunker.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AstChunker = void 0;
+const textsplitters_1 = require("@langchain/textsplitters");
+/**
+ * Splits TS/JS source into embeddable pieces aligned to top-level declaration
+ * ranges (AST strategy). Falls back to the character-based recursive splitter
+ * for schema files, files without symbol analysis, or when strategy is
+ * 'character' — that path is byte-for-byte the previous behavior.
+ */
+class AstChunker {
+    config;
+    jsSplitter;
+    schemaSplitter;
+    chunkSize;
+    constructor(config) {
+        this.config = config;
+        this.chunkSize = config.indexer.chunkSize;
+        this.jsSplitter = textsplitters_1.RecursiveCharacterTextSplitter.fromLanguage('js', {
+            chunkSize: config.indexer.chunkSize,
+            chunkOverlap: config.indexer.chunkOverlap,
+        });
+        this.schemaSplitter = new textsplitters_1.RecursiveCharacterTextSplitter({
+            chunkSize: config.indexer.chunkSize,
+            chunkOverlap: config.indexer.chunkOverlap,
+            separators: ['\n\n', '\n', ' '],
+        });
+    }
+    async chunk(code, opts) {
+        if (opts.isSchemaFile) {
+            return this.splitWholeFile(code, this.schemaSplitter);
+        }
+        if (opts.strategy === 'character' || opts.symbols.length === 0) {
+            return this.splitWholeFile(code, this.jsSplitter);
+        }
+        return this.chunkByAst(code, opts.symbols);
+    }
+    /** Character-splitter path for a whole file; line numbers from splitter metadata. */
+    async splitWholeFile(code, splitter) {
+        const docs = await splitter.createDocuments([code]);
+        return docs.map((d) => {
+            const from = (d.metadata?.loc?.lines?.from ?? 1);
+            const to = (d.metadata?.loc?.lines?.to ?? from);
+            return { content: d.pageContent, startLine: from, endLine: to };
+        });
+    }
+    async chunkByAst(code, symbols) {
+        const lines = code.split('\n');
+        const total = lines.length;
+        const intervals = AstChunker.buildIntervals(symbols, total);
+        const pieces = [];
+        let cursor = 1;
+        for (const iv of intervals) {
+            if (cursor < iv.start) {
+                pieces.push(...await this.regionPieces(lines, cursor, iv.start - 1, true));
+            }
+            pieces.push(...await this.regionPieces(lines, iv.start, iv.end, false));
+            cursor = iv.end + 1;
+        }
+        if (cursor <= total) {
+            pieces.push(...await this.regionPieces(lines, cursor, total, true));
+        }
+        return pieces;
+    }
+    /**
+     * Build disjoint, sorted line intervals from symbol ranges. Overlapping /
+     * nested ranges merge into the outermost (a merged region covers any symbol
+     * inside it). Ranges are clamped to the file's line count.
+     */
+    static buildIntervals(symbols, total) {
+        const raw = symbols
+            .filter(s => s.line != null && s.line >= 1 && s.line <= total)
+            .map(s => ({
+            start: s.line,
+            end: Math.min(Math.max(s.endLine ?? s.line, s.line), total),
+        }))
+            .sort((a, b) => a.start - b.start || b.end - a.end);
+        const merged = [];
+        for (const iv of raw) {
+            const last = merged[merged.length - 1];
+            if (last && iv.start <= last.end) {
+                last.end = Math.max(last.end, iv.end);
+            }
+            else {
+                merged.push({ ...iv });
+            }
+        }
+        return merged;
+    }
+    /**
+     * Emit pieces for a 1-based inclusive line region. Whitespace-only gaps are
+     * dropped; regions longer than chunkSize are sub-split with the char splitter,
+     * with sub-piece line numbers offset back to absolute file lines.
+     */
+    async regionPieces(lines, start, end, isGap) {
+        const text = lines.slice(start - 1, end).join('\n');
+        if (isGap && text.trim() === '')
+            return [];
+        if (text.length <= this.chunkSize) {
+            return [{ content: text, startLine: start, endLine: end }];
+        }
+        const docs = await this.jsSplitter.createDocuments([text]);
+        return docs.map((d) => {
+            const from = (d.metadata?.loc?.lines?.from ?? 1);
+            const to = (d.metadata?.loc?.lines?.to ?? from);
+            return {
+                content: d.pageContent,
+                startLine: start + from - 1,
+                endLine: start + to - 1,
+            };
+        });
+    }
+}
+exports.AstChunker = AstChunker;

package/dist/src/services/AstParserService.d.ts

@@ -1,12 +1,10 @@
-import type { IAstParser, DepEdge, FileAnalysis } from '../interfaces/IAstParser';
-import { LoggerService } from './LoggerService';
+import type { IAstParser, DepEdge, FileAnalysis, AnalyzeProjectOpts } from '../interfaces/IAstParser';
+import type { ILogger } from '../interfaces';
 export declare class AstParserService implements IAstParser {
     private logger;
     private morphProjects;
-    constructor(logger?: LoggerService);
-    analyzeProject(filePaths: string[], serviceName: string, projectRoot?: string, opts?: {
-        skipDependencyResolution?: boolean;
-    }): Promise<Map<string, FileAnalysis>>;
+    constructor(logger?: ILogger);
+    analyzeProject(filePaths: string[], serviceName: string, projectRoot?: string, opts?: AnalyzeProjectOpts): Promise<Map<string, FileAnalysis>>;
     clearCache(projectRoot?: string): void;
     analyzeFile(filePath: string, serviceName: string, projectRoot?: string): Promise<FileAnalysis>;
     extractImportEdges(filePath: string, serviceName: string, projectRoot?: string): Promise<DepEdge[]>;
@@ -16,6 +14,12 @@ export declare class AstParserService implements IAstParser {
     private resolveFromSymbol;
     private buildUsageMap;
     private extractSymbols;
+    /**
+     * Method / constructor / accessor line ranges with their enclosing class, for
+     * owner-path resolution only. Deliberately NOT fed into `code_symbol` (methods
+     * stay grep-based in find_symbol), so this is separate from extractSymbols.
+     */
+    private extractOwnerRanges;
     private extractCalls;
     private getContainerName;
 }

package/dist/src/services/AstParserService.js

@@ -54,9 +54,10 @@ class AstParserService {
     async analyzeProject(filePaths, serviceName, projectRoot = process.cwd(), opts = {}) {
         const t0 = Date.now();
         const skipDependencyResolution = opts.skipDependencyResolution ?? false;
-        this.logger.debug('AstParser: analyzeProject start', { serviceName, projectRoot, files: filePaths.length, skipDependencyResolution });
+        const rootTsConfigPath = opts.rootTsConfigPath;
+        this.logger.debug('AstParser: analyzeProject start', { serviceName, projectRoot, files: filePaths.length, skipDependencyResolution, rootTsConfigPath });
         const analysisMap = new Map();
-        const morphProject = this.createMorphProject(projectRoot, skipDependencyResolution);
+        const morphProject = this.createMorphProject(projectRoot, skipDependencyResolution, rootTsConfigPath);
         for (const filePath of filePaths) {
             if (!/\.(ts|tsx|js|jsx)$/.test(filePath) || /\.d\.ts$/.test(filePath)) {
                 analysisMap.set(filePath, { edges: [], symbols: [], calls: [] });
@@ -76,7 +77,8 @@ class AstParserService {
                 const edges = this.extractEdges(sourceFile, filePath, serviceName);
                 const symbols = this.extractSymbols(sourceFile, filePath, serviceName);
                 const calls = this.extractCalls(sourceFile, filePath, serviceName);
-                analysisMap.set(filePath, { edges, symbols, calls });
+                const ownerRanges = this.extractOwnerRanges(sourceFile);
+                analysisMap.set(filePath, { edges, symbols, calls, ownerRanges });
             }
             catch (err) {
                 this.logger.warn('AstParser: failed to analyze file', { filePath, reason: err.message });
@@ -125,9 +127,10 @@ class AstParserService {
         const edges = this.extractEdges(sourceFile, filePath, serviceName);
         const symbols = this.extractSymbols(sourceFile, filePath, serviceName);
         const calls = this.extractCalls(sourceFile, filePath, serviceName);
+        const ownerRanges = this.extractOwnerRanges(sourceFile);
         morphProject.removeSourceFile(sourceFile);
         this.logger.debug('AstParser: analyzeFile done', { filePath, edges: edges.length, symbols: symbols.length, calls: calls.length, ms: Date.now() - t0 });
-        return { edges, symbols, calls };
+        return { edges, symbols, calls, ownerRanges };
     }
     // Kept for test compatibility (extract-import-edges.test.ts).
     async extractImportEdges(filePath, serviceName, projectRoot) {
@@ -135,22 +138,37 @@ class AstParserService {
         return edges;
     }
     // ── private: MorphProject cache (LRU, max MORPH_CACHE_MAX entries) ──────────
-    createMorphProject(projectRoot, skipFileDependencyResolution = false) {
+    createMorphProject(projectRoot, skipFileDependencyResolution = false, rootTsConfigPath) {
         const t0 = Date.now();
-        const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
-        const hasTsconfig = fs.existsSync(tsconfigPath);
-        this.logger.debug('AstParser: tsconfig lookup', { projectRoot, found: hasTsconfig, skipFileDependencyResolution });
+        // Determine which tsconfig to use:
+        // 1. Project-local tsconfig.json
+        // 2. Root tsconfig (e.g. tsconfig.base.json for Nx monorepos)
+        // 3. Fallback options
+        const localTsconfigPath = path.join(projectRoot, 'tsconfig.json');
+        const hasLocalTsconfig = fs.existsSync(localTsconfigPath);
+        const hasRootTsconfig = rootTsConfigPath ? fs.existsSync(rootTsConfigPath) : false;
+        // For monorepos: prefer the root tsconfig.base.json which contains
+        // workspace-wide path aliases (e.g. @scope/* → libs/*/src)
+        const effectiveTsconfig = hasRootTsconfig ? rootTsConfigPath : (hasLocalTsconfig ? localTsconfigPath : null);
+        this.logger.debug('AstParser: tsconfig lookup', {
+            projectRoot,
+            localFound: hasLocalTsconfig,
+            rootTsConfigPath: rootTsConfigPath ?? null,
+            rootFound: hasRootTsconfig,
+            effective: effectiveTsconfig,
+            skipFileDependencyResolution,
+        });
         let project;
         try {
-            const opts = hasTsconfig
-                ? { tsConfigFilePath: tsconfigPath, skipAddingFilesFromTsConfig: true, skipFileDependencyResolution }
+            const opts = effectiveTsconfig
+                ? { tsConfigFilePath: effectiveTsconfig, skipAddingFilesFromTsConfig: true, skipFileDependencyResolution }
                 : { ...FALLBACK_OPTS, skipFileDependencyResolution };
             project = new ts_morph_1.Project(opts);
-            if (hasTsconfig) {
+            if (effectiveTsconfig) {
                 const co = project.getCompilerOptions();
                 const pathsMap = co.paths ?? {};
                 const pathCount = Object.keys(pathsMap).length;
-                this.logger.debug('AstParser: tsconfig loaded', { pathCount, ms: Date.now() - t0 });
+                this.logger.debug('AstParser: tsconfig loaded', { tsconfig: effectiveTsconfig, pathCount, ms: Date.now() - t0 });
                 if (pathCount > 0) {
                     this.logger.debug('AstParser: path aliases', { aliases: Object.keys(pathsMap) });
                 }
@@ -161,7 +179,7 @@ class AstParserService {
         }
         catch (err) {
             this.logger.warn('AstParser: tsconfig load failed, using fallback', {
-                tsconfigPath,
+                tsconfigPath: effectiveTsconfig ?? localTsconfigPath,
                 reason: err.message,
                 ms: Date.now() - t0,
             });
@@ -353,6 +371,33 @@ class AstParserService {
         }
         return symbols;
     }
+    /**
+     * Method / constructor / accessor line ranges with their enclosing class, for
+     * owner-path resolution only. Deliberately NOT fed into `code_symbol` (methods
+     * stay grep-based in find_symbol), so this is separate from extractSymbols.
+     */
+    extractOwnerRanges(sourceFile) {
+        const ranges = [];
+        for (const cls of sourceFile.getClasses()) {
+            const container = cls.getName();
+            if (!container)
+                continue;
+            const members = [
+                ...cls.getMethods().map(n => ({ name: n.getName(), node: n })),
+                ...cls.getGetAccessors().map(n => ({ name: n.getName(), node: n })),
+                ...cls.getSetAccessors().map(n => ({ name: n.getName(), node: n })),
+                ...cls.getConstructors().map(n => ({ name: 'constructor', node: n })),
+            ];
+            for (const { name, node } of members) {
+                ranges.push({
+                    name, container,
+                    line: node.getStartLineNumber(),
+                    endLine: node.getEndLineNumber(),
+                });
+            }
+        }
+        return ranges;
+    }
     // ── private: call graph extraction ────────────────────────────────────────
     extractCalls(sourceFile, filePath, serviceName) {
         const calls = [];
@@ -367,7 +412,7 @@ class AstParserService {
                     const sym = expr.getNameNode().getSymbol();
                     const decl = sym?.getDeclarations()?.[0];
                     const declPath = decl?.getSourceFile().getFilePath();
-                    if (declPath && !declPath.includes('/node_modules/') && declPath !== filePath) {
+                    if (declPath && !declPath.includes('/node_modules/')) {
                         calleeFile = declPath;
                         calleeSymbol = calleeName;
                     }
@@ -383,7 +428,7 @@ class AstParserService {
                             : sym;
                         const decl = resolved.getDeclarations()?.[0];
                         const declPath = decl?.getSourceFile().getFilePath();
-                        if (declPath && !declPath.includes('/node_modules/') && declPath !== filePath) {
+                        if (declPath && !declPath.includes('/node_modules/')) {
                             calleeFile = declPath;
                             calleeSymbol = calleeName;
                         }

package/dist/src/services/DatabaseService.d.ts

@@ -1,11 +1,12 @@
 import type { NodePgDatabase, NodePgTransaction } from 'drizzle-orm/node-postgres';
 import type { ExtractTablesWithRelations } from 'drizzle-orm/relations';
 import type { Config } from '../config';
+import type { IDatabase, IndexMeta } from '../interfaces/IDatabase';
 import * as schema from '../db/schema';
 type Schema = typeof schema;
 export type DrizzleDb = NodePgDatabase<Schema>;
 export type DrizzleTx = NodePgTransaction<Schema, ExtractTablesWithRelations<Schema>>;
-export declare class DatabaseService {
+export declare class DatabaseService implements IDatabase {
     private config;
     private pool;
     private _db;
@@ -16,6 +17,18 @@ export declare class DatabaseService {
     destroy(): Promise<void>;
     initDb(): Promise<void>;
     initDbWithSchema(): Promise<void>;
+    /**
+     * Create `code_chunk` at `dimensions` if it does not exist, plus its HNSW and
+     * (serviceName, filePath) indexes and the additive `contentHash`/`ownerPath`
+     * columns for pre-existing tables. Idempotent — safe to call repeatedly.
+     */
+    ensureChunkTable(dimensions: number): Promise<void>;
+    /** Drop and recreate `code_chunk` at `dimensions` — used on a dimension change. */
+    recreateChunkTable(dimensions: number): Promise<void>;
+    readIndexMeta(): Promise<IndexMeta | null>;
+    writeIndexMeta(meta: IndexMeta): Promise<void>;
+    /** Guard against SQL injection — the dimension is interpolated into DDL. */
+    private assertDim;
     private ensureDatabaseExists;
 }
 export {};

package/dist/src/services/DatabaseService.js

@@ -66,33 +66,20 @@ class DatabaseService {
     async initDbWithSchema() {
         await this.ensureDatabaseExists();
         await this.initDb();
-        // code_chunk table
-        const [{ exists }] = await this.query(`
-      SELECT EXISTS (
-        SELECT 1 FROM information_schema.tables
-        WHERE table_schema = 'public' AND table_name = 'code_chunk'
+        // code_chunk table — created at the legacy default width (1024) so search
+        // tools always have a table. IndexerService recreates it at the resolved
+        // width before indexing when the active model's dimension differs.
+        await this.ensureChunkTable(1024);
+        // index_meta table — source of truth for the model that built the index.
+        await this.query(`
+      CREATE TABLE IF NOT EXISTS index_meta (
+        id          BOOLEAN PRIMARY KEY DEFAULT true,
+        provider    TEXT NOT NULL,
+        model       TEXT NOT NULL,
+        dimensions  INT  NOT NULL,
+        "indexedAt" TIMESTAMPTZ NOT NULL DEFAULT now()
       )
     `);
-        if (!exists) {
-            await this.query(`
-        CREATE TABLE code_chunk (
-          id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-          "serviceName" TEXT NOT NULL,
-          "filePath"    TEXT NOT NULL,
-          "startLine"   INT,
-          content       TEXT NOT NULL,
-          embedding     vector(1024) NOT NULL,
-          "lastModified" DOUBLE PRECISION,
-          "contentHash"  VARCHAR(64)
-        )
-      `);
-            await this.query(`
-        CREATE INDEX idx_code_chunk_embedding
-        ON code_chunk USING hnsw (embedding vector_cosine_ops)
-      `);
-        }
-        await this.query(`CREATE INDEX IF NOT EXISTS idx_code_chunk_service_file ON code_chunk ("serviceName", "filePath")`);
-        await this.query(`ALTER TABLE code_chunk ADD COLUMN IF NOT EXISTS "contentHash" varchar(64) NULL`);
         // code_dependency table
         const [{ existsDep }] = await this.query(`
       SELECT EXISTS (
@@ -160,6 +147,64 @@ class DatabaseService {
         await this.query(`CREATE INDEX IF NOT EXISTS idx_call_callee_file ON code_call (project, "calleeFile")`);
         await this.query(`CREATE INDEX IF NOT EXISTS idx_call_from        ON code_call (project, "fromFile")`);
     }
+    /**
+     * Create `code_chunk` at `dimensions` if it does not exist, plus its HNSW and
+     * (serviceName, filePath) indexes and the additive `contentHash`/`ownerPath`
+     * columns for pre-existing tables. Idempotent — safe to call repeatedly.
+     */
+    async ensureChunkTable(dimensions) {
+        const dim = this.assertDim(dimensions);
+        await this.query(`
+      CREATE TABLE IF NOT EXISTS code_chunk (
+        id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        "serviceName" TEXT NOT NULL,
+        "filePath"    TEXT NOT NULL,
+        "startLine"   INT,
+        content       TEXT NOT NULL,
+        embedding     vector(${dim}) NOT NULL,
+        "lastModified" DOUBLE PRECISION,
+        "contentHash"  VARCHAR(64),
+        "ownerPath"    VARCHAR
+      )
+    `);
+        await this.query(`ALTER TABLE code_chunk ADD COLUMN IF NOT EXISTS "contentHash" varchar(64) NULL`);
+        await this.query(`ALTER TABLE code_chunk ADD COLUMN IF NOT EXISTS "ownerPath" varchar NULL`);
+        await this.query(`CREATE INDEX IF NOT EXISTS idx_code_chunk_embedding ON code_chunk USING hnsw (embedding vector_cosine_ops)`);
+        await this.query(`CREATE INDEX IF NOT EXISTS idx_code_chunk_service_file ON code_chunk ("serviceName", "filePath")`);
+    }
+    /** Drop and recreate `code_chunk` at `dimensions` — used on a dimension change. */
+    async recreateChunkTable(dimensions) {
+        const dim = this.assertDim(dimensions);
+        await this.query(`DROP TABLE IF EXISTS code_chunk`);
+        await this.ensureChunkTable(dim);
+    }
+    async readIndexMeta() {
+        try {
+            const rows = await this.query(`SELECT provider, model, dimensions FROM index_meta LIMIT 1`);
+            const row = rows[0];
+            return row ? { provider: row.provider, model: row.model, dimensions: Number(row.dimensions) } : null;
+        }
+        catch {
+            // Table absent (un-migrated DB) — treat as "no metadata".
+            return null;
+        }
+    }
+    async writeIndexMeta(meta) {
+        await this.query(`INSERT INTO index_meta (id, provider, model, dimensions, "indexedAt")
+       VALUES (true, $1, $2, $3, now())
+       ON CONFLICT (id) DO UPDATE
+         SET provider = EXCLUDED.provider,
+             model = EXCLUDED.model,
+             dimensions = EXCLUDED.dimensions,
+             "indexedAt" = now()`, [meta.provider, meta.model, meta.dimensions]);
+    }
+    /** Guard against SQL injection — the dimension is interpolated into DDL. */
+    assertDim(dimensions) {
+        if (!Number.isInteger(dimensions) || dimensions <= 0 || dimensions > 2000) {
+            throw new Error(`Invalid vector dimension: ${dimensions} (must be an integer 1–2000)`);
+        }
+        return dimensions;
+    }
     async ensureDatabaseExists() {
         const { host, port, username, password, database } = this.config.db;
         const client = new pg_1.Client({ host, port, user: username, password, database: 'postgres' });

package/dist/src/services/EmbedderFactory.d.ts

@@ -0,0 +1,9 @@
+import type { Config } from '../config';
+import type { IEmbedder } from '../interfaces/IEmbedder';
+import type { ILogger } from '../interfaces/ILogger';
+import { type EmbedderDeps } from './OpenAICompatibleEmbedder';
+/**
+ * Construct the `IEmbedder` implementation selected by `config.embedding.provider`.
+ * The default (`ollama`) keeps existing installs working unchanged.
+ */
+export declare function createEmbedder(config: Config, logger?: ILogger, deps?: EmbedderDeps): IEmbedder;