opencode-codebase-index 0.3.0 → 0.3.2

package/dist/index.js

@@ -708,8 +708,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);
 }
@@ -719,10 +732,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,
@@ -744,6 +761,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",
@@ -751,7 +779,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 = {
@@ -816,6 +845,7 @@ function getDefaultModelForProvider(provider) {
 // src/indexer/index.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync, promises as fsPromises2 } from "fs";
 import * as path5 from "path";
+import { performance as performance2 } from "perf_hooks";
 
 // node_modules/eventemitter3/index.mjs
 var import_index = __toESM(require_eventemitter3(), 1);
@@ -2325,6 +2355,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
 import * as path3 from "path";
 import * as os2 from "os";
@@ -2453,6 +2775,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;
@@ -2851,12 +3188,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") {
@@ -2935,6 +3278,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
@@ -2966,9 +3314,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();
@@ -3052,6 +3405,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,
@@ -3081,6 +3436,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();
@@ -3089,11 +3449,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 fsPromises2.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,
@@ -3101,7 +3467,12 @@ var Indexer = class {
       chunksProcessed: 0,
       totalChunks: 0
     });
+    const parseStartTime = performance2.now();
     const parsedFiles = parseFiles(changedFiles);
+    const parseMs = performance2.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()) {
@@ -3183,6 +3554,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));
@@ -3226,6 +3604,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) {
@@ -3264,13 +3647,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
+                  });
                 }
               }
             }
@@ -3297,6 +3683,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,
@@ -3307,7 +3699,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)
+          });
         }
       });
     }
@@ -3329,6 +3725,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;
     }
@@ -3341,18 +3747,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 = performance2.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 = performance2.now();
+    const embedding = await this.getQueryEmbedding(query, provider);
+    const embeddingMs = performance2.now() - embeddingStartTime;
+    const vectorStartTime = performance2.now();
     const semanticResults = store.search(embedding, maxResults * 4);
+    const vectorMs = performance2.now() - vectorStartTime;
+    const keywordStartTime = performance2.now();
     const keywordResults = await this.keywordSearch(query, maxResults * 4);
+    const keywordMs = performance2.now() - keywordStartTime;
+    const fusionStartTime = performance2.now();
     const combined = this.fuseResults(semanticResults, keywordResults, hybridWeight, maxResults * 4);
+    const fusionMs = performance2.now() - fusionStartTime;
     let branchChunkIds = null;
     if (filterByBranch && this.currentBranch !== "default") {
       branchChunkIds = new Set(database.getBranchChunkIds(this.currentBranch));
@@ -3373,6 +3857,22 @@ var Indexer = class {
       }
       return true;
     }).slice(0, maxResults);
+    const totalSearchMs = performance2.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
+    });
     return Promise.all(
       filtered.map(async (r) => {
         let content = "";
@@ -3411,11 +3911,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);
@@ -3478,6 +3975,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) {
@@ -3504,6 +4002,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() {
@@ -3537,9 +4042,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,
@@ -3574,6 +4082,9 @@ var Indexer = class {
     const { database } = await this.ensureInitialized();
     return database.getStats();
   }
+  getLogger() {
+    return this.logger;
+  }
 };
 
 // node_modules/chokidar/index.js
@@ -5613,6 +6124,51 @@ var index_health_check = tool({
     return lines.join("\n");
   }
 });
+var index_metrics = 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 = 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");
+  }
+});
 function formatIndexStats(stats, verbose = false) {
   const lines = [];
   if (stats.indexedChunks === 0 && stats.removedChunks === 0) {
@@ -5797,7 +6353,9 @@ var plugin = async ({ directory }) => {
       codebase_search,
       index_codebase,
       index_status,
-      index_health_check
+      index_health_check,
+      index_metrics,
+      index_logs
     },
     async config(cfg) {
       cfg.command = cfg.command ?? {};