feat: add ranking explanation page + raw score and semantic score + label link (#53)

* feat: add ranking explanation page

* add link to issues filtered by label

---------

Co-authored-by: zx <[email protected]>

Author: zxt-tzx

packages/core/src/constants/ranking.constant.ts

@@ -0,0 +1,26 @@
+// would need to recalibrate normalization + score colors in IssueCard.tsx
+// if we change weights/algorithm here
+
+// Ranking weights (should sum to 1)
+export const RANKING_WEIGHTS = {
+  SEMANTIC_SIMILARITY: 0.8, // Start with higher weight for semantic search
+  COMMENT_COUNT: 0.12, // Activity level
+  RECENCY: 0.05, // Recent updates
+  ISSUE_STATE: 0.03, // Small bonus for open issues
+} as const;
+
+// Time-based constants
+export const TIME_CONSTANTS = {
+  // Base time unit in days for recency calculation
+  RECENCY_BASE_DAYS: 30,
+} as const;
+
+export const COMMENT_COUNT_CAP = 80;
+
+// Score multipliers
+export const SCORE_MULTIPLIERS = {
+  OPEN_ISSUE: 1.0,
+  CLOSED_ISSUE: 0.8,
+} as const;
+
+export const NORMALIZATION_ANCHOR = 0.65;

packages/core/src/semsearch/index.ts

@@ -185,6 +185,7 @@ async function filterAfterVectorSearch(
     let query = tx
       .select({
         ...getBaseSelect(),
+        similarityScore,
         rankingScore,
         // Add a window function to get the total count in the same query
         totalCount: sql<number>`count(*) over()`.as("total_count"),
@@ -278,6 +279,7 @@ async function filterBeforeVectorSearch(
         repoLastSyncedAt: vectorSearchSubquery.repoLastSyncedAt,
         commentCount: vectorSearchSubquery.commentCount,
         rankingScore,
+        similarityScore,
         // Add window function to get total count in same query
         totalCount: sql<number>`count(*) over()`.as("total_count"),
       })

packages/core/src/semsearch/ranking.ts

@@ -1,29 +1,13 @@
+import {
+  COMMENT_COUNT_CAP,
+  RANKING_WEIGHTS,
+  SCORE_MULTIPLIERS,
+  TIME_CONSTANTS,
+} from "@/constants/ranking.constant";
 import type { AnyColumn, SQL } from "@/db";
 import { sql } from "@/db";
 import { comments } from "@/db/schema/entities/comment.sql";
 
-// would need to recalibrate normalization + score colors in IssueCard.tsx
-// if we change weights/algorithm here
-
-// Ranking weights (should sum to 1)
-const RANKING_WEIGHTS = {
-  SEMANTIC_SIMILARITY: 0.8, // Start with higher weight for semantic search
-  COMMENT_COUNT: 0.12, // Activity level
-  RECENCY: 0.05, // Recent updates
-  ISSUE_STATE: 0.03, // Small bonus for open issues
-} as const;
-
-// Time-based constants
-const TIME_CONSTANTS = {
-  // Base time unit in days for recency calculation
-  RECENCY_BASE_DAYS: 30,
-} as const;
-
-// Score multipliers
-const SCORE_MULTIPLIERS = {
-  OPEN_ISSUE: 1.0,
-  CLOSED_ISSUE: 0.8,
-} as const;
 /**
  * Calculates recency score using exponential decay
  * exp(-t/τ) where:
@@ -57,7 +41,7 @@ export function calculateRecencyScore(issueUpdatedAtColumn: SQL | AnyColumn) {
 export function calculateCommentScore(issueId: SQL | AnyColumn) {
   return sql<number>`
     LN(GREATEST((SELECT count(*) FROM ${comments} WHERE ${comments.issueId} = ${issueId})::float + 1, 1)) /
-    LN(51)  -- ln(50 + 1) ≈ 3.93 as normalizing factor
+    LN(${COMMENT_COUNT_CAP} + 1)
   `;
 }
 

packages/core/src/semsearch/schema.ts

@@ -67,10 +67,8 @@ const searchIssueSchema = createSelectSchema(issueTable, {
     // Search-specific fields
     commentCount: z.number(),
     rankingScore: z.number(),
-  })
-  .transform((issue) => ({
-    ...issue,
-  }));
+    similarityScore: z.number(),
+  });
 
 export const searchResultSchema = z.object({
   data: z.array(searchIssueSchema),

packages/web/src/components/search/IssueCard.tsx

@@ -1,3 +1,4 @@
+import { Link } from "@tanstack/react-router";
 import DOMPurify from "dompurify";
 import {
   CircleCheckIcon,
@@ -6,6 +7,7 @@ import {
   MessageSquareIcon,
 } from "lucide-react";
 
+import { NORMALIZATION_ANCHOR } from "@/core/constants/ranking.constant";
 import type { AggregateReactions } from "@/core/db/schema/shared";
 import type { PublicSearchIssuesResponse } from "@/lib/api/search";
 import { formatLocalDateTime, getTimeAgo } from "@/lib/time";
@@ -118,11 +120,8 @@ function RepoTag({ issue }: { issue: Issue }) {
   );
 }
 
-// would need to recalibrate normalization + score colors based on weights
-// and algorithm used in semsearch/ranking.ts
 function normalizeScore(rawScore: number): number {
-  const ANCHOR = 0.65;
-  const normalizedScore = (rawScore / ANCHOR) * 100;
+  const normalizedScore = (rawScore / NORMALIZATION_ANCHOR) * 100;
   return Math.min(normalizedScore, 100);
 }
 
@@ -133,12 +132,26 @@ function getScoreColor(rawScore: number): string {
   return "bg-gray-100 text-gray-800";
 }
 
-function ScoreBadge({ score }: { score: number }) {
-  const normalizedScore = normalizeScore(score);
-  const colorClass = getScoreColor(score);
+function ScoreBadge({
+  rankingScore,
+  similarityScore,
+}: {
+  rankingScore: number;
+  similarityScore: number;
+}) {
+  const normalizedScore = normalizeScore(rankingScore);
+  const colorClass = getScoreColor(rankingScore);
+  const toolTipContent = (
+    <>
+      Raw score: {(rankingScore * 100).toFixed(1)}%
+      <br />
+      Similarity: {(similarityScore * 100).toFixed(1)}%
+      <br />
+      <Link to="/ranking">Learn more</Link>
+    </>
+  );
   return (
-    // TODO: add more scores showing breakdown?
-    <FastTooltip content={`Raw score: ${(score * 100).toFixed(1)}%`}>
+    <FastTooltip content={toolTipContent}>
       <span
         className={`mr-1.5 inline-flex rounded-md px-1.5 py-0.5 text-sm font-medium ${colorClass}`}
       >
@@ -150,17 +163,28 @@ function ScoreBadge({ score }: { score: number }) {
 
 function IssueTitleWithLabels({ issue }: { issue: Issue }) {
   const renderLabel = (label: Issue["labels"][number]) => {
+    // Get the base repo URL by removing '/issues/number' from the issue URL
+    const repoBaseUrl = issue.issueUrl.split("/issues/")[0];
+    const labelFilterUrl = `${repoBaseUrl}/issues?q=is:issue+label:"${encodeURIComponent(label.name)}"`;
+
     const badgeElement = (
-      <Badge
-        variant="secondary"
-        className="mx-1 inline-flex rounded-full px-2 py-0.5"
-        style={{
-          backgroundColor: `#${label.color}`,
-          color: `${parseInt(label.color, 16) > 0x7fffff ? "#000" : "#fff"}`,
-        }}
+      <a
+        href={labelFilterUrl}
+        target="_blank"
+        rel="noopener noreferrer"
+        onClick={(e) => e.stopPropagation()}
       >
-        {label.name}
-      </Badge>
+        <Badge
+          variant="secondary"
+          className="mx-1 inline-flex rounded-full px-2 py-0.5 hover:opacity-80"
+          style={{
+            backgroundColor: `#${label.color}`,
+            color: `${parseInt(label.color, 16) > 0x7fffff ? "#000" : "#fff"}`,
+          }}
+        >
+          {label.name}
+        </Badge>
+      </a>
     );
 
     // description can be null or empty string
@@ -178,7 +202,10 @@ function IssueTitleWithLabels({ issue }: { issue: Issue }) {
 
   return (
     <div className="min-w-0 grow text-lg font-semibold">
-      <ScoreBadge score={issue.rankingScore} />
+      <ScoreBadge
+        rankingScore={issue.rankingScore}
+        similarityScore={issue.similarityScore}
+      />
       <a
         href={issue.issueUrl}
         target="_blank"

packages/web/src/routeTree.gen.ts

@@ -12,6 +12,7 @@
 
 import { Route as rootRoute } from './routes/__root'
 import { Route as SearchImport } from './routes/search'
+import { Route as RankingImport } from './routes/ranking'
 import { Route as IndexImport } from './routes/index'
 import { Route as ReposIndexImport } from './routes/repos/index'
 import { Route as ReposSearchImport } from './routes/repos/search'
@@ -25,6 +26,11 @@ const SearchRoute = SearchImport.update({
   getParentRoute: () => rootRoute,
 } as any)
 
+const RankingRoute = RankingImport.update({
+  path: '/ranking',
+  getParentRoute: () => rootRoute,
+} as any)
+
 const IndexRoute = IndexImport.update({
   path: '/',
   getParentRoute: () => rootRoute,
@@ -61,6 +67,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexImport
       parentRoute: typeof rootRoute
     }
+    '/ranking': {
+      id: '/ranking'
+      path: '/ranking'
+      fullPath: '/ranking'
+      preLoaderRoute: typeof RankingImport
+      parentRoute: typeof rootRoute
+    }
     '/search': {
       id: '/search'
       path: '/search'
@@ -103,6 +116,7 @@ declare module '@tanstack/react-router' {
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/ranking': typeof RankingRoute
   '/search': typeof SearchRoute
   '/repos/search': typeof ReposSearchRoute
   '/repos': typeof ReposIndexRoute
@@ -112,6 +126,7 @@ export interface FileRoutesByFullPath {
 
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/ranking': typeof RankingRoute
   '/search': typeof SearchRoute
   '/repos/search': typeof ReposSearchRoute
   '/repos': typeof ReposIndexRoute
@@ -122,6 +137,7 @@ export interface FileRoutesByTo {
 export interface FileRoutesById {
   __root__: typeof rootRoute
   '/': typeof IndexRoute
+  '/ranking': typeof RankingRoute
   '/search': typeof SearchRoute
   '/repos/search': typeof ReposSearchRoute
   '/repos/': typeof ReposIndexRoute
@@ -133,6 +149,7 @@ export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
     | '/'
+    | '/ranking'
     | '/search'
     | '/repos/search'
     | '/repos'
@@ -141,6 +158,7 @@ export interface FileRouteTypes {
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
+    | '/ranking'
     | '/search'
     | '/repos/search'
     | '/repos'
@@ -149,6 +167,7 @@ export interface FileRouteTypes {
   id:
     | '__root__'
     | '/'
+    | '/ranking'
     | '/search'
     | '/repos/search'
     | '/repos/'
@@ -159,6 +178,7 @@ export interface FileRouteTypes {
 
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  RankingRoute: typeof RankingRoute
   SearchRoute: typeof SearchRoute
   ReposSearchRoute: typeof ReposSearchRoute
   ReposIndexRoute: typeof ReposIndexRoute
@@ -168,6 +188,7 @@ export interface RootRouteChildren {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  RankingRoute: RankingRoute,
   SearchRoute: SearchRoute,
   ReposSearchRoute: ReposSearchRoute,
   ReposIndexRoute: ReposIndexRoute,
@@ -188,6 +209,7 @@ export const routeTree = rootRoute
       "filePath": "__root.tsx",
       "children": [
         "/",
+        "/ranking",
         "/search",
         "/repos/search",
         "/repos/",
@@ -198,6 +220,9 @@ export const routeTree = rootRoute
     "/": {
       "filePath": "index.tsx"
     },
+    "/ranking": {
+      "filePath": "ranking.tsx"
+    },
     "/search": {
       "filePath": "search.tsx"
     },

packages/web/src/routes/r/your/repo.tsx

@@ -29,34 +29,29 @@ function YourRepoPage() {
                 <span className="text-blue-600 dark:text-blue-500">Sem</span>
                 <span className="text-orange-500">Hub</span> a try
               </h2>
-              <ul className="flex flex-col gap-3 text-left text-muted-foreground">
-                <li className="flex items-center gap-3">
-                  <div className="size-1.5 rounded-full bg-blue-600/40" />
+              <ul className="flex list-disc flex-col gap-3 pl-5 text-left text-muted-foreground marker:text-blue-600/40">
+                <li>
                   <span>
                     Help users find answers faster with semantic search
                   </span>
                 </li>
-                <li className="flex items-center gap-3">
-                  <div className="size-1.5 rounded-full bg-blue-600/40" />
+                <li>
                   <span>
                     Reduce duplicate issues by making existing ones discoverable
                   </span>
                 </li>
-                <li className="flex items-center gap-3">
-                  <div className="size-1.5 rounded-full bg-blue-600/40" />
+                <li>
                   <span>Simple setup - just add a badge to your README</span>
                 </li>
-                <li className="flex items-center gap-3">
-                  <div className="size-1.5 rounded-full bg-blue-600/20" />
+                <li className="marker:!text-blue-600/20">
                   <span className="[word-break:break-word]">
                     Search across pull requests and discussions
                     <Badge variant="coming-soon" className="ml-2">
                       Coming soon
                     </Badge>
                   </span>
                 </li>
-                <li className="flex items-center gap-3">
-                  <div className="size-1.5 rounded-full bg-blue-600/20" />
+                <li className="marker:!text-blue-600/20">
                   <span className="[word-break:break-word]">
                     Search across a collection of multiple repos, including
                     private repos