Legacy library
This page describes the old TypeScript @sylphx/coderag library. It is not the Locus MCP server. The live server is local Rust BM25 in @sylphx/locus. Start at the quickstart.
TypeScript Types
Comprehensive type definitions for Locus API.
Indexer Types
IndexerOptions
Configuration for CodebaseIndexer constructor.
interface IndexerOptions {
codebaseRoot?: string // Root directory (default: process.cwd())
maxFileSize?: number // Max file size in bytes (default: 1MB)
storage?: Storage // Storage implementation (default: MemoryStorage)
onProgress?: (current: number, total: number, file: string) => void
watch?: boolean // Enable file watching (default: false)
onFileChange?: (event: FileChangeEvent) => void
embeddingProvider?: EmbeddingProvider // Optional for vector search
vectorBatchSize?: number // Embedding batch size (default: 10)
indexingBatchSize?: number // Files per batch (default: 50)
lowMemoryMode?: boolean // Use SQL search (default: true with PersistentStorage)
}IndexingStatus
Current indexing progress.
interface IndexingStatus {
isIndexing: boolean // Currently indexing
progress: number // 0-100
totalFiles: number // Total files found
processedFiles: number // Files processed
totalChunks: number // Total chunks created
indexedChunks: number // Chunks indexed
currentFile?: string // Current file being processed
}FileChangeEvent
File system change event.
interface FileChangeEvent {
type: 'add' | 'change' | 'unlink'
path: string
timestamp: number
}FileDiff
Filesystem diff result for incremental updates.
interface FileDiff {
added: FileMetadata[] // New files
changed: FileMetadata[] // Modified files
deleted: string[] // Deleted file paths
unchanged: number // Unchanged file count
}SearchResult
Search result from CodebaseIndexer.search().
interface SearchResult {
path: string // File path
score: number // Relevance score
matchedTerms: string[] // Matched query terms
language?: string // Detected language
size: number // Content size
snippet?: string // Code snippet with line numbers
chunkType?: string // AST node type (e.g., 'FunctionDeclaration')
startLine?: number // Chunk start line
endLine?: number // Chunk end line
}Storage Types
Storage
Storage interface implemented by PersistentStorage and MemoryStorage.
interface Storage {
storeFile(file: CodebaseFile): Promise<void>
storeFiles?(files: CodebaseFile[]): Promise<void>
getFile(path: string): Promise<CodebaseFile | null>
getAllFiles(): Promise<CodebaseFile[]>
deleteFile(path: string): Promise<void>
clear(): Promise<void>
count(): Promise<number>
getChunkCount?(): Promise<number>
exists(path: string): Promise<boolean>
}CodebaseFile
Stored file representation.
interface CodebaseFile {
path: string // Relative file path
content: string // File content
size: number // File size in bytes
mtime: number | Date // Modification time
language?: string // Detected language
hash: string // Content hash
}DbConfig
Database configuration for PersistentStorage.
interface DbConfig {
codebaseRoot?: string // Project root (default: process.cwd())
dbPath?: string // Custom database path (optional)
}ChunkData
Chunk data for storage.
interface ChunkData {
content: string
type: string // AST node type
startLine: number
endLine: number
metadata?: Record<string, unknown>
}StoredChunk
Chunk with database ID.
interface StoredChunk extends ChunkData {
id: number // Chunk ID
fileId: number // Parent file ID
filePath: string // File path
}Search Types
HybridSearchOptions
Options for hybrid search.
interface HybridSearchOptions {
limit?: number // Max results (default: 10)
minScore?: number // Min relevance score (default: 0.01)
vectorWeight?: number // 0-1, vector vs TF-IDF (default: 0.7)
includeContent?: boolean // Include snippets (default: false)
fileExtensions?: string[] // Filter by extension
pathFilter?: string // Include paths containing string
excludePaths?: string[] // Exclude paths
}HybridSearchResult
Result from hybrid search.
interface HybridSearchResult {
path: string
score: number
method: 'vector' | 'tfidf' | 'hybrid'
matchedTerms?: string[]
similarity?: number
content?: string
chunkType?: string
startLine?: number
endLine?: number
language?: string
}SearchIndex
TF-IDF search index structure.
interface SearchIndex {
documents: DocumentVector[]
idf: Map<string, number>
totalDocuments: number
metadata: {
generatedAt: string
version: string
}
}DocumentVector
TF-IDF document vector.
interface DocumentVector {
uri: string
magnitude: number
rawTerms: Map<string, number>
tfidf: Map<string, number>
}Embedding Types
EmbeddingConfig
Embedding provider configuration.
interface EmbeddingConfig {
provider: 'openai' | 'openai-compatible' | 'mock'
model: string // Model name
dimensions: number // Vector dimensions
apiKey?: string // API key
baseURL?: string // Custom endpoint for OpenAI-compatible APIs
batchSize?: number // Embedding batch size (default: 10)
}EmbeddingProvider
Embedding provider interface.
interface EmbeddingProvider {
name: string
model: string
dimensions: number
generateEmbedding(text: string): Promise<number[]>
generateEmbeddings(texts: string[]): Promise<number[][]>
}Vector Storage Types
VectorStorageOptions
Configuration for vector storage.
interface VectorStorageOptions {
dimensions: number // Vector dimensions
dbPath: string // LanceDB path
}VectorDocument
Document with embedding.
interface VectorDocument {
id: string
embedding: number[]
metadata: Record<string, unknown>
}VectorSearchResult
Vector search result.
interface VectorSearchResult {
doc: VectorDocument
similarity: number
}VectorStorageStats
Vector storage statistics.
interface VectorStorageStats {
documentCount: number
dimensions: number
}Chunking Types
ASTChunkOptions
Options for AST-based chunking.
interface ASTChunkOptions {
maxChunkSize?: number // Max chunk chars (default: 1000)
minChunkSize?: number // Min chunk chars (default: 100)
preserveContext?: boolean // Include imports/types (default: true)
nodeTypes?: string[] // Custom AST node types to chunk
parseEmbedded?: boolean // Parse code in markdown (default: true)
}ChunkResult
Chunk with metadata.
interface ChunkResult {
content: string // Chunk content
type: string // AST node type
startLine: number // Start line (1-indexed)
endLine: number // End line (inclusive)
metadata: Record<string, unknown> // Additional metadata
}Language Configuration Types
LanguageConfig
Language-specific configuration.
interface LanguageConfig {
parser: string // Parser module name
boundaries: string[] // AST node types for semantic boundaries
contextTypes?: string[] // Node types to preserve as context
parserOptions?: Record<string, unknown>
embedded?: EmbeddedLanguageConfig[]
}EmbeddedLanguageConfig
Configuration for embedded code parsing.
interface EmbeddedLanguageConfig {
nodeType: string // Parent node type
langAttr?: string // Attribute containing language name
defaultLanguage?: string // Default language if not specified
recursive?: boolean // Enable recursive parsing
}TF-IDF Types
IncrementalUpdate
Update operation for incremental TF-IDF.
interface IncrementalUpdate {
type: 'add' | 'update' | 'delete'
uri: string
newContent?: string
oldDocument?: DocumentVector
}IncrementalStats
Statistics from incremental update.
interface IncrementalStats {
affectedDocuments: number
affectedTerms: number
updateTime: number
}Utility Types
ScanOptions
Options for file scanning.
interface ScanOptions {
ignoreFilter?: Ignore
codebaseRoot?: string
maxFileSize?: number
}ScanResult
File scan result.
interface ScanResult {
path: string
size: number
}FileMetadata
File metadata without content.
interface FileMetadata {
path: string
absolutePath: string
size: number
mtime: number
language?: string
}ProjectMetadata
Project metadata for database location.
interface ProjectMetadata {
codebaseRoot: string
hash: string
dataDir: string
}Cache Types
CacheEntry
LRU cache entry.
interface CacheEntry<T> {
value: T
timestamp: number
}CacheStats
Cache statistics.
interface CacheStats {
hits: number
misses: number
size: number
maxSize: number
}Type Guards
Useful type guards for working with Locus types.
function isPersistentStorage(storage: Storage): storage is PersistentStorage {
return 'storeChunks' in storage
}
function hasChunkMetadata(result: SearchResult): result is SearchResult & {
chunkType: string
startLine: number
endLine: number
} {
return result.chunkType !== undefined &&
result.startLine !== undefined &&
result.endLine !== undefined
}
function isHybridResult(result: HybridSearchResult): boolean {
return result.method === 'hybrid'
}Generic Types
// Storage key-value types
type StorageKey = string
type StorageValue = string | number | boolean | null
// Vector types
type Vector = number[]
type VectorId = string
// Score types
type Score = number // 0-1 for cosine similarity, unbounded for TF-IDF/BM25
type Similarity = number // -1 to 1 for cosine similarity
// Path types
type FilePath = string
type AbsolutePath = string
type RelativePath = stringConstants
// Default values
const DEFAULT_MAX_FILE_SIZE = 1048576 // 1MB
const DEFAULT_MAX_CHUNK_SIZE = 1000
const DEFAULT_MIN_CHUNK_SIZE = 100
const DEFAULT_VECTOR_BATCH_SIZE = 10
const DEFAULT_INDEXING_BATCH_SIZE = 50
const DEFAULT_SEARCH_LIMIT = 10
const DEFAULT_VECTOR_WEIGHT = 0.7
// BM25 parameters
const BM25_K1 = 1.2
const BM25_B = 0.75Usage Examples
Type-Safe Indexer Configuration
import type { IndexerOptions, EmbeddingConfig } from '@sylphx/coderag'
const embeddingConfig: EmbeddingConfig = {
provider: 'openai',
model: 'text-embedding-3-small',
dimensions: 1536,
apiKey: process.env.OPENAI_API_KEY
}
const indexerOptions: IndexerOptions = {
codebaseRoot: './src',
maxFileSize: 2 * 1024 * 1024,
watch: true,
onProgress: (current, total, file) => {
console.log(`${current}/${total}: ${file}`)
}
}Type-Safe Search
import type { SearchResult, HybridSearchOptions } from '@sylphx/coderag'
const options: HybridSearchOptions = {
limit: 20,
vectorWeight: 0.7,
fileExtensions: ['.ts', '.tsx']
}
const results: SearchResult[] = await indexer.search('auth', options)
for (const result of results) {
if (hasChunkMetadata(result)) {
console.log(`${result.chunkType} at ${result.startLine}`)
}
}Type-Safe Storage
import type { CodebaseFile, StoredChunk } from '@sylphx/coderag'
const file: CodebaseFile = {
path: 'src/index.ts',
content: code,
size: code.length,
mtime: Date.now(),
language: 'typescript',
hash: computeHash(code)
}
await storage.storeFile(file)
const chunks: StoredChunk[] = await storage.getChunksForFile(file.path)