( query: string, results: SearchResult[] )
| 19 | } |
| 20 | |
| 21 | export function assessSearchQuality( |
| 22 | query: string, |
| 23 | results: SearchResult[] |
| 24 | ): SearchQualityAssessment { |
| 25 | if (results.length === 0) { |
| 26 | return { |
| 27 | status: 'low_confidence', |
| 28 | confidence: 0, |
| 29 | signals: ['no results returned'], |
| 30 | nextSteps: [ |
| 31 | 'Try a narrower query with one concrete symbol, route, or file hint.', |
| 32 | 'Apply search filters (framework/language/componentType/layer).', |
| 33 | 'Use get_symbol_references to find where a specific symbol is used across the codebase.' |
| 34 | ] |
| 35 | }; |
| 36 | } |
| 37 | |
| 38 | const topSlice = results.slice(0, Math.min(3, results.length)); |
| 39 | const topScore = results[0].score; |
| 40 | const secondScore = results[1]?.score ?? topScore; |
| 41 | const topAverage = topSlice.reduce((sum, result) => sum + result.score, 0) / topSlice.length; |
| 42 | const topSeparation = Math.max(0, topScore - secondScore); |
| 43 | const testRatio = |
| 44 | topSlice.filter((result) => isTestArtifactPath(result.filePath)).length / topSlice.length; |
| 45 | const queryIsTesting = isTestingRelatedQuery(query); |
| 46 | |
| 47 | const signals: string[] = []; |
| 48 | if (topScore < 0.3) { |
| 49 | signals.push(`low top score (${topScore.toFixed(2)})`); |
| 50 | } |
| 51 | if (topAverage < 0.32) { |
| 52 | signals.push(`weak top-${topSlice.length} average (${topAverage.toFixed(2)})`); |
| 53 | } |
| 54 | if (topSlice.length > 1 && topSeparation < 0.03) { |
| 55 | signals.push(`tight top spread (${topSeparation.toFixed(2)})`); |
| 56 | } |
| 57 | if (!queryIsTesting && testRatio >= 0.67) { |
| 58 | signals.push( |
| 59 | `test artifacts dominate top-${topSlice.length} (${Math.round(testRatio * 100)}%)` |
| 60 | ); |
| 61 | } |
| 62 | |
| 63 | let confidence = topScore; |
| 64 | if (topAverage < 0.32) confidence -= 0.08; |
| 65 | if (topSlice.length > 1 && topSeparation < 0.03) confidence -= 0.05; |
| 66 | if (!queryIsTesting && testRatio >= 0.67) confidence -= 0.15; |
| 67 | confidence = Math.max(0, Math.min(1, Number(confidence.toFixed(2)))); |
| 68 | |
| 69 | const lowConfidence = signals.length >= 2 || confidence < 0.35; |
| 70 | |
| 71 | return { |
| 72 | status: lowConfidence ? 'low_confidence' : 'ok', |
| 73 | confidence, |
| 74 | signals, |
| 75 | ...(lowConfidence && { |
| 76 | nextSteps: [ |
| 77 | 'Add one or two concrete symbols, routes, or file hints to the query.', |
| 78 | 'Apply filters (framework/language/componentType/layer) to narrow candidates.', |
no test coverage detected