opencode-codebase-index 0.8.1 → 0.10.0

package/README.md

@@ -211,7 +211,9 @@ graph TD
 
 1. **Parsing**: We use `tree-sitter` to intelligently parse your code into meaningful blocks (functions, classes, interfaces). JSDoc comments and docstrings are automatically included with their associated code.
 
-**Supported Languages (Tree-sitter semantic parsing)**: TypeScript, JavaScript, Python, Rust, Go, Java, C#, Ruby, PHP, Apex, Bash, C, C++, JSON, TOML, YAML, Zig
+**Supported Languages (Tree-sitter semantic parsing)**: TypeScript, JavaScript, Python, Rust, Go, Java, C#, Ruby, PHP, Apex, Bash, C, C++, JSON, TOML, YAML, Zig, GDScript, MATLAB†
+
+† MATLAB (`.m`) is opt-in — see below.
 
 **Additional Supported Formats (line-based chunking)**: TXT, HTML, HTM, Markdown, Shell scripts
 
@@ -223,11 +225,16 @@ graph TD
 **/*.{sql,graphql,proto}        **/*.{yaml,yml,toml}
 **/*.{md,mdx}                   **/*.{sh,bash,zsh}
 **/*.{txt,html,htm}              **/*.{cls,trigger}
-**/*.zig
+**/*.zig                         **/*.gd
 ```
 
 Use `include` to replace defaults, or `additionalInclude` to extend (e.g. `"**/*.pdf"`, `"**/*.csv"`).
 
+†**MATLAB opt-in**: `.m` is excluded from defaults because it conflicts with the Objective-C extension used on Apple codebases. To enable MATLAB discovery, add to your global config (`~/.config/opencode/codebase-index.json`):
+```json
+{ "additionalInclude": ["**/*.m"] }
+```
+
 **Max File Size**: Default 1MB (1048576 bytes). Configure via `indexing.maxFileSize` (bytes).
 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.
@@ -353,7 +360,7 @@ Returns recent debug logs with optional filtering.
 
 ### `call_graph`
 
-Query the call graph to find callers or callees of a function/method. Automatically built during indexing for TypeScript, JavaScript, Python, Go, Rust, PHP, and Zig.
+Query the call graph to find callers or callees of a function/method. Automatically built during indexing for TypeScript, JavaScript, Python, Go, Rust, PHP, Apex, Zig, GDScript, and MATLAB.
 
 - **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).
@@ -363,6 +370,7 @@ Query the call graph to find callers or callees of a function/method. Automatica
 Add a folder as a knowledge base to be indexed alongside project code.
 - **Use for**: Indexing external documentation, API references, example programs.
 - **Parameters**: `path` (folder path, absolute or relative), `reindex` (optional, default `true`).
+- **Restrictions**: System directories (`/etc`, `/proc`, `/sys`, `/dev`) and sensitive home directories (`.ssh`, `.gnupg`, `.aws`, `.docker`, `.kube`) are blocked. Symlinks are resolved before validation.
 - **Example**: `add_knowledge_base(path="/path/to/docs")`
 
 ### `list_knowledge_bases`
@@ -432,10 +440,10 @@ Global-level config (`~/.config/opencode/codebase-index.json`):
 {
   "embeddingProvider": "custom",
   "customProvider": {
-    "baseUrl": "https://api.siliconflow.cn/v1",
+    "baseUrl": "{env:EMBED_BASE_URL}",
     "model": "BAAI/bge-m3",
     "dimensions": 1024,
-    "apiKey": "{env:SILICONFLOW_API_KEY}"
+    "apiKey": "{env:EMBED_API_KEY}"
   }
 }
 ```
@@ -459,9 +467,9 @@ Add to your config (`.opencode/codebase-index.json` or global config):
 {
   "reranker": {
     "enabled": true,
-    "baseUrl": "https://api.siliconflow.cn/v1",
-    "model": "BAAI/bge-reranker-v2-m3",
-    "apiKey": "{env:SILICONFLOW_API_KEY}",
+    "baseUrl": "https://api.cohere.ai/v1",
+    "model": "rerank-v3.5",
+    "apiKey": "{env:RERANK_API_KEY}",
     "topN": 20
   }
 }
@@ -511,10 +519,10 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 
   // === Custom Embedding API (when embeddingProvider is "custom") ===
   "customProvider": {
-    "baseUrl": "https://api.siliconflow.cn/v1",
+    "baseUrl": "{env:EMBED_BASE_URL}",
     "model": "BAAI/bge-m3",
     "dimensions": 1024,
-    "apiKey": "{env:SILICONFLOW_API_KEY}",
+    "apiKey": "{env:EMBED_API_KEY}",
     "maxTokens": 8192,                        // Max tokens per input text
     "timeoutMs": 30000,                       // Request timeout (ms)
     "concurrency": 3,                         // Max concurrent requests
@@ -567,7 +575,8 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
     "rrfK": 60,                               // RRF smoothing constant
     "rerankTopN": 20,                         // Deterministic rerank depth
     "contextLines": 0,                        // Extra lines before/after match
-    "routingHints": true                      // Runtime nudges for local discovery/definition queries
+    "routingHints": true,                     // Runtime nudges for local discovery/definition queries
+    "routingHintRole": "system"              // system | developer (message role used for hints)
   },
   "reranker": {
     "enabled": false,
@@ -638,6 +647,7 @@ String values in `codebase-index.json` can reference environment variables with
 | `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 |
 | `routingHints` | `true` | Inject lightweight runtime hints for local conceptual discovery and definition lookups. Set to `false` to disable plugin-side routing nudges. |
+| `routingHintRole` | `"system"` | Message role used when injecting routing hints: `"system"` (default) or `"developer"`. |
 | **reranker** | | Optional second-stage model reranker for the top candidate pool |
 | `enabled` | `false` | Turn external reranking on/off |
 | `provider` | `"custom"` | Hosted shortcuts: `cohere`, `jina`, or `custom` |
@@ -656,10 +666,19 @@ String values in `codebase-index.json` can reference environment variables with
 | `logBranch` | `true` | Log branch detection and switches |
 | `metrics` | `false` | Enable metrics collection (indexing stats, search timing, cache performance) |
 
+### Recovery warnings in debug logs
+
+When debug logging is enabled, the indexer now emits warn-level recovery messages if persisted cache state cannot be read safely.
+
+- Corrupted or unreadable `file-hashes.json` causes the in-memory file hash cache to be reset.
+- Corrupted or unreadable `failed-batches.json` causes persisted retry batches to be skipped for that run.
+
+These warnings improve observability but do **not** change the recovery behavior: the indexer still falls back to a safe reset/skip path instead of crashing. If these warnings recur, remove the affected file under `.opencode/index/` (or the global index directory) and rebuild with `/index force`.
+
 ### Retrieval ranking behavior
 
 - `codebase_search` and `codebase_peek` use the hybrid path: semantic + keyword retrieval → fusion (`fusionStrategy`) → deterministic rerank (`rerankTopN`) → optional external reranker (`reranker`) → filtering.
-- When `search.routingHints` is enabled (default), the plugin adds tiny per-turn runtime hints for local conceptual discovery and definition queries. Conceptual discovery is nudged toward `codebase_peek` / `codebase_search`, while definition questions are nudged toward `implementation_lookup`. Exact identifier and unrelated operational tasks are left alone.
+- When `search.routingHints` is enabled (default), the plugin adds tiny per-turn runtime hints for local conceptual discovery and definition queries. Conceptual discovery is nudged toward `codebase_peek` / `codebase_search`, while definition questions are nudged toward `implementation_lookup`. Exact identifier and unrelated operational tasks are left alone. Set `search.routingHintRole` to `"developer"` if your client/runtime expects developer-role guidance instead of system-role guidance.
 - `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.
 - When enabled, the external reranker sees path metadata plus a bounded on-disk code snippet for each candidate so it can distinguish real implementations from docs/tests more reliably.
@@ -1007,7 +1026,7 @@ The Rust native module handles performance-critical operations:
 - **usearch**: High-performance vector similarity search with F16 quantization
 - **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, PHP, Zig)
+- **Call graph extraction**: Tree-sitter query-based extraction of function calls, method calls, constructors, and imports (TypeScript/JavaScript, Python, Go, Rust, PHP, Apex, Zig, GDScript, MATLAB)
 - **xxhash**: Fast content hashing for change detection
 
 Rebuild with: `npm run build:native` (requires Rust toolchain)