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

@@ -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;
         }
       }
@@ -591,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;
@@ -617,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.'
+      ]
+    })
+  };
+}