feat(leaderboard): implement composite scoring with precomputed metrics

Implement composite leaderboard scoring combining Bayesian rating, trending score, and engagement metrics. Add precomputed columns (composite_score, bayesian_rating, trending_score, favorite_count) to skills table with indexing for performance. Refactor search algorithms to support query aliases and improved boosting. Add signal badge component and leaderboard utility functions. Update migration and seed data.

Author: mrgoonie

.claude/agent-memory/code-reviewer/MEMORY.md

@@ -0,0 +1,25 @@
+# Code Reviewer Memory - SkillX Project
+
+## Project Context
+- SkillX.sh: AI agent skills marketplace (React Router v7 + Cloudflare Workers + D1/SQLite)
+- Monorepo: `apps/web` (main app), `packages/cli`
+- DB: Drizzle ORM with `mode: "timestamp_ms"` (stores integers, returns Date objects)
+- Cache: KV with `getCached()` pattern (no explicit invalidation helper exists)
+
+## Key Patterns Discovered
+- **Date in raw SQL:** Drizzle `timestamp_ms` columns store integer ms. Typed queries handle conversion, but raw `sql` template literals do NOT auto-convert `Date` to ms. Always use `.getTime()` in raw SQL.
+- **KV cache key collisions:** Multiple loaders can share cache key prefixes. If they select different column sets, the first writer poisons the cache for others. Always ensure same-key = same-shape.
+- **Pre-existing TS errors:** ~20+ TS errors exist in search, embed, auth, and other routes. These are NOT from new changes. Don't flag them as regressions.
+- **No cache invalidation utility:** `kv-cache.ts` only has `getCached()`. There's no `invalidate()` or `deleteCached()`. Cache relies purely on TTL expiry.
+
+## Recurring Patterns to Watch
+- Synchronous DB-heavy operations in request path (should use `waitUntil()` on Workers)
+- Code duplication across SSR loader and API route for same data
+- `getOrderColumn` switch-case duplicated between page route and API route
+- Badge computation logic duplicated between API and page loaders
+
+## Architecture Notes
+- Leaderboard uses precomputed score columns updated on write events
+- Search uses real-time boost scoring (different weights than leaderboard)
+- Two weight systems: search boost (7 signals incl. RRF) vs leaderboard composite (6 signals)
+- Scoring utils shared: `logNormalize`, `recencyScore` in `~/lib/scoring-utils.ts`

apps/web/.claude/agent-memory/code-reviewer/MEMORY.md

@@ -0,0 +1,44 @@
+# Code Reviewer Memory - SkillX Project
+
+## Project Context
+- SkillX.sh: AI agent skills marketplace (React Router v7 + Vite + SSR on Cloudflare Workers)
+- DB: Cloudflare D1 (SQLite) + Drizzle ORM
+- Search: FTS5 + Vectorize (768-dim) + RRF fusion + 7-signal boost scoring
+- Max 200 LOC per file rule enforced
+
+## Key Patterns Observed
+
+### Search Architecture
+- FTS5 virtual table: `skills_fts(name, description, content)` with BM25 weights (10/5/1)
+- Vectorize: `bge-base-en-v1.5`, 768-dim, cosine similarity
+- RRF fusion constant k=60 (standard)
+- Boost: 50% RRF, 15% rating, 10% stars, 8% usage, 7% success, 5% recency, 5% favorite
+- Pre-filtering pushed to retrieval (FTS5 WHERE + Vectorize metadata filter)
+- Fallback chain: hybrid -> FTS5-only -> empty
+
+### Recurring Issues
+- FTS5 fallback logic duplicated 4x across 3 files (DRY violation)
+- `api.search.ts` has implicit `any[]` TS errors on `results` variable
+- Drizzle timestamp columns use `mode: "timestamp_ms"` but some routes pass raw numbers
+- Pre-existing TS errors in non-search routes (api.skill-rate, api.skill-review, etc.)
+
+### SQL Injection Safety
+- FTS5 sanitization: `query.replace(/[^\w\s]/g, '')` strips specials before MATCH
+- All Drizzle queries use parameterized API
+- Raw SQL uses `sql` tagged template literals
+
+### Edge Cases to Watch
+- Multi-word aliases (cli, gcp, devops) expand to individual OR terms, not phrases
+- `Math.max(...largeArray)` can stack overflow but currently bounded by limit*2
+- Vectorize metadata filter types must match index schema (is_paid as int vs bool)
+
+## File Locations
+- Search modules: `apps/web/app/lib/search/`
+- DB schema: `apps/web/app/lib/db/schema.ts`
+- FTS5 migration: `apps/web/drizzle/migrations/0001_fts5-fulltext-search.sql`
+- API search route: `apps/web/app/routes/api.search.ts`
+- Page search route: `apps/web/app/routes/search.tsx`
+
+## Typecheck Command
+- `pnpm typecheck` from `apps/web/` directory
+- 25+ pre-existing TS errors in non-search routes (timestamp/type issues)

apps/web/app/components/filter-tabs.tsx

@@ -4,10 +4,11 @@ interface FilterTabsProps {
 }
 
 const TABS = [
-  { id: "all", label: "All Time" },
+  { id: "best", label: "Best" },
+  { id: "rating", label: "Top Rated" },
+  { id: "installs", label: "Most Installed" },
   { id: "trending", label: "Trending" },
-  { id: "top", label: "Top Rated" },
-  { id: "new", label: "New" },
+  { id: "newest", label: "Newest" },
 ];
 
 export function FilterTabs({ activeTab, onTabChange }: FilterTabsProps) {

apps/web/app/components/home-leaderboard.tsx

@@ -37,7 +37,7 @@ export function HomeLeaderboard({
 
     try {
       const res = await fetch(
-        `/api/leaderboard?sort=installs&offset=${entriesLengthRef.current}&limit=${PAGE_SIZE}`
+        `/api/leaderboard?sort=best&offset=${entriesLengthRef.current}&limit=${PAGE_SIZE}`
       );
       const data = (await res.json()) as {
         entries: LeaderboardEntry[];

apps/web/app/components/leaderboard-table.tsx

@@ -1,71 +1,42 @@
-import { ArrowUpDown, ExternalLink } from "lucide-react";
+import { ExternalLink } from "lucide-react";
 import { Link } from "react-router";
 import { RatingBadge } from "./rating-badge";
+import { SignalBadge } from "./signal-badge";
 
-interface LeaderboardEntry {
+export interface LeaderboardEntry {
   rank: number;
   slug: string;
   name: string;
   author: string;
   installs: number;
   rating: number;
+  badges?: string[];
 }
 
 interface LeaderboardTableProps {
   entries: LeaderboardEntry[];
-  onSort?: (column: string) => void;
 }
 
-export function LeaderboardTable({ entries, onSort }: LeaderboardTableProps) {
+export function LeaderboardTable({ entries }: LeaderboardTableProps) {
   return (
     <div className="overflow-x-auto rounded-lg border border-sx-border">
       <table className="w-full">
         <thead className="sticky top-0 bg-sx-bg-elevated">
           <tr className="border-b border-sx-border">
-            <th className="px-4 py-3 text-left">
-              <button
-                onClick={() => onSort?.("rank")}
-                className="flex items-center gap-1 font-mono text-xs uppercase tracking-wide text-sx-fg-muted hover:text-sx-fg"
-              >
-                Rank
-                <ArrowUpDown size={12} />
-              </button>
+            <th className="px-4 py-3 text-left font-mono text-xs uppercase tracking-wide text-sx-fg-muted">
+              Rank
             </th>
-            <th className="px-4 py-3 text-left">
-              <button
-                onClick={() => onSort?.("skill")}
-                className="flex items-center gap-1 font-mono text-xs uppercase tracking-wide text-sx-fg-muted hover:text-sx-fg"
-              >
-                Skill
-                <ArrowUpDown size={12} />
-              </button>
+            <th className="px-4 py-3 text-left font-mono text-xs uppercase tracking-wide text-sx-fg-muted">
+              Skill
             </th>
-            <th className="px-4 py-3 text-left">
-              <button
-                onClick={() => onSort?.("author")}
-                className="flex items-center gap-1 font-mono text-xs uppercase tracking-wide text-sx-fg-muted hover:text-sx-fg"
-              >
-                Author
-                <ArrowUpDown size={12} />
-              </button>
+            <th className="px-4 py-3 text-left font-mono text-xs uppercase tracking-wide text-sx-fg-muted">
+              Author
             </th>
-            <th className="px-4 py-3 text-left">
-              <button
-                onClick={() => onSort?.("installs")}
-                className="flex items-center gap-1 font-mono text-xs uppercase tracking-wide text-sx-fg-muted hover:text-sx-fg"
-              >
-                Installs
-                <ArrowUpDown size={12} />
-              </button>
+            <th className="px-4 py-3 text-left font-mono text-xs uppercase tracking-wide text-sx-fg-muted">
+              Installs
             </th>
-            <th className="px-4 py-3 text-left">
-              <button
-                onClick={() => onSort?.("rating")}
-                className="flex items-center gap-1 font-mono text-xs uppercase tracking-wide text-sx-fg-muted hover:text-sx-fg"
-              >
-                Rating
-                <ArrowUpDown size={12} />
-              </button>
+            <th className="px-4 py-3 text-left font-mono text-xs uppercase tracking-wide text-sx-fg-muted">
+              Rating
             </th>
             <th className="px-4 py-3 text-right font-mono text-xs uppercase tracking-wide text-sx-fg-muted">
               Actions
@@ -96,12 +67,17 @@ export function LeaderboardTable({ entries, onSort }: LeaderboardTableProps) {
                 </span>
               </td>
               <td className="px-4 py-3">
-                <Link
-                  to={`/skills/${entry.slug}`}
-                  className="font-medium text-sx-fg hover:text-sx-accent"
-                >
-                  {entry.name}
-                </Link>
+                <div className="flex flex-wrap items-center">
+                  <Link
+                    to={`/skills/${entry.slug}`}
+                    className="font-medium text-sx-fg hover:text-sx-accent"
+                  >
+                    {entry.name}
+                  </Link>
+                  {entry.badges?.map((b) => (
+                    <SignalBadge key={b} type={b} />
+                  ))}
+                </div>
               </td>
               <td className="px-4 py-3 text-sm text-sx-fg-muted">
                 {entry.author}

apps/web/app/components/signal-badge.tsx

@@ -0,0 +1,26 @@
+/** Small pill badge showing quality signals on leaderboard entries */
+
+const BADGE_CONFIG: Record<string, { label: string; className: string }> = {
+  "top-rated": { label: "Top Rated", className: "bg-yellow-500/10 text-yellow-400" },
+  "popular": { label: "Popular", className: "bg-sx-accent-muted text-sx-accent" },
+  "trending": { label: "Trending", className: "bg-orange-500/10 text-orange-400" },
+  "well-maintained": { label: "Maintained", className: "bg-blue-500/10 text-blue-400" },
+  "community-pick": { label: "Community Pick", className: "bg-pink-500/10 text-pink-400" },
+};
+
+interface SignalBadgeProps {
+  type: string;
+}
+
+export function SignalBadge({ type }: SignalBadgeProps) {
+  const config = BADGE_CONFIG[type];
+  if (!config) return null;
+
+  return (
+    <span
+      className={`ml-1.5 inline-flex rounded-full px-2 py-0.5 font-mono text-[10px] uppercase tracking-wide ${config.className}`}
+    >
+      {config.label}
+    </span>
+  );
+}

apps/web/app/lib/db/schema.ts

@@ -20,13 +20,20 @@ export const skills = sqliteTable(
     rating_count: integer("rating_count").default(0),
     github_stars: integer("github_stars").default(0),
     install_count: integer("install_count").default(0),
+    // Precomputed leaderboard scores (updated on write events)
+    composite_score: real("composite_score").default(0),
+    bayesian_rating: real("bayesian_rating").default(0),
+    trending_score: real("trending_score").default(0),
+    favorite_count: integer("favorite_count").default(0),
     created_at: integer("created_at", { mode: "timestamp_ms" }).notNull(),
     updated_at: integer("updated_at", { mode: "timestamp_ms" }).notNull(),
   },
   (table) => [
     index("idx_skills_category").on(table.category),
     index("idx_skills_author").on(table.author),
     index("idx_skills_avg_rating").on(table.avg_rating),
+    index("idx_skills_composite_score").on(table.composite_score),
+    index("idx_skills_trending_score").on(table.trending_score),
   ]
 );
 

apps/web/app/lib/leaderboard/leaderboard-scoring.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure scoring functions for leaderboard composite ranking.
+ * Bayesian average, composite score (6 weighted signals), trending velocity.
+ */
+
+import { logNormalize, recencyScore } from "~/lib/scoring-utils";
+
+/** Leaderboard composite weights — must sum to 1.0 */
+const WEIGHTS = {
+  bayesianRating: 0.35,
+  installs: 0.25,
+  stars: 0.15,
+  success: 0.10,
+  recency: 0.10,
+  favorites: 0.05,
+} as const;
+
+/** Default confidence threshold for Bayesian average */
+const DEFAULT_CONFIDENCE = 10;
+
+/**
+ * Bayesian average rating — pulls low-sample skills toward global mean.
+ * Formula: (C * m + avg * n) / (C + n)
+ */
+export function computeBayesianRating(
+  avgRating: number,
+  ratingCount: number,
+  globalAvgRating: number,
+  confidence = DEFAULT_CONFIDENCE,
+): number {
+  return (confidence * globalAvgRating + avgRating * ratingCount) /
+    (confidence + ratingCount);
+}
+
+export interface CompositeInputs {
+  bayesianRating: number;
+  installCount: number;
+  githubStars: number;
+  successRate: number;
+  updatedAt: Date | null;
+  favoriteCount: number;
+  maxInstalls: number;
+  maxStars: number;
+  maxFavorites: number;
+}
+
+/**
+ * Composite leaderboard score combining 6 normalized signals.
+ * Returns value in 0-1 range.
+ */
+export function computeCompositeScore(inputs: CompositeInputs): number {
+  const normalizedRating = inputs.bayesianRating / 10; // scale is 0-10
+  const normalizedInstalls = logNormalize(inputs.installCount, inputs.maxInstalls);
+  const normalizedStars = logNormalize(inputs.githubStars, inputs.maxStars);
+  const normalizedFavorites = logNormalize(inputs.favoriteCount, inputs.maxFavorites);
+  const normalizedRecency = recencyScore(inputs.updatedAt);
+
+  return (
+    normalizedRating * WEIGHTS.bayesianRating +
+    normalizedInstalls * WEIGHTS.installs +
+    normalizedStars * WEIGHTS.stars +
+    inputs.successRate * WEIGHTS.success +
+    normalizedRecency * WEIGHTS.recency +
+    normalizedFavorites * WEIGHTS.favorites
+  );
+}
+
+/**
+ * Trending score based on 7-day activity velocity.
+ * Ratings weighted 2x over usage events.
+ */
+export function computeTrendingScore(
+  recentRatings7d: number,
+  recentUsage7d: number,
+  maxTrendingRaw: number,
+): number {
+  const raw = recentRatings7d * 2 + recentUsage7d;
+  return logNormalize(raw, maxTrendingRaw);
+}