opencode-codebase-index 0.3.2 → 0.4.0

package/README.md

@@ -64,11 +64,12 @@ 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 |
 | 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 |
 
-**Rule of thumb**: Semantic search for discovery → grep for precision.
+**Rule of thumb**: `codebase_peek` to find locations → `Read` to examine → `grep` for precision.
 
 ## 📊 Token Usage
 
@@ -187,6 +188,18 @@ The plugin exposes these tools to the OpenCode agent:
 | "code that calculates shipping costs" | "shipping" |
 | "where user permissions are checked" | "permissions" |
 
+### `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`.
+- **Example output**:
+  ```
+  [1] function "validatePayment" at src/billing.ts:45-67 (score: 0.92)
+  [2] class "PaymentProcessor" at src/processor.ts:12-89 (score: 0.87)
+  
+  Use Read tool to examine specific files.
+  ```
+- **Workflow**: `codebase_peek` → find locations → `Read` specific files
+
 ### `index_codebase`
 Manually trigger indexing.
 - **Use for**: Forcing a re-index or checking stats.

package/dist/index.cjs

@@ -3879,12 +3879,13 @@ var Indexer = class {
       keywordMs: Math.round(keywordMs * 100) / 100,
       fusionMs: Math.round(fusionMs * 100) / 100
     });
+    const metadataOnly = options?.metadataOnly ?? false;
     return Promise.all(
       filtered.map(async (r) => {
         let content = "";
         let contextStartLine = r.metadata.startLine;
         let contextEndLine = r.metadata.endLine;
-        if (this.config.search.includeContext) {
+        if (!metadataOnly && this.config.search.includeContext) {
           try {
             const fileContent = await import_fs4.promises.readFile(
               r.metadata.filePath,
@@ -4091,6 +4092,91 @@ var Indexer = class {
   getLogger() {
     return this.logger;
   }
+  async findSimilar(code, limit, options) {
+    const searchStartTime = import_perf_hooks.performance.now();
+    const { store, provider, database } = await this.ensureInitialized();
+    if (store.count() === 0) {
+      this.logger.search("debug", "Find similar on empty index");
+      return [];
+    }
+    const maxResults = limit ?? this.config.search.maxResults;
+    const filterByBranch = options?.filterByBranch ?? true;
+    this.logger.search("debug", "Starting find similar", {
+      codeLength: code.length,
+      maxResults,
+      filterByBranch
+    });
+    const embeddingStartTime = import_perf_hooks.performance.now();
+    const { embedding, tokensUsed } = await provider.embed(code);
+    const embeddingMs = import_perf_hooks.performance.now() - embeddingStartTime;
+    this.logger.recordEmbeddingApiCall(tokensUsed);
+    const vectorStartTime = import_perf_hooks.performance.now();
+    const semanticResults = store.search(embedding, maxResults * 2);
+    const vectorMs = import_perf_hooks.performance.now() - vectorStartTime;
+    let branchChunkIds = null;
+    if (filterByBranch && this.currentBranch !== "default") {
+      branchChunkIds = new Set(database.getBranchChunkIds(this.currentBranch));
+    }
+    const filtered = semanticResults.filter((r) => {
+      if (r.score < this.config.search.minScore) return false;
+      if (branchChunkIds && !branchChunkIds.has(r.id)) return false;
+      if (options?.excludeFile) {
+        if (r.metadata.filePath === options.excludeFile) return false;
+      }
+      if (options?.fileType) {
+        const ext = r.metadata.filePath.split(".").pop()?.toLowerCase();
+        if (ext !== options.fileType.toLowerCase().replace(/^\./, "")) return false;
+      }
+      if (options?.directory) {
+        const normalizedDir = options.directory.replace(/^\/|\/$/g, "");
+        if (!r.metadata.filePath.includes(`/${normalizedDir}/`) && !r.metadata.filePath.includes(`${normalizedDir}/`)) return false;
+      }
+      if (options?.chunkType) {
+        if (r.metadata.chunkType !== options.chunkType) return false;
+      }
+      return true;
+    }).slice(0, maxResults);
+    const totalSearchMs = import_perf_hooks.performance.now() - searchStartTime;
+    this.logger.recordSearch(totalSearchMs, {
+      embeddingMs,
+      vectorMs,
+      keywordMs: 0,
+      fusionMs: 0
+    });
+    this.logger.search("info", "Find similar complete", {
+      codeLength: code.length,
+      results: filtered.length,
+      totalMs: Math.round(totalSearchMs * 100) / 100,
+      embeddingMs: Math.round(embeddingMs * 100) / 100,
+      vectorMs: Math.round(vectorMs * 100) / 100
+    });
+    return Promise.all(
+      filtered.map(async (r) => {
+        let content = "";
+        if (this.config.search.includeContext) {
+          try {
+            const fileContent = await import_fs4.promises.readFile(
+              r.metadata.filePath,
+              "utf-8"
+            );
+            const lines = fileContent.split("\n");
+            content = lines.slice(r.metadata.startLine - 1, r.metadata.endLine).join("\n");
+          } catch {
+            content = "[File not accessible]";
+          }
+        }
+        return {
+          filePath: r.metadata.filePath,
+          startLine: r.metadata.startLine,
+          endLine: r.metadata.endLine,
+          content,
+          score: r.score,
+          chunkType: r.metadata.chunkType,
+          name: r.metadata.name
+        };
+      })
+    );
+  }
 };
 
 // node_modules/chokidar/index.js
@@ -6032,7 +6118,7 @@ function getIndexer() {
   return sharedIndexer;
 }
 var codebase_search = (0, import_plugin.tool)({
-  description: "Search codebase by MEANING, not keywords. Use when you don't know exact function/class names. Returns focused results (5-10 files). For known identifiers like 'validateToken' or 'UserService', use grep instead - it's faster and finds all occurrences. Best for: 'find authentication logic', 'code that handles payments', 'error middleware'.",
+  description: "Search codebase by MEANING, not keywords. Returns full code content. Use when you need to see actual implementation. For just finding WHERE code is (saves ~90% tokens), use codebase_peek instead. For known identifiers like 'validateToken', use grep - it's faster.",
   args: {
     query: z.string().describe("Natural language description of what code you're looking for. Describe behavior, not syntax."),
     limit: z.number().optional().default(10).describe("Maximum number of results to return"),
@@ -6064,6 +6150,38 @@ ${r.content}
 ${formatted.join("\n\n")}`;
   }
 });
+var codebase_peek = (0, import_plugin.tool)({
+  description: "Quick lookup of code locations by meaning. Returns only metadata (file, line, name, type) WITHOUT code content. Use this first to find WHERE code is, then use Read tool to examine specific files. Saves tokens by not returning full code blocks. Best for: discovery, navigation, finding multiple related locations.",
+  args: {
+    query: z.string().describe("Natural language description of what code you're looking for."),
+    limit: z.number().optional().default(10).describe("Maximum number of results to return"),
+    fileType: z.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+    directory: z.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+    chunkType: z.enum(["function", "class", "method", "interface", "type", "enum", "struct", "impl", "trait", "module", "other"]).optional().describe("Filter by code chunk type")
+  },
+  async execute(args) {
+    const indexer = getIndexer();
+    const results = await indexer.search(args.query, args.limit ?? 10, {
+      fileType: args.fileType,
+      directory: args.directory,
+      chunkType: args.chunkType,
+      metadataOnly: true
+    });
+    if (results.length === 0) {
+      return "No matching code found. Try a different query or run index_codebase first.";
+    }
+    const formatted = results.map((r, idx) => {
+      const location = `${r.filePath}:${r.startLine}-${r.endLine}`;
+      const name = r.name ? `"${r.name}"` : "(anonymous)";
+      return `[${idx + 1}] ${r.chunkType} ${name} at ${location} (score: ${r.score.toFixed(2)})`;
+    });
+    return `Found ${results.length} locations for "${args.query}":
+
+${formatted.join("\n")}
+
+Use Read tool to examine specific files.`;
+  }
+});
 var index_codebase = (0, import_plugin.tool)({
   description: "Index the codebase for semantic search. Creates vector embeddings of code chunks. Incremental - only re-indexes changed files (~50ms when nothing changed). Run before first codebase_search.",
   args: {
@@ -6175,6 +6293,39 @@ var index_logs = (0, import_plugin.tool)({
     }).join("\n");
   }
 });
+var find_similar = (0, import_plugin.tool)({
+  description: "Find code similar to a given snippet. Use for duplicate detection, pattern discovery, or refactoring prep. Paste code and find semantically similar implementations elsewhere in the codebase.",
+  args: {
+    code: z.string().describe("The code snippet to find similar code for"),
+    limit: z.number().optional().default(10).describe("Maximum number of results to return"),
+    fileType: z.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+    directory: z.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+    chunkType: z.enum(["function", "class", "method", "interface", "type", "enum", "struct", "impl", "trait", "module", "other"]).optional().describe("Filter by code chunk type"),
+    excludeFile: z.string().optional().describe("Exclude results from this file path (useful when searching for duplicates of code from a specific file)")
+  },
+  async execute(args) {
+    const indexer = getIndexer();
+    const results = await indexer.findSimilar(args.code, args.limit ?? 10, {
+      fileType: args.fileType,
+      directory: args.directory,
+      chunkType: args.chunkType,
+      excludeFile: args.excludeFile
+    });
+    if (results.length === 0) {
+      return "No similar code found. Try a different snippet or run index_codebase first.";
+    }
+    const formatted = results.map((r, idx) => {
+      const header = r.name ? `[${idx + 1}] ${r.chunkType} "${r.name}" in ${r.filePath}:${r.startLine}-${r.endLine}` : `[${idx + 1}] ${r.chunkType} in ${r.filePath}:${r.startLine}-${r.endLine}`;
+      return `${header} (similarity: ${(r.score * 100).toFixed(1)}%)
+\`\`\`
+${r.content}
+\`\`\``;
+    });
+    return `Found ${results.length} similar code blocks:
+
+${formatted.join("\n\n")}`;
+  }
+});
 function formatIndexStats(stats, verbose = false) {
   const lines = [];
   if (stats.indexedChunks === 0 && stats.removedChunks === 0) {
@@ -6358,11 +6509,13 @@ var plugin = async ({ directory }) => {
   return {
     tool: {
       codebase_search,
+      codebase_peek,
       index_codebase,
       index_status,
       index_health_check,
       index_metrics,
-      index_logs
+      index_logs,
+      find_similar
     },
     async config(cfg) {
       cfg.command = cfg.command ?? {};