opencode-codebase-index 0.5.1 → 0.5.2

package/README.md

@@ -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": {
@@ -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)
@@ -585,8 +615,9 @@ 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)

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.