codebase-context 1.4.1 → 1.6.0

package/dist/core/search.js

@@ -9,13 +9,67 @@ import { getEmbeddingProvider } from '../embeddings/index.js';
 import { getStorageProvider } from '../storage/index.js';
 import { analyzerRegistry } from './analyzer-registry.js';
 import { IndexCorruptedError } from '../errors/index.js';
+import { isTestingRelatedQuery } from '../preflight/query-scope.js';
+import { assessSearchQuality } from './search-quality.js';
+import { rerank } from './reranker.js';
 import { CODEBASE_CONTEXT_DIRNAME, INTELLIGENCE_FILENAME, KEYWORD_INDEX_FILENAME, VECTOR_DB_DIRNAME } from '../constants/codebase-context.js';
 const DEFAULT_SEARCH_OPTIONS = {
     useSemanticSearch: true,
     useKeywordSearch: true,
-    semanticWeight: 0.7,
-    keywordWeight: 0.3
+    // semanticWeight/keywordWeight intentionally omitted —
+    // intent classification provides per-query weights.
+    // Callers can still override by passing explicit values.
+    profile: 'explore',
+    enableQueryExpansion: true,
+    enableLowConfidenceRescue: true,
+    candidateFloor: 30,
+    enableReranker: true
 };
+const QUERY_EXPANSION_HINTS = [
+    {
+        pattern: /\b(auth|authentication|login|signin|sign-in|session|token|oauth)\b/i,
+        terms: ['auth', 'login', 'token', 'session', 'guard', 'oauth']
+    },
+    {
+        pattern: /\b(route|routes|routing|router|navigate|navigation|redirect|path)\b/i,
+        terms: ['router', 'route', 'navigation', 'redirect', 'path']
+    },
+    {
+        pattern: /\b(config|configuration|configure|setup|register|provider|providers|bootstrap)\b/i,
+        terms: ['config', 'setup', 'register', 'provider', 'bootstrap']
+    },
+    {
+        pattern: /\b(role|roles|permission|permissions|authorization|authorisation|access)\b/i,
+        terms: ['roles', 'permissions', 'access', 'policy', 'guard']
+    },
+    {
+        pattern: /\b(interceptor|middleware|request|response|http)\b/i,
+        terms: ['interceptor', 'middleware', 'http', 'request', 'response']
+    },
+    {
+        pattern: /\b(theme|styles?|styling|palette|color|branding|upload)\b/i,
+        terms: ['theme', 'styles', 'palette', 'color', 'branding', 'upload']
+    }
+];
+const QUERY_STOP_WORDS = new Set([
+    'the',
+    'a',
+    'an',
+    'to',
+    'of',
+    'for',
+    'and',
+    'or',
+    'with',
+    'in',
+    'on',
+    'by',
+    'how',
+    'are',
+    'is',
+    'after',
+    'before'
+]);
 export class CodebaseSearcher {
     rootPath;
     storagePath;
@@ -24,8 +78,9 @@ export class CodebaseSearcher {
     embeddingProvider = null;
     storageProvider = null;
     initialized = false;
-    // v1.2: Pattern intelligence for trend detection
+    // Pattern intelligence for trend detection
     patternIntelligence = null;
+    importCentrality = null;
     constructor(rootPath) {
         this.rootPath = rootPath;
         this.storagePath = path.join(rootPath, CODEBASE_CONTEXT_DIRNAME, VECTOR_DB_DIRNAME);
@@ -78,7 +133,7 @@ export class CodebaseSearcher {
         }
     }
     /**
-     * v1.2: Load pattern intelligence for trend detection and warnings
+     * Load pattern intelligence for trend detection and warnings
      */
     async loadPatternIntelligence() {
         try {
@@ -112,14 +167,32 @@ export class CodebaseSearcher {
             }
             this.patternIntelligence = { decliningPatterns, risingPatterns, patternWarnings };
             console.error(`[search] Loaded pattern intelligence: ${decliningPatterns.size} declining, ${risingPatterns.size} rising patterns`);
+            this.importCentrality = new Map();
+            if (intelligence.internalFileGraph && intelligence.internalFileGraph.imports) {
+                // Count how many files import each file (in-degree centrality)
+                const importCounts = new Map();
+                for (const [_importingFile, importedFiles] of Object.entries(intelligence.internalFileGraph.imports)) {
+                    const imports = importedFiles;
+                    for (const imported of imports) {
+                        importCounts.set(imported, (importCounts.get(imported) || 0) + 1);
+                    }
+                }
+                // Normalize centrality to 0-1 range
+                const maxImports = Math.max(...Array.from(importCounts.values()), 1);
+                for (const [file, count] of importCounts) {
+                    this.importCentrality.set(file, count / maxImports);
+                }
+                console.error(`[search] Computed import centrality for ${importCounts.size} files`);
+            }
         }
         catch (error) {
             console.warn('Pattern intelligence load failed (will proceed without trend detection):', error);
             this.patternIntelligence = null;
+            this.importCentrality = null;
         }
     }
     /**
-     * v1.2: Detect pattern trend from chunk content
+     * Detect pattern trend from chunk content
      */
     detectChunkTrend(chunk) {
         if (!this.patternIntelligence) {
@@ -144,82 +217,281 @@ export class CodebaseSearcher {
         }
         return { trend: 'Stable' };
     }
-    async search(query, limit = 5, filters, options = DEFAULT_SEARCH_OPTIONS) {
-        if (!this.initialized) {
-            await this.initialize();
+    isTestFile(filePath) {
+        const normalized = filePath.toLowerCase().replace(/\\/g, '/');
+        return (normalized.includes('.spec.') ||
+            normalized.includes('.test.') ||
+            normalized.includes('/e2e/') ||
+            normalized.includes('/__tests__/'));
+    }
+    normalizeQueryTerms(query) {
+        return query
+            .toLowerCase()
+            .split(/[^a-z0-9_]+/)
+            .filter((term) => term.length > 2 && !QUERY_STOP_WORDS.has(term));
+    }
+    /**
+     * Classify query intent based on heuristic patterns
+     */
+    classifyQueryIntent(query) {
+        const lowerQuery = query.toLowerCase();
+        // EXACT_NAME: Contains PascalCase or camelCase tokens (literal class/component names)
+        if (/[A-Z][a-z]+[A-Z]/.test(query) || /[a-z][A-Z]/.test(query)) {
+            return {
+                intent: 'EXACT_NAME',
+                weights: { semantic: 0.4, keyword: 0.6 } // Keyword search dominates for exact names
+            };
         }
-        const { useSemanticSearch, useKeywordSearch, semanticWeight, keywordWeight } = {
-            ...DEFAULT_SEARCH_OPTIONS,
-            ...options
+        // CONFIG: Configuration/setup queries
+        const configKeywords = [
+            'config',
+            'setup',
+            'routing',
+            'providers',
+            'configuration',
+            'bootstrap'
+        ];
+        if (configKeywords.some((kw) => lowerQuery.includes(kw))) {
+            return {
+                intent: 'CONFIG',
+                weights: { semantic: 0.5, keyword: 0.5 } // Balanced
+            };
+        }
+        // WIRING: DI/registration queries
+        const wiringKeywords = [
+            'provide',
+            'inject',
+            'dependency',
+            'register',
+            'wire',
+            'bootstrap',
+            'module'
+        ];
+        if (wiringKeywords.some((kw) => lowerQuery.includes(kw))) {
+            return {
+                intent: 'WIRING',
+                weights: { semantic: 0.5, keyword: 0.5 } // Balanced
+            };
+        }
+        // FLOW: Action/navigation queries
+        const flowVerbs = [
+            'navigate',
+            'redirect',
+            'route',
+            'handle',
+            'process',
+            'execute',
+            'trigger',
+            'dispatch'
+        ];
+        if (flowVerbs.some((verb) => lowerQuery.includes(verb))) {
+            return {
+                intent: 'FLOW',
+                weights: { semantic: 0.6, keyword: 0.4 } // Semantic helps with flow understanding
+            };
+        }
+        // CONCEPTUAL: Natural language without code tokens (default)
+        return {
+            intent: 'CONCEPTUAL',
+            weights: { semantic: 0.7, keyword: 0.3 } // Semantic dominates for concepts
         };
-        const results = new Map();
-        if (useSemanticSearch && this.embeddingProvider && this.storageProvider) {
-            try {
-                const vectorResults = await this.semanticSearch(query, limit * 2, filters);
-                vectorResults.forEach((result) => {
-                    const id = result.chunk.id;
-                    const existing = results.get(id);
-                    if (existing) {
-                        existing.scores.push(result.score * (semanticWeight || 0.7));
-                    }
-                    else {
-                        results.set(id, {
-                            chunk: result.chunk,
-                            scores: [result.score * (semanticWeight || 0.7)]
-                        });
-                    }
-                });
+    }
+    buildQueryVariants(query, maxExpansions) {
+        const variants = [{ query, weight: 1 }];
+        if (maxExpansions <= 0)
+            return variants;
+        const normalized = query.toLowerCase();
+        const terms = new Set(this.normalizeQueryTerms(query));
+        for (const hint of QUERY_EXPANSION_HINTS) {
+            if (!hint.pattern.test(query))
+                continue;
+            for (const term of hint.terms) {
+                if (!normalized.includes(term)) {
+                    terms.add(term);
+                }
             }
-            catch (error) {
-                if (error instanceof IndexCorruptedError) {
-                    throw error; // Propagate to handler for auto-heal
+        }
+        const addedTerms = Array.from(terms).filter((term) => !normalized.includes(term));
+        if (addedTerms.length === 0)
+            return variants;
+        const firstExpansion = `${query} ${addedTerms.slice(0, 6).join(' ')}`.trim();
+        if (firstExpansion !== query) {
+            variants.push({ query: firstExpansion, weight: 0.35 });
+        }
+        if (maxExpansions > 1 && addedTerms.length > 6) {
+            const secondExpansion = `${query} ${addedTerms.slice(6, 12).join(' ')}`.trim();
+            if (secondExpansion !== query) {
+                variants.push({ query: secondExpansion, weight: 0.25 });
+            }
+        }
+        return variants.slice(0, 1 + maxExpansions);
+    }
+    isTemplateOrStyleFile(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        return ['.html', '.scss', '.css', '.less', '.sass', '.styl'].includes(ext);
+    }
+    isCompositionRootFile(filePath) {
+        const normalized = filePath.toLowerCase().replace(/\\/g, '/');
+        const base = path.basename(normalized);
+        if (/^(main|index|bootstrap|startup)\./.test(base))
+            return true;
+        return (normalized.includes('/routes') ||
+            normalized.includes('/routing') ||
+            normalized.includes('/router') ||
+            normalized.includes('/config') ||
+            normalized.includes('/providers'));
+    }
+    queryPathTokenOverlap(filePath, query) {
+        const queryTerms = new Set(this.normalizeQueryTerms(query));
+        if (queryTerms.size === 0)
+            return 0;
+        const pathTerms = this.normalizeQueryTerms(filePath.replace(/\\/g, '/'));
+        return pathTerms.reduce((count, term) => (queryTerms.has(term) ? count + 1 : count), 0);
+    }
+    isLikelyWiringOrFlowQuery(query) {
+        return /\b(route|router|routing|navigate|navigation|redirect|auth|authentication|login|provider|register|config|configuration|interceptor|middleware)\b/i.test(query);
+    }
+    isActionOrHowQuery(query) {
+        return /\b(how|where|configure|configured|setup|register|wire|wiring|navigate|redirect|login|authenticate|copy|upload|handle|create|update|delete)\b/i.test(query);
+    }
+    isDefinitionHeavyResult(chunk) {
+        const normalizedPath = chunk.filePath.toLowerCase().replace(/\\/g, '/');
+        const componentType = (chunk.componentType || '').toLowerCase();
+        if (['type', 'interface', 'enum', 'constant'].includes(componentType))
+            return true;
+        return (normalizedPath.includes('/models/') ||
+            normalizedPath.includes('/interfaces/') ||
+            normalizedPath.includes('/types/') ||
+            normalizedPath.includes('/constants'));
+    }
+    scoreAndSortResults(query, limit, results, profile, intent, totalVariantWeight) {
+        const likelyWiringQuery = this.isLikelyWiringOrFlowQuery(query);
+        const actionQuery = this.isActionOrHowQuery(query);
+        // RRF: k=60 is the standard parameter (proven robust in Elasticsearch + TOSS paper arXiv:2208.11274)
+        const RRF_K = 60;
+        // Collect all unique chunks from both retrieval channels
+        const allChunks = new Map();
+        const rrfScores = new Map();
+        // Gather all chunks
+        for (const [id, entry] of results.semantic) {
+            allChunks.set(id, entry.chunk);
+        }
+        for (const [id, entry] of results.keyword) {
+            if (!allChunks.has(id)) {
+                allChunks.set(id, entry.chunk);
+            }
+        }
+        // Calculate RRF scores: RRF(d) = SUM(weight_i / (k + rank_i))
+        for (const [id] of allChunks) {
+            let rrfScore = 0;
+            // Add contributions from semantic ranks
+            const semanticEntry = results.semantic.get(id);
+            if (semanticEntry) {
+                for (const { rank, weight } of semanticEntry.ranks) {
+                    rrfScore += weight / (RRF_K + rank);
                 }
-                console.warn('Semantic search failed:', error);
             }
+            // Add contributions from keyword ranks
+            const keywordEntry = results.keyword.get(id);
+            if (keywordEntry) {
+                for (const { rank, weight } of keywordEntry.ranks) {
+                    rrfScore += weight / (RRF_K + rank);
+                }
+            }
+            rrfScores.set(id, rrfScore);
         }
-        if (useKeywordSearch && this.fuseIndex) {
-            try {
-                const keywordResults = await this.keywordSearch(query, limit * 2, filters);
-                keywordResults.forEach((result) => {
-                    const id = result.chunk.id;
-                    const existing = results.get(id);
-                    if (existing) {
-                        existing.scores.push(result.score * (keywordWeight || 0.3));
-                    }
-                    else {
-                        results.set(id, {
-                            chunk: result.chunk,
-                            scores: [result.score * (keywordWeight || 0.3)]
-                        });
-                    }
-                });
+        // Normalize by theoretical maximum (rank-0 in every list), NOT by actual max.
+        // Using actual max makes top result always 1.0, breaking quality confidence gating.
+        const theoreticalMaxRrf = totalVariantWeight / (RRF_K + 0);
+        const maxRrfScore = Math.max(theoreticalMaxRrf, 0.01);
+        // Separate test files from implementation files before scoring
+        const isNonTestQuery = !isTestingRelatedQuery(query);
+        const implementationChunks = [];
+        const testChunks = [];
+        for (const [id, chunk] of allChunks.entries()) {
+            if (this.isTestFile(chunk.filePath)) {
+                testChunks.push([id, chunk]);
             }
-            catch (error) {
-                console.warn('Keyword search failed:', error);
+            else {
+                implementationChunks.push([id, chunk]);
             }
         }
-        const combinedResults = Array.from(results.entries())
-            .map(([_id, { chunk, scores }]) => {
-            // Calculate base combined score
-            let combinedScore = scores.reduce((sum, score) => sum + score, 0);
-            // Normalize to 0-1 range (scores are already weighted)
-            // If both semantic and keyword matched, max possible is ~1.0
-            combinedScore = Math.min(1.0, combinedScore);
-            // Boost scores for Angular components with proper detection
-            if (chunk.componentType && chunk.framework === 'angular') {
-                combinedScore = Math.min(1.0, combinedScore * 1.3);
+        // For non-test queries: filter test files from candidate pool, keep max 1 test file only if < 3 implementation matches
+        const chunksToScore = isNonTestQuery ? implementationChunks : Array.from(allChunks.entries());
+        const scoredResults = chunksToScore
+            .map(([id, chunk]) => {
+            // RRF score normalized to [0,1] range. Boosts below are unclamped
+            // to preserve score differentiation — only relative ordering matters.
+            let combinedScore = rrfScores.get(id) / maxRrfScore;
+            // Slight boost when analyzer identified a concrete component type
+            if (chunk.componentType && chunk.componentType !== 'unknown') {
+                combinedScore *= 1.1;
             }
             // Boost if layer is detected
             if (chunk.layer && chunk.layer !== 'unknown') {
-                combinedScore = Math.min(1.0, combinedScore * 1.1);
+                combinedScore *= 1.1;
+            }
+            if (actionQuery && this.isDefinitionHeavyResult(chunk)) {
+                combinedScore *= 0.82;
+            }
+            if (actionQuery &&
+                ['service', 'component', 'interceptor', 'guard', 'module', 'resolver'].includes((chunk.componentType || '').toLowerCase())) {
+                combinedScore *= 1.06;
             }
-            // v1.2: Detect pattern trend and apply momentum boost
+            // Demote template/style files for behavioral queries — they describe
+            // structure/presentation, not implementation logic.
+            if ((intent === 'FLOW' || intent === 'WIRING' || actionQuery) &&
+                this.isTemplateOrStyleFile(chunk.filePath)) {
+                combinedScore *= 0.75;
+            }
+            // Light intent-aware boost for likely wiring/configuration queries.
+            if (likelyWiringQuery && profile !== 'explore') {
+                if (this.isCompositionRootFile(chunk.filePath)) {
+                    combinedScore *= 1.12;
+                }
+            }
+            if (intent === 'FLOW') {
+                // Boost service/guard/interceptor files for action/navigation queries
+                if (['service', 'guard', 'interceptor', 'middleware'].includes((chunk.componentType || '').toLowerCase())) {
+                    combinedScore *= 1.15;
+                }
+            }
+            else if (intent === 'CONFIG') {
+                // Boost composition-root files for configuration queries
+                if (this.isCompositionRootFile(chunk.filePath)) {
+                    combinedScore *= 1.2;
+                }
+            }
+            else if (intent === 'WIRING') {
+                // Boost DI/module files for wiring queries
+                if (['module', 'provider', 'config'].some((type) => (chunk.componentType || '').toLowerCase().includes(type))) {
+                    combinedScore *= 1.18;
+                }
+                if (this.isCompositionRootFile(chunk.filePath)) {
+                    combinedScore *= 1.22;
+                }
+            }
+            const pathOverlap = this.queryPathTokenOverlap(chunk.filePath, query);
+            if (pathOverlap >= 2) {
+                combinedScore *= 1.08;
+            }
+            if (this.importCentrality) {
+                const normalizedRoot = this.rootPath.replace(/\\/g, '/').replace(/\/?$/, '/');
+                const normalizedPath = chunk.filePath.replace(/\\/g, '/').replace(normalizedRoot, '');
+                const centrality = this.importCentrality.get(normalizedPath);
+                if (centrality !== undefined && centrality > 0.1) {
+                    // Boost files with high centrality (many imports)
+                    const centralityBoost = 1.0 + centrality * 0.15; // Up to +15% for max centrality
+                    combinedScore *= centralityBoost;
+                }
+            }
+            // Detect pattern trend and apply momentum boost
             const { trend, warning } = this.detectChunkTrend(chunk);
             if (trend === 'Rising') {
-                combinedScore = Math.min(1.0, combinedScore * 1.15); // +15% for modern patterns
+                combinedScore *= 1.15; // +15% for modern patterns
             }
             else if (trend === 'Declining') {
-                combinedScore = combinedScore * 0.9; // -10% for legacy patterns
+                combinedScore *= 0.9; // -10% for legacy patterns
             }
             const summary = this.generateSummary(chunk);
             const snippet = this.generateSnippet(chunk.content);
@@ -236,14 +508,181 @@ export class CodebaseSearcher {
                 componentType: chunk.componentType,
                 layer: chunk.layer,
                 metadata: chunk.metadata,
-                // v1.2: Pattern momentum awareness
                 trend,
                 patternWarning: warning
             };
         })
-            .sort((a, b) => b.score - a.score)
-            .slice(0, limit);
-        return combinedResults;
+            .sort((a, b) => b.score - a.score);
+        const seenFiles = new Set();
+        const deduped = [];
+        for (const result of scoredResults) {
+            const normalizedPath = result.filePath.toLowerCase().replace(/\\/g, '/');
+            if (seenFiles.has(normalizedPath))
+                continue;
+            seenFiles.add(normalizedPath);
+            deduped.push(result);
+            if (deduped.length >= limit)
+                break;
+        }
+        const finalResults = deduped;
+        if (isNonTestQuery &&
+            finalResults.length < 3 &&
+            finalResults.length < limit &&
+            testChunks.length > 0) {
+            // Find the highest-scoring test file
+            const bestTestChunk = testChunks
+                .map(([id, chunk]) => ({
+                id,
+                chunk,
+                score: rrfScores.get(id) / maxRrfScore
+            }))
+                .sort((a, b) => b.score - a.score)[0];
+            if (bestTestChunk) {
+                const { trend, warning } = this.detectChunkTrend(bestTestChunk.chunk);
+                const summary = this.generateSummary(bestTestChunk.chunk);
+                const snippet = this.generateSnippet(bestTestChunk.chunk.content);
+                finalResults.push({
+                    summary,
+                    snippet,
+                    filePath: bestTestChunk.chunk.filePath,
+                    startLine: bestTestChunk.chunk.startLine,
+                    endLine: bestTestChunk.chunk.endLine,
+                    score: bestTestChunk.score * 0.5, // Demote below implementation files
+                    relevanceReason: this.generateRelevanceReason(bestTestChunk.chunk, query) + ' (test file)',
+                    language: bestTestChunk.chunk.language,
+                    framework: bestTestChunk.chunk.framework,
+                    componentType: bestTestChunk.chunk.componentType,
+                    layer: bestTestChunk.chunk.layer,
+                    metadata: bestTestChunk.chunk.metadata,
+                    trend,
+                    patternWarning: warning
+                });
+            }
+        }
+        return finalResults;
+    }
+    pickBetterResultSet(query, primary, rescue) {
+        const primaryQuality = assessSearchQuality(query, primary);
+        const rescueQuality = assessSearchQuality(query, rescue);
+        if (rescueQuality.status === 'ok' &&
+            primaryQuality.status === 'low_confidence' &&
+            rescueQuality.confidence >= primaryQuality.confidence) {
+            return rescue;
+        }
+        if (rescueQuality.confidence >= primaryQuality.confidence + 0.05) {
+            return rescue;
+        }
+        return primary;
+    }
+    async collectHybridMatches(queryVariants, candidateLimit, filters, useSemanticSearch, useKeywordSearch, semanticWeight, keywordWeight) {
+        const semanticRanks = new Map();
+        const keywordRanks = new Map();
+        // RRF uses ranks instead of scores for fusion robustness
+        if (useSemanticSearch && this.embeddingProvider && this.storageProvider) {
+            try {
+                for (const variant of queryVariants) {
+                    const vectorResults = await this.semanticSearch(variant.query, candidateLimit, filters);
+                    // Assign ranks based on retrieval order (0-indexed)
+                    vectorResults.forEach((result, index) => {
+                        const id = result.chunk.id;
+                        const rank = index; // 0-indexed rank
+                        const weight = semanticWeight * variant.weight;
+                        const existing = semanticRanks.get(id);
+                        if (existing) {
+                            existing.ranks.push({ rank, weight });
+                        }
+                        else {
+                            semanticRanks.set(id, {
+                                chunk: result.chunk,
+                                ranks: [{ rank, weight }]
+                            });
+                        }
+                    });
+                }
+            }
+            catch (error) {
+                if (error instanceof IndexCorruptedError) {
+                    throw error; // Propagate to handler for auto-heal
+                }
+                console.warn('Semantic search failed:', error);
+            }
+        }
+        if (useKeywordSearch && this.fuseIndex) {
+            try {
+                for (const variant of queryVariants) {
+                    const keywordResults = await this.keywordSearch(variant.query, candidateLimit, filters);
+                    // Assign ranks based on retrieval order (0-indexed)
+                    keywordResults.forEach((result, index) => {
+                        const id = result.chunk.id;
+                        const rank = index; // 0-indexed rank
+                        const weight = keywordWeight * variant.weight;
+                        const existing = keywordRanks.get(id);
+                        if (existing) {
+                            existing.ranks.push({ rank, weight });
+                        }
+                        else {
+                            keywordRanks.set(id, {
+                                chunk: result.chunk,
+                                ranks: [{ rank, weight }]
+                            });
+                        }
+                    });
+                }
+            }
+            catch (error) {
+                console.warn('Keyword search failed:', error);
+            }
+        }
+        return { semantic: semanticRanks, keyword: keywordRanks };
+    }
+    async search(query, limit = 5, filters, options = DEFAULT_SEARCH_OPTIONS) {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        const merged = {
+            ...DEFAULT_SEARCH_OPTIONS,
+            ...options
+        };
+        const { useSemanticSearch, useKeywordSearch, profile, enableQueryExpansion, enableLowConfidenceRescue, candidateFloor, enableReranker } = merged;
+        const { intent, weights: intentWeights } = this.classifyQueryIntent(query);
+        // Intent weights are the default; caller-supplied weights override them
+        const finalSemanticWeight = merged.semanticWeight ?? intentWeights.semantic;
+        const finalKeywordWeight = merged.keywordWeight ?? intentWeights.keyword;
+        const candidateLimit = Math.max(limit * 2, candidateFloor || 30);
+        const primaryVariants = this.buildQueryVariants(query, enableQueryExpansion ? 1 : 0);
+        const primaryMatches = await this.collectHybridMatches(primaryVariants, candidateLimit, filters, Boolean(useSemanticSearch), Boolean(useKeywordSearch), finalSemanticWeight, finalKeywordWeight);
+        const primaryTotalWeight = primaryVariants.reduce((sum, v) => sum + v.weight, 0) *
+            (finalSemanticWeight + finalKeywordWeight);
+        const primaryResults = this.scoreAndSortResults(query, limit, primaryMatches, (profile || 'explore'), intent, primaryTotalWeight);
+        let bestResults = primaryResults;
+        if (enableLowConfidenceRescue) {
+            const primaryQuality = assessSearchQuality(query, primaryResults);
+            if (primaryQuality.status === 'low_confidence') {
+                const rescueVariants = this.buildQueryVariants(query, 2).slice(1);
+                if (rescueVariants.length > 0) {
+                    const rescueMatches = await this.collectHybridMatches(rescueVariants.map((variant, index) => ({
+                        query: variant.query,
+                        weight: index === 0 ? 1 : 0.8
+                    })), candidateLimit, filters, Boolean(useSemanticSearch), Boolean(useKeywordSearch), finalSemanticWeight, finalKeywordWeight);
+                    const rescueVariantWeights = rescueVariants.map((_, i) => (i === 0 ? 1 : 0.8));
+                    const rescueTotalWeight = rescueVariantWeights.reduce((sum, w) => sum + w, 0) *
+                        (finalSemanticWeight + finalKeywordWeight);
+                    const rescueResults = this.scoreAndSortResults(query, limit, rescueMatches, (profile || 'explore'), intent, rescueTotalWeight);
+                    bestResults = this.pickBetterResultSet(query, primaryResults, rescueResults);
+                }
+            }
+        }
+        // Stage-2: cross-encoder reranking when top scores are ambiguous
+        if (enableReranker) {
+            try {
+                bestResults = await rerank(query, bestResults);
+            }
+            catch (error) {
+                // Reranker is non-critical — log and return unranked results
+                console.warn('[reranker] Failed, returning original order:', error);
+            }
+        }
+        return bestResults;
     }
     generateSummary(chunk) {
         const analyzer = chunk.framework ? analyzerRegistry.get(chunk.framework) : null;
@@ -287,7 +726,7 @@ export class CodebaseSearcher {
         };
         return `${langMap[ext] || ext.toUpperCase()} in ${fileName}.`;
     }
-    generateSnippet(content, maxLines = 100) {
+    generateSnippet(content, maxLines = 20) {
         const lines = content.split('\n');
         if (lines.length <= maxLines) {
             return content;