@comfanion/usethis_search 3.0.0-dev.22 → 3.0.0-dev.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/usethis_search",
-  "version": "3.0.0-dev.22",
+  "version": "3.0.0-dev.23",
   "description": "OpenCode plugin: semantic search with graph-based context (v3: graph relations, 1-hop context, LSP + regex analyzers)",
   "type": "module",
   "main": "./index.ts",

package/tools/search.ts

@@ -164,24 +164,34 @@ Examples:
       }
 
       // ── Reranking — boost results where query keywords appear in text ──────
+      // Also store score components for breakdown display
       const queryKeywords = args.query.toLowerCase().split(/\s+/).filter((w: string) => w.length > 2)
-      if (queryKeywords.length > 0) {
-        for (const r of allResults) {
-          const text = (r.content || "").toLowerCase()
-          let keywordHits = 0
+      for (const r of allResults) {
+        // Vector score (L2 → similarity)
+        const vectorScore = r._distance != null ? Math.max(0, 1 - r._distance / 2) : 0
+        r._vectorScore = vectorScore
+
+        // BM25 component (present only in hybrid mode — embedded in _combinedScore)
+        // If _combinedScore exists and differs from vectorScore, the difference is BM25 contribution
+        r._bm25Component = r._combinedScore != null ? Math.max(0, r._combinedScore - vectorScore) : 0
+
+        // Base score before keyword boost
+        const baseScore = r._combinedScore ?? vectorScore
+
+        // Keyword matching
+        const text = (r.content || "").toLowerCase()
+        const matchedKeywords: string[] = []
+        if (queryKeywords.length > 0) {
           for (const kw of queryKeywords) {
-            if (text.includes(kw)) keywordHits++
+            if (text.includes(kw)) matchedKeywords.push(kw)
           }
-          const keywordBonus = queryKeywords.length > 0 ? (keywordHits / queryKeywords.length) * 0.15 : 0
-          const baseScore = r._combinedScore ?? (r._distance != null ? Math.max(0, 1 - r._distance / 2) : 0)
-          r._finalScore = baseScore + keywordBonus
-        }
-        allResults.sort((a: any, b: any) => (b._finalScore ?? 0) - (a._finalScore ?? 0))
-      } else {
-        for (const r of allResults) {
-          r._finalScore = r._combinedScore ?? (r._distance != null ? Math.max(0, 1 - r._distance / 2) : 0)
         }
+        r._matchedKeywords = matchedKeywords
+        const keywordBonus = queryKeywords.length > 0 ? (matchedKeywords.length / queryKeywords.length) * 0.15 : 0
+        r._keywordBonus = keywordBonus
+        r._finalScore = baseScore + keywordBonus
       }
+      allResults.sort((a: any, b: any) => (b._finalScore ?? 0) - (a._finalScore ?? 0))
 
       // ── Group by file — best chunk per file, with chunk count ─────────────
       const fileGroups = new Map<string, { best: any, chunks: any[] }>()
@@ -233,8 +243,19 @@ Examples:
         if (r.class_name) metaParts.push(`class: ${r.class_name}`)
         const metaLine = metaParts.length > 0 ? ` (${metaParts.join(", ")})` : ""
 
+        // Score breakdown: vector + bm25 + keywords
+        const breakdownParts: string[] = [`vec: ${(r._vectorScore ?? 0).toFixed(2)}`]
+        if (r._bm25Component > 0.005) breakdownParts.push(`bm25: +${r._bm25Component.toFixed(2)}`)
+        if (r._keywordBonus > 0.005) breakdownParts.push(`kw: +${r._keywordBonus.toFixed(2)}`)
+        const breakdown = breakdownParts.join(", ")
+
+        // Matched keywords
+        const kwDisplay = r._matchedKeywords && r._matchedKeywords.length > 0
+          ? ` | matched: "${r._matchedKeywords.join('", "')}"`
+          : ""
+
         output += `### ${i + 1}. ${r.file}${indexLabel}${chunkNote}\n`
-        output += `**Relevance:** ${score}${metaLine}\n\n`
+        output += `**Score:** ${score} (${breakdown}${kwDisplay})${metaLine}\n\n`
         output += "```\n"
         const content = r.content.length > 500 ? r.content.substring(0, 500) + "\n... (truncated)" : r.content
         output += content