opencode-codebase-index 0.3.2 → 0.4.1

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.
@@ -233,7 +246,8 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
     "semanticOnly": false,
     "autoGc": true,
     "gcIntervalDays": 7,
-    "gcOrphanThreshold": 100
+    "gcOrphanThreshold": 100,
+    "requireProjectMarker": true
   },
   "search": {
     "maxResults": 20,
@@ -266,6 +280,7 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 | `autoGc` | `true` | Automatically run garbage collection to remove orphaned embeddings/chunks |
 | `gcIntervalDays` | `7` | Run GC on initialization if last GC was more than N days ago |
 | `gcOrphanThreshold` | `100` | Run GC after indexing if orphan count exceeds this threshold |
+| `requireProjectMarker` | `true` | Require a project marker (`.git`, `package.json`, etc.) to enable file watching and auto-indexing. Prevents accidentally indexing large directories like home. Set to `false` to index any directory. |
 | **search** | | |
 | `maxResults` | `20` | Maximum results to return |
 | `minScore` | `0.1` | Minimum similarity score (0-1). Lower = more results |

package/dist/index.cjs

@@ -701,7 +701,8 @@ function getDefaultIndexingConfig() {
     retryDelayMs: 1e3,
     autoGc: true,
     gcIntervalDays: 7,
-    gcOrphanThreshold: 100
+    gcOrphanThreshold: 100,
+    requireProjectMarker: true
   };
 }
 function getDefaultSearchConfig() {
@@ -756,7 +757,8 @@ function parseConfig(raw) {
     retryDelayMs: typeof rawIndexing.retryDelayMs === "number" ? rawIndexing.retryDelayMs : defaultIndexing.retryDelayMs,
     autoGc: typeof rawIndexing.autoGc === "boolean" ? rawIndexing.autoGc : defaultIndexing.autoGc,
     gcIntervalDays: typeof rawIndexing.gcIntervalDays === "number" ? Math.max(1, rawIndexing.gcIntervalDays) : defaultIndexing.gcIntervalDays,
-    gcOrphanThreshold: typeof rawIndexing.gcOrphanThreshold === "number" ? Math.max(0, rawIndexing.gcOrphanThreshold) : defaultIndexing.gcOrphanThreshold
+    gcOrphanThreshold: typeof rawIndexing.gcOrphanThreshold === "number" ? Math.max(0, rawIndexing.gcOrphanThreshold) : defaultIndexing.gcOrphanThreshold,
+    requireProjectMarker: typeof rawIndexing.requireProjectMarker === "boolean" ? rawIndexing.requireProjectMarker : defaultIndexing.requireProjectMarker
   };
   const rawSearch = input.search && typeof input.search === "object" ? input.search : {};
   const search = {
@@ -2186,6 +2188,30 @@ var OllamaEmbeddingProvider = class {
 var import_ignore = __toESM(require_ignore(), 1);
 var import_fs2 = require("fs");
 var path2 = __toESM(require("path"), 1);
+var PROJECT_MARKERS = [
+  ".git",
+  "package.json",
+  "Cargo.toml",
+  "go.mod",
+  "pyproject.toml",
+  "setup.py",
+  "requirements.txt",
+  "Gemfile",
+  "composer.json",
+  "pom.xml",
+  "build.gradle",
+  "CMakeLists.txt",
+  "Makefile",
+  ".opencode"
+];
+function hasProjectMarker(projectRoot) {
+  for (const marker of PROJECT_MARKERS) {
+    if ((0, import_fs2.existsSync)(path2.join(projectRoot, marker))) {
+      return true;
+    }
+  }
+  return false;
+}
 function createIgnoreFilter(projectRoot) {
   const ig = (0, import_ignore.default)();
   const defaultIgnores = [
@@ -3879,12 +3905,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 +4118,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
@@ -6021,6 +6133,13 @@ function createWatcherWithIndexer(indexer, projectRoot, config) {
 // src/tools/index.ts
 var import_plugin = require("@opencode-ai/plugin");
 var z = import_plugin.tool.schema;
+var MAX_CONTENT_LINES = 30;
+function truncateContent(content) {
+  const lines = content.split("\n");
+  if (lines.length <= MAX_CONTENT_LINES) return content;
+  return lines.slice(0, MAX_CONTENT_LINES).join("\n") + `
+// ... (${lines.length - MAX_CONTENT_LINES} more lines)`;
+}
 var sharedIndexer = null;
 function initializeTools(projectRoot, config) {
   sharedIndexer = new Indexer(projectRoot, config);
@@ -6032,10 +6151,10 @@ 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"),
+    limit: z.number().optional().default(5).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"),
@@ -6043,7 +6162,7 @@ var codebase_search = (0, import_plugin.tool)({
   },
   async execute(args) {
     const indexer = getIndexer();
-    const results = await indexer.search(args.query, args.limit ?? 10, {
+    const results = await indexer.search(args.query, args.limit ?? 5, {
       fileType: args.fileType,
       directory: args.directory,
       chunkType: args.chunkType,
@@ -6056,7 +6175,7 @@ var codebase_search = (0, import_plugin.tool)({
       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} (score: ${r.score.toFixed(2)})
 \`\`\`
-${r.content}
+${truncateContent(r.content)}
 \`\`\``;
     });
     return `Found ${results.length} results for "${args.query}":
@@ -6064,6 +6183,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 +6326,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)}%)
+\`\`\`
+${truncateContent(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) {
@@ -6345,24 +6529,32 @@ var plugin = async ({ directory }) => {
   const config = parseConfig(rawConfig);
   initializeTools(projectRoot, config);
   const indexer = new Indexer(projectRoot, config);
-  if (config.indexing.autoIndex) {
+  const isValidProject = !config.indexing.requireProjectMarker || hasProjectMarker(projectRoot);
+  if (!isValidProject) {
+    console.warn(
+      `[codebase-index] Skipping file watching and auto-indexing: no project marker found in "${projectRoot}". Set "indexing.requireProjectMarker": false in config to override.`
+    );
+  }
+  if (config.indexing.autoIndex && isValidProject) {
     indexer.initialize().then(() => {
       indexer.index().catch(() => {
       });
     }).catch(() => {
     });
   }
-  if (config.indexing.watchFiles) {
+  if (config.indexing.watchFiles && isValidProject) {
     createWatcherWithIndexer(indexer, projectRoot, config);
   }
   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 ?? {};