opencode-codebase-index 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -713,8 +713,21 @@ function getDefaultSearchConfig() {
     contextLines: 0
   };
 }
+function getDefaultDebugConfig() {
+  return {
+    enabled: false,
+    logLevel: "info",
+    logSearch: true,
+    logEmbedding: true,
+    logCache: true,
+    logGc: true,
+    logBranch: true,
+    metrics: true
+  };
+}
 var VALID_PROVIDERS = ["auto", "github-copilot", "openai", "google", "ollama"];
 var VALID_SCOPES = ["project", "global"];
+var VALID_LOG_LEVELS = ["error", "warn", "info", "debug"];
 function isValidProvider(value) {
   return typeof value === "string" && VALID_PROVIDERS.includes(value);
 }
@@ -724,10 +737,14 @@ function isValidScope(value) {
 function isStringArray(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function isValidLogLevel(value) {
+  return typeof value === "string" && VALID_LOG_LEVELS.includes(value);
+}
 function parseConfig(raw) {
   const input = raw && typeof raw === "object" ? raw : {};
   const defaultIndexing = getDefaultIndexingConfig();
   const defaultSearch = getDefaultSearchConfig();
+  const defaultDebug = getDefaultDebugConfig();
   const rawIndexing = input.indexing && typeof input.indexing === "object" ? input.indexing : {};
   const indexing = {
     autoIndex: typeof rawIndexing.autoIndex === "boolean" ? rawIndexing.autoIndex : defaultIndexing.autoIndex,
@@ -749,6 +766,17 @@ function parseConfig(raw) {
     hybridWeight: typeof rawSearch.hybridWeight === "number" ? Math.min(1, Math.max(0, rawSearch.hybridWeight)) : defaultSearch.hybridWeight,
     contextLines: typeof rawSearch.contextLines === "number" ? Math.min(50, Math.max(0, rawSearch.contextLines)) : defaultSearch.contextLines
   };
+  const rawDebug = input.debug && typeof input.debug === "object" ? input.debug : {};
+  const debug = {
+    enabled: typeof rawDebug.enabled === "boolean" ? rawDebug.enabled : defaultDebug.enabled,
+    logLevel: isValidLogLevel(rawDebug.logLevel) ? rawDebug.logLevel : defaultDebug.logLevel,
+    logSearch: typeof rawDebug.logSearch === "boolean" ? rawDebug.logSearch : defaultDebug.logSearch,
+    logEmbedding: typeof rawDebug.logEmbedding === "boolean" ? rawDebug.logEmbedding : defaultDebug.logEmbedding,
+    logCache: typeof rawDebug.logCache === "boolean" ? rawDebug.logCache : defaultDebug.logCache,
+    logGc: typeof rawDebug.logGc === "boolean" ? rawDebug.logGc : defaultDebug.logGc,
+    logBranch: typeof rawDebug.logBranch === "boolean" ? rawDebug.logBranch : defaultDebug.logBranch,
+    metrics: typeof rawDebug.metrics === "boolean" ? rawDebug.metrics : defaultDebug.metrics
+  };
   return {
     embeddingProvider: isValidProvider(input.embeddingProvider) ? input.embeddingProvider : "auto",
     embeddingModel: typeof input.embeddingModel === "string" ? input.embeddingModel : "auto",
@@ -756,7 +784,8 @@ function parseConfig(raw) {
     include: isStringArray(input.include) ? input.include : DEFAULT_INCLUDE,
     exclude: isStringArray(input.exclude) ? input.exclude : DEFAULT_EXCLUDE,
     indexing,
-    search
+    search,
+    debug
   };
 }
 var EMBEDDING_MODELS = {
@@ -821,6 +850,7 @@ function getDefaultModelForProvider(provider) {
 // src/indexer/index.ts
 var import_fs4 = require("fs");
 var path5 = __toESM(require("path"), 1);
+var import_perf_hooks = require("perf_hooks");
 
 // node_modules/eventemitter3/index.mjs
 var import_index = __toESM(require_eventemitter3(), 1);
@@ -2330,6 +2360,298 @@ function padRight(str, length) {
   return str.padEnd(length);
 }
 
+// src/utils/logger.ts
+var LOG_LEVEL_PRIORITY = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3
+};
+function createEmptyMetrics() {
+  return {
+    filesScanned: 0,
+    filesParsed: 0,
+    parseMs: 0,
+    chunksProcessed: 0,
+    chunksEmbedded: 0,
+    chunksFromCache: 0,
+    chunksRemoved: 0,
+    embeddingApiCalls: 0,
+    embeddingTokensUsed: 0,
+    embeddingErrors: 0,
+    searchCount: 0,
+    searchTotalMs: 0,
+    searchAvgMs: 0,
+    searchLastMs: 0,
+    embeddingCallMs: 0,
+    vectorSearchMs: 0,
+    keywordSearchMs: 0,
+    fusionMs: 0,
+    cacheHits: 0,
+    cacheMisses: 0,
+    queryCacheHits: 0,
+    queryCacheSimilarHits: 0,
+    queryCacheMisses: 0,
+    gcRuns: 0,
+    gcOrphansRemoved: 0,
+    gcChunksRemoved: 0,
+    gcEmbeddingsRemoved: 0
+  };
+}
+var Logger = class {
+  config;
+  metrics;
+  logs = [];
+  maxLogs = 1e3;
+  constructor(config) {
+    this.config = config;
+    this.metrics = createEmptyMetrics();
+  }
+  shouldLog(level) {
+    if (!this.config.enabled) return false;
+    return LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[this.config.logLevel];
+  }
+  log(level, category, message, data) {
+    if (!this.shouldLog(level)) return;
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      category,
+      message,
+      data
+    };
+    this.logs.push(entry);
+    if (this.logs.length > this.maxLogs) {
+      this.logs.shift();
+    }
+  }
+  search(level, message, data) {
+    if (this.config.logSearch) {
+      this.log(level, "search", message, data);
+    }
+  }
+  embedding(level, message, data) {
+    if (this.config.logEmbedding) {
+      this.log(level, "embedding", message, data);
+    }
+  }
+  cache(level, message, data) {
+    if (this.config.logCache) {
+      this.log(level, "cache", message, data);
+    }
+  }
+  gc(level, message, data) {
+    if (this.config.logGc) {
+      this.log(level, "gc", message, data);
+    }
+  }
+  branch(level, message, data) {
+    if (this.config.logBranch) {
+      this.log(level, "branch", message, data);
+    }
+  }
+  info(message, data) {
+    this.log("info", "general", message, data);
+  }
+  warn(message, data) {
+    this.log("warn", "general", message, data);
+  }
+  error(message, data) {
+    this.log("error", "general", message, data);
+  }
+  debug(message, data) {
+    this.log("debug", "general", message, data);
+  }
+  recordIndexingStart() {
+    if (!this.config.metrics) return;
+    this.metrics.indexingStartTime = Date.now();
+  }
+  recordIndexingEnd() {
+    if (!this.config.metrics) return;
+    this.metrics.indexingEndTime = Date.now();
+  }
+  recordFilesScanned(count) {
+    if (!this.config.metrics) return;
+    this.metrics.filesScanned = count;
+  }
+  recordFilesParsed(count) {
+    if (!this.config.metrics) return;
+    this.metrics.filesParsed = count;
+  }
+  recordParseDuration(durationMs) {
+    if (!this.config.metrics) return;
+    this.metrics.parseMs = durationMs;
+  }
+  recordChunksProcessed(count) {
+    if (!this.config.metrics) return;
+    this.metrics.chunksProcessed += count;
+  }
+  recordChunksEmbedded(count) {
+    if (!this.config.metrics) return;
+    this.metrics.chunksEmbedded += count;
+  }
+  recordChunksFromCache(count) {
+    if (!this.config.metrics) return;
+    this.metrics.chunksFromCache += count;
+  }
+  recordChunksRemoved(count) {
+    if (!this.config.metrics) return;
+    this.metrics.chunksRemoved += count;
+  }
+  recordEmbeddingApiCall(tokens) {
+    if (!this.config.metrics) return;
+    this.metrics.embeddingApiCalls++;
+    this.metrics.embeddingTokensUsed += tokens;
+  }
+  recordEmbeddingError() {
+    if (!this.config.metrics) return;
+    this.metrics.embeddingErrors++;
+  }
+  recordSearch(durationMs, breakdown) {
+    if (!this.config.metrics) return;
+    this.metrics.searchCount++;
+    this.metrics.searchTotalMs += durationMs;
+    this.metrics.searchLastMs = durationMs;
+    this.metrics.searchAvgMs = this.metrics.searchTotalMs / this.metrics.searchCount;
+    if (breakdown) {
+      this.metrics.embeddingCallMs = breakdown.embeddingMs;
+      this.metrics.vectorSearchMs = breakdown.vectorMs;
+      this.metrics.keywordSearchMs = breakdown.keywordMs;
+      this.metrics.fusionMs = breakdown.fusionMs;
+    }
+  }
+  recordCacheHit() {
+    if (!this.config.metrics) return;
+    this.metrics.cacheHits++;
+  }
+  recordCacheMiss() {
+    if (!this.config.metrics) return;
+    this.metrics.cacheMisses++;
+  }
+  recordQueryCacheHit() {
+    if (!this.config.metrics) return;
+    this.metrics.queryCacheHits++;
+  }
+  recordQueryCacheSimilarHit() {
+    if (!this.config.metrics) return;
+    this.metrics.queryCacheSimilarHits++;
+  }
+  recordQueryCacheMiss() {
+    if (!this.config.metrics) return;
+    this.metrics.queryCacheMisses++;
+  }
+  recordGc(orphans, chunks, embeddings) {
+    if (!this.config.metrics) return;
+    this.metrics.gcRuns++;
+    this.metrics.gcOrphansRemoved += orphans;
+    this.metrics.gcChunksRemoved += chunks;
+    this.metrics.gcEmbeddingsRemoved += embeddings;
+  }
+  getMetrics() {
+    return { ...this.metrics };
+  }
+  getLogs(limit) {
+    const logs = [...this.logs];
+    if (limit) {
+      return logs.slice(-limit);
+    }
+    return logs;
+  }
+  getLogsByCategory(category, limit) {
+    const filtered = this.logs.filter((l) => l.category === category);
+    if (limit) {
+      return filtered.slice(-limit);
+    }
+    return filtered;
+  }
+  getLogsByLevel(level, limit) {
+    const filtered = this.logs.filter((l) => l.level === level);
+    if (limit) {
+      return filtered.slice(-limit);
+    }
+    return filtered;
+  }
+  resetMetrics() {
+    this.metrics = createEmptyMetrics();
+  }
+  clearLogs() {
+    this.logs = [];
+  }
+  formatMetrics() {
+    const m = this.metrics;
+    const lines = [];
+    lines.push("=== Metrics ===");
+    if (m.indexingStartTime && m.indexingEndTime) {
+      const duration = m.indexingEndTime - m.indexingStartTime;
+      lines.push(`Indexing duration: ${(duration / 1e3).toFixed(2)}s`);
+    }
+    lines.push("");
+    lines.push("Indexing:");
+    lines.push(`  Files scanned: ${m.filesScanned}`);
+    lines.push(`  Files parsed: ${m.filesParsed}`);
+    lines.push(`  Chunks processed: ${m.chunksProcessed}`);
+    lines.push(`  Chunks embedded: ${m.chunksEmbedded}`);
+    lines.push(`  Chunks from cache: ${m.chunksFromCache}`);
+    lines.push(`  Chunks removed: ${m.chunksRemoved}`);
+    lines.push("");
+    lines.push("Embedding API:");
+    lines.push(`  API calls: ${m.embeddingApiCalls}`);
+    lines.push(`  Tokens used: ${m.embeddingTokensUsed.toLocaleString()}`);
+    lines.push(`  Errors: ${m.embeddingErrors}`);
+    if (m.searchCount > 0) {
+      lines.push("");
+      lines.push("Search:");
+      lines.push(`  Total searches: ${m.searchCount}`);
+      lines.push(`  Average time: ${m.searchAvgMs.toFixed(2)}ms`);
+      lines.push(`  Last search: ${m.searchLastMs.toFixed(2)}ms`);
+      if (m.embeddingCallMs > 0) {
+        lines.push(`    - Embedding: ${m.embeddingCallMs.toFixed(2)}ms`);
+        lines.push(`    - Vector search: ${m.vectorSearchMs.toFixed(2)}ms`);
+        lines.push(`    - Keyword search: ${m.keywordSearchMs.toFixed(2)}ms`);
+        lines.push(`    - Fusion: ${m.fusionMs.toFixed(2)}ms`);
+      }
+    }
+    const totalCacheOps = m.cacheHits + m.cacheMisses;
+    if (totalCacheOps > 0) {
+      lines.push("");
+      lines.push("Cache:");
+      lines.push(`  Hits: ${m.cacheHits}`);
+      lines.push(`  Misses: ${m.cacheMisses}`);
+      lines.push(`  Hit rate: ${(m.cacheHits / totalCacheOps * 100).toFixed(1)}%`);
+    }
+    if (m.gcRuns > 0) {
+      lines.push("");
+      lines.push("Garbage Collection:");
+      lines.push(`  GC runs: ${m.gcRuns}`);
+      lines.push(`  Orphans removed: ${m.gcOrphansRemoved}`);
+      lines.push(`  Chunks removed: ${m.gcChunksRemoved}`);
+      lines.push(`  Embeddings removed: ${m.gcEmbeddingsRemoved}`);
+    }
+    return lines.join("\n");
+  }
+  formatRecentLogs(limit = 20) {
+    const logs = this.getLogs(limit);
+    if (logs.length === 0) {
+      return "No logs recorded.";
+    }
+    return logs.map((l) => {
+      const dataStr = l.data ? ` ${JSON.stringify(l.data)}` : "";
+      return `[${l.timestamp}] [${l.level.toUpperCase()}] [${l.category}] ${l.message}${dataStr}`;
+    }).join("\n");
+  }
+  isEnabled() {
+    return this.config.enabled;
+  }
+  isMetricsEnabled() {
+    return this.config.enabled && this.config.metrics;
+  }
+};
+var globalLogger = null;
+function initializeLogger(config) {
+  globalLogger = new Logger(config);
+  return globalLogger;
+}
+
 // src/native/index.ts
 var path3 = __toESM(require("path"), 1);
 var os2 = __toESM(require("os"), 1);
@@ -2459,6 +2781,21 @@ var VectorStore = class {
       metadata: JSON.parse(r.metadata)
     }));
   }
+  getMetadata(id) {
+    const result = this.inner.getMetadata(id);
+    if (result === null || result === void 0) {
+      return void 0;
+    }
+    return JSON.parse(result);
+  }
+  getMetadataBatch(ids) {
+    const results = this.inner.getMetadataBatch(ids);
+    const map = /* @__PURE__ */ new Map();
+    for (const { key, metadata } of results) {
+      map.set(key, JSON.parse(metadata));
+    }
+    return map;
+  }
 };
 var CHARS_PER_TOKEN = 4;
 var MAX_BATCH_TOKENS = 7500;
@@ -2857,12 +3194,18 @@ var Indexer = class {
   failedBatchesPath = "";
   currentBranch = "default";
   baseBranch = "main";
+  logger;
+  queryEmbeddingCache = /* @__PURE__ */ new Map();
+  maxQueryCacheSize = 100;
+  queryCacheTtlMs = 5 * 60 * 1e3;
+  querySimilarityThreshold = 0.85;
   constructor(projectRoot, config) {
     this.projectRoot = projectRoot;
     this.config = config;
     this.indexPath = this.getIndexPath();
     this.fileHashCachePath = path5.join(this.indexPath, "file-hashes.json");
     this.failedBatchesPath = path5.join(this.indexPath, "failed-batches.json");
+    this.logger = initializeLogger(config.debug);
   }
   getIndexPath() {
     if (this.config.scope === "global") {
@@ -2941,6 +3284,11 @@ var Indexer = class {
         "No embedding provider available. Configure GitHub, OpenAI, Google, or Ollama."
       );
     }
+    this.logger.info("Initializing indexer", {
+      provider: this.detectedProvider.provider,
+      model: this.detectedProvider.modelInfo.model,
+      scope: this.config.scope
+    });
     this.provider = createEmbeddingProvider(
       this.detectedProvider.credentials,
       this.detectedProvider.modelInfo
@@ -2972,9 +3320,14 @@ var Indexer = class {
     if (isGitRepo(this.projectRoot)) {
       this.currentBranch = getBranchOrDefault(this.projectRoot);
       this.baseBranch = getBaseBranch(this.projectRoot);
+      this.logger.branch("info", "Detected git repository", {
+        currentBranch: this.currentBranch,
+        baseBranch: this.baseBranch
+      });
     } else {
       this.currentBranch = "default";
       this.baseBranch = "default";
+      this.logger.branch("debug", "Not a git repository, using default branch");
     }
     if (this.config.indexing.autoGc) {
       await this.maybeRunAutoGc();
@@ -3058,6 +3411,8 @@ var Indexer = class {
   }
   async index(onProgress) {
     const { store, provider, invertedIndex, database, detectedProvider } = await this.ensureInitialized();
+    this.logger.recordIndexingStart();
+    this.logger.info("Starting indexing", { projectRoot: this.projectRoot });
     const startTime = Date.now();
     const stats = {
       totalFiles: 0,
@@ -3087,6 +3442,11 @@ var Indexer = class {
     );
     stats.totalFiles = files.length;
     stats.skippedFiles = skipped;
+    this.logger.recordFilesScanned(files.length);
+    this.logger.cache("debug", "Scanning files for changes", {
+      totalFiles: files.length,
+      skippedFiles: skipped.length
+    });
     const changedFiles = [];
     const unchangedFilePaths = /* @__PURE__ */ new Set();
     const currentFileHashes = /* @__PURE__ */ new Map();
@@ -3095,11 +3455,17 @@ var Indexer = class {
       currentFileHashes.set(f.path, currentHash);
       if (this.fileHashCache.get(f.path) === currentHash) {
         unchangedFilePaths.add(f.path);
+        this.logger.recordCacheHit();
       } else {
         const content = await import_fs4.promises.readFile(f.path, "utf-8");
         changedFiles.push({ path: f.path, content, hash: currentHash });
+        this.logger.recordCacheMiss();
       }
     }
+    this.logger.cache("info", "File hash cache results", {
+      unchanged: unchangedFilePaths.size,
+      changed: changedFiles.length
+    });
     onProgress?.({
       phase: "parsing",
       filesProcessed: 0,
@@ -3107,7 +3473,12 @@ var Indexer = class {
       chunksProcessed: 0,
       totalChunks: 0
     });
+    const parseStartTime = import_perf_hooks.performance.now();
     const parsedFiles = parseFiles(changedFiles);
+    const parseMs = import_perf_hooks.performance.now() - parseStartTime;
+    this.logger.recordFilesParsed(parsedFiles.length);
+    this.logger.recordParseDuration(parseMs);
+    this.logger.debug("Parsed changed files", { parsedCount: parsedFiles.length, parseMs: parseMs.toFixed(2) });
     const existingChunks = /* @__PURE__ */ new Map();
     const existingChunksByFile = /* @__PURE__ */ new Map();
     for (const { key, metadata } of store.getAllMetadata()) {
@@ -3189,6 +3560,13 @@ var Indexer = class {
     stats.totalChunks = pendingChunks.length;
     stats.existingChunks = currentChunkIds.size - pendingChunks.length;
     stats.removedChunks = removedCount;
+    this.logger.recordChunksProcessed(currentChunkIds.size);
+    this.logger.recordChunksRemoved(removedCount);
+    this.logger.info("Chunk analysis complete", {
+      pending: pendingChunks.length,
+      existing: stats.existingChunks,
+      removed: removedCount
+    });
     if (pendingChunks.length === 0 && removedCount === 0) {
       database.clearBranch(this.currentBranch);
       database.addChunksToBranchBatch(this.currentBranch, Array.from(currentChunkIds));
@@ -3232,6 +3610,11 @@ var Indexer = class {
     const missingHashes = new Set(database.getMissingEmbeddings(allContentHashes));
     const chunksNeedingEmbedding = pendingChunks.filter((c) => missingHashes.has(c.contentHash));
     const chunksWithExistingEmbedding = pendingChunks.filter((c) => !missingHashes.has(c.contentHash));
+    this.logger.cache("info", "Embedding cache lookup", {
+      needsEmbedding: chunksNeedingEmbedding.length,
+      fromCache: chunksWithExistingEmbedding.length
+    });
+    this.logger.recordChunksFromCache(chunksWithExistingEmbedding.length);
     for (const chunk of chunksWithExistingEmbedding) {
       const embeddingBuffer = database.getEmbedding(chunk.contentHash);
       if (embeddingBuffer) {
@@ -3270,13 +3653,16 @@ var Indexer = class {
                 const message = getErrorMessage(error);
                 if (isRateLimitError(error)) {
                   rateLimitBackoffMs = Math.min(providerRateLimits.maxRetryMs, (rateLimitBackoffMs || providerRateLimits.minRetryMs) * 2);
-                  console.error(
-                    `Rate limited (attempt ${error.attemptNumber}/${error.retriesLeft + error.attemptNumber}): waiting ${rateLimitBackoffMs / 1e3}s before retry...`
-                  );
+                  this.logger.embedding("warn", `Rate limited, backing off`, {
+                    attempt: error.attemptNumber,
+                    retriesLeft: error.retriesLeft,
+                    backoffMs: rateLimitBackoffMs
+                  });
                 } else {
-                  console.error(
-                    `Embedding batch failed (attempt ${error.attemptNumber}): ${message}`
-                  );
+                  this.logger.embedding("error", `Embedding batch failed`, {
+                    attempt: error.attemptNumber,
+                    error: message
+                  });
                 }
               }
             }
@@ -3303,6 +3689,12 @@ var Indexer = class {
           }
           stats.indexedChunks += batch.length;
           stats.tokensUsed += result.totalTokensUsed;
+          this.logger.recordChunksEmbedded(batch.length);
+          this.logger.recordEmbeddingApiCall(result.totalTokensUsed);
+          this.logger.embedding("debug", `Embedded batch`, {
+            batchSize: batch.length,
+            tokens: result.totalTokensUsed
+          });
           onProgress?.({
             phase: "embedding",
             filesProcessed: files.length,
@@ -3313,7 +3705,11 @@ var Indexer = class {
         } catch (error) {
           stats.failedChunks += batch.length;
           this.addFailedBatch(batch, getErrorMessage(error));
-          console.error(`Failed to embed batch after retries: ${getErrorMessage(error)}`);
+          this.logger.recordEmbeddingError();
+          this.logger.embedding("error", `Failed to embed batch after retries`, {
+            batchSize: batch.length,
+            error: getErrorMessage(error)
+          });
         }
       });
     }
@@ -3335,6 +3731,16 @@ var Indexer = class {
       await this.maybeRunOrphanGc();
     }
     stats.durationMs = Date.now() - startTime;
+    this.logger.recordIndexingEnd();
+    this.logger.info("Indexing complete", {
+      files: stats.totalFiles,
+      indexed: stats.indexedChunks,
+      existing: stats.existingChunks,
+      removed: stats.removedChunks,
+      failed: stats.failedChunks,
+      tokens: stats.tokensUsed,
+      durationMs: stats.durationMs
+    });
     if (stats.failedChunks > 0) {
       stats.failedBatchesPath = this.failedBatchesPath;
     }
@@ -3347,18 +3753,96 @@ var Indexer = class {
     });
     return stats;
   }
+  async getQueryEmbedding(query, provider) {
+    const now = Date.now();
+    const cached = this.queryEmbeddingCache.get(query);
+    if (cached && now - cached.timestamp < this.queryCacheTtlMs) {
+      this.logger.cache("debug", "Query embedding cache hit (exact)", { query: query.slice(0, 50) });
+      this.logger.recordQueryCacheHit();
+      return cached.embedding;
+    }
+    const similarMatch = this.findSimilarCachedQuery(query, now);
+    if (similarMatch) {
+      this.logger.cache("debug", "Query embedding cache hit (similar)", {
+        query: query.slice(0, 50),
+        similarTo: similarMatch.key.slice(0, 50),
+        similarity: similarMatch.similarity.toFixed(3)
+      });
+      this.logger.recordQueryCacheSimilarHit();
+      return similarMatch.embedding;
+    }
+    this.logger.cache("debug", "Query embedding cache miss", { query: query.slice(0, 50) });
+    this.logger.recordQueryCacheMiss();
+    const { embedding, tokensUsed } = await provider.embed(query);
+    this.logger.recordEmbeddingApiCall(tokensUsed);
+    if (this.queryEmbeddingCache.size >= this.maxQueryCacheSize) {
+      const oldestKey = this.queryEmbeddingCache.keys().next().value;
+      if (oldestKey) {
+        this.queryEmbeddingCache.delete(oldestKey);
+      }
+    }
+    this.queryEmbeddingCache.set(query, { embedding, timestamp: now });
+    return embedding;
+  }
+  findSimilarCachedQuery(query, now) {
+    const queryTokens = this.tokenize(query);
+    if (queryTokens.size === 0) return null;
+    let bestMatch = null;
+    for (const [cachedQuery, { embedding, timestamp }] of this.queryEmbeddingCache) {
+      if (now - timestamp >= this.queryCacheTtlMs) continue;
+      const cachedTokens = this.tokenize(cachedQuery);
+      const similarity = this.jaccardSimilarity(queryTokens, cachedTokens);
+      if (similarity >= this.querySimilarityThreshold) {
+        if (!bestMatch || similarity > bestMatch.similarity) {
+          bestMatch = { key: cachedQuery, embedding, similarity };
+        }
+      }
+    }
+    return bestMatch;
+  }
+  tokenize(text) {
+    return new Set(
+      text.toLowerCase().replace(/[^\w\s]/g, " ").split(/\s+/).filter((t) => t.length > 1)
+    );
+  }
+  jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0) return 1;
+    if (a.size === 0 || b.size === 0) return 0;
+    let intersection = 0;
+    for (const token of a) {
+      if (b.has(token)) intersection++;
+    }
+    const union = a.size + b.size - intersection;
+    return intersection / union;
+  }
   async search(query, limit, options) {
+    const searchStartTime = import_perf_hooks.performance.now();
     const { store, provider, database } = await this.ensureInitialized();
     if (store.count() === 0) {
+      this.logger.search("debug", "Search on empty index", { query });
       return [];
     }
     const maxResults = limit ?? this.config.search.maxResults;
     const hybridWeight = options?.hybridWeight ?? this.config.search.hybridWeight;
     const filterByBranch = options?.filterByBranch ?? true;
-    const { embedding } = await provider.embed(query);
+    this.logger.search("debug", "Starting search", {
+      query,
+      maxResults,
+      hybridWeight,
+      filterByBranch
+    });
+    const embeddingStartTime = import_perf_hooks.performance.now();
+    const embedding = await this.getQueryEmbedding(query, provider);
+    const embeddingMs = import_perf_hooks.performance.now() - embeddingStartTime;
+    const vectorStartTime = import_perf_hooks.performance.now();
     const semanticResults = store.search(embedding, maxResults * 4);
+    const vectorMs = import_perf_hooks.performance.now() - vectorStartTime;
+    const keywordStartTime = import_perf_hooks.performance.now();
     const keywordResults = await this.keywordSearch(query, maxResults * 4);
+    const keywordMs = import_perf_hooks.performance.now() - keywordStartTime;
+    const fusionStartTime = import_perf_hooks.performance.now();
     const combined = this.fuseResults(semanticResults, keywordResults, hybridWeight, maxResults * 4);
+    const fusionMs = import_perf_hooks.performance.now() - fusionStartTime;
     let branchChunkIds = null;
     if (filterByBranch && this.currentBranch !== "default") {
       branchChunkIds = new Set(database.getBranchChunkIds(this.currentBranch));
@@ -3379,12 +3863,29 @@ var Indexer = class {
       }
       return true;
     }).slice(0, maxResults);
+    const totalSearchMs = import_perf_hooks.performance.now() - searchStartTime;
+    this.logger.recordSearch(totalSearchMs, {
+      embeddingMs,
+      vectorMs,
+      keywordMs,
+      fusionMs
+    });
+    this.logger.search("info", "Search complete", {
+      query,
+      results: filtered.length,
+      totalMs: Math.round(totalSearchMs * 100) / 100,
+      embeddingMs: Math.round(embeddingMs * 100) / 100,
+      vectorMs: Math.round(vectorMs * 100) / 100,
+      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,
@@ -3417,11 +3918,8 @@ var Indexer = class {
     if (scores.size === 0) {
       return [];
     }
-    const allMetadata = store.getAllMetadata();
-    const metadataMap = /* @__PURE__ */ new Map();
-    for (const { key, metadata } of allMetadata) {
-      metadataMap.set(key, metadata);
-    }
+    const chunkIds = Array.from(scores.keys());
+    const metadataMap = store.getMetadataBatch(chunkIds);
     const results = [];
     for (const [chunkId, score] of scores) {
       const metadata = metadataMap.get(chunkId);
@@ -3484,6 +3982,7 @@ var Indexer = class {
   }
   async healthCheck() {
     const { store, invertedIndex, database } = await this.ensureInitialized();
+    this.logger.gc("info", "Starting health check");
     const allMetadata = store.getAllMetadata();
     const filePathsToChunkKeys = /* @__PURE__ */ new Map();
     for (const { key, metadata } of allMetadata) {
@@ -3510,6 +4009,13 @@ var Indexer = class {
     }
     const gcOrphanEmbeddings = database.gcOrphanEmbeddings();
     const gcOrphanChunks = database.gcOrphanChunks();
+    this.logger.recordGc(removedCount, gcOrphanChunks, gcOrphanEmbeddings);
+    this.logger.gc("info", "Health check complete", {
+      removedStale: removedCount,
+      orphanEmbeddings: gcOrphanEmbeddings,
+      orphanChunks: gcOrphanChunks,
+      removedFiles: removedFilePaths.length
+    });
     return { removed: removedCount, filePaths: removedFilePaths, gcOrphanEmbeddings, gcOrphanChunks };
   }
   async retryFailedBatches() {
@@ -3543,9 +4049,12 @@ var Indexer = class {
           invertedIndex.removeChunk(chunk.id);
           invertedIndex.addChunk(chunk.id, chunk.content);
         }
+        this.logger.recordChunksEmbedded(batch.chunks.length);
+        this.logger.recordEmbeddingApiCall(result.totalTokensUsed);
         succeeded += batch.chunks.length;
       } catch (error) {
         failed += batch.chunks.length;
+        this.logger.recordEmbeddingError();
         stillFailing.push({
           ...batch,
           attemptCount: batch.attemptCount + 1,
@@ -3580,6 +4089,94 @@ var Indexer = class {
     const { database } = await this.ensureInitialized();
     return database.getStats();
   }
+  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
@@ -5521,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"),
@@ -5553,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: {
@@ -5619,6 +6248,84 @@ var index_health_check = (0, import_plugin.tool)({
     return lines.join("\n");
   }
 });
+var index_metrics = (0, import_plugin.tool)({
+  description: "Get metrics and performance statistics for the codebase index. Shows indexing stats, search timings, cache hit rates, and API usage. Requires debug.enabled=true and debug.metrics=true in config.",
+  args: {},
+  async execute() {
+    const indexer = getIndexer();
+    const logger = indexer.getLogger();
+    if (!logger.isEnabled()) {
+      return 'Debug mode is disabled. Enable it in your config:\n\n```json\n{\n  "debug": {\n    "enabled": true,\n    "metrics": true\n  }\n}\n```';
+    }
+    if (!logger.isMetricsEnabled()) {
+      return 'Metrics collection is disabled. Enable it in your config:\n\n```json\n{\n  "debug": {\n    "enabled": true,\n    "metrics": true\n  }\n}\n```';
+    }
+    return logger.formatMetrics();
+  }
+});
+var index_logs = (0, import_plugin.tool)({
+  description: "Get recent debug logs from the codebase indexer. Shows timestamped log entries with level and category. Requires debug.enabled=true in config.",
+  args: {
+    limit: z.number().optional().default(20).describe("Maximum number of log entries to return"),
+    category: z.enum(["search", "embedding", "cache", "gc", "branch", "general"]).optional().describe("Filter by log category"),
+    level: z.enum(["error", "warn", "info", "debug"]).optional().describe("Filter by minimum log level")
+  },
+  async execute(args) {
+    const indexer = getIndexer();
+    const logger = indexer.getLogger();
+    if (!logger.isEnabled()) {
+      return 'Debug mode is disabled. Enable it in your config:\n\n```json\n{\n  "debug": {\n    "enabled": true\n  }\n}\n```';
+    }
+    let logs;
+    if (args.category) {
+      logs = logger.getLogsByCategory(args.category, args.limit);
+    } else if (args.level) {
+      logs = logger.getLogsByLevel(args.level, args.limit);
+    } else {
+      logs = logger.getLogs(args.limit);
+    }
+    if (logs.length === 0) {
+      return "No logs recorded yet. Logs are captured during indexing and search operations.";
+    }
+    return logs.map((l) => {
+      const dataStr = l.data ? ` ${JSON.stringify(l.data)}` : "";
+      return `[${l.timestamp}] [${l.level.toUpperCase()}] [${l.category}] ${l.message}${dataStr}`;
+    }).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) {
@@ -5802,9 +6509,13 @@ var plugin = async ({ directory }) => {
   return {
     tool: {
       codebase_search,
+      codebase_peek,
       index_codebase,
       index_status,
-      index_health_check
+      index_health_check,
+      index_metrics,
+      index_logs,
+      find_similar
     },
     async config(cfg) {
       cfg.command = cfg.command ?? {};