fix: harden search reliability and indexing hygiene

Author: PatrickSys

.gitignore

@@ -7,6 +7,8 @@ dist/
 *.log
 .DS_Store
 .env
+opencode.jsonc
+nul
 .vscode/
 *.swp
 *.swo

src/core/analyzer-registry.ts

@@ -70,7 +70,9 @@ export class AnalyzerRegistry {
     const analyzer = this.findAnalyzer(filePath, content);
 
     if (!analyzer) {
-      console.warn(`No analyzer found for file: ${filePath}`);
+      if (process.env.CODEBASE_CONTEXT_DEBUG) {
+        console.error(`[DEBUG] No analyzer found for file: ${filePath}`);
+      }
       return null;
     }
 

src/core/indexer.ts

@@ -194,7 +194,7 @@ export class CodebaseIndexer {
 
         console.error(
           `Incremental diff: ${diff.added.length} added, ${diff.changed.length} changed, ` +
-          `${diff.deleted.length} deleted, ${diff.unchanged.length} unchanged`
+            `${diff.deleted.length} deleted, ${diff.unchanged.length} unchanged`
         );
 
         stats.incremental = {
@@ -210,6 +210,20 @@ export class CodebaseIndexer {
           this.updateProgress('complete', 100);
           stats.duration = Date.now() - startTime;
           stats.completedAt = new Date();
+
+          // Preserve accurate counts from the existing index (nothing changed, index is intact)
+          try {
+            const existingIndexPath = path.join(contextDir, KEYWORD_INDEX_FILENAME);
+            const existingChunks = JSON.parse(await fs.readFile(existingIndexPath, 'utf-8'));
+            if (Array.isArray(existingChunks)) {
+              stats.totalChunks = existingChunks.length;
+              const uniqueFiles = new Set(existingChunks.map((c: { filePath?: string }) => c.filePath));
+              stats.indexedFiles = uniqueFiles.size;
+            }
+          } catch {
+            // Keyword index doesn't exist yet — keep counts as 0
+          }
+
           return stats;
         }
       }
@@ -418,8 +432,8 @@ export class CodebaseIndexer {
         this.updateProgress('embedding', 50);
         console.error(
           `Creating embeddings for ${chunksToEmbed.length} chunks` +
-          (diff ? ` (${allChunks.length} total, ${chunksToEmbed.length} changed)` : '') +
-          '...'
+            (diff ? ` (${allChunks.length} total, ${chunksToEmbed.length} changed)` : '') +
+            '...'
         );
 
         // Initialize embedding provider
@@ -480,11 +494,13 @@ export class CodebaseIndexer {
 
         if (diff) {
           // Incremental: delete old chunks for changed + deleted files, then add new
-          const filesToDelete = [...diff.changed, ...diff.deleted]
-            .map((rel) => path.join(this.rootPath, rel).replace(/\\/g, '/'));
+          const filesToDelete = [...diff.changed, ...diff.deleted].map((rel) =>
+            path.join(this.rootPath, rel).replace(/\\/g, '/')
+          );
           // Also try with OS-native separators for matching
-          const filePathsForDelete = [...diff.changed, ...diff.deleted]
-            .map((rel) => path.resolve(this.rootPath, rel));
+          const filePathsForDelete = [...diff.changed, ...diff.deleted].map((rel) =>
+            path.resolve(this.rootPath, rel)
+          );
           const allDeletePaths = [...new Set([...filesToDelete, ...filePathsForDelete])];
 
           if (allDeletePaths.length > 0) {
@@ -495,7 +511,7 @@ export class CodebaseIndexer {
           }
           console.error(
             `Incremental store: deleted chunks for ${diff.changed.length + diff.deleted.length} files, ` +
-            `added ${chunksWithEmbeddings.length} new chunks`
+              `added ${chunksWithEmbeddings.length} new chunks`
           );
         } else {
           // Full: clear and re-store everything
@@ -508,7 +524,8 @@ export class CodebaseIndexer {
       // Keyword index always uses ALL chunks (full regen)
       const indexPath = path.join(contextDir, KEYWORD_INDEX_FILENAME);
       // Memory safety: cap keyword index too
-      const keywordChunks = allChunks.length > MAX_CHUNKS ? allChunks.slice(0, MAX_CHUNKS) : allChunks;
+      const keywordChunks =
+        allChunks.length > MAX_CHUNKS ? allChunks.slice(0, MAX_CHUNKS) : allChunks;
       await fs.writeFile(indexPath, JSON.stringify(keywordChunks));
 
       // Save library usage and pattern stats (always full regen)
@@ -552,7 +569,7 @@ export class CodebaseIndexer {
       const manifest: FileManifest = {
         version: 1,
         generatedAt: new Date().toISOString(),
-        files: currentHashes ?? await computeFileHashes(files, this.rootPath)
+        files: currentHashes ?? (await computeFileHashes(files, this.rootPath))
       };
       await writeManifest(manifestPath, manifest);
 
@@ -565,8 +582,8 @@ export class CodebaseIndexer {
       if (diff) {
         console.error(
           `Incremental indexing complete in ${stats.duration}ms ` +
-          `(${diff.added.length} added, ${diff.changed.length} changed, ` +
-          `${diff.deleted.length} deleted, ${diff.unchanged.length} unchanged)`
+            `(${diff.added.length} added, ${diff.changed.length} changed, ` +
+            `${diff.deleted.length} deleted, ${diff.unchanged.length} unchanged)`
         );
       } else {
         console.error(`Indexing complete in ${stats.duration}ms`);
@@ -588,6 +605,7 @@ export class CodebaseIndexer {
 
   private async scanFiles(): Promise<string[]> {
     const files: string[] = [];
+    const seen = new Set<string>();
 
     // Read .gitignore if respecting it
     let ig: ReturnType<typeof ignore.default> | null = null;
@@ -614,6 +632,12 @@ export class CodebaseIndexer {
       });
 
       for (const file of matches) {
+        const normalizedFile = file.replace(/\\/g, '/');
+        if (seen.has(normalizedFile)) {
+          continue;
+        }
+        seen.add(normalizedFile);
+
         const relativePath = path.relative(this.rootPath, file);
 
         // Check gitignore

src/core/search-quality.ts

@@ -0,0 +1,83 @@
+import type { SearchResult } from '../types/index.js';
+import { isTestingRelatedQuery } from '../preflight/query-scope.js';
+
+export interface SearchQualityAssessment {
+  status: 'ok' | 'low_confidence';
+  confidence: number;
+  signals: string[];
+  nextSteps?: string[];
+}
+
+export function isTestArtifactPath(filePath: string): boolean {
+  const normalized = filePath.toLowerCase().replace(/\\/g, '/');
+  return (
+    normalized.includes('.spec.') ||
+    normalized.includes('.test.') ||
+    normalized.includes('/e2e/') ||
+    normalized.includes('/__tests__/')
+  );
+}
+
+export function assessSearchQuality(
+  query: string,
+  results: SearchResult[]
+): SearchQualityAssessment {
+  if (results.length === 0) {
+    return {
+      status: 'low_confidence',
+      confidence: 0,
+      signals: ['no results returned'],
+      nextSteps: [
+        'Try a narrower query with one concrete symbol, route, or file hint.',
+        'Apply search filters (framework/language/componentType/layer).',
+        'Use get_component_usage for dependency or wiring lookups.'
+      ]
+    };
+  }
+
+  const topSlice = results.slice(0, Math.min(3, results.length));
+  const topScore = results[0].score;
+  const secondScore = results[1]?.score ?? topScore;
+  const topAverage = topSlice.reduce((sum, result) => sum + result.score, 0) / topSlice.length;
+  const topSeparation = Math.max(0, topScore - secondScore);
+  const testRatio =
+    topSlice.filter((result) => isTestArtifactPath(result.filePath)).length / topSlice.length;
+  const queryIsTesting = isTestingRelatedQuery(query);
+
+  const signals: string[] = [];
+  if (topScore < 0.3) {
+    signals.push(`low top score (${topScore.toFixed(2)})`);
+  }
+  if (topAverage < 0.32) {
+    signals.push(`weak top-${topSlice.length} average (${topAverage.toFixed(2)})`);
+  }
+  if (topSlice.length > 1 && topSeparation < 0.03) {
+    signals.push(`tight top spread (${topSeparation.toFixed(2)})`);
+  }
+  if (!queryIsTesting && testRatio >= 0.67) {
+    signals.push(
+      `test artifacts dominate top-${topSlice.length} (${Math.round(testRatio * 100)}%)`
+    );
+  }
+
+  let confidence = topScore;
+  if (topAverage < 0.32) confidence -= 0.08;
+  if (topSlice.length > 1 && topSeparation < 0.03) confidence -= 0.05;
+  if (!queryIsTesting && testRatio >= 0.67) confidence -= 0.15;
+  confidence = Math.max(0, Math.min(1, Number(confidence.toFixed(2))));
+
+  const lowConfidence = signals.length >= 2 || confidence < 0.35;
+
+  return {
+    status: lowConfidence ? 'low_confidence' : 'ok',
+    confidence,
+    signals,
+    ...(lowConfidence && {
+      nextSteps: [
+        'Add one or two concrete symbols, routes, or file hints to the query.',
+        'Apply filters (framework/language/componentType/layer) to narrow candidates.',
+        'Use get_component_usage when the question is about wiring or usages.'
+      ]
+    })
+  };
+}