@code-rag/core 0.1.6 → 0.1.8

package/dist/embedding/lancedb-store.js

@@ -1,15 +1,13 @@
 import { ok, err } from 'neverthrow';
 import { StoreError } from '../types/provider.js';
 import * as lancedb from '@lancedb/lancedb';
+import { safeString, safeRecord } from '../utils/safe-cast.js';
 const TABLE_NAME = 'chunks';
 const SAFE_ID_PATTERN = /^[a-zA-Z0-9_\-:.]+$/;
 function safeParseJSON(json) {
     try {
         const parsed = JSON.parse(json);
-        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-            return parsed;
-        }
-        return {};
+        return safeRecord(parsed, {});
     }
     catch {
         return {};
@@ -18,6 +16,24 @@ function safeParseJSON(json) {
 function validateId(id) {
     return SAFE_ID_PATTERN.test(id) && id.length > 0 && id.length <= 256;
 }
+/** Convert raw LanceDB toArray() rows into typed LanceDBQueryResult[]. */
+function toLanceDBQueryResults(rows) {
+    return rows.map((row) => {
+        const r = safeRecord(row, {});
+        return {
+            id: safeString(r['id'], ''),
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Array.isArray guard; LanceDB stores vectors as number[]
+            vector: Array.isArray(r['vector']) ? r['vector'] : [],
+            content: safeString(r['content'], ''),
+            nl_summary: safeString(r['nl_summary'], ''),
+            chunk_type: safeString(r['chunk_type'], ''),
+            file_path: safeString(r['file_path'], ''),
+            language: safeString(r['language'], ''),
+            metadata: safeString(r['metadata'], '{}'),
+            _distance: typeof r['_distance'] === 'number' ? r['_distance'] : 0,
+        };
+    });
+}
 export class LanceDBStore {
     storagePath;
     _dimensions;
@@ -62,15 +78,16 @@ export class LanceDBStore {
                 return {
                     id,
                     vector: embeddings[i] ?? [],
-                    content: meta['content'] ?? '',
-                    nl_summary: meta['nl_summary'] ?? '',
-                    chunk_type: meta['chunk_type'] ?? '',
-                    file_path: meta['file_path'] ?? '',
-                    language: meta['language'] ?? '',
+                    content: safeString(meta['content'], ''),
+                    nl_summary: safeString(meta['nl_summary'], ''),
+                    chunk_type: safeString(meta['chunk_type'], ''),
+                    file_path: safeString(meta['file_path'], ''),
+                    language: safeString(meta['language'], ''),
                     metadata: JSON.stringify(meta),
                 };
             });
-            const data = rows;
+            // Justified cast: LanceDB API requires Record<string, unknown>[] but rows satisfy this structurally
+            const data = rows.map((row) => ({ ...row }));
             if (!this.table) {
                 this.table = await this.db.createTable(TABLE_NAME, data);
             }
@@ -101,10 +118,11 @@ export class LanceDBStore {
             if (!this.table) {
                 return ok([]);
             }
-            const results = (await this.table
+            const rawResults = await this.table
                 .search(embedding)
                 .limit(topK)
-                .toArray());
+                .toArray();
+            const results = toLanceDBQueryResults(rawResults);
             const mapped = results.map((row) => ({
                 id: row.id,
                 score: 1 / (1 + (row._distance ?? 0)),
@@ -159,6 +177,82 @@ export class LanceDBStore {
             return err(new StoreError(`LanceDB count failed: ${message}`));
         }
     }
+    async getById(id) {
+        try {
+            if (!validateId(id)) {
+                return err(new StoreError(`Invalid chunk ID: ${id}`));
+            }
+            await this.ensureConnected();
+            if (!this.table) {
+                return ok(undefined);
+            }
+            const filter = `id = '${id}'`;
+            const rows = (await this.table.query().where(filter).limit(1).toArray());
+            if (rows.length === 0) {
+                return ok(undefined);
+            }
+            const row = rows[0];
+            return ok({
+                id: row.id,
+                metadata: {
+                    content: row.content,
+                    nl_summary: row.nl_summary,
+                    chunk_type: row.chunk_type,
+                    file_path: row.file_path,
+                    language: row.language,
+                    ...(row.metadata ? safeParseJSON(row.metadata) : {}),
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return err(new StoreError(`LanceDB getById failed: ${message}`));
+        }
+    }
+    /**
+     * Scan all rows from the table.
+     * Returns an array of { id, metadata } objects (no vectors).
+     * Useful for index analysis and benchmark generation.
+     */
+    async getAll(limit) {
+        try {
+            await this.ensureConnected();
+            if (!this.table) {
+                return ok([]);
+            }
+            let query = this.table.query();
+            if (limit !== undefined && limit > 0) {
+                query = query.limit(limit);
+            }
+            const rawRows = await query.toArray();
+            const results = rawRows.map((row) => {
+                const r = safeRecord(row, {});
+                const id = safeString(r['id'], '');
+                const content = safeString(r['content'], '');
+                const nlSummary = safeString(r['nl_summary'], '');
+                const chunkType = safeString(r['chunk_type'], '');
+                const filePath = safeString(r['file_path'], '');
+                const language = safeString(r['language'], '');
+                const metaStr = safeString(r['metadata'], '{}');
+                return {
+                    id,
+                    metadata: {
+                        content,
+                        nl_summary: nlSummary,
+                        chunk_type: chunkType,
+                        file_path: filePath,
+                        language,
+                        ...safeParseJSON(metaStr),
+                    },
+                };
+            });
+            return ok(results);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return err(new StoreError(`LanceDB getAll failed: ${message}`));
+        }
+    }
     close() {
         if (this.table) {
             this.table.close();

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export type { IndexedFileState, ScannedFile, IndexerConfig, ChangeSet, IndexerRe
 export { IndexState, computeFileHash, FileScanner, ScanError, IncrementalIndexer, IndexerError, MultiRepoIndexer, MultiRepoIndexerError, checkIndexExists, FileWatcher, } from './indexer/index.js';
 export type { OllamaEmbeddingConfig, OpenAICompatibleEmbeddingConfig, QdrantConfig, ModelLifecycleConfig, BackendInfo, BackendType, GpuMode, DockerConfig, ProgressCallback, ProcessExecutor, FetchFn, } from './embedding/index.js';
 export { OllamaEmbeddingProvider, OpenAICompatibleEmbeddingProvider, ModelLifecycleManager, ModelLifecycleError, LanceDBStore, QdrantVectorStore, BM25Index, HybridSearch, } from './embedding/index.js';
-export type { AnalyzedQuery, QueryIntent, QueryEntity, ReadonlyGraph, RelationshipType, RelatedChunk, GraphExcerpt, ExpandedContext, TokenBudgetConfig, AssembledContext, CrossEncoderConfig, } from './retrieval/index.js';
+export type { AnalyzedQuery, QueryIntent, QueryEntity, ReadonlyGraph, RelationshipType, RelatedChunk, GraphExcerpt, ExpandedContext, ChunkLookupFn, TokenBudgetConfig, AssembledContext, CrossEncoderConfig, } from './retrieval/index.js';
 export { QueryAnalyzer, ContextExpander, TokenBudgetOptimizer, CrossEncoderReRanker, ReRankerError, } from './retrieval/index.js';
 export type { ReRankerConfig, ReRanker, BacklogConfig } from './types/index.js';
 export type { BacklogItemType, BacklogItem, BacklogQuery, BacklogProvider, AzureDevOpsConfig, ClickUpConfig, JiraConfig, BacklogCodeMap, CoverageReport, } from './backlog/index.js';
@@ -29,3 +29,10 @@ export type { Role, Action, RepoAccessLevel, RepoPermission, User, AuthToken, Au
 export { ROLE_HIERARCHY, AuthError, RBACManager, OIDCProvider, SAMLProvider, AuditLogger } from './auth/index.js';
 export type { CloudStorageProvider, CloudStorageConfig, S3Config, AzureBlobConfig, GCSConfig, GCSCredentials, } from './storage/index.js';
 export { StorageError, S3StorageProvider, AzureBlobStorageProvider, GCSStorageProvider, } from './storage/index.js';
+export { safeString, safeNumber, safeRecord, safeArray, safeStringUnion, } from './utils/safe-cast.js';
+export type { CodeRAGRuntime, RuntimeOptions } from './runtime.js';
+export { createRuntime, RuntimeError } from './runtime.js';
+export type { ScannedEntity, IndexScanResult, BenchmarkQueryType, GeneratedQuery, QueryGeneratorOptions, QueryEvalResult, QueryMetrics, AggregateEvalMetrics, QueryTypeBreakdown, BenchmarkReport, BenchmarkMetadata, SearchFn, BenchmarkProgressFn, } from './benchmarks/index.js';
+export { IndexScanError, parseIndexRows, buildCallerMap, buildTestMap, generateQueries, generateFindByNameQueries, generateFindByDescriptionQueries, generateFindCallersQueries, generateFindTestsQueries, generateFindImportsQueries, BenchmarkEvalError, computeQueryMetrics, computeAggregateMetrics as computeBenchmarkAggregateMetrics, computeQueryTypeBreakdown, runBenchmark, formatBenchmarkSummary, } from './benchmarks/index.js';
+export { PaginationMetaSchema, ChunkSummarySchema, ChunkDetailSchema, GraphNodeSchema, GraphEdgeSchema, ViewerSearchResultSchema, EmbeddingPointSchema, ViewerStatsResponseSchema, ViewerChunksResponseSchema, ViewerChunkDetailResponseSchema, ViewerSearchResponseSchema, ViewerGraphResponseSchema, ViewerEmbeddingsResponseSchema, } from './api-contracts/index.js';
+export type { ViewerPaginationMeta, ViewerChunkSummary, ViewerChunkDetail, ViewerGraphNode, ViewerGraphEdge, ViewerSearchResultType, ViewerEmbeddingPoint, ViewerStatsResponse, ViewerChunksResponse, ViewerChunkDetailResponse, ViewerSearchResponse, ViewerGraphResponse, ViewerEmbeddingsResponse, } from './api-contracts/index.js';

package/dist/index.js

@@ -13,3 +13,8 @@ export { ConfluenceError, ConfluenceProvider, confluenceStorageToPlainText, } fr
 export { SharePointError, SharePointProvider, extractTextFromDocx, extractTextFromPdf, } from './docs/index.js';
 export { ROLE_HIERARCHY, AuthError, RBACManager, OIDCProvider, SAMLProvider, AuditLogger } from './auth/index.js';
 export { StorageError, S3StorageProvider, AzureBlobStorageProvider, GCSStorageProvider, } from './storage/index.js';
+export { safeString, safeNumber, safeRecord, safeArray, safeStringUnion, } from './utils/safe-cast.js';
+export { createRuntime, RuntimeError } from './runtime.js';
+export { IndexScanError, parseIndexRows, buildCallerMap, buildTestMap, generateQueries, generateFindByNameQueries, generateFindByDescriptionQueries, generateFindCallersQueries, generateFindTestsQueries, generateFindImportsQueries, BenchmarkEvalError, computeQueryMetrics, computeAggregateMetrics as computeBenchmarkAggregateMetrics, computeQueryTypeBreakdown, runBenchmark, formatBenchmarkSummary, } from './benchmarks/index.js';
+// --- API Contracts (shared Zod schemas for viewer REST API) ---
+export { PaginationMetaSchema, ChunkSummarySchema, ChunkDetailSchema, GraphNodeSchema, GraphEdgeSchema, ViewerSearchResultSchema, EmbeddingPointSchema, ViewerStatsResponseSchema, ViewerChunksResponseSchema, ViewerChunkDetailResponseSchema, ViewerSearchResponseSchema, ViewerGraphResponseSchema, ViewerEmbeddingsResponseSchema, } from './api-contracts/index.js';

package/dist/retrieval/context-expander.d.ts

@@ -25,16 +25,18 @@ export interface ExpandedContext {
     relatedChunks: RelatedChunk[];
     graphExcerpt: GraphExcerpt;
 }
+/** Callback to resolve a chunk by its ID. May be sync or async (await handles both). */
+export type ChunkLookupFn = (chunkId: string) => SearchResult | undefined | Promise<SearchResult | undefined>;
 export declare class ContextExpander {
     private readonly graph;
     private readonly chunkLookup;
-    constructor(dependencyGraph: ReadonlyGraph, chunkLookup: (chunkId: string) => SearchResult | undefined);
+    constructor(dependencyGraph: ReadonlyGraph, chunkLookup: ChunkLookupFn);
     /**
      * Expand search results with graph-based context.
      * For each result, walks the dependency graph to find related chunks
      * and classifies their relationships.
      */
-    expand(results: SearchResult[], maxRelated?: number): ExpandedContext;
+    expand(results: SearchResult[], maxRelated?: number): Promise<ExpandedContext>;
     /**
      * Classify the relationship between two nodes based on graph edges and naming conventions.
      */

package/dist/retrieval/context-expander.js

@@ -11,7 +11,7 @@ export class ContextExpander {
      * For each result, walks the dependency graph to find related chunks
      * and classifies their relationships.
      */
-    expand(results, maxRelated = DEFAULT_MAX_RELATED) {
+    async expand(results, maxRelated = DEFAULT_MAX_RELATED) {
         const relatedMap = new Map();
         const graphNodes = new Set();
         const graphEdges = [];
@@ -30,7 +30,7 @@ export class ContextExpander {
                 // Don't add duplicates — keep the one with shortest distance
                 if (relatedMap.has(relatedId))
                     continue;
-                const relatedResult = this.chunkLookup(relatedId);
+                const relatedResult = await this.chunkLookup(relatedId);
                 if (!relatedResult)
                     continue;
                 const relationship = this.classifyRelationship(nodeId, relatedId);

package/dist/retrieval/index.d.ts

@@ -1,6 +1,6 @@
 export type { AnalyzedQuery, QueryIntent, QueryEntity } from './query-analyzer.js';
 export { QueryAnalyzer } from './query-analyzer.js';
-export type { ReadonlyGraph, RelationshipType, RelatedChunk, GraphExcerpt, ExpandedContext, } from './context-expander.js';
+export type { ReadonlyGraph, RelationshipType, RelatedChunk, GraphExcerpt, ExpandedContext, ChunkLookupFn, } from './context-expander.js';
 export { ContextExpander } from './context-expander.js';
 export type { TokenBudgetConfig, AssembledContext, } from './token-budget.js';
 export { TokenBudgetOptimizer } from './token-budget.js';

package/dist/runtime.d.ts

@@ -0,0 +1,37 @@
+import { type Result } from 'neverthrow';
+import { LanceDBStore } from './embedding/lancedb-store.js';
+import { HybridSearch } from './embedding/hybrid-search.js';
+import { ContextExpander, type ReadonlyGraph } from './retrieval/context-expander.js';
+import type { ReRanker } from './types/provider.js';
+import type { CodeRAGConfig } from './types/config.js';
+/** All services needed at query time, initialized and ready. */
+export interface CodeRAGRuntime {
+    readonly config: CodeRAGConfig;
+    readonly store: LanceDBStore;
+    readonly hybridSearch: HybridSearch;
+    readonly contextExpander: ContextExpander | null;
+    readonly reranker: ReRanker | null;
+    readonly graph: ReadonlyGraph;
+    /** Shut down all connections (LanceDB, etc.). */
+    close(): void;
+}
+export interface RuntimeOptions {
+    /** Project root directory (must contain .coderag.yaml). */
+    rootDir: string;
+    /**
+     * If true, skip context expander, reranker, and graph.
+     * Useful for CLI search where only HybridSearch is needed.
+     */
+    searchOnly?: boolean;
+}
+export declare class RuntimeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Initialize a CodeRAGRuntime with all services wired together.
+ *
+ * Loads config, creates embedding provider, connects LanceDB, loads BM25 index,
+ * builds HybridSearch, and optionally creates ContextExpander with a real
+ * chunkLookup backed by LanceDB, re-ranker, and dependency graph.
+ */
+export declare function createRuntime(options: RuntimeOptions): Promise<Result<CodeRAGRuntime, RuntimeError>>;

package/dist/runtime.js

@@ -0,0 +1,170 @@
+import { ok, err } from 'neverthrow';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { loadConfig } from './config/config-parser.js';
+import { OllamaEmbeddingProvider } from './embedding/ollama-embedding-provider.js';
+import { OpenAICompatibleEmbeddingProvider } from './embedding/openai-compatible-embedding-provider.js';
+import { LanceDBStore } from './embedding/lancedb-store.js';
+import { BM25Index } from './embedding/bm25-index.js';
+import { HybridSearch } from './embedding/hybrid-search.js';
+import { DependencyGraph } from './graph/dependency-graph.js';
+import { ContextExpander } from './retrieval/context-expander.js';
+import { CrossEncoderReRanker } from './retrieval/cross-encoder-reranker.js';
+import { safeString, safeStringUnion } from './utils/safe-cast.js';
+export class RuntimeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RuntimeError';
+    }
+}
+/**
+ * Build a ChunkLookupFn that resolves chunk IDs via LanceDB.
+ * Returns a SearchResult compatible with ContextExpander.
+ */
+function buildChunkLookup(store) {
+    return async (chunkId) => {
+        const result = await store.getById(chunkId);
+        if (result.isErr())
+            return undefined;
+        const row = result.value;
+        if (!row)
+            return undefined;
+        const meta = row.metadata;
+        const CHUNK_TYPES = ['function', 'method', 'class', 'module', 'interface', 'type_alias', 'config_block', 'import_block', 'doc'];
+        const storedChunkType = safeStringUnion(meta['chunk_type'], CHUNK_TYPES, 'function');
+        const storedName = safeString(meta['name'], '');
+        const storedFilePath = safeString(meta['file_path'], '');
+        const storedLanguage = safeString(meta['language'], 'unknown');
+        const storedContent = safeString(meta['content'], '');
+        const storedNlSummary = safeString(meta['nl_summary'], '');
+        const chunkMetadata = {
+            chunkType: storedChunkType,
+            name: storedName,
+            declarations: [],
+            imports: [],
+            exports: [],
+        };
+        return {
+            chunkId: row.id,
+            content: storedContent,
+            nlSummary: storedNlSummary,
+            score: 0,
+            method: 'hybrid',
+            metadata: chunkMetadata,
+            chunk: {
+                id: row.id,
+                content: storedContent,
+                nlSummary: storedNlSummary,
+                filePath: storedFilePath,
+                startLine: 0,
+                endLine: 0,
+                language: storedLanguage,
+                metadata: chunkMetadata,
+            },
+        };
+    };
+}
+/**
+ * Create an embedding provider from config.
+ * Supports 'ollama' and 'openai-compatible' providers.
+ * The 'auto' mode with lifecycle management is only used by the CLI index command.
+ */
+function createEmbeddingProvider(config) {
+    if (config.embedding.provider === 'openai-compatible' && config.embedding.openaiCompatible) {
+        return new OpenAICompatibleEmbeddingProvider({
+            baseUrl: config.embedding.openaiCompatible.baseUrl,
+            model: config.embedding.model,
+            dimensions: config.embedding.dimensions,
+            apiKey: config.embedding.openaiCompatible.apiKey,
+            maxBatchSize: config.embedding.openaiCompatible.maxBatchSize,
+        });
+    }
+    // Default to Ollama (covers 'ollama', 'auto', and any other value)
+    return new OllamaEmbeddingProvider({
+        model: config.embedding.model,
+        dimensions: config.embedding.dimensions,
+    });
+}
+/**
+ * Initialize a CodeRAGRuntime with all services wired together.
+ *
+ * Loads config, creates embedding provider, connects LanceDB, loads BM25 index,
+ * builds HybridSearch, and optionally creates ContextExpander with a real
+ * chunkLookup backed by LanceDB, re-ranker, and dependency graph.
+ */
+export async function createRuntime(options) {
+    const { rootDir, searchOnly = false } = options;
+    // --- Load config ---
+    const configResult = await loadConfig(rootDir);
+    if (configResult.isErr()) {
+        return err(new RuntimeError(`Config load failed: ${configResult.error.message}`));
+    }
+    const config = configResult.value;
+    // --- Resolve + validate storage path ---
+    const storagePath = resolve(rootDir, config.storage.path);
+    if (!storagePath.startsWith(resolve(rootDir))) {
+        return err(new RuntimeError('Storage path escapes project root'));
+    }
+    // --- Create embedding provider ---
+    const embeddingProvider = createEmbeddingProvider(config);
+    // --- Connect LanceDB ---
+    const store = new LanceDBStore(storagePath, config.embedding.dimensions);
+    try {
+        await store.connect();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return err(new RuntimeError(`LanceDB connection failed: ${message}`));
+    }
+    // --- Load BM25 index ---
+    let bm25Index = new BM25Index();
+    const bm25Path = join(storagePath, 'bm25-index.json');
+    try {
+        const bm25Data = await readFile(bm25Path, 'utf-8');
+        bm25Index = BM25Index.deserialize(bm25Data);
+    }
+    catch {
+        // No saved BM25 index, start empty
+    }
+    // --- Create HybridSearch ---
+    const hybridSearch = new HybridSearch(store, bm25Index, embeddingProvider, config.search);
+    // --- Optional: graph, reranker, context expander ---
+    let contextExpander = null;
+    let reranker = null;
+    let graph = new DependencyGraph();
+    if (!searchOnly) {
+        // Load dependency graph
+        const graphPath = join(storagePath, 'graph.json');
+        try {
+            const graphData = await readFile(graphPath, 'utf-8');
+            const parsed = JSON.parse(graphData);
+            if (parsed !== null && typeof parsed === 'object' && 'nodes' in parsed && 'edges' in parsed) {
+                graph = DependencyGraph.fromJSON(parsed);
+            }
+        }
+        catch {
+            // No saved graph, use empty
+        }
+        // Create re-ranker if enabled
+        if (config.reranker?.enabled) {
+            reranker = new CrossEncoderReRanker({
+                model: config.reranker.model,
+                topN: config.reranker.topN,
+            });
+        }
+        // Create context expander with REAL chunk lookup
+        const chunkLookup = buildChunkLookup(store);
+        contextExpander = new ContextExpander(graph, chunkLookup);
+    }
+    return ok({
+        config,
+        store,
+        hybridSearch,
+        contextExpander,
+        reranker,
+        graph,
+        close() {
+            store.close();
+        },
+    });
+}

package/dist/utils/safe-cast.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Runtime type-checking utilities to replace unsafe `as` type assertions.
+ *
+ * Each function validates the runtime type of an unknown value and returns
+ * a properly typed result, using a fallback when provided or throwing
+ * a descriptive TypeError when the value does not match.
+ */
+/**
+ * Safely extract a string from an unknown value.
+ * Returns the value if it is a string, the fallback if provided, or throws.
+ */
+export declare function safeString(value: unknown, fallback?: string): string;
+/**
+ * Safely extract a number from an unknown value.
+ * Returns the value if it is a finite number, the fallback if provided, or throws.
+ */
+export declare function safeNumber(value: unknown, fallback?: number): number;
+/**
+ * Safely extract a Record<string, unknown> from an unknown value.
+ * Returns the value if it is a non-null, non-array object, the fallback if provided, or throws.
+ */
+export declare function safeRecord(value: unknown, fallback?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Safely extract an array from an unknown value.
+ * Returns the value if it is an array, the fallback if provided, or throws.
+ */
+export declare function safeArray(value: unknown, fallback?: unknown[]): unknown[];
+/**
+ * Safely extract a string that must be one of the allowed values (union type guard).
+ * Returns the value if it matches, the fallback if provided, or throws.
+ */
+export declare function safeStringUnion<T extends string>(value: unknown, allowed: readonly T[], fallback?: T): T;

package/dist/utils/safe-cast.js

@@ -0,0 +1,76 @@
+/**
+ * Runtime type-checking utilities to replace unsafe `as` type assertions.
+ *
+ * Each function validates the runtime type of an unknown value and returns
+ * a properly typed result, using a fallback when provided or throwing
+ * a descriptive TypeError when the value does not match.
+ */
+/**
+ * Safely extract a string from an unknown value.
+ * Returns the value if it is a string, the fallback if provided, or throws.
+ */
+export function safeString(value, fallback) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (fallback !== undefined) {
+        return fallback;
+    }
+    throw new TypeError(`Expected string, got ${typeof value}`);
+}
+/**
+ * Safely extract a number from an unknown value.
+ * Returns the value if it is a finite number, the fallback if provided, or throws.
+ */
+export function safeNumber(value, fallback) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (fallback !== undefined) {
+        return fallback;
+    }
+    throw new TypeError(`Expected number, got ${typeof value}`);
+}
+/**
+ * Safely extract a Record<string, unknown> from an unknown value.
+ * Returns the value if it is a non-null, non-array object, the fallback if provided, or throws.
+ */
+export function safeRecord(value, fallback) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Runtime guard validates non-null, non-array object
+        return value;
+    }
+    if (fallback !== undefined) {
+        return fallback;
+    }
+    throw new TypeError(`Expected record (object), got ${value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value}`);
+}
+/**
+ * Safely extract an array from an unknown value.
+ * Returns the value if it is an array, the fallback if provided, or throws.
+ */
+export function safeArray(value, fallback) {
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (fallback !== undefined) {
+        return fallback;
+    }
+    throw new TypeError(`Expected array, got ${typeof value}`);
+}
+/**
+ * Safely extract a string that must be one of the allowed values (union type guard).
+ * Returns the value if it matches, the fallback if provided, or throws.
+ */
+export function safeStringUnion(value, allowed, fallback) {
+    if (typeof value === 'string') {
+        const matched = allowed.find((item) => item === value);
+        if (matched !== undefined) {
+            return matched;
+        }
+    }
+    if (fallback !== undefined) {
+        return fallback;
+    }
+    throw new TypeError(`Expected one of [${allowed.join(', ')}], got ${typeof value === 'string' ? `"${value}"` : typeof value}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-rag/core",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Core library for CodeRAG — intelligent codebase context engine with AST parsing, embeddings, and hybrid search",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./api-contracts": {
+      "import": "./dist/api-contracts/index.js",
+      "types": "./dist/api-contracts/index.d.ts"
     }
   },
   "dependencies": {