opencode-codebase-index 0.18.1 → 0.19.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "codebase-index",
       "description": "Semantic code search and codebase graph tools for Claude Code",
       "source": "./",
-      "version": "0.18.1"
+      "version": "0.19.1"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-index",
-  "version": "0.18.1",
+  "version": "0.19.1",
   "description": "Semantic code search and codebase graph tools for Claude Code",
   "displayName": "Codebase Index",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-index",
-  "version": "0.18.1",
+  "version": "0.19.1",
   "description": "Semantic code search and codebase graph tools for Codex",
   "author": {
     "name": "Kenneth",

package/README.md

@@ -407,7 +407,7 @@ Use `include` to replace defaults, or `additionalInclude` to extend (e.g. `"**/*
 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, fuses (`rrf` default, `weighted` fallback), applies deterministic rerank, then filters by current branch/metadata.
+5. **Hybrid Search**: Combines semantic similarity (vectors) with BM25 keyword matching, applies branch and hard metadata scopes before reranking, fuses candidates (`rrf` default, `weighted` fallback), then applies deterministic local intent ranking and optional external reranking.
 
 **Performance characteristics:**
 - **Incremental indexing**: ~50ms check time — only re-embeds changed files
@@ -479,9 +479,13 @@ The plugin exposes these tools to the OpenCode agent:
 **Behavioral semantic retrieval with full content.** Searches code by describing behavior.
 - **Use for**: Discovery when you already want full matching snippets and are ready to inspect implementation text.
 - **Example**: `"find the middleware that sanitizes input"`
-- **Ranking path**: hybrid retrieval → fusion (`search.fusionStrategy`) → deterministic rerank (`search.rerankTopN`) → filters
+- **Ranking path**: hybrid retrieval → branch/directory/file-type/chunk/blame scope → fusion (`search.fusionStrategy`) → deterministic local intent rerank (`search.rerankTopN`) → optional external rerank within local evidence classes → minimum-score filter
 - **Blame filters**: when `indexing.gitBlame.enabled` is `true`, filter with `blameAuthor`, `blameSha`, or `blameSince`.
 
+The local ranker is deterministic and does not call another model. Exact symbol names receive a strong NFKC and case-normalized match signal. Definition and implementation questions prefer authoritative declarations over imports, export wrappers, tests, fixtures, docs, and generated or vendor files. Explicit test, docs, config, and call-flow wording instead promotes the requested evidence class. Natural-language conceptual queries keep retrieval score as the dominant signal, while nested duplicate chunks are removed and remaining evidence is spread across relevant files. True score ties retain input order, then candidate id as a final deterministic fallback.
+
+When an external reranker is enabled, hard directory, file-type, chunk-type, and blame scopes are enforced before any request. The external service receives only candidates already inside that scope and only the candidate's exact indexed line range, without extra surrounding source. Local intent classification, exact-name promotion, duplicate suppression, and evidence-class ordering remain local.
+
 **Writing good queries:**
 
 | ✅ Good queries (describe behavior) | ❌ Bad queries (too vague) |
@@ -530,8 +534,12 @@ Checks if the index is ready and healthy.
 Maintenance tool to remove stale entries from deleted files and orphaned embeddings/chunks from the database.
 
 ### `index_metrics`
-Returns collected metrics about indexing and search performance. Requires `debug.enabled` and `debug.metrics` to be `true`.
+Returns collected metrics about indexing and search performance. Operational metrics require `debug.enabled` and `debug.metrics` to be `true`.
 - **Metrics include**: Files indexed, chunks created, cache hit rate, search timing breakdown, GC stats, embedding API call stats.
+- **Privacy-safe effectiveness metrics**: Set top-level `effectivenessMetrics.enabled` to `true`. This path does not enable debug logging. It records only fixed route/host/outcome counters and bounded result-count, latency, token-budget, and returned-token histograms. Counters are disabled by default, memory-only, fixed-cardinality, and process-lifetime across Indexer replacement and configuration-watcher refresh. One process-wide collector aggregates opted-in calls without project or repository identity dimensions. It never retains queries, response text, source, symbols, paths, repository names, user identity, or stable identifiers.
+- **Effectiveness-only privacy boundary**: With only `effectivenessMetrics.enabled` set, `debug.enabled` remains `false`, `index_logs` remains disabled, operational debug metrics remain off, and no query, path, source, secret, or response text is emitted by metrics output or written to index files. Only the bounded aggregate snapshot is returned by `index_metrics`.
+- **Debug logging is separate**: Explicitly enabling `debug.enabled` with `debug.logSearch` preserves the existing diagnostic behavior and may retain raw queries and repository details in memory. Do not enable debug search logs when only privacy-safe aggregates are wanted.
+- **Reset**: Pass `reset: true` to clear both operational and process-wide effectiveness metrics before returning the new zeroed snapshot. Process exit also clears effectiveness metrics because they are never persisted.
 
 ### `index_logs`
 Returns recent debug logs with optional filtering.
@@ -544,7 +552,7 @@ Query the call graph to find callers or callees of a function/method. Automatica
 For Swift, resolution remains name-based, so overloads, extension duplicates, and protocol dispatch can remain ambiguous. Syntax alone cannot always distinguish a superclass from a protocol conformance or an enum raw-value type from a protocol. Constructor classification uses an uppercase ASCII initial heuristic while retaining the exact name for resolution. `tree-sitter-swift` 0.7.3 also has limitations around `sending`, abbreviated collection constructors such as `[Int]()`, and some generic calls after `self`, `super`, optional chaining, or chained calls. The index does not infer SourceKit semantics for these cases.
 
 - **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), `relationshipType` (optional: `Call`, `MethodCall`, `Constructor`, `Import`, `Inherits`, `Implements`).
+- **Parameters**: `name` (function name), `direction` (`callers` or `callees`), `filePath` (optional duplicate-name disambiguator), `symbolId` (optional backward-compatible escape hatch), `relationshipType` (optional: `Call`, `MethodCall`, `Constructor`, `Import`, `Inherits`, `Implements`). Unique names resolve automatically; ambiguous names return bounded candidate locations.
 - **Example**: Find who calls `validateToken` → `call_graph(name="validateToken", direction="callers")`
 
 ### `call_graph_path`
@@ -552,7 +560,7 @@ For Swift, resolution remains name-based, so overloads, extension duplicates, an
 Find the shortest known call-graph path between two symbols. Use it after `codebase_peek`, `implementation_lookup`, or `call_graph` identifies the important source and target names.
 
 - **Use for**: Blast-radius checks, dependency-chain discovery, explaining how one subsystem reaches another.
-- **Parameters**: `from` (source symbol name), `to` (target symbol name), `maxDepth` (optional, default `10`).
+- **Parameters**: `from` (source symbol name), `to` (target symbol name), `fromFilePath` and `toFilePath` (optional duplicate-name disambiguators), `maxDepth` (optional, default `10`).
 - **Example**: Trace how `createOrder` reaches `chargeCard` → `call_graph_path(from="createOrder", to="chargeCard")`
 
 ### `pr_impact`
@@ -788,7 +796,10 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 
   // === Indexing ===
   "indexing": {
-    "autoIndex": false,                       // Auto-index on plugin load
+    "autoIndex": false,                       // Explicit opt-in for automatic indexing
+    "autoIndexWaitMs": 10000,                 // First-retrieval wait bound (0-60000ms)
+    "autoIndexMaxRetries": 5,                 // Transient interprocess lock retries (0-10)
+    "autoIndexRetryDelayMs": 100,             // Initial exponential lock retry delay
     "watchFiles": true,                       // Re-index on file changes
     "maxFileSize": 1048576,                   // Max file size in bytes (default: 1MB)
     "maxChunksPerFile": 100,                  // Max chunks per file
@@ -833,7 +844,10 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
     "logCache": true,                         // Log cache hits/misses
     "logGc": true,                            // Log garbage collection
     "logBranch": true,                        // Log branch detection
-    "metrics": false                          // Enable metrics collection
+    "metrics": false                          // Enable operational metrics collection
+  },
+  "effectivenessMetrics": {
+    "enabled": false                          // Opt in without enabling debug logs
   }
 }
 ```
@@ -854,6 +868,8 @@ String values in `codebase-index.json` can reference environment variables with
 
 ### Options Reference
 
+`indexing.autoIndex` remains disabled by default because indexing can invoke a paid embedding provider. When explicitly enabled, MCP hosts start one process-scoped job before accepting tool work where practical, skip a healthy current index, retry transient multiprocess lock contention within the configured bound, and expose sanitized state/progress through `index_status`. If no readable index exists, retrieval tools wait up to `autoIndexWaitMs`; after that they report that indexing is still running or failed instead of returning misleading empty search results. Home-directory and project-marker protections still apply.
+
 | Option | Default | Description |
 |--------|---------|-------------|
 | `embeddingProvider` | `"auto"` | Which AI to use: `auto`, `github-copilot`, `openai`, `google`, `ollama`, `custom` |
@@ -863,7 +879,10 @@ String values in `codebase-index.json` can reference environment variables with
 | `additionalInclude` | `[]` | Additional file patterns to include (extends defaults, e.g. `"**/*.txt"`, `"**/*.html"`) |
 | `knowledgeBases` | `[]` | External directories to index as knowledge bases (absolute or relative paths) |
 | **indexing** | | |
-| `autoIndex` | `false` | Automatically index on plugin load |
+| `autoIndex` | `false` | Explicitly opt in to automatic startup/first-use indexing. When disabled, retrieval never starts indexing or paid embedding work. |
+| `autoIndexWaitMs` | `10000` | Maximum time (0-60000ms) a first retrieval waits for an enabled automatic index job before returning actionable in-progress status. |
+| `autoIndexMaxRetries` | `5` | Maximum transient interprocess lock retries (0-10) for background automatic indexing. |
+| `autoIndexRetryDelayMs` | `100` | Initial exponential lock retry delay in milliseconds (10-10000). |
 | `watchFiles` | `true` | Re-index when files change |
 | `maxFileSize` | `1048576` | Skip files larger than this (bytes). Default: 1MB |
 | `maxChunksPerFile` | `100` | Maximum chunks to index per file (controls token costs for large files) |
@@ -906,6 +925,8 @@ String values in `codebase-index.json` can reference environment variables with
 | `logGc` | `true` | Log garbage collection operations |
 | `logBranch` | `true` | Log branch detection and switches |
 | `metrics` | `false` | Enable metrics collection (indexing stats, search timing, cache performance) |
+| **effectivenessMetrics** | | |
+| `enabled` | `false` | Independently opt in to memory-only, fixed-cardinality repository-tool effectiveness counters. Does not enable debug logs; stores no queries, response text, code, symbols, paths, repo names, user identity, or stable identifiers. |
 
 ### Recovery warnings in debug logs
 
@@ -938,12 +959,16 @@ npm run eval
 npm run eval:ci
 npm run eval:ci:ollama
 npm run eval:compare -- --against benchmarks/baselines/eval-baseline-summary.json
+npm run eval:effectiveness
 ```
 
 CI usage split:
 
 - `npm run eval:smoke`: harness smoke check with local mock embeddings (used in main CI)
 - `npm run eval:ci`: real quality gate against baseline/budget (for scheduled/manual quality workflow)
+- `npm run eval:effectiveness`: deterministic offline synthetic-fixture formatting report. Every route receives the same capped ranked result list and final-response token budget. Evidence is credited only when its literal marker is visible in returned text. The baseline emits only exact matching source lines, performs no arbitrary complete reads, makes no network calls, and writes `benchmarks/baselines/privacy-safe-effectiveness.json`.
+
+The effectiveness report includes median/p95 `cl100k_base` token counts and final-text evidence recall. Context and peek are metadata-oriented in this benchmark, so they receive no content-evidence credit unless the marker is actually visible in their response. The exact-search snippet baseline uses oracle markers and excludes discovery cost. The report does not measure retrieval quality, latency, end-to-end agent success, causal impact, or production-repository performance.
 
 For `eval-quality.yml`, the default CI path uses **GitHub Models** with the workflow `GITHUB_TOKEN` plus `models: read`, so you do not need a separate OpenAI API key just to run the scheduled gate.
 

package/commands/call-graph.md

@@ -10,19 +10,20 @@ Interpret input as follows:
 - If input asks for a path, connection, route, chain, or "from X to Y", use `call_graph_path`.
 - 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"`.
+- Unique names resolve automatically for both directions. Use optional `filePath=<path>` only when duplicate names are reported.
+- `symbolId=<id>` remains an optional backward-compatible escape hatch.
 - For path queries, parse `from=<function>`, `to=<function>`, and optional `maxDepth=<number>`.
 
 Execution flow:
 1. If input asks for a path and has source/target names, call `call_graph_path` with `{ from, to, maxDepth? }`.
 2. If direction is `callers`, call `call_graph` with `{ name, direction: "callers" }`.
-3. If direction is `callees` and `symbolId` is present, call `call_graph` with `{ name, direction: "callees", symbolId }`.
-4. 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.
+3. If direction is `callees`, call `call_graph` with `{ name, direction: "callees" }`.
+4. If the tool reports duplicate names, retry with the suggested `filePath`; for paths use `fromFilePath` or `toFilePath`.
 
 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
+- `/call-graph callees name=Database filePath=src/database.ts` → callees for a duplicate name at that location
 - `/call-graph path from=createOrder to=chargeCard` → shortest known path between the two symbols
 
 If output says no callers found, suggest running `/index force` first.