opencode-codebase-index 0.5.0 → 0.5.2

package/README.md

@@ -16,8 +16,8 @@
 - ⚡ **Blazing Fast Indexing**: Powered by a Rust native module using `tree-sitter` and `usearch`. Incremental updates take milliseconds.
 - 🌿 **Branch-Aware**: Seamlessly handles git branch switches — reuses embeddings, filters stale results.
 - 🔒 **Privacy Focused**: Your vector index is stored locally in your project.
- 🔌 **Model Agnostic**: Works out-of-the-box with GitHub Copilot, OpenAI, Gemini, or local Ollama models.
- 🌐 **MCP Server**: Use with Cursor, Claude Code, Windsurf, or any MCP-compatible client — index once, search from anywhere.
+- 🔌 **Model Agnostic**: Works out-of-the-box with GitHub Copilot, OpenAI, Gemini, or local Ollama models.
+- 🌐 **MCP Server**: Use with Cursor, Claude Code, Windsurf, or any MCP-compatible client — index once, search from anywhere.
 
 ## ⚡ Quick Start
 
@@ -82,7 +82,7 @@ Use the same semantic search from any MCP-compatible client. Index once, search
    npx opencode-codebase-index-mcp                            # uses current directory
    ```
 
-The MCP server exposes all 8 tools (`codebase_search`, `codebase_peek`, `find_similar`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`) and 4 prompts (`search`, `find`, `index`, `status`).
+The MCP server exposes all 9 tools (`codebase_search`, `codebase_peek`, `find_similar`, `call_graph`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`) and 4 prompts (`search`, `find`, `index`, `status`).
 
 The MCP dependencies (`@modelcontextprotocol/sdk`, `zod`) are optional peer dependencies — they're only needed if you use the MCP server.
 
@@ -112,6 +112,7 @@ src/api/checkout.ts:89      (Route handler for /pay)
 | Don't know the function name | `codebase_search` | Semantic search finds by meaning |
 | Exploring unfamiliar codebase | `codebase_search` | Discovers related code across files |
 | Just need to find locations | `codebase_peek` | Returns metadata only, saves ~90% tokens |
+| Understand code flow | `call_graph` | Find callers/callees of any function |
 | Know exact identifier | `grep` | Faster, finds all occurrences |
 | Need ALL matches | `grep` | Semantic returns top N only |
 | Mixed discovery + precision | `/find` (hybrid) | Best of both worlds |
@@ -157,10 +158,11 @@ graph TD
     Q[User Query] -->|Embedding Model| V[Query Vector]
     V -->|Cosine Similarity| D
     Q -->|BM25| E
-    G -->|Branch Filter| F
-    D --> F[Hybrid Fusion]
+    D --> F[Hybrid Fusion RRF/Weighted]
     E --> F
-    F --> R[Ranked Results]
+    F --> X[Deterministic Rerank]
+    G -->|Branch + Metadata Filters| X
+    X --> R[Ranked Results]
     end
 ```
 
@@ -170,7 +172,7 @@ graph TD
 2. **Chunking**: Large blocks are split with overlapping windows to preserve context across chunk boundaries.
 3. **Embedding**: These blocks are converted into vector representations using your configured AI provider.
 4. **Storage**: Embeddings are stored in SQLite (deduplicated by content hash) and vectors in `usearch` with F16 quantization for 50% memory savings. A branch catalog tracks which chunks exist on each branch.
-5. **Hybrid Search**: Combines semantic similarity (vectors) with BM25 keyword matching, filtered by current branch.
+5. **Hybrid Search**: Combines semantic similarity (vectors) with BM25 keyword matching, fuses (`rrf` default, `weighted` fallback), applies deterministic rerank, then filters by current branch/metadata.
 
 **Performance characteristics:**
 - **Incremental indexing**: ~50ms check time — only re-embeds changed files
@@ -211,7 +213,7 @@ When you switch branches, code changes but embeddings for unchanged content rema
 
 ```
 .opencode/index/
-├── codebase.db           # SQLite: embeddings, chunks, branch catalog
+├── codebase.db           # SQLite: embeddings, chunks, branch catalog, symbols, call edges
 ├── vectors.usearch       # Vector index (uSearch)
 ├── inverted-index.json   # BM25 keyword index
 └── file-hashes.json      # File change detection
@@ -225,6 +227,7 @@ The plugin exposes these tools to the OpenCode agent:
 **The primary tool.** Searches code by describing behavior.
 - **Use for**: Discovery, understanding flows, finding logic when you don't know the names.
 - **Example**: `"find the middleware that sanitizes input"`
+- **Ranking path**: hybrid retrieval → fusion (`search.fusionStrategy`) → deterministic rerank (`search.rerankTopN`) → filters
 
 **Writing good queries:**
 
@@ -239,6 +242,7 @@ The plugin exposes these tools to the OpenCode agent:
 ### `codebase_peek`
 **Token-efficient discovery.** Returns only metadata (file, line, name, type) without code content.
 - **Use for**: Finding WHERE code is before deciding what to read. Saves ~90% tokens vs `codebase_search`.
+- **Ranking path**: same hybrid ranking path as `codebase_search` (metadata-only output)
 - **Example output**:
   ```
   [1] function "validatePayment" at src/billing.ts:45-67 (score: 0.92)
@@ -248,6 +252,11 @@ The plugin exposes these tools to the OpenCode agent:
   ```
 - **Workflow**: `codebase_peek` → find locations → `Read` specific files
 
+### `find_similar`
+Find code similar to a provided snippet.
+- **Use for**: Duplicate detection, refactor prep, pattern mining.
+- **Ranking path**: semantic retrieval only + deterministic rerank (no BM25, no RRF).
+
 ### `index_codebase`
 Manually trigger indexing.
 - **Use for**: Forcing a re-index or checking stats.
@@ -267,6 +276,12 @@ Returns collected metrics about indexing and search performance. Requires `debug
 Returns recent debug logs with optional filtering.
 - **Parameters**: `category` (optional: `search`, `embedding`, `cache`, `gc`, `branch`), `level` (optional: `error`, `warn`, `info`, `debug`), `limit` (default: 50).
 
+### `call_graph`
+Query the call graph to find callers or callees of a function/method. Automatically built during indexing for TypeScript, JavaScript, Python, Go, and Rust.
+- **Use for**: Understanding code flow, tracing dependencies, impact analysis.
+- **Parameters**: `name` (function name), `direction` (`callers` or `callees`), `symbolId` (required for `callees`, returned by previous queries).
+- **Example**: Find who calls `validateToken` → `call_graph(name="validateToken", direction="callers")`
+
 ## 🎮 Slash Commands
 
 The plugin automatically registers these slash commands:
@@ -301,6 +316,9 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
     "maxResults": 20,
     "minScore": 0.1,
     "hybridWeight": 0.5,
+    "fusionStrategy": "rrf",
+    "rrfK": 60,
+    "rerankTopN": 20,
     "contextLines": 0
   },
   "debug": {
@@ -315,7 +333,7 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `embeddingProvider` | `"auto"` | Which AI to use: `auto`, `github-copilot`, `openai`, `google`, `ollama` |
+| `embeddingProvider` | `"auto"` | Which AI to use: `auto`, `github-copilot`, `openai`, `google`, `ollama`, `custom` |
 | `scope` | `"project"` | `project` = index per repo, `global` = shared index across repos |
 | **indexing** | | |
 | `autoIndex` | `false` | Automatically index on plugin load |
@@ -333,6 +351,9 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 | `maxResults` | `20` | Maximum results to return |
 | `minScore` | `0.1` | Minimum similarity score (0-1). Lower = more results |
 | `hybridWeight` | `0.5` | Balance between keyword (1.0) and semantic (0.0) search |
+| `fusionStrategy` | `"rrf"` | Hybrid fusion mode: `"rrf"` (rank-based reciprocal rank fusion) or `"weighted"` (legacy score blending fallback) |
+| `rrfK` | `60` | RRF smoothing constant. Higher values flatten rank impact, lower values prioritize top-ranked candidates more strongly |
+| `rerankTopN` | `20` | Deterministic rerank depth cap. Applies lightweight name/path/chunk-type rerank to top-N only |
 | `contextLines` | `0` | Extra lines to include before/after each match |
 | **debug** | | |
 | `enabled` | `false` | Enable debug logging and metrics collection |
@@ -344,6 +365,15 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 | `logBranch` | `true` | Log branch detection and switches |
 | `metrics` | `false` | Enable metrics collection (indexing stats, search timing, cache performance) |
 
+### Retrieval ranking behavior (Phase 1)
+
+- `codebase_search` and `codebase_peek` use the hybrid path: semantic + keyword retrieval → fusion (`fusionStrategy`) → deterministic rerank (`rerankTopN`) → filtering.
+- `find_similar` stays semantic-only: semantic retrieval + deterministic rerank only (no keyword retrieval, no RRF).
+- For compatibility rollbacks, set `search.fusionStrategy` to `"weighted"` to use the legacy weighted fusion path.
+- Retrieval benchmark artifacts are separated by role:
+  - baseline (versioned): `benchmarks/baselines/retrieval-baseline.json`
+  - latest candidate run (generated): `benchmark-results/retrieval-candidate.json`
+
 ### Embedding Providers
 The plugin automatically detects available credentials in this order:
 1. **GitHub Copilot** (Free if you have it)
@@ -351,6 +381,8 @@ The plugin automatically detects available credentials in this order:
 3. **Google** (Gemini Embeddings)
 4. **Ollama** (Local/Private - requires `nomic-embed-text`)
 
+You can also use **Custom** to connect any OpenAI-compatible embedding endpoint (llama.cpp, vLLM, text-embeddings-inference, LiteLLM, etc.).
+
 ### Rate Limits by Provider
 
 Each provider has different rate limits. The plugin automatically adjusts concurrency and delays:
@@ -361,6 +393,7 @@ Each provider has different rate limits. The plugin automatically adjusts concur
 | **OpenAI** | 3 | 500ms | Medium codebases |
 | **Google** | 5 | 200ms | Medium-large codebases |
 | **Ollama** | 5 | None | Large codebases (10k+ files) |
+| **Custom** | 3 | 1s | Any OpenAI-compatible endpoint |
 
 **For large codebases**, use Ollama locally to avoid rate limits:
 
@@ -460,6 +493,7 @@ Use this decision tree to pick the right embedding provider:
 | **GitHub Copilot** | Slow (rate limited) | Free* | Cloud | Small codebases, existing subscribers |
 | **OpenAI** | Medium | ~$0.0001/1K tokens | Cloud | General use |
 | **Google** | Fast | Free tier available | Cloud | Medium-large codebases |
+| **Custom** | Varies | Varies | Varies | Self-hosted or third-party endpoints |
 
 *Requires active Copilot subscription
 
@@ -495,6 +529,23 @@ No setup needed if you have an active Copilot subscription.
 { "embeddingProvider": "github-copilot" }
 ```
 
+**Custom (OpenAI-compatible)**
+Works with any server that implements the OpenAI `/v1/embeddings` API format (llama.cpp, vLLM, text-embeddings-inference, LiteLLM, etc.).
+```json
+{
+  "embeddingProvider": "custom",
+  "customProvider": {
+    "baseUrl": "http://localhost:11434/v1",
+    "model": "nomic-embed-text",
+    "dimensions": 768,
+    "apiKey": "optional-api-key",
+    "maxTokens": 8192,
+    "timeoutMs": 30000
+  }
+}
+```
+Required fields: `baseUrl`, `model`, `dimensions` (positive integer). Optional: `apiKey`, `maxTokens`, `timeoutMs` (default: 30000).
+
 ## ⚠️ Tradeoffs
 
 Be aware of these characteristics:
@@ -564,12 +615,27 @@ CI will automatically run tests and type checking on your PR.
 The Rust native module handles performance-critical operations:
 - **tree-sitter**: Language-aware code parsing with JSDoc/docstring extraction
 - **usearch**: High-performance vector similarity search with F16 quantization
-- **SQLite**: Persistent storage for embeddings, chunks, and branch catalog
+- **SQLite**: Persistent storage for embeddings, chunks, branch catalog, symbols, and call edges
 - **BM25 inverted index**: Fast keyword search for hybrid retrieval
+- **Call graph extraction**: Tree-sitter query-based extraction of function calls, method calls, constructors, and imports (TypeScript/JavaScript, Python, Go, Rust)
 - **xxhash**: Fast content hashing for change detection
 
 Rebuild with: `npm run build:native` (requires Rust toolchain)
 
+### Platform Support
+
+Pre-built native binaries are published for:
+
+| Platform | Architecture | SIMD Acceleration |
+|----------|-------------|--------------------|
+| macOS | x86_64 | ✅ simsimd |
+| macOS | ARM64 (Apple Silicon) | ✅ simsimd |
+| Linux | x86_64 (GNU) | ✅ simsimd |
+| Linux | ARM64 (GNU) | ✅ simsimd |
+| Windows | x86_64 (MSVC) | ❌ scalar fallback |
+
+Windows builds use scalar distance functions instead of SIMD — functionally identical, marginally slower for very large indexes. This is due to MSVC lacking support for certain AVX-512 intrinsics used by simsimd.
+
 ## License
 
 MIT

package/commands/call-graph.md

@@ -0,0 +1,24 @@
+---
+description: Trace callers or callees using the call graph
+---
+
+Trace function dependencies using the `call_graph` tool.
+
+User input: $ARGUMENTS
+
+Interpret input as follows:
+- Default to `direction="callers"` unless input asks for callees/calls/makes calls.
+- `name=<function>` or plain text function name sets `name`.
+- `symbolId=<id>` is required for `direction="callees"`.
+
+Execution flow:
+1. If direction is `callers`, call `call_graph` with `{ name, direction: "callers" }`.
+2. If direction is `callees` and `symbolId` is present, call `call_graph` with `{ name, direction: "callees", symbolId }`.
+3. If direction is `callees` and `symbolId` is missing, first call `call_graph` with `direction="callers"` to get symbol IDs, then ask the user to choose one if multiple are returned.
+
+Examples:
+- `/call-graph Database` → callers for `Database`
+- `/call-graph callers name=Indexer` → callers for `Indexer`
+- `/call-graph callees name=Database symbolId=sym_abc123` → callees for selected symbol
+
+If output says no callers found, suggest running `/index force` first.