@doccov/api 0.2.0 → 0.2.2

package/api/scan.ts

@@ -0,0 +1,64 @@
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+
+export const config = {
+  runtime: 'nodejs',
+  maxDuration: 10,
+};
+
+interface ScanRequestBody {
+  url: string;
+  ref?: string;
+  package?: string;
+}
+
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+  // CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    return res.status(200).end();
+  }
+
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  const body = req.body as ScanRequestBody;
+
+  if (!body.url) {
+    return res.status(400).json({ error: 'url is required' });
+  }
+
+  // Parse GitHub URL
+  const urlMatch = body.url.match(/github\.com\/([^/]+)\/([^/]+)/);
+  if (!urlMatch) {
+    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,
+  });
+  if (body.package) {
+    params.set('package', body.package);
+  }
+
+  // Return job ID and stream URL with all params
+  return res.status(202).json({
+    jobId,
+    status: 'pending',
+    streamUrl: `/scan-stream?${params.toString()}`,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/api",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",
@@ -27,14 +27,16 @@
     "format": "biome format --write src/"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.2.0",
+    "@openpkg-ts/spec": "^0.3.0",
     "@vercel/sandbox": "^1.0.3",
     "hono": "^4.0.0",
     "ms": "^2.1.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@types/ms": "^0.7.34"
+    "@types/ms": "^0.7.34",
+    "@types/node": "^20.0.0",
+    "@vercel/node": "^3.0.0",
+    "typescript": "^5.0.0"
   }
 }
-

package/src/index.ts

@@ -3,6 +3,7 @@ import { cors } from 'hono/cors';
 import { badgeRoute } from './routes/badge';
 import { leaderboardRoute } from './routes/leaderboard';
 import { scanRoute } from './routes/scan';
+import { widgetRoute } from './routes/widget';
 
 const app = new Hono();
 
@@ -16,6 +17,7 @@ app.get('/', (c) => {
     version: '0.2.0',
     endpoints: {
       badge: '/badge/:owner/:repo',
+      widget: '/widget/:owner/:repo',
       leaderboard: '/leaderboard',
       scan: '/scan',
       health: '/health',
@@ -29,14 +31,9 @@ app.get('/health', (c) => {
 
 // Routes
 app.route('/badge', badgeRoute);
+app.route('/widget', widgetRoute);
 app.route('/leaderboard', leaderboardRoute);
 app.route('/scan', scanRoute);
 
-const port = Number(process.env.PORT) || 3000;
-
-console.log(`DocCov API running on http://localhost:${port}`);
-
-export default {
-  port,
-  fetch: app.fetch,
-};
+// Vercel serverless handler + Bun auto-serves this export
+export default app;

package/src/routes/badge.ts

@@ -1,5 +1,5 @@
-import type { OpenPkg } from '@openpkg-ts/spec';
 import { Hono } from 'hono';
+import { fetchSpecFromGitHub } from '../utils/github';
 
 export const badgeRoute = new Hono();
 
@@ -70,30 +70,6 @@ function generateBadgeSvg(options: BadgeOptions): string {
 </svg>`;
 }
 
-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;
-}
-
 // GET /badge/:owner/:repo
 badgeRoute.get('/:owner/:repo', async (c) => {
   const { owner, repo } = c.req.param();
@@ -126,7 +102,7 @@ badgeRoute.get('/:owner/:repo', async (c) => {
       'Content-Type': 'image/svg+xml',
       'Cache-Control': 'public, max-age=300', // Cache for 5 minutes
     });
-  } catch (error) {
+  } catch {
     const svg = generateBadgeSvg({
       label: 'docs',
       message: 'error',

package/src/routes/leaderboard.ts

@@ -52,7 +52,7 @@ async function fetchSpecFromGitHub(owner: string, repo: string): Promise<OpenPkg
   return null;
 }
 
-async function buildLeaderboard(category?: string): Promise<LeaderboardEntry[]> {
+async function buildLeaderboard(_category?: string): Promise<LeaderboardEntry[]> {
   const entries: LeaderboardEntry[] = [];
 
   // Fetch specs for all tracked repos

package/src/routes/widget.ts

@@ -0,0 +1,178 @@
+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] ?? ''}`);
+});

package/src/utils/github.ts

@@ -0,0 +1,25 @@
+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;
+}

package/tsconfig.json

@@ -3,17 +3,13 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "bundler",
-    "strict": true,
     "esModuleInterop": true,
+    "strict": true,
     "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
-    "declaration": true,
-    "declarationMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src"
+    "isolatedModules": true,
+    "noEmit": true
   },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "include": ["api/**/*", "src/**/*"],
+  "exclude": ["node_modules"]
 }
-

package/vercel.json

@@ -1,6 +1,10 @@
 {
-  "buildCommand": "bun install",
-  "installCommand": "bun install",
-  "framework": null,
-  "outputDirectory": "."
-}
+  "rewrites": [
+    { "source": "/badge/:path*", "destination": "/api" },
+    { "source": "/spec/:path*", "destination": "/api" },
+    { "source": "/scan-stream", "destination": "/api/scan-stream" },
+    { "source": "/scan/detect", "destination": "/api/scan/detect" },
+    { "source": "/scan", "destination": "/api/scan" },
+    { "source": "/(.*)", "destination": "/api" }
+  ]
+}