raggrep 0.1.0

package/dist/domain/ports/embedding.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Embedding Port
+ *
+ * Abstract interface for embedding generation.
+ * This allows the domain to remain independent of the actual embedding implementation
+ * (e.g., Transformers.js, OpenAI API, local models).
+ */
+/**
+ * Available embedding model names
+ */
+export type EmbeddingModelName = 'all-MiniLM-L6-v2' | 'all-MiniLM-L12-v2' | 'bge-small-en-v1.5' | 'paraphrase-MiniLM-L3-v2';
+/**
+ * Configuration for embedding provider
+ */
+export interface EmbeddingConfig {
+    /** Model name to use */
+    model: EmbeddingModelName;
+    /** Whether to show progress during model loading */
+    showProgress?: boolean;
+}
+/**
+ * Abstract embedding provider interface.
+ *
+ * Implementations might use:
+ * - Local models (Transformers.js)
+ * - Remote APIs (OpenAI, Cohere)
+ * - Custom models
+ */
+export interface EmbeddingProvider {
+    /**
+     * Generate embedding for a single text
+     * @returns Embedding vector (typically 384 dimensions for MiniLM)
+     */
+    getEmbedding(text: string): Promise<number[]>;
+    /**
+     * Generate embeddings for multiple texts (batched for efficiency)
+     * @returns Array of embedding vectors
+     */
+    getEmbeddings(texts: string[]): Promise<number[][]>;
+    /**
+     * Get the dimension of embeddings produced by this provider
+     */
+    getDimension(): number;
+    /**
+     * Get the current model name
+     */
+    getModelName(): string;
+    /**
+     * Initialize the provider (e.g., load model)
+     */
+    initialize?(config: EmbeddingConfig): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    dispose?(): Promise<void>;
+}
+/**
+ * Calculate cosine similarity between two vectors
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;

package/dist/domain/ports/filesystem.d.ts

@@ -0,0 +1,78 @@
+/**
+ * FileSystem Port
+ *
+ * Abstract interface for filesystem operations.
+ * This allows the domain to remain independent of the actual filesystem implementation.
+ */
+/**
+ * File statistics
+ */
+export interface FileStats {
+    /** ISO timestamp of last modification */
+    lastModified: string;
+    /** File size in bytes */
+    size?: number;
+}
+/**
+ * Abstract filesystem interface.
+ *
+ * All filesystem operations should go through this interface
+ * to maintain domain independence from Node.js fs module.
+ */
+export interface FileSystem {
+    /**
+     * Read a file's content as UTF-8 string
+     */
+    readFile(filepath: string): Promise<string>;
+    /**
+     * Write content to a file (creates directories if needed)
+     */
+    writeFile(filepath: string, content: string): Promise<void>;
+    /**
+     * Delete a file
+     */
+    deleteFile(filepath: string): Promise<void>;
+    /**
+     * Get file statistics
+     */
+    getStats(filepath: string): Promise<FileStats>;
+    /**
+     * Check if a file exists
+     */
+    exists(filepath: string): Promise<boolean>;
+    /**
+     * Create directory (and parent directories)
+     */
+    mkdir(dirpath: string): Promise<void>;
+    /**
+     * List files in a directory
+     */
+    readDir(dirpath: string): Promise<string[]>;
+    /**
+     * Find files matching patterns
+     * @param rootDir - Root directory to search from
+     * @param patterns - Glob patterns to match (e.g., ['**\/*.ts'])
+     * @param ignore - Patterns to ignore
+     */
+    findFiles(rootDir: string, patterns: string[], ignore: string[]): Promise<string[]>;
+    /**
+     * Join path segments
+     */
+    join(...segments: string[]): string;
+    /**
+     * Get relative path from one path to another
+     */
+    relative(from: string, to: string): string;
+    /**
+     * Resolve to absolute path
+     */
+    resolve(...segments: string[]): string;
+    /**
+     * Get directory name from path
+     */
+    dirname(filepath: string): string;
+    /**
+     * Get file extension
+     */
+    extname(filepath: string): string;
+}

package/dist/domain/ports/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Domain Ports
+ *
+ * Interfaces defining what the domain needs from external systems.
+ * These are implemented by infrastructure adapters.
+ */
+export type { FileSystem, FileStats } from './filesystem';
+export type { EmbeddingProvider, EmbeddingConfig, EmbeddingModelName } from './embedding';
+export { cosineSimilarity } from './embedding';
+export type { IndexStorage } from './storage';

package/dist/domain/ports/storage.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Index Storage Port
+ *
+ * Abstract interface for storing and retrieving index data.
+ * This allows the domain to remain independent of the actual storage implementation.
+ */
+import type { FileIndex, ModuleManifest, GlobalManifest, Config } from '../entities';
+import type { Tier1Manifest } from '../entities';
+/**
+ * Abstract index storage interface.
+ *
+ * Handles persistence of index data (Tier 1 and Tier 2).
+ * Implementations might use:
+ * - Filesystem (current)
+ * - SQLite
+ * - IndexedDB (for browser)
+ */
+export interface IndexStorage {
+    /**
+     * Load configuration from storage
+     */
+    loadConfig(): Promise<Config>;
+    /**
+     * Save configuration to storage
+     */
+    saveConfig(config: Config): Promise<void>;
+    /**
+     * Load global manifest
+     */
+    loadGlobalManifest(): Promise<GlobalManifest | null>;
+    /**
+     * Save global manifest
+     */
+    saveGlobalManifest(manifest: GlobalManifest): Promise<void>;
+    /**
+     * Load module manifest
+     */
+    loadModuleManifest(moduleId: string): Promise<ModuleManifest | null>;
+    /**
+     * Save module manifest
+     */
+    saveModuleManifest(moduleId: string, manifest: ModuleManifest): Promise<void>;
+    /**
+     * Load Tier 1 index for a module
+     */
+    loadTier1Index(moduleId: string): Promise<Tier1Manifest | null>;
+    /**
+     * Save Tier 1 index for a module
+     */
+    saveTier1Index(moduleId: string, manifest: Tier1Manifest): Promise<void>;
+    /**
+     * Load file index (Tier 2)
+     */
+    loadFileIndex(moduleId: string, filepath: string): Promise<FileIndex | null>;
+    /**
+     * Save file index (Tier 2)
+     */
+    saveFileIndex(moduleId: string, filepath: string, index: FileIndex): Promise<void>;
+    /**
+     * Delete file index
+     */
+    deleteFileIndex(moduleId: string, filepath: string): Promise<void>;
+    /**
+     * List all indexed files for a module
+     */
+    listIndexedFiles(moduleId: string): Promise<string[]>;
+    /**
+     * Check if index exists for this project
+     */
+    indexExists(): Promise<boolean>;
+    /**
+     * Delete entire index
+     */
+    deleteIndex(): Promise<void>;
+    /**
+     * Get the root directory being indexed
+     */
+    getRootDir(): string;
+}

package/dist/domain/services/bm25.d.ts

@@ -0,0 +1,82 @@
+/**
+ * BM25 (Best Matching 25) Implementation
+ *
+ * A ranking function for keyword-based search. This is a pure domain service
+ * with no external dependencies - just algorithms operating on data.
+ *
+ * BM25 estimates relevance of documents to a search query using term frequency
+ * and inverse document frequency with length normalization.
+ */
+/**
+ * Tokenize text into normalized terms.
+ *
+ * @param text - Text to tokenize
+ * @returns Array of lowercase tokens
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Document data for BM25 scoring.
+ */
+export interface BM25Document {
+    id: string;
+    content: string;
+    /** Pre-computed tokens (optional, computed from content if not provided) */
+    tokens?: string[];
+}
+/**
+ * BM25 search result.
+ */
+export interface BM25Result {
+    id: string;
+    score: number;
+}
+/**
+ * BM25 search index.
+ *
+ * This is a pure in-memory data structure with no I/O operations.
+ * Build the index by adding documents, then search against it.
+ */
+export declare class BM25Index {
+    private documents;
+    private avgDocLength;
+    private documentFrequencies;
+    private totalDocs;
+    /**
+     * Add documents to the index.
+     *
+     * @param documents - Array of documents to index
+     */
+    addDocuments(documents: BM25Document[]): void;
+    /**
+     * Calculate IDF (Inverse Document Frequency) for a term.
+     */
+    private idf;
+    /**
+     * Calculate BM25 score for a document given query terms.
+     */
+    private score;
+    /**
+     * Search the index with a query.
+     *
+     * @param query - Search query
+     * @param topK - Maximum number of results to return
+     * @returns Sorted array of results (highest score first)
+     */
+    search(query: string, topK?: number): BM25Result[];
+    /**
+     * Get the number of indexed documents.
+     */
+    get size(): number;
+    /**
+     * Clear the index.
+     */
+    clear(): void;
+}
+/**
+ * Normalize a raw score to 0-1 range using sigmoid function.
+ *
+ * @param score - Raw score
+ * @param midpoint - Score at which output is 0.5
+ * @returns Normalized score between 0 and 1
+ */
+export declare function normalizeScore(score: number, midpoint?: number): number;

package/dist/domain/services/bm25.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for BM25 search implementation
+ */
+export {};

package/dist/domain/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Domain Services
+ *
+ * Pure algorithms and business logic with no external dependencies.
+ * These services operate only on domain entities and primitive data.
+ */
+export { BM25Index, tokenize, normalizeScore, type BM25Document, type BM25Result, } from './bm25';
+export { extractKeywords, extractPathKeywords, COMMON_KEYWORDS, } from './keywords';

package/dist/domain/services/keywords.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Keyword Extraction Service
+ *
+ * Pure domain service for extracting keywords from code.
+ * No external dependencies - operates only on string data.
+ */
+/**
+ * Common programming keywords to exclude from keyword extraction.
+ * These appear in almost every code file and don't add search value.
+ */
+export declare const COMMON_KEYWORDS: Set<string>;
+/**
+ * Extract keywords from code content and optional name.
+ *
+ * @param content - Code content to extract keywords from
+ * @param name - Optional name (function name, class name, etc.)
+ * @param maxKeywords - Maximum keywords to return (default: 50)
+ * @returns Array of unique lowercase keywords
+ */
+export declare function extractKeywords(content: string, name?: string, maxKeywords?: number): string[];
+/**
+ * Extract keywords from a file path.
+ *
+ * @param filepath - File path to extract keywords from
+ * @returns Array of keywords from path segments
+ */
+export declare function extractPathKeywords(filepath: string): string[];

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * RAGgrep - Local filesystem-based RAG system for codebases
+ *
+ * Provides semantic search over code using local embeddings.
+ *
+ * @example
+ * ```ts
+ * import raggrep from 'raggrep';
+ *
+ * // Index a directory
+ * await raggrep.index('/path/to/project');
+ *
+ * // Search the index
+ * const results = await raggrep.search('/path/to/project', 'user authentication');
+ *
+ * // Clean up stale entries
+ * await raggrep.cleanup('/path/to/project');
+ * ```
+ */
+import type { IndexResult, IndexOptions, CleanupResult } from './indexer';
+import { formatSearchResults } from './search';
+import type { SearchOptions, SearchResult } from './types';
+export type { IndexResult, IndexOptions, CleanupResult } from './indexer';
+export type { SearchOptions, SearchResult, Chunk, FileIndex } from './types';
+/**
+ * Index a directory for semantic search.
+ *
+ * Creates a `.raggrep/` folder with the index data.
+ *
+ * @param directory - Path to the directory to index
+ * @param options - Index options
+ * @returns Array of results per module
+ *
+ * @example
+ * ```ts
+ * // Basic indexing
+ * await raggrep.index('./my-project');
+ *
+ * // With options
+ * await raggrep.index('./my-project', {
+ *   model: 'bge-small-en-v1.5',
+ *   verbose: true
+ * });
+ * ```
+ */
+export declare function index(directory: string, options?: IndexOptions): Promise<IndexResult[]>;
+/**
+ * Search the indexed codebase.
+ *
+ * @param directory - Path to the indexed directory
+ * @param query - Natural language search query
+ * @param options - Search options
+ * @returns Array of search results sorted by relevance
+ *
+ * @example
+ * ```ts
+ * // Basic search
+ * const results = await raggrep.search('./my-project', 'user login');
+ *
+ * // With options
+ * const results = await raggrep.search('./my-project', 'database query', {
+ *   topK: 5,
+ *   minScore: 0.2,
+ *   filePatterns: ['*.ts']
+ * });
+ * ```
+ */
+export declare function search(directory: string, query: string, options?: SearchOptions): Promise<SearchResult[]>;
+/**
+ * Clean up stale index entries for files that no longer exist.
+ *
+ * @param directory - Path to the indexed directory
+ * @param options - Cleanup options
+ * @returns Array of cleanup results per module
+ *
+ * @example
+ * ```ts
+ * const results = await raggrep.cleanup('./my-project');
+ * console.log(`Removed ${results[0].removed} stale entries`);
+ * ```
+ */
+export declare function cleanup(directory: string, options?: {
+    verbose?: boolean;
+}): Promise<CleanupResult[]>;
+/**
+ * Format search results for display.
+ *
+ * @param results - Array of search results
+ * @returns Formatted string for console output
+ */
+export { formatSearchResults };
+declare const raggrep: {
+    index: typeof index;
+    search: typeof search;
+    cleanup: typeof cleanup;
+    formatSearchResults: typeof formatSearchResults;
+};
+export default raggrep;