@doccov/api 0.2.3 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @doccov/api
 
+## 0.3.1
+
+### Patch Changes
+
+- consolidate api routes to use unified SDK modules.
+- Updated dependencies
+  - @openpkg-ts/spec@0.5.0
+
+## 0.3.0
+
+### Minor Changes
+
+- add rate limiting middleware and job store abstractions
+
+### Patch Changes
+
+- Updated dependencies
+  - @openpkg-ts/spec@0.4.1
+
 ## 0.2.3
 
 ### Patch Changes

package/api/scan/detect.ts

@@ -1,4 +1,13 @@
-import { Writable } from 'node:stream';
+/**
+ * Detect endpoint - uses SDK detection via SandboxFileSystem.
+ * Detects monorepo structure and package manager for a GitHub repository.
+ */
+
+import {
+  detectMonorepo as sdkDetectMonorepo,
+  detectPackageManager,
+  SandboxFileSystem,
+} from '@doccov/sdk';
 import type { VercelRequest, VercelResponse } from '@vercel/node';
 import { Sandbox } from '@vercel/sandbox';
 
@@ -26,18 +35,6 @@ interface DetectResponse {
   error?: string;
 }
 
-// Helper to capture stream output
-function createCaptureStream(): { stream: Writable; getOutput: () => string } {
-  let output = '';
-  const stream = new Writable({
-    write(chunk, _encoding, callback) {
-      output += chunk.toString();
-      callback();
-    },
-  });
-  return { stream, getOutput: () => output };
-}
-
 export default async function handler(req: VercelRequest, res: VercelResponse) {
   // CORS
   res.setHeader('Access-Control-Allow-Origin', '*');
@@ -59,7 +56,7 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
   }
 
   try {
-    const result = await detectMonorepo(body.url, body.ref ?? 'main');
+    const result = await detectRepoStructure(body.url);
     return res.status(200).json(result);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -71,7 +68,10 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
   }
 }
 
-async function detectMonorepo(url: string, _ref: string): Promise<DetectResponse> {
+/**
+ * Detect repository structure using SDK utilities via SandboxFileSystem.
+ */
+async function detectRepoStructure(url: string): Promise<DetectResponse> {
   const sandbox = await Sandbox.create({
     source: {
       url,
@@ -83,131 +83,35 @@ async function detectMonorepo(url: string, _ref: string): Promise<DetectResponse
   });
 
   try {
-    // List root files
-    const lsCapture = createCaptureStream();
-    await sandbox.runCommand({
-      cmd: 'ls',
-      args: ['-1'],
-      stdout: lsCapture.stream,
-    });
-    const files = lsCapture.getOutput();
-
-    // Detect package manager
-    let packageManager: DetectResponse['packageManager'] = 'npm';
-    if (files.includes('pnpm-lock.yaml')) {
-      packageManager = 'pnpm';
-    } else if (files.includes('bun.lock') || files.includes('bun.lockb')) {
-      packageManager = 'bun';
-    } else if (files.includes('yarn.lock')) {
-      packageManager = 'yarn';
-    }
-
-    // Read root package.json
-    const pkgCapture = createCaptureStream();
-    await sandbox.runCommand({
-      cmd: 'cat',
-      args: ['package.json'],
-      stdout: pkgCapture.stream,
-    });
-
-    let rootPkg: { workspaces?: string[] | { packages?: string[] }; name?: string } = {};
-    try {
-      rootPkg = JSON.parse(pkgCapture.getOutput());
-    } catch {
-      // Not a valid package.json
-    }
+    // Create SDK FileSystem abstraction for sandbox
+    const fs = new SandboxFileSystem(sandbox);
 
-    // Check for workspaces (npm/yarn/bun) or pnpm-workspace.yaml
-    let workspacePatterns: string[] = [];
+    // Use SDK detection functions
+    const [monoInfo, pmInfo] = await Promise.all([
+      sdkDetectMonorepo(fs),
+      detectPackageManager(fs),
+    ]);
 
-    if (rootPkg.workspaces) {
-      if (Array.isArray(rootPkg.workspaces)) {
-        workspacePatterns = rootPkg.workspaces;
-      } else if (rootPkg.workspaces.packages) {
-        workspacePatterns = rootPkg.workspaces.packages;
-      }
-    }
-
-    // Check pnpm-workspace.yaml
-    if (files.includes('pnpm-workspace.yaml')) {
-      const wsCapture = createCaptureStream();
-      await sandbox.runCommand({
-        cmd: 'cat',
-        args: ['pnpm-workspace.yaml'],
-        stdout: wsCapture.stream,
-      });
-      const wsContent = wsCapture.getOutput();
-      // Simple YAML parsing for packages array
-      const packagesMatch = wsContent.match(/packages:\s*\n((?:\s+-\s*.+\n?)+)/);
-      if (packagesMatch) {
-        const lines = packagesMatch[1].split('\n');
-        for (const line of lines) {
-          const match = line.match(/^\s+-\s*['"]?([^'"]+)['"]?\s*$/);
-          if (match) {
-            workspacePatterns.push(match[1]);
-          }
-        }
-      }
-    }
-
-    // Not a monorepo
-    if (workspacePatterns.length === 0) {
+    if (!monoInfo.isMonorepo) {
       return {
         isMonorepo: false,
-        packageManager,
+        packageManager: pmInfo.name,
       };
     }
 
-    // Find all packages
-    const packages: PackageInfo[] = [];
-
-    // Use find to locate package.json files in workspace dirs
-    const findCapture = createCaptureStream();
-    await sandbox.runCommand({
-      cmd: 'find',
-      args: ['.', '-name', 'package.json', '-maxdepth', '3', '-type', 'f'],
-      stdout: findCapture.stream,
-    });
-
-    const packagePaths = findCapture
-      .getOutput()
-      .trim()
-      .split('\n')
-      .filter((p) => p && p !== './package.json');
-
-    for (const pkgPath of packagePaths.slice(0, 30)) {
-      // Limit to 30 packages
-      const catCapture = createCaptureStream();
-      await sandbox.runCommand({
-        cmd: 'cat',
-        args: [pkgPath],
-        stdout: catCapture.stream,
-      });
-
-      try {
-        const pkg = JSON.parse(catCapture.getOutput()) as {
-          name?: string;
-          description?: string;
-          private?: boolean;
-        };
-        if (pkg.name && !pkg.private) {
-          packages.push({
-            name: pkg.name,
-            path: pkgPath.replace('./package.json', '.').replace('/package.json', ''),
-            description: pkg.description,
-          });
-        }
-      } catch {
-        // Skip invalid package.json
-      }
-    }
-
-    // Sort by name
-    packages.sort((a, b) => a.name.localeCompare(b.name));
+    // Map SDK package info to API response format
+    const packages: PackageInfo[] = monoInfo.packages
+      .filter((p) => !p.private)
+      .map((p) => ({
+        name: p.name,
+        path: p.path,
+        description: p.description,
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name));
 
     return {
       isMonorepo: true,
-      packageManager,
+      packageManager: pmInfo.name,
       packages,
       defaultPackage: packages[0]?.name,
     };

package/api/scan-stream.ts

@@ -1,14 +1,15 @@
 import { Writable } from 'node:stream';
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-import { Sandbox } from '@vercel/sandbox';
 import {
-  SandboxFileSystem,
   detectBuildInfo,
   detectMonorepo,
   detectPackageManager,
   getInstallCommand,
   getPrimaryBuildScript,
+  SandboxFileSystem,
+  type ScanResult,
 } from '@doccov/sdk';
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import { Sandbox } from '@vercel/sandbox';
 
 export const config = {
   runtime: 'nodejs',
@@ -24,23 +25,6 @@ interface JobEvent {
   availablePackages?: string[];
 }
 
-interface ScanResult {
-  owner: string;
-  repo: string;
-  ref: string;
-  packageName?: string;
-  coverage: number;
-  exportCount: number;
-  typeCount: number;
-  driftCount: number;
-  undocumented: string[];
-  drift: Array<{
-    export: string;
-    type: string;
-    issue: string;
-  }>;
-}
-
 // Helper to capture stream output
 function createCaptureStream(): { stream: Writable; getOutput: () => string } {
   let output = '';
@@ -153,7 +137,13 @@ async function runScanWithProgress(
           // Try fetching the ref first (might be a tag not fetched by shallow clone)
           await sandbox.runCommand({
             cmd: 'git',
-            args: ['fetch', '--depth', '1', 'origin', `refs/tags/${options.ref}:refs/tags/${options.ref}`],
+            args: [
+              'fetch',
+              '--depth',
+              '1',
+              'origin',
+              `refs/tags/${options.ref}:refs/tags/${options.ref}`,
+            ],
           });
           const retryResult = await sandbox.runCommand({
             cmd: 'git',
@@ -174,7 +164,9 @@ async function runScanWithProgress(
 
       // Detect package manager using SDK
       const pmInfo = await detectPackageManager(fs);
-      const pmMessage = pmInfo.lockfile ? `Detected ${pmInfo.name} project` : 'No lockfile detected';
+      const pmMessage = pmInfo.lockfile
+        ? `Detected ${pmInfo.name} project`
+        : 'No lockfile detected';
       sendEvent({ type: 'progress', stage: 'detecting', message: pmMessage, progress: 15 });
 
       // Early monorepo detection - fail fast if monorepo without package param
@@ -189,9 +181,7 @@ async function runScanWithProgress(
             progress: 17,
           });
 
-          const availablePackages = mono.packages
-            .filter((p) => !p.private)
-            .map((p) => p.name);
+          const availablePackages = mono.packages.filter((p) => !p.private).map((p) => p.name);
 
           await sandbox.stop();
           sendEvent({

package/api/scan.ts

@@ -1,3 +1,4 @@
+import { parseGitHubUrl } from '@doccov/sdk';
 import type { VercelRequest, VercelResponse } from '@vercel/node';
 
 export const config = {
@@ -31,25 +32,23 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
     return res.status(400).json({ error: 'url is required' });
   }
 
-  // Parse GitHub URL
-  const urlMatch = body.url.match(/github\.com\/([^/]+)\/([^/]+)/);
-  if (!urlMatch) {
+  // Parse GitHub URL using SDK
+  let parsed;
+  try {
+    parsed = parseGitHubUrl(body.url, body.ref ?? 'main');
+  } catch {
     return res.status(400).json({ error: 'Invalid GitHub URL' });
   }
 
-  const [, owner, repoWithExt] = urlMatch;
-  const repo = repoWithExt.replace(/\.git$/, '');
-  const ref = body.ref ?? 'main';
-
   // Generate a job ID
   const jobId = `scan-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 
   // Build stream URL with params encoded
   const params = new URLSearchParams({
     url: body.url,
-    ref,
-    owner,
-    repo,
+    ref: parsed.ref,
+    owner: parsed.owner,
+    repo: parsed.repo,
   });
   if (body.package) {
     params.set('package', body.package);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/api",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",
@@ -27,10 +27,11 @@
     "format": "biome format --write src/"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.4.0",
+    "@openpkg-ts/spec": "^0.5.0",
     "@vercel/sandbox": "^1.0.3",
     "hono": "^4.0.0",
-    "ms": "^2.1.3"
+    "ms": "^2.1.3",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/index.ts

@@ -1,24 +1,31 @@
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
+import { rateLimit } from './middleware/rate-limit';
 import { badgeRoute } from './routes/badge';
-import { leaderboardRoute } from './routes/leaderboard';
 import { scanRoute } from './routes/scan';
-import { widgetRoute } from './routes/widget';
 
 const app = new Hono();
 
 // Middleware
 app.use('*', cors());
 
+// Rate limit /scan endpoint: 10 requests per minute per IP
+app.use(
+  '/scan/*',
+  rateLimit({
+    windowMs: 60 * 1000,
+    max: 10,
+    message: 'Too many scan requests. Please try again in a minute.',
+  }),
+);
+
 // Health check
 app.get('/', (c) => {
   return c.json({
     name: 'DocCov API',
-    version: '0.2.0',
+    version: '0.3.0',
     endpoints: {
       badge: '/badge/:owner/:repo',
-      widget: '/widget/:owner/:repo',
-      leaderboard: '/leaderboard',
       scan: '/scan',
       health: '/health',
     },
@@ -31,8 +38,6 @@ app.get('/health', (c) => {
 
 // Routes
 app.route('/badge', badgeRoute);
-app.route('/widget', widgetRoute);
-app.route('/leaderboard', leaderboardRoute);
 app.route('/scan', scanRoute);
 
 // Vercel serverless handler + Bun auto-serves this export

package/src/middleware/rate-limit.ts

@@ -0,0 +1,112 @@
+import type { Context, MiddlewareHandler, Next } from 'hono';
+
+interface RateLimitOptions {
+  /** Time window in milliseconds */
+  windowMs: number;
+  /** Max requests per window */
+  max: number;
+  /** Message to return when rate limited */
+  message?: string;
+}
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * In-memory rate limiter store
+ * Can be swapped for Redis in production
+ */
+class RateLimitStore {
+  private store = new Map<string, RateLimitEntry>();
+
+  get(key: string): RateLimitEntry | undefined {
+    const entry = this.store.get(key);
+    if (entry && Date.now() > entry.resetAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry;
+  }
+
+  increment(key: string, windowMs: number): RateLimitEntry {
+    const now = Date.now();
+    const existing = this.get(key);
+
+    if (existing) {
+      existing.count++;
+      return existing;
+    }
+
+    const entry: RateLimitEntry = {
+      count: 1,
+      resetAt: now + windowMs,
+    };
+    this.store.set(key, entry);
+    return entry;
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (now > entry.resetAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+}
+
+const store = new RateLimitStore();
+
+// Cleanup expired entries every minute
+setInterval(() => store.cleanup(), 60 * 1000).unref();
+
+/**
+ * Get client IP from request
+ */
+function getClientIp(c: Context): string {
+  // Check common proxy headers
+  const forwarded = c.req.header('x-forwarded-for');
+  if (forwarded) {
+    return forwarded.split(',')[0].trim();
+  }
+
+  const realIp = c.req.header('x-real-ip');
+  if (realIp) {
+    return realIp;
+  }
+
+  // Vercel-specific
+  const vercelIp = c.req.header('x-vercel-forwarded-for');
+  if (vercelIp) {
+    return vercelIp.split(',')[0].trim();
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Rate limiting middleware for Hono
+ */
+export function rateLimit(options: RateLimitOptions): MiddlewareHandler {
+  const { windowMs, max, message = 'Too many requests, please try again later' } = options;
+
+  return async (c: Context, next: Next) => {
+    const ip = getClientIp(c);
+    const key = `ratelimit:${ip}`;
+
+    const entry = store.increment(key, windowMs);
+
+    // Set rate limit headers
+    c.header('X-RateLimit-Limit', String(max));
+    c.header('X-RateLimit-Remaining', String(Math.max(0, max - entry.count)));
+    c.header('X-RateLimit-Reset', String(Math.ceil(entry.resetAt / 1000)));
+
+    if (entry.count > max) {
+      return c.json({ error: message }, 429);
+    }
+
+    await next();
+  };
+}

package/src/routes/scan.ts

@@ -3,26 +3,37 @@ import * as path from 'node:path';
 import { Hono } from 'hono';
 import { isSandboxAvailable, runScanInSandbox } from '../sandbox-runner';
 import { type ScanJob, type ScanResult, scanJobStore } from '../scan-worker';
+import { scanRequestSchema } from '../schemas/scan';
 
 export const scanRoute = new Hono();
 
-interface ScanRequestBody {
-  url: string;
-  ref?: string;
-  package?: string;
-}
-
 /**
  * POST /scan
  * Start a new scan job
  */
 scanRoute.post('/', async (c) => {
-  const body = await c.req.json<ScanRequestBody>();
+  // Parse JSON with error handling
+  let rawBody: unknown;
+  try {
+    rawBody = await c.req.json();
+  } catch {
+    return c.json({ error: 'Invalid JSON' }, 400);
+  }
 
-  if (!body.url) {
-    return c.json({ error: 'url is required' }, 400);
+  // Validate request body with Zod schema
+  const parsed = scanRequestSchema.safeParse(rawBody);
+  if (!parsed.success) {
+    return c.json(
+      {
+        error: 'Validation failed',
+        details: parsed.error.issues.map((i) => i.message),
+      },
+      400,
+    );
   }
 
+  const body = parsed.data;
+
   // Generate job ID
   const jobId = `scan-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 

package/src/sandbox-runner.ts

@@ -2,9 +2,9 @@
  * Vercel Sandbox runner for isolated repo scanning
  */
 
+import type { ScanResult } from '@doccov/sdk';
 import { Sandbox } from '@vercel/sandbox';
 import ms from 'ms';
-import type { ScanResult } from './scan-worker';
 
 export interface ScanOptions {
   url: string;

package/src/scan-worker.ts

@@ -2,22 +2,11 @@
  * Scan job store and caching layer
  */
 
-export interface ScanResult {
-  owner: string;
-  repo: string;
-  ref: string;
-  packageName?: string;
-  coverage: number;
-  exportCount: number;
-  typeCount: number;
-  driftCount: number;
-  undocumented: string[];
-  drift: Array<{
-    export: string;
-    type: string;
-    issue: string;
-  }>;
-}
+import type { ScanResult } from '@doccov/sdk';
+import type { JobStore } from './stores/job-store.interface';
+
+// Re-export ScanResult for backwards compatibility
+export type { ScanResult } from '@doccov/sdk';
 
 export interface ScanJob {
   id: string;
@@ -42,8 +31,9 @@ const JOB_TTL_MS = 10 * 60 * 1000; // 10 minutes
 
 /**
  * In-memory job store with caching
+ * Implements JobStore interface for easy swap to Redis/KV
  */
-class ScanJobStore {
+class ScanJobStore implements JobStore {
   private jobs = new Map<string, ScanJob>();
   private cache = new Map<string, CacheEntry>();
 
@@ -123,9 +113,10 @@ class ScanJobStore {
 export const scanJobStore = new ScanJobStore();
 
 // Periodic cleanup every 5 minutes
+// Use .unref() to prevent keeping the process alive
 setInterval(
   () => {
     scanJobStore.cleanup();
   },
   5 * 60 * 1000,
-);
+).unref();

package/src/schemas/scan.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+/**
+ * Schema for POST /scan request body
+ * Validates and restricts URLs to GitHub only
+ */
+export const scanRequestSchema = z.object({
+  url: z
+    .string()
+    .url('Invalid URL format')
+    .regex(/^https:\/\/github\.com\//, 'Only GitHub URLs are allowed'),
+  ref: z.string().optional(),
+  package: z.string().optional(),
+});
+
+export type ScanRequestBody = z.infer<typeof scanRequestSchema>;

package/src/stores/job-store.interface.ts

@@ -0,0 +1,25 @@
+import type { ScanJob, ScanResult } from '../scan-worker';
+
+/**
+ * Interface for scan job storage
+ * Allows swapping in-memory store for Redis/KV in production
+ */
+export interface JobStore {
+  /** Get a job by ID */
+  get(jobId: string): ScanJob | undefined | Promise<ScanJob | undefined>;
+
+  /** Set/update a job */
+  set(jobId: string, job: ScanJob): void | Promise<void>;
+
+  /** Get cached scan result */
+  getFromCache(key: string): ScanResult | undefined | Promise<ScanResult | undefined>;
+
+  /** Cache a scan result */
+  setCache(key: string, result: ScanResult): void | Promise<void>;
+
+  /** Cleanup expired entries */
+  cleanup(): void | Promise<void>;
+
+  /** Get store statistics */
+  stats(): { jobs: number; cache: number } | Promise<{ jobs: number; cache: number }>;
+}

package/src/utils/github.ts

@@ -1,25 +1,5 @@
-import type { OpenPkg } from '@openpkg-ts/spec';
-
-export async function fetchSpecFromGitHub(
-  owner: string,
-  repo: string,
-  branch = 'main',
-): Promise<OpenPkg | null> {
-  const urls = [
-    `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/openpkg.json`,
-    `https://raw.githubusercontent.com/${owner}/${repo}/master/openpkg.json`,
-  ];
-
-  for (const url of urls) {
-    try {
-      const response = await fetch(url);
-      if (response.ok) {
-        return (await response.json()) as OpenPkg;
-      }
-    } catch {
-      // Try next URL
-    }
-  }
-
-  return null;
-}
+/**
+ * Re-export GitHub utilities from SDK for backwards compatibility.
+ * @deprecated Import directly from '@doccov/sdk' instead.
+ */
+export { fetchSpec as fetchSpecFromGitHub } from '@doccov/sdk';

package/src/routes/leaderboard.ts

@@ -1,214 +0,0 @@
-import type { OpenPkg } from '@openpkg-ts/spec';
-import { Hono } from 'hono';
-
-export const leaderboardRoute = new Hono();
-
-interface LeaderboardEntry {
-  owner: string;
-  repo: string;
-  coverage: number;
-  exportCount: number;
-  driftCount: number;
-  lastUpdated: string;
-}
-
-// In-memory cache for demo purposes
-// In production, this would be backed by a database
-const leaderboardCache = new Map<string, LeaderboardEntry[]>();
-const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
-let lastCacheUpdate = 0;
-
-// Popular TypeScript libraries to track
-const TRACKED_REPOS = [
-  { owner: 'tanstack', repo: 'query' },
-  { owner: 'trpc', repo: 'trpc' },
-  { owner: 'colinhacks', repo: 'zod' },
-  { owner: 'drizzle-team', repo: 'drizzle-orm' },
-  { owner: 'pmndrs', repo: 'zustand' },
-  { owner: 'jaredpalmer', repo: 'formik' },
-  { owner: 'react-hook-form', repo: 'react-hook-form' },
-  { owner: 'TanStack', repo: 'router' },
-  { owner: 'TanStack', repo: 'table' },
-  { owner: 'tailwindlabs', repo: 'headlessui' },
-];
-
-async function fetchSpecFromGitHub(owner: string, repo: string): Promise<OpenPkg | null> {
-  const urls = [
-    `https://raw.githubusercontent.com/${owner}/${repo}/main/openpkg.json`,
-    `https://raw.githubusercontent.com/${owner}/${repo}/master/openpkg.json`,
-  ];
-
-  for (const url of urls) {
-    try {
-      const response = await fetch(url);
-      if (response.ok) {
-        return (await response.json()) as OpenPkg;
-      }
-    } catch {
-      // Try next URL
-    }
-  }
-
-  return null;
-}
-
-async function buildLeaderboard(_category?: string): Promise<LeaderboardEntry[]> {
-  const entries: LeaderboardEntry[] = [];
-
-  // Fetch specs for all tracked repos
-  const fetchPromises = TRACKED_REPOS.map(async ({ owner, repo }) => {
-    const spec = await fetchSpecFromGitHub(owner, repo);
-    if (spec) {
-      const driftCount = spec.exports.reduce((count, exp) => {
-        return count + (exp.docs?.drift?.length ?? 0);
-      }, 0);
-
-      entries.push({
-        owner,
-        repo,
-        coverage: spec.docs?.coverageScore ?? 0,
-        exportCount: spec.exports.length,
-        driftCount,
-        lastUpdated: new Date().toISOString(),
-      });
-    }
-  });
-
-  await Promise.allSettled(fetchPromises);
-
-  // Sort by coverage descending
-  entries.sort((a, b) => b.coverage - a.coverage);
-
-  return entries;
-}
-
-// GET /leaderboard
-leaderboardRoute.get('/', async (c) => {
-  const category = c.req.query('category');
-  const limit = Math.min(Number(c.req.query('limit')) || 100, 100);
-
-  const cacheKey = category ?? 'all';
-  const now = Date.now();
-
-  // Check cache
-  if (leaderboardCache.has(cacheKey) && now - lastCacheUpdate < CACHE_TTL) {
-    const cached = leaderboardCache.get(cacheKey) ?? [];
-    return c.json({
-      entries: cached.slice(0, limit),
-      total: cached.length,
-      category: category ?? 'all',
-      lastUpdated: new Date(lastCacheUpdate).toISOString(),
-    });
-  }
-
-  try {
-    const entries = await buildLeaderboard(category);
-    leaderboardCache.set(cacheKey, entries);
-    lastCacheUpdate = now;
-
-    return c.json({
-      entries: entries.slice(0, limit),
-      total: entries.length,
-      category: category ?? 'all',
-      lastUpdated: new Date().toISOString(),
-    });
-  } catch (error) {
-    return c.json(
-      {
-        error: 'Failed to fetch leaderboard',
-        message: error instanceof Error ? error.message : 'Unknown error',
-      },
-      500,
-    );
-  }
-});
-
-// GET /leaderboard/:owner/:repo
-leaderboardRoute.get('/:owner/:repo', async (c) => {
-  const { owner, repo } = c.req.param();
-
-  try {
-    const spec = await fetchSpecFromGitHub(owner, repo);
-
-    if (!spec) {
-      return c.json(
-        {
-          error: 'Not found',
-          message: `No openpkg.json found for ${owner}/${repo}`,
-        },
-        404,
-      );
-    }
-
-    const driftCount = spec.exports.reduce((count, exp) => {
-      return count + (exp.docs?.drift?.length ?? 0);
-    }, 0);
-
-    const missingDocs = spec.exports.filter((exp) => (exp.docs?.missing?.length ?? 0) > 0);
-
-    return c.json({
-      owner,
-      repo,
-      coverage: spec.docs?.coverageScore ?? 0,
-      exportCount: spec.exports.length,
-      driftCount,
-      missingDocsCount: missingDocs.length,
-      version: spec.meta.version,
-      name: spec.meta.name,
-      exports: spec.exports.map((exp) => ({
-        name: exp.name,
-        kind: exp.kind,
-        coverage: exp.docs?.coverageScore ?? 0,
-        driftCount: exp.docs?.drift?.length ?? 0,
-        missing: exp.docs?.missing ?? [],
-      })),
-    });
-  } catch (error) {
-    return c.json(
-      {
-        error: 'Failed to fetch repo',
-        message: error instanceof Error ? error.message : 'Unknown error',
-      },
-      500,
-    );
-  }
-});
-
-// POST /leaderboard/submit
-// Allow repos to submit themselves to the leaderboard
-leaderboardRoute.post('/submit', async (c) => {
-  try {
-    const body = await c.req.json<{ owner: string; repo: string }>();
-    const { owner, repo } = body;
-
-    if (!owner || !repo) {
-      return c.json({ error: 'Missing owner or repo' }, 400);
-    }
-
-    const spec = await fetchSpecFromGitHub(owner, repo);
-
-    if (!spec) {
-      return c.json(
-        {
-          error: 'Not found',
-          message: `No openpkg.json found for ${owner}/${repo}. Generate one with: doccov generate`,
-        },
-        404,
-      );
-    }
-
-    return c.json({
-      success: true,
-      message: `${owner}/${repo} added to leaderboard tracking`,
-      coverage: spec.docs?.coverageScore ?? 0,
-    });
-  } catch (error) {
-    return c.json(
-      {
-        error: 'Invalid request',
-        message: error instanceof Error ? error.message : 'Unknown error',
-      },
-      400,
-    );
-  }
-});

package/src/routes/widget.ts

@@ -1,178 +0,0 @@
-import type { OpenPkg } from '@openpkg-ts/spec';
-import { Hono } from 'hono';
-import { fetchSpecFromGitHub } from '../utils/github';
-
-export const widgetRoute = new Hono();
-
-type SignalCoverage = {
-  description: number;
-  params: number;
-  returns: number;
-  examples: number;
-  overall: number;
-};
-
-function computeSignalCoverage(spec: OpenPkg): SignalCoverage {
-  const exports = spec.exports ?? [];
-  const signals = {
-    description: { covered: 0, total: 0 },
-    params: { covered: 0, total: 0 },
-    returns: { covered: 0, total: 0 },
-    examples: { covered: 0, total: 0 },
-  };
-
-  for (const exp of exports) {
-    const missing = exp.docs?.missing ?? [];
-    for (const sig of ['description', 'params', 'returns', 'examples'] as const) {
-      signals[sig].total++;
-      if (!missing.includes(sig)) signals[sig].covered++;
-    }
-  }
-
-  const pct = (s: { covered: number; total: number }) =>
-    s.total ? Math.round((s.covered / s.total) * 100) : 0;
-
-  return {
-    description: pct(signals.description),
-    params: pct(signals.params),
-    returns: pct(signals.returns),
-    examples: pct(signals.examples),
-    overall: spec.docs?.coverageScore ?? 0,
-  };
-}
-
-function getColorForScore(score: number): string {
-  if (score >= 90) return '#4c1';
-  if (score >= 80) return '#97ca00';
-  if (score >= 70) return '#a4a61d';
-  if (score >= 60) return '#dfb317';
-  if (score >= 50) return '#fe7d37';
-  return '#e05d44';
-}
-
-type WidgetTheme = 'dark' | 'light';
-
-interface WidgetOptions {
-  theme: WidgetTheme;
-  compact: boolean;
-}
-
-function generateWidgetSvg(stats: SignalCoverage, options: WidgetOptions): string {
-  const { theme, compact } = options;
-  const isDark = theme === 'dark';
-
-  const bg = isDark ? '#0d1117' : '#ffffff';
-  const fg = isDark ? '#c9d1d9' : '#24292f';
-  const border = isDark ? '#30363d' : '#d0d7de';
-  const barBg = isDark ? '#21262d' : '#eaeef2';
-  const accent = '#58a6ff';
-
-  const width = compact ? 160 : 200;
-  const rowHeight = 18;
-  const headerHeight = 28;
-  const padding = 8;
-  const barWidth = compact ? 60 : 80;
-  const labelWidth = compact ? 0 : 70;
-
-  const signals = [
-    { key: 'description', label: 'desc', pct: stats.description },
-    { key: 'params', label: 'params', pct: stats.params },
-    { key: 'returns', label: 'returns', pct: stats.returns },
-    { key: 'examples', label: 'examples', pct: stats.examples },
-  ];
-
-  const height = headerHeight + signals.length * rowHeight + padding * 2;
-
-  const rows = signals
-    .map((s, i) => {
-      const y = headerHeight + padding + i * rowHeight;
-      const barFill = (s.pct / 100) * barWidth;
-      const color = getColorForScore(s.pct);
-
-      if (compact) {
-        return `
-      <g transform="translate(${padding}, ${y})">
-        <rect x="0" y="2" width="${barWidth}" height="12" rx="2" fill="${barBg}"/>
-        <rect x="0" y="2" width="${barFill}" height="12" rx="2" fill="${color}"/>
-        <text x="${barWidth + 6}" y="12" font-size="10" fill="${fg}">${s.pct}%</text>
-      </g>`;
-      }
-
-      return `
-      <g transform="translate(${padding}, ${y})">
-        <text x="0" y="12" font-size="10" fill="${fg}">${s.label}</text>
-        <rect x="${labelWidth}" y="2" width="${barWidth}" height="12" rx="2" fill="${barBg}"/>
-        <rect x="${labelWidth}" y="2" width="${barFill}" height="12" rx="2" fill="${color}"/>
-        <text x="${labelWidth + barWidth + 6}" y="12" font-size="10" fill="${fg}">${s.pct}%</text>
-      </g>`;
-    })
-    .join('');
-
-  const overallColor = getColorForScore(stats.overall);
-
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
-  <rect width="${width}" height="${height}" rx="6" fill="${bg}" stroke="${border}" stroke-width="1"/>
-  <g transform="translate(${padding}, 0)">
-    <text x="0" y="18" font-size="12" font-weight="600" fill="${accent}">DocCov</text>
-    <text x="${width - padding * 2}" y="18" font-size="12" font-weight="600" fill="${overallColor}" text-anchor="end">${stats.overall}%</text>
-  </g>
-  <line x1="0" y1="${headerHeight}" x2="${width}" y2="${headerHeight}" stroke="${border}" stroke-width="1"/>
-  <style>text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; }</style>
-  ${rows}
-</svg>`;
-}
-
-function generateErrorSvg(message: string, theme: WidgetTheme): string {
-  const isDark = theme === 'dark';
-  const bg = isDark ? '#0d1117' : '#ffffff';
-  const fg = isDark ? '#c9d1d9' : '#24292f';
-  const border = isDark ? '#30363d' : '#d0d7de';
-
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="160" height="50" viewBox="0 0 160 50">
-  <rect width="160" height="50" rx="6" fill="${bg}" stroke="${border}" stroke-width="1"/>
-  <text x="80" y="20" font-size="12" font-weight="600" fill="#58a6ff" text-anchor="middle">DocCov</text>
-  <text x="80" y="36" font-size="10" fill="${fg}" text-anchor="middle">${message}</text>
-  <style>text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; }</style>
-</svg>`;
-}
-
-// GET /widget/:owner/:repo
-widgetRoute.get('/:owner/:repo', async (c) => {
-  const { owner, repo } = c.req.param();
-  const branch = c.req.query('branch') ?? 'main';
-  const theme = (c.req.query('theme') ?? 'dark') as WidgetTheme;
-  const compact = c.req.query('compact') === 'true';
-
-  try {
-    const spec = await fetchSpecFromGitHub(owner, repo, branch);
-
-    if (!spec) {
-      const svg = generateErrorSvg('not found', theme);
-      return c.body(svg, 404, {
-        'Content-Type': 'image/svg+xml',
-        'Cache-Control': 'no-cache',
-      });
-    }
-
-    const stats = computeSignalCoverage(spec);
-    const svg = generateWidgetSvg(stats, { theme, compact });
-
-    return c.body(svg, 200, {
-      'Content-Type': 'image/svg+xml',
-      'Cache-Control': 'public, max-age=300',
-    });
-  } catch {
-    const svg = generateErrorSvg('error', theme);
-    return c.body(svg, 500, {
-      'Content-Type': 'image/svg+xml',
-      'Cache-Control': 'no-cache',
-    });
-  }
-});
-
-// GET /widget/:owner/:repo.svg (alias)
-widgetRoute.get('/:owner/:repo.svg', async (c) => {
-  const { owner, repo } = c.req.param();
-  const repoName = repo.replace(/\.svg$/, '');
-  return c.redirect(`/widget/${owner}/${repoName}?${c.req.url.split('?')[1] ?? ''}`);
-});