kontext-engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,485 @@
+/** A single search result with chunk location, content, and relevance score (0–1). */
+interface SearchResult {
+    chunkId: number;
+    filePath: string;
+    lineStart: number;
+    lineEnd: number;
+    name: string | null;
+    type: string;
+    text: string;
+    score: number;
+    language: string;
+}
+/** Optional filters applied as post-processing on search results. */
+interface SearchFilters {
+    language?: string;
+}
+
+interface VectorResult {
+    chunkId: number;
+    distance: number;
+}
+
+interface FileInput {
+    path: string;
+    language: string;
+    hash: string;
+    size: number;
+}
+interface FileRecord {
+    id: number;
+    path: string;
+    language: string;
+    hash: string;
+    lastIndexed: number;
+    size: number;
+}
+interface ChunkInput {
+    lineStart: number;
+    lineEnd: number;
+    type: string;
+    name: string | null;
+    parent: string | null;
+    text: string;
+    imports: string[];
+    exports: boolean;
+    hash: string;
+}
+interface ChunkRecord {
+    id: number;
+    fileId: number;
+    lineStart: number;
+    lineEnd: number;
+    type: string;
+    name: string | null;
+    parent: string | null;
+    text: string;
+    imports: string[];
+    exports: boolean;
+    hash: string;
+}
+interface ChunkWithFile {
+    id: number;
+    fileId: number;
+    filePath: string;
+    language: string;
+    lineStart: number;
+    lineEnd: number;
+    type: string;
+    name: string | null;
+    parent: string | null;
+    text: string;
+}
+interface ChunkSearchFilters {
+    name?: string;
+    nameMode?: "exact" | "prefix" | "contains";
+    type?: string;
+    parent?: string;
+    language?: string;
+}
+interface FTSResult {
+    chunkId: number;
+    name: string | null;
+    rank: number;
+}
+/** Main database interface. Provides CRUD for files, chunks, vectors, FTS, and stats. */
+interface KontextDatabase {
+    upsertFile(file: FileInput): number;
+    getFile(filePath: string): FileRecord | null;
+    getFilesByHash(hashes: Map<string, string>): Map<string, FileRecord>;
+    deleteFile(filePath: string): void;
+    insertChunks(fileId: number, chunks: ChunkInput[]): number[];
+    getChunksByFile(fileId: number): ChunkRecord[];
+    getChunksByIds(ids: number[]): ChunkWithFile[];
+    deleteChunksByFile(fileId: number): void;
+    insertDependency(sourceChunkId: number, targetChunkId: number, type: string): void;
+    getDependencies(chunkId: number): {
+        targetChunkId: number;
+        type: string;
+    }[];
+    getReverseDependencies(chunkId: number): {
+        sourceChunkId: number;
+        type: string;
+    }[];
+    insertVector(chunkId: number, vector: Float32Array): void;
+    searchVectors(query: Float32Array, limit: number): VectorResult[];
+    searchChunks(filters: ChunkSearchFilters, limit: number): ChunkWithFile[];
+    searchFTS(query: string, limit: number): FTSResult[];
+    getAllFilePaths(): string[];
+    getFileCount(): number;
+    getChunkCount(): number;
+    getVectorCount(): number;
+    getLanguageBreakdown(): Map<string, number>;
+    getLastIndexed(): string | null;
+    transaction<T>(fn: () => T): T;
+    vacuum(): void;
+    close(): void;
+    getSchemaVersion(): number;
+    pragma(key: string): string;
+}
+/** Create or open a SQLite database at the given path. Initializes schema and loads sqlite-vec. */
+declare function createDatabase(dbPath: string, dimensions?: number): KontextDatabase;
+
+type ProgressCallback = (done: number, total: number) => void;
+/** Embedding provider: generates vector representations of text. */
+interface Embedder {
+    readonly name: string;
+    readonly dimensions: number;
+    embed(texts: string[], onProgress?: ProgressCallback): Promise<Float32Array[]>;
+    embedSingle(text: string): Promise<Float32Array>;
+}
+/** Format a chunk into embedding-friendly text with file path and name prefix. */
+declare function prepareChunkText(filePath: string, parent: string | null, text: string): string;
+/** Create a local embedder using Xenova/all-MiniLM-L6-v2 (384 dims, ONNX Runtime). */
+declare function createLocalEmbedder(): Promise<Embedder>;
+/** Create an embedder using Voyage AI's code embedding API. */
+declare function createVoyageEmbedder(apiKey: string): Embedder;
+/** Create an embedder using OpenAI's text-embedding-3-small API. */
+declare function createOpenAIEmbedder(apiKey: string): Embedder;
+
+/** Project-level configuration stored in .ctx/config.json. */
+interface KontextConfig {
+    embedder: {
+        provider: string;
+        model: string;
+        dimensions: number;
+    };
+    search: {
+        defaultLimit: number;
+        strategies: string[];
+        weights: Record<string, number>;
+    };
+    watch: {
+        debounceMs: number;
+        ignored: string[];
+    };
+    llm: {
+        provider: string | null;
+        model: string | null;
+    };
+}
+
+/** A source file discovered during scanning, with its detected language. */
+interface DiscoveredFile {
+    path: string;
+    absolutePath: string;
+    language: string;
+    size: number;
+    lastModified: number;
+}
+interface DiscoverOptions {
+    root: string;
+    extraIgnore?: string[];
+    followSymlinks?: boolean;
+}
+/** Maps file extensions to language names. Used for filtering and language detection. */
+declare const LANGUAGE_MAP: Record<string, string>;
+/** Recursively scan a directory for source files, respecting .gitignore and .ctxignore. */
+declare function discoverFiles(options: DiscoverOptions): Promise<DiscoveredFile[]>;
+
+/** An extracted AST node: function, class, method, type, import, or constant. */
+interface ASTNode {
+    type: "function" | "class" | "method" | "import" | "export" | "type" | "constant";
+    name: string | null;
+    lineStart: number;
+    lineEnd: number;
+    language: string;
+    parent: string | null;
+    params?: string[];
+    returnType?: string;
+    docstring?: string;
+    imports?: string[];
+    exports?: boolean;
+    text: string;
+}
+/** Initialize the Tree-sitter WebAssembly parser. Must be called before parseFile. */
+declare function initParser(): Promise<void>;
+/** Parse a source file with Tree-sitter and extract AST nodes. */
+declare function parseFile(filePath: string, language: string): Promise<ASTNode[]>;
+
+/** A logical code chunk with content, location, and a deterministic content hash. */
+interface Chunk {
+    id: string;
+    filePath: string;
+    lineStart: number;
+    lineEnd: number;
+    language: string;
+    type: "function" | "class" | "method" | "type" | "import" | "constant" | "config";
+    name: string | null;
+    parent: string | null;
+    text: string;
+    imports: string[];
+    exports: boolean;
+    hash: string;
+}
+interface ChunkOptions {
+    maxTokens?: number;
+    overlapLines?: number;
+}
+/** Rough token count estimate (~4 chars per token). */
+declare function estimateTokens(text: string): number;
+/** Split AST nodes into logical chunks. Merges small constants; keeps functions/classes whole. */
+declare function chunkFile(nodes: ASTNode[], filePath: string, options?: ChunkOptions): Chunk[];
+
+/** Names of available search strategies. */
+type StrategyName = "vector" | "fts" | "ast" | "path" | "dependency";
+/** Results from a single search strategy, ready for fusion. */
+interface StrategyResult {
+    strategy: StrategyName;
+    weight: number;
+    results: SearchResult[];
+}
+/** Merge results from multiple strategies using Reciprocal Rank Fusion (K=60). */
+declare function fusionMerge(strategyResults: StrategyResult[], limit: number): SearchResult[];
+
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** LLM provider for the steering layer. Wraps Gemini, OpenAI, or Anthropic chat APIs. */
+interface LLMProvider {
+    name: string;
+    chat(messages: ChatMessage[]): Promise<string>;
+}
+interface StrategyPlan {
+    strategy: StrategyName;
+    query: string;
+    weight: number;
+    reason: string;
+}
+interface SearchPlan {
+    interpretation: string;
+    strategies: StrategyPlan[];
+}
+/** Full result from LLM-steered search: plan, results, explanation, and cost. */
+interface SteeringResult {
+    interpretation: string;
+    strategies: StrategyPlan[];
+    results: SearchResult[];
+    explanation: string;
+    tokensUsed: number;
+    costEstimate: number;
+}
+type SearchExecutor = (strategies: StrategyPlan[], limit: number) => Promise<SearchResult[]>;
+/** Ask the LLM to interpret a query and plan which search strategies to use. */
+declare function planSearch(provider: LLMProvider, query: string): Promise<SearchPlan>;
+/** Full steering pipeline: plan → search → synthesize. Falls back to basic search on failure. */
+declare function steer(provider: LLMProvider, query: string, limit: number, searchExecutor: SearchExecutor): Promise<SteeringResult>;
+
+/** A single file change event from the watcher. */
+interface FileChange {
+    type: "add" | "change" | "unlink";
+    path: string;
+}
+/** Handle returned by createWatcher. Call start() to begin, stop() to clean up. */
+interface WatcherHandle {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+
+/** Result of incremental change detection: files categorized by status. */
+interface IncrementalResult {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+    unchanged: string[];
+    /** SHA-256 content hashes for added + modified files */
+    hashes: Map<string, string>;
+    /** Wall-clock duration in milliseconds */
+    duration: number;
+}
+/** Minimal DB surface needed for change detection */
+interface ChangeDetectionDb {
+    getFile(filePath: string): {
+        hash: string;
+    } | null;
+    getAllFilePaths(): string[];
+}
+/** Compare discovered files against stored hashes to detect adds, modifies, and deletes. */
+declare function computeChanges(discovered: DiscoveredFile[], db: ChangeDetectionDb): Promise<IncrementalResult>;
+
+/** KNN vector similarity search. Scores normalized as 1/(1+distance). */
+declare function vectorSearch(db: KontextDatabase, embedder: Embedder, query: string, limit: number, filters?: SearchFilters): Promise<SearchResult[]>;
+
+/** Full-text search via SQLite FTS5 with BM25 ranking. Scores normalized as 1/(1+|rank|). */
+declare function ftsSearch(db: KontextDatabase, query: string, limit: number, filters?: SearchFilters): SearchResult[];
+
+interface ASTFilters {
+    name?: string;
+    type?: string;
+    parent?: string;
+    language?: string;
+    matchMode?: "exact" | "prefix" | "fuzzy";
+}
+/** AST-aware symbol search by name, type, parent, and language. Supports exact/prefix/fuzzy matching. */
+declare function astSearch(db: KontextDatabase, filters: ASTFilters, limit: number): SearchResult[];
+
+/** Search files by glob pattern. Converts globs to SQL LIKE clauses. */
+declare function pathSearch(db: KontextDatabase, pattern: string, limit: number): SearchResult[];
+/** BFS traversal of the import/dependency graph. Scores decay with depth. */
+declare function dependencyTrace(db: KontextDatabase, chunkId: number, direction: "imports" | "importedBy", depth: number): SearchResult[];
+
+/** Options for the init pipeline. */
+interface InitOptions {
+    log?: (msg: string) => void;
+    skipEmbedding?: boolean;
+}
+interface IndexStats {
+    filesDiscovered: number;
+    filesAdded: number;
+    filesModified: number;
+    filesDeleted: number;
+    filesUnchanged: number;
+    chunksCreated: number;
+    vectorsCreated: number;
+    durationMs: number;
+    languageCounts: Map<string, number>;
+}
+/** Index a codebase: discover → parse → chunk → embed → store. Runs incrementally on subsequent calls. */
+declare function runInit(projectPath: string, options?: InitOptions): Promise<IndexStats>;
+
+/** Options for the query command. */
+interface QueryOptions {
+    limit: number;
+    strategies: StrategyName[];
+    language?: string;
+    format: "json" | "text";
+}
+interface QueryOutputResult {
+    file: string;
+    lines: [number, number];
+    name: string | null;
+    type: string;
+    score: number;
+    snippet: string;
+    language: string;
+}
+interface QueryOutput {
+    query: string;
+    results: QueryOutputResult[];
+    stats: {
+        strategies: string[];
+        totalResults: number;
+        searchTimeMs: number;
+    };
+    text?: string;
+}
+/** Execute a multi-strategy search with RRF fusion. Returns ranked results. */
+declare function runQuery(projectPath: string, query: string, options: QueryOptions): Promise<QueryOutput>;
+
+/** Options for the LLM-steered ask command. */
+interface AskOptions {
+    limit: number;
+    format: "json" | "text";
+    provider?: LLMProvider;
+    providerName?: string;
+    noExplain?: boolean;
+}
+interface AskOutputResult {
+    file: string;
+    lines: [number, number];
+    name: string | null;
+    type: string;
+    score: number;
+    snippet: string;
+    language: string;
+}
+interface AskOutput {
+    query: string;
+    interpretation: string;
+    results: AskOutputResult[];
+    explanation: string;
+    stats: {
+        strategies: string[];
+        tokensUsed: number;
+        costEstimate: number;
+        totalResults: number;
+    };
+    fallback?: boolean;
+    text?: string;
+}
+/** LLM-steered natural language search. Falls back to basic multi-strategy search without API key. */
+declare function runAsk(projectPath: string, query: string, options: AskOptions): Promise<AskOutput>;
+
+interface ProjectConfig {
+    model: string;
+    dimensions: number;
+}
+/** Structured output from the status command. */
+interface StatusOutput {
+    initialized: boolean;
+    fileCount: number;
+    chunkCount: number;
+    vectorCount: number;
+    dbSizeBytes: number;
+    lastIndexed: string | null;
+    languages: Map<string, number>;
+    config: ProjectConfig | null;
+    text: string;
+}
+/** Gather index statistics: file/chunk/vector counts, languages, DB size, config. */
+declare function runStatus(projectPath: string): Promise<StatusOutput>;
+
+/** String constants for all Kontext error codes. */
+declare const ErrorCode: {
+    readonly NOT_INITIALIZED: "NOT_INITIALIZED";
+    readonly INDEX_FAILED: "INDEX_FAILED";
+    readonly PARSE_FAILED: "PARSE_FAILED";
+    readonly CHUNK_FAILED: "CHUNK_FAILED";
+    readonly EMBEDDER_FAILED: "EMBEDDER_FAILED";
+    readonly SEARCH_FAILED: "SEARCH_FAILED";
+    readonly CONFIG_INVALID: "CONFIG_INVALID";
+    readonly DB_CORRUPTED: "DB_CORRUPTED";
+    readonly DB_WRITE_FAILED: "DB_WRITE_FAILED";
+    readonly WATCHER_FAILED: "WATCHER_FAILED";
+    readonly LLM_FAILED: "LLM_FAILED";
+};
+/** Union type of all error code string values. */
+type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Base error class for all Kontext errors. Carries a typed `code` and optional `cause`. */
+declare class KontextError extends Error {
+    readonly code: ErrorCodeValue;
+    constructor(message: string, code: ErrorCodeValue, cause?: Error);
+}
+/** Error during indexing: file discovery, parsing, chunking, or embedding. */
+declare class IndexError extends KontextError {
+    constructor(message: string, code: ErrorCodeValue, cause?: Error);
+}
+/** Error during search: vector, FTS, AST, path, or fusion. */
+declare class SearchError extends KontextError {
+    constructor(message: string, code: ErrorCodeValue, cause?: Error);
+}
+/** Error reading, writing, or validating configuration. */
+declare class ConfigError extends KontextError {
+    constructor(message: string, code: ErrorCodeValue, cause?: Error);
+}
+/** Error in SQLite storage operations. */
+declare class DatabaseError extends KontextError {
+    constructor(message: string, code: ErrorCodeValue, cause?: Error);
+}
+
+/** Numeric log level constants. Lower = more verbose. */
+declare const LogLevel: {
+    readonly DEBUG: 0;
+    readonly INFO: 1;
+    readonly WARN: 2;
+    readonly ERROR: 3;
+    readonly SILENT: 4;
+};
+/** Union type of all log level numeric values. */
+type LogLevelValue = (typeof LogLevel)[keyof typeof LogLevel];
+/** Leveled logger that writes to stderr. */
+interface Logger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+/** Options for creating a logger instance. */
+interface LoggerOptions {
+    level?: LogLevelValue;
+}
+/** Create a logger. Respects `CTX_DEBUG=1` env var for debug output. */
+declare function createLogger(options?: LoggerOptions): Logger;
+
+export { type ASTNode, type Chunk, ConfigError, DatabaseError, type DiscoverOptions, type DiscoveredFile, type Embedder, ErrorCode, type FileChange, IndexError, type KontextConfig, type KontextDatabase, KontextError, LANGUAGE_MAP, type LLMProvider, LogLevel, type Logger, SearchError, type SearchFilters, type SearchResult, type SteeringResult, type StrategyName, type StrategyResult, type WatcherHandle, astSearch, chunkFile, computeChanges, createDatabase, createLocalEmbedder, createLogger, createOpenAIEmbedder, createVoyageEmbedder, dependencyTrace, discoverFiles, estimateTokens, ftsSearch, fusionMerge, initParser, parseFile, pathSearch, planSearch, prepareChunkText, runAsk, runInit, runQuery, runStatus, steer, vectorSearch };