raggrep 0.1.0 → 0.1.4

package/README.md

@@ -1,15 +1,147 @@
-# raggrep
+# RAGgrep
 
-To install dependencies:
+**Local filesystem-based RAG system for codebases** — semantic search using local embeddings.
+
+RAGgrep indexes your code and allows semantic search using natural language queries. Everything runs locally on your machine — no external API calls required.
+
+## Features
+
+- **🏠 Local-first** — All indexing and search happens locally. No cloud dependencies.
+- **📁 Filesystem-based** — Index stored as readable JSON files alongside your code.
+- **⚡ Tiered search** — Fast keyword filtering + semantic search for efficiency.
+- **🔍 Hybrid scoring** — Combines semantic similarity with BM25 keyword matching.
+- **🔄 Incremental** — Only re-indexes files that have changed.
+- **📝 TypeScript-optimized** — AST-based parsing extracts functions, classes, interfaces, types.
+- **🎯 Zero config** — Works out of the box with sensible defaults.
+
+## Installation
 
 ```bash
-bun install
+# Install globally
+npm install -g raggrep
+
+# Or use without installing
+npx raggrep --help
 ```
 
-To run:
+## Quick Start
 
 ```bash
-bun run index.ts
+# Index your project
+cd your-project
+raggrep index
+
+# Search your codebase
+raggrep query "user authentication"
 ```
 
-This project was created using `bun init` in bun v1.3.0. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### Example Output
+
+```
+Found 3 results:
+
+1. src/auth/authService.ts:24-55 (login)
+   Score: 34.4% | Type: function | exported
+      export async function login(credentials: LoginCredentials): Promise<AuthResult> ...
+
+2. src/auth/authService.ts:60-62 (logout)
+   Score: 27.5% | Type: function | exported
+      export async function logout(token: string): Promise<void> {
+
+3. src/users/types.ts:3-12 (User)
+   Score: 26.0% | Type: interface | exported
+      export interface User {
+        id: string;
+```
+
+## Programmatic API
+
+```typescript
+import raggrep from "raggrep";
+
+// Index a directory
+await raggrep.index("./my-project");
+
+// Search
+const results = await raggrep.search("./my-project", "user authentication");
+console.log(raggrep.formatSearchResults(results));
+
+// Cleanup stale entries
+await raggrep.cleanup("./my-project");
+```
+
+## CLI Reference
+
+```bash
+# Index commands
+raggrep index                              # Index current directory
+raggrep index --watch                      # Watch mode: re-index on file changes
+raggrep index --model bge-small-en-v1.5    # Use different embedding model
+raggrep index --verbose                    # Show detailed progress
+
+# Search commands
+raggrep query "user login"                 # Basic search
+raggrep query "error handling" --top 5     # Limit results
+raggrep query "database" --min-score 0.1   # Lower threshold (more results)
+raggrep query "interface" --type ts        # Filter by file type
+
+# Maintenance
+raggrep cleanup                            # Remove stale index entries
+raggrep status                             # Show index status
+```
+
+## How It Works
+
+RAGgrep uses a two-tier index system:
+
+1. **Symbolic Index** — Lightweight file summaries with extracted keywords. Used for fast BM25 filtering.
+2. **Embedding Index** — Full chunk embeddings for semantic search. Only loaded for relevant files.
+
+This design keeps memory usage low and enables fast search on large codebases.
+
+```
+Query → BM25 filter (symbolic) → Load candidates → Semantic search → Results
+```
+
+## What Gets Indexed
+
+**File types:** `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, `.md`
+
+**Code structures:**
+
+- Functions (regular, async, arrow)
+- Classes (including abstract)
+- Interfaces
+- Type aliases
+- Enums
+- Exported variables
+
+**Automatically ignored:**
+
+- `node_modules`, `dist`, `build`, `.git`
+- `.next`, `.nuxt`, `__pycache__`, `venv`
+- See [Configuration](./docs/configuration.md) for full list
+
+## Documentation
+
+- [Getting Started](./docs/getting-started.md) — Installation and first steps
+- [CLI Reference](./docs/cli-reference.md) — All commands and options
+- [Configuration](./docs/configuration.md) — Customize indexing behavior
+- [Architecture](./docs/architecture.md) — How RAGgrep works internally
+
+## Performance
+
+| Operation                | Time       | Notes                                  |
+| ------------------------ | ---------- | -------------------------------------- |
+| Initial index (1k files) | 1-2 min    | Embedding generation is the bottleneck |
+| Incremental update       | <2s        | Only changed files                     |
+| Search                   | ~100-500ms | Depends on codebase size               |
+
+## Requirements
+
+- Node.js 18+
+- ~50MB disk space for models (cached globally)
+
+## License
+
+MIT

package/dist/{indexer → app/indexer}/index.d.ts

@@ -1,4 +1,4 @@
-import { EmbeddingModelName } from '../utils/embeddings';
+import type { EmbeddingModelName } from '../../domain/ports';
 export interface IndexResult {
     moduleId: string;
     indexed: number;
@@ -18,6 +18,24 @@ export interface CleanupResult {
     /** Number of valid entries kept */
     kept: number;
 }
+export interface IndexStatus {
+    /** Whether an index exists */
+    exists: boolean;
+    /** Root directory path */
+    rootDir: string;
+    /** Index directory path */
+    indexDir: string;
+    /** Last time the index was updated */
+    lastUpdated?: string;
+    /** Active modules and their file counts */
+    modules: Array<{
+        id: string;
+        fileCount: number;
+        lastUpdated: string;
+    }>;
+    /** Total number of indexed files */
+    totalFiles: number;
+}
 /**
  * Index a directory using all enabled modules
  */
@@ -31,3 +49,10 @@ export declare function indexDirectory(rootDir: string, options?: IndexOptions):
 export declare function cleanupIndex(rootDir: string, options?: {
     verbose?: boolean;
 }): Promise<CleanupResult[]>;
+/**
+ * Get the current status of the index
+ * @param rootDir - Root directory of the project
+ * @returns Index status information
+ */
+export declare function getIndexStatus(rootDir: string): Promise<IndexStatus>;
+export { watchDirectory, type WatchOptions, type FileWatcher } from './watcher';

package/dist/app/indexer/watcher.d.ts

@@ -0,0 +1,33 @@
+/**
+ * File watcher for incremental indexing
+ *
+ * Best practices implemented:
+ * - Debouncing: Batches rapid file changes (e.g., IDE saves, git operations)
+ * - Queuing: Prevents concurrent index operations
+ * - Efficient filtering: Only watches relevant file types
+ * - Graceful shutdown: Proper cleanup on SIGINT/SIGTERM
+ * - Error recovery: Continues watching after index errors
+ */
+import { type IndexOptions, type IndexResult } from './index';
+export interface WatchOptions extends IndexOptions {
+    /** Debounce delay in milliseconds (default: 300) */
+    debounceMs?: number;
+    /** Callback when indexing starts */
+    onIndexStart?: (files: string[]) => void;
+    /** Callback when indexing completes */
+    onIndexComplete?: (results: IndexResult[]) => void;
+    /** Callback when a file change is detected */
+    onFileChange?: (event: 'add' | 'change' | 'unlink', filepath: string) => void;
+    /** Callback for errors */
+    onError?: (error: Error) => void;
+}
+export interface FileWatcher {
+    /** Stop watching and clean up */
+    stop: () => Promise<void>;
+    /** Whether the watcher is currently running */
+    isRunning: () => boolean;
+}
+/**
+ * Start watching a directory for file changes and index incrementally
+ */
+export declare function watchDirectory(rootDir: string, options?: WatchOptions): Promise<FileWatcher>;

package/dist/{search → app/search}/index.d.ts

@@ -1,4 +1,4 @@
-import { SearchOptions, SearchResult } from '../types';
+import { SearchOptions, SearchResult } from '../../types';
 /**
  * Search across all enabled modules
  */