@doccov/api 0.5.0 → 0.6.1

package/src/routes/badge.ts

@@ -205,10 +205,114 @@ badgeRoute.get('/:owner/:repo', async (c) => {
   }
 });
 
-// GET /badge/:owner/:repo.svg (alias)
-badgeRoute.get('/:owner/:repo.svg', async (c) => {
+// GET /badge/:owner/:repo/json - Shields.io endpoint format
+// https://shields.io/badges/endpoint-badge
+badgeRoute.get('/:owner/:repo/json', async (c) => {
   const { owner, repo } = c.req.param();
-  const repoName = repo.replace(/\.svg$/, '');
-  const query = new URL(c.req.url).search;
-  return c.redirect(`/badge/${owner}/${repoName}${query}`);
+
+  const ref = c.req.query('ref') ?? c.req.query('branch') ?? 'main';
+  const specPath = c.req.query('path') ?? c.req.query('package') ?? 'openpkg.json';
+
+  try {
+    const spec = await fetchSpec(owner, repo, { ref, path: specPath });
+
+    if (!spec) {
+      return c.json(
+        { schemaVersion: 1, label: 'docs', message: 'not found', color: 'lightgrey' },
+        404,
+        { 'Cache-Control': 'no-cache' },
+      );
+    }
+
+    const validation = validateSpec(spec);
+    if (!validation.ok) {
+      return c.json(
+        { schemaVersion: 1, label: 'docs', message: 'invalid', color: 'lightgrey' },
+        422,
+        { 'Cache-Control': 'no-cache' },
+      );
+    }
+
+    const coverageScore =
+      (spec as { docs?: { coverageScore?: number } }).docs?.coverageScore ??
+      computeCoverageScore(spec);
+
+    return c.json(
+      {
+        schemaVersion: 1,
+        label: 'docs',
+        message: `${coverageScore}%`,
+        color: getColorForScore(coverageScore),
+      },
+      200,
+      { 'Cache-Control': 'public, max-age=300, stale-if-error=3600' },
+    );
+  } catch {
+    return c.json(
+      { schemaVersion: 1, label: 'docs', message: 'error', color: 'red' },
+      500,
+      { 'Cache-Control': 'no-cache' },
+    );
+  }
+});
+
+// GET /badge/:owner/:repo/drift - Drift badge variant
+badgeRoute.get('/:owner/:repo/drift', async (c) => {
+  const { owner, repo } = c.req.param();
+
+  const ref = c.req.query('ref') ?? c.req.query('branch') ?? 'main';
+  const specPath = c.req.query('path') ?? c.req.query('package') ?? 'openpkg.json';
+  const style = (c.req.query('style') ?? 'flat') as BadgeStyle;
+
+  try {
+    const spec = await fetchSpec(owner, repo, { ref, path: specPath });
+
+    if (!spec) {
+      const svg = generateBadgeSvg({
+        label: 'drift',
+        message: 'not found',
+        color: 'lightgrey',
+        style,
+      });
+      return c.body(svg, 404, CACHE_HEADERS_ERROR);
+    }
+
+    // Compute drift score from exports with drift issues
+    const exports = spec.exports ?? [];
+    const exportsWithDrift = exports.filter((e) => {
+      const docs = (e as { docs?: { drift?: unknown[] } }).docs;
+      return docs?.drift && Array.isArray(docs.drift) && docs.drift.length > 0;
+    });
+    const driftScore = exports.length === 0 ? 0 : Math.round((exportsWithDrift.length / exports.length) * 100);
+
+    // Lower drift is better
+    const color = getDriftColor(driftScore);
+
+    const svg = generateBadgeSvg({
+      label: 'drift',
+      message: `${driftScore}%`,
+      color,
+      style,
+    });
+
+    return c.body(svg, 200, CACHE_HEADERS_SUCCESS);
+  } catch {
+    const svg = generateBadgeSvg({
+      label: 'drift',
+      message: 'error',
+      color: 'red',
+      style,
+    });
+    return c.body(svg, 500, CACHE_HEADERS_ERROR);
+  }
 });
+
+function getDriftColor(score: number): BadgeColor {
+  // Inverse of coverage - lower is better
+  if (score <= 5) return 'brightgreen';
+  if (score <= 10) return 'green';
+  if (score <= 20) return 'yellowgreen';
+  if (score <= 30) return 'yellow';
+  if (score <= 50) return 'orange';
+  return 'red';
+}

package/src/routes/coverage.ts

@@ -92,13 +92,9 @@ coverageRoute.get('/projects/:projectId/history', async (c) => {
       'version',
       'branch',
       'commitSha',
-      'coveragePercent',
-      'documentedCount',
-      'totalCount',
-      'descriptionCount',
-      'paramsCount',
-      'returnsCount',
-      'examplesCount',
+      'coverageScore',
+      'documentedExports',
+      'totalExports',
       'driftCount',
       'source',
       'createdAt',
@@ -129,13 +125,9 @@ coverageRoute.post('/projects/:projectId/snapshots', async (c) => {
     version?: string;
     branch?: string;
     commitSha?: string;
-    coveragePercent: number;
-    documentedCount: number;
-    totalCount: number;
-    descriptionCount?: number;
-    paramsCount?: number;
-    returnsCount?: number;
-    examplesCount?: number;
+    coverageScore: number;
+    documentedExports: number;
+    totalExports: number;
     driftCount?: number;
     source?: 'ci' | 'manual' | 'scheduled';
   }>();
@@ -162,13 +154,9 @@ coverageRoute.post('/projects/:projectId/snapshots', async (c) => {
       version: body.version || null,
       branch: body.branch || null,
       commitSha: body.commitSha || null,
-      coveragePercent: body.coveragePercent,
-      documentedCount: body.documentedCount,
-      totalCount: body.totalCount,
-      descriptionCount: body.descriptionCount || null,
-      paramsCount: body.paramsCount || null,
-      returnsCount: body.returnsCount || null,
-      examplesCount: body.examplesCount || null,
+      coverageScore: body.coverageScore,
+      documentedExports: body.documentedExports,
+      totalExports: body.totalExports,
       driftCount: body.driftCount || 0,
       source: body.source || 'manual',
     })
@@ -179,7 +167,7 @@ coverageRoute.post('/projects/:projectId/snapshots', async (c) => {
   await db
     .updateTable('projects')
     .set({
-      coverageScore: body.coveragePercent,
+      coverageScore: body.coverageScore,
       driftCount: body.driftCount || 0,
       lastAnalyzedAt: new Date(),
     })
@@ -192,9 +180,9 @@ coverageRoute.post('/projects/:projectId/snapshots', async (c) => {
 // Helper: Generate insights from coverage data
 interface Snapshot {
   version: string | null;
-  coveragePercent: number;
-  documentedCount: number;
-  totalCount: number;
+  coverageScore: number;
+  documentedExports: number;
+  totalExports: number;
   driftCount: number;
 }
 
@@ -210,7 +198,7 @@ function generateInsights(snapshots: Snapshot[]): Insight[] {
 
   const first = snapshots[0];
   const last = snapshots[snapshots.length - 1];
-  const diff = last.coveragePercent - first.coveragePercent;
+  const diff = last.coverageScore - first.coverageScore;
 
   // Overall improvement/regression
   if (diff > 0) {
@@ -228,8 +216,8 @@ function generateInsights(snapshots: Snapshot[]): Insight[] {
   }
 
   // Predict time to 100%
-  if (diff > 0 && last.coveragePercent < 100) {
-    const remaining = 100 - last.coveragePercent;
+  if (diff > 0 && last.coverageScore < 100) {
+    const remaining = 100 - last.coverageScore;
     const avgGainPerSnapshot = diff / (snapshots.length - 1);
     if (avgGainPerSnapshot > 0) {
       const snapshotsToComplete = Math.ceil(remaining / avgGainPerSnapshot);
@@ -245,8 +233,7 @@ function generateInsights(snapshots: Snapshot[]): Insight[] {
   const milestones = [50, 75, 90, 100];
   for (const milestone of milestones) {
     const crossedAt = snapshots.findIndex(
-      (s, i) =>
-        i > 0 && s.coveragePercent >= milestone && snapshots[i - 1].coveragePercent < milestone,
+      (s, i) => i > 0 && s.coverageScore >= milestone && snapshots[i - 1].coverageScore < milestone,
     );
     if (crossedAt > 0) {
       insights.push({
@@ -271,7 +258,7 @@ function detectRegression(
   for (let i = 1; i < recent.length; i++) {
     const prev = recent[i - 1];
     const curr = recent[i];
-    const drop = prev.coveragePercent - curr.coveragePercent;
+    const drop = prev.coverageScore - curr.coverageScore;
 
     if (drop >= 3) {
       // 3% or more drop
@@ -279,7 +266,7 @@ function detectRegression(
         fromVersion: prev.version || `v${i}`,
         toVersion: curr.version || `v${i + 1}`,
         coverageDrop: Math.round(drop),
-        exportsLost: prev.documentedCount - curr.documentedCount,
+        exportsLost: prev.documentedExports - curr.documentedExports,
       };
     }
   }

package/src/routes/demo.ts

@@ -3,6 +3,7 @@
  * Uses the /plan and /execute-stream endpoints from the Vercel API
  */
 
+import { fetchGitHubContext, parseScanGitHubUrl } from '@doccov/sdk';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 import { anonymousRateLimit } from '../middleware/anonymous-rate-limit';
@@ -86,20 +87,85 @@ async function fetchNpmPackage(packageName: string): Promise<NpmPackageInfo> {
 }
 
 /**
- * Analysis result summary (matches SpecSummary from Vercel API)
+ * Analysis result summary (matches SDK CoverageSnapshot naming)
  */
 interface AnalysisSummary {
   packageName: string;
   version: string;
-  coverage: number;
-  exportCount: number;
-  documentedCount: number;
-  undocumentedCount: number;
+  coverageScore: number;
+  totalExports: number;
+  documentedExports: number;
   driftCount: number;
   topUndocumented: string[];
   topDrift: Array<{ name: string; issue: string }>;
 }
 
+/**
+ * Workspace package info for monorepo detection
+ */
+interface WorkspacePackageInfo {
+  name: string;
+  path: string;
+  private: boolean;
+}
+
+/**
+ * Resolve workspace patterns to actual package names via GitHub API.
+ * Fetches package.json from each directory to get real package names.
+ */
+async function resolveGitHubPackages(
+  owner: string,
+  repo: string,
+  ref: string,
+  patterns: string[],
+): Promise<WorkspacePackageInfo[]> {
+  const packages: WorkspacePackageInfo[] = [];
+  const seen = new Set<string>();
+
+  for (const pattern of patterns) {
+    // Extract base directory from pattern: "packages/*" -> "packages"
+    const baseDir = pattern.replace(/\/?\*\*?$/, '');
+    if (!baseDir || baseDir.includes('*')) continue;
+
+    // List directories via GitHub API
+    const contentsUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${baseDir}?ref=${ref}`;
+    const contentsRes = await fetch(contentsUrl, {
+      headers: { 'User-Agent': 'DocCov', Accept: 'application/vnd.github.v3+json' },
+    });
+
+    if (!contentsRes.ok) continue;
+
+    const contents = (await contentsRes.json()) as Array<{ name: string; type: string }>;
+
+    // Fetch package.json from each subdirectory
+    for (const item of contents) {
+      if (item.type !== 'dir') continue;
+
+      const pkgPath = `${baseDir}/${item.name}`;
+      const pkgJsonUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${pkgPath}/package.json`;
+
+      try {
+        const pkgRes = await fetch(pkgJsonUrl);
+        if (!pkgRes.ok) continue;
+
+        const pkg = (await pkgRes.json()) as { name?: string; private?: boolean };
+        if (pkg.name && !seen.has(pkg.name)) {
+          seen.add(pkg.name);
+          packages.push({
+            name: pkg.name,
+            path: pkgPath,
+            private: pkg.private ?? false,
+          });
+        }
+      } catch {
+        // Skip invalid package.json
+      }
+    }
+  }
+
+  return packages.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 // GET /demo/analyze?package=lodash
 demoRoute.get('/analyze', async (c) => {
   const packageName = c.req.query('package');
@@ -228,6 +294,250 @@ demoRoute.get('/analyze', async (c) => {
                     exports: number;
                     documented: number;
                     undocumented: number;
+                    driftCount: number;
+                    topUndocumented: string[];
+                    topDrift: Array<{ name: string; issue: string }>;
+                  };
+                  error?: string;
+                };
+
+                // Forward progress events
+                if (eventType === 'progress') {
+                  await sendEvent('log', { message: eventData.message || eventData.stage });
+                } else if (eventType === 'step:start') {
+                  await sendEvent('status', {
+                    step: eventData.stepId === 'analyze' ? 'analyze' : 'build',
+                    message: eventData.name || `Running ${eventData.stepId}...`,
+                  });
+                } else if (eventType === 'step:complete' && eventData.stepId) {
+                  await sendEvent('log', {
+                    message: `${eventData.stepId} completed`,
+                  });
+                } else if (eventType === 'complete' && eventData.summary) {
+                  // Transform summary to our format (SDK-aligned field names)
+                  const summary: AnalysisSummary = {
+                    packageName: eventData.summary.name,
+                    version: eventData.summary.version,
+                    coverageScore: eventData.summary.coverage,
+                    totalExports: eventData.summary.exports,
+                    documentedExports: eventData.summary.documented,
+                    driftCount: eventData.summary.driftCount ?? 0,
+                    topUndocumented: eventData.summary.topUndocumented ?? [],
+                    topDrift: eventData.summary.topDrift ?? [],
+                  };
+
+                  await sendEvent('log', {
+                    message: `Found ${summary.totalExports} exports, ${summary.documentedExports} documented`,
+                  });
+
+                  await sendEvent('status', {
+                    step: 'complete',
+                    message: 'Analysis complete!',
+                  });
+
+                  await sendEvent('result', { data: summary });
+                  return;
+                } else if (eventType === 'error') {
+                  throw new Error(eventData.error || 'Execution failed');
+                }
+              } catch (parseError) {
+                // Ignore JSON parse errors for incomplete data
+                if (parseError instanceof SyntaxError) continue;
+                throw parseError;
+              }
+            }
+          }
+        }
+      }
+
+      // If we get here without a complete event, something went wrong
+      throw new Error('Execution completed without results');
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Analysis failed';
+      await sendEvent('error', { message });
+    }
+  });
+});
+
+// POST /demo/detect - detect monorepo packages from GitHub URL
+demoRoute.post('/detect', async (c) => {
+  const body = (await c.req.json()) as { url?: string };
+
+  if (!body.url) {
+    return c.json({ error: 'GitHub URL required' }, 400);
+  }
+
+  // Validate and parse GitHub URL
+  const parsed = parseScanGitHubUrl(body.url);
+  if (!parsed) {
+    return c.json({ error: 'Invalid GitHub URL' }, 400);
+  }
+
+  try {
+    // Fetch context from GitHub
+    const context = await fetchGitHubContext(body.url);
+
+    // If not a monorepo, return simple response
+    if (!context.workspace.isMonorepo) {
+      return c.json({
+        isMonorepo: false,
+        packageManager: context.packageManager,
+        owner: context.metadata.owner,
+        repo: context.metadata.repo,
+        ref: context.ref,
+        packages: [],
+      });
+    }
+
+    // Resolve actual package names from workspace patterns
+    const patterns = context.workspace.packages || ['packages/*'];
+    const packages = await resolveGitHubPackages(
+      context.metadata.owner,
+      context.metadata.repo,
+      context.ref,
+      patterns,
+    );
+
+    return c.json({
+      isMonorepo: true,
+      packageManager: context.packageManager,
+      owner: context.metadata.owner,
+      repo: context.metadata.repo,
+      ref: context.ref,
+      packages,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Detection failed';
+    return c.json({ error: message }, 500);
+  }
+});
+
+// GET /demo/analyze-repo?url=...&package=... - analyze GitHub repo directly
+demoRoute.get('/analyze-repo', async (c) => {
+  const repoUrl = c.req.query('url');
+  const packageName = c.req.query('package');
+
+  if (!repoUrl) {
+    return c.json({ error: 'GitHub URL required' }, 400);
+  }
+
+  // Validate GitHub URL
+  const parsed = parseScanGitHubUrl(repoUrl);
+  if (!parsed) {
+    return c.json({ error: 'Invalid GitHub URL' }, 400);
+  }
+
+  return streamSSE(c, async (stream) => {
+    const sendEvent = async (
+      type: 'status' | 'log' | 'result' | 'error',
+      data: { step?: string; message?: string; data?: unknown },
+    ) => {
+      await stream.writeSSE({
+        data: JSON.stringify({ type, ...data }),
+        event: type === 'error' ? 'error' : type === 'result' ? 'complete' : 'progress',
+      });
+    };
+
+    try {
+      // Step 1: Log repo info
+      await sendEvent('status', {
+        step: 'repo',
+        message: `Analyzing ${parsed.owner}/${parsed.repo}...`,
+      });
+
+      await sendEvent('log', {
+        message: `Repository: ${repoUrl}`,
+      });
+
+      if (packageName) {
+        await sendEvent('log', {
+          message: `Package: ${packageName}`,
+        });
+      }
+
+      // Step 2: Generate build plan via /plan endpoint
+      await sendEvent('status', {
+        step: 'plan',
+        message: 'Generating build plan...',
+      });
+
+      const planResponse = await fetch(`${VERCEL_API_URL}/plan`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          url: repoUrl,
+          package: packageName,
+        }),
+      });
+
+      if (!planResponse.ok) {
+        const errorData = (await planResponse.json()) as { error?: string };
+        throw new Error(errorData.error || `Plan generation failed: ${planResponse.status}`);
+      }
+
+      const planData = (await planResponse.json()) as {
+        plan: unknown;
+        context: { isMonorepo: boolean; packageManager: string };
+      };
+
+      await sendEvent('log', {
+        message: `Build plan ready (${planData.context.packageManager}${planData.context.isMonorepo ? ', monorepo' : ''})`,
+      });
+
+      // Step 3: Execute build plan via /execute-stream endpoint
+      await sendEvent('status', {
+        step: 'build',
+        message: 'Building and analyzing...',
+      });
+
+      const executeResponse = await fetch(`${VERCEL_API_URL}/execute-stream`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ plan: planData.plan }),
+      });
+
+      if (!executeResponse.ok || !executeResponse.body) {
+        throw new Error(`Execution failed: ${executeResponse.status}`);
+      }
+
+      // Stream the execute-stream SSE events and forward relevant ones
+      const reader = executeResponse.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          if (line.startsWith('event:')) {
+            const eventType = line.slice(7).trim();
+
+            // Get the next data line
+            const dataLineIndex = lines.indexOf(line) + 1;
+            if (dataLineIndex < lines.length && lines[dataLineIndex].startsWith('data:')) {
+              const dataStr = lines[dataLineIndex].slice(5).trim();
+              try {
+                const eventData = JSON.parse(dataStr) as {
+                  stage?: string;
+                  message?: string;
+                  stepId?: string;
+                  name?: string;
+                  success?: boolean;
+                  summary?: {
+                    name: string;
+                    version: string;
+                    coverage: number;
+                    exports: number;
+                    documented: number;
+                    undocumented: number;
+                    driftCount: number;
+                    topUndocumented: string[];
+                    topDrift: Array<{ name: string; issue: string }>;
                   };
                   error?: string;
                 };
@@ -245,21 +555,20 @@ demoRoute.get('/analyze', async (c) => {
                     message: `${eventData.stepId} completed`,
                   });
                 } else if (eventType === 'complete' && eventData.summary) {
-                  // Transform summary to our format
+                  // Transform summary to our format (SDK-aligned field names)
                   const summary: AnalysisSummary = {
                     packageName: eventData.summary.name,
                     version: eventData.summary.version,
-                    coverage: eventData.summary.coverage,
-                    exportCount: eventData.summary.exports,
-                    documentedCount: eventData.summary.documented,
-                    undocumentedCount: eventData.summary.undocumented,
-                    driftCount: 0,
-                    topUndocumented: [],
-                    topDrift: [],
+                    coverageScore: eventData.summary.coverage,
+                    totalExports: eventData.summary.exports,
+                    documentedExports: eventData.summary.documented,
+                    driftCount: eventData.summary.driftCount ?? 0,
+                    topUndocumented: eventData.summary.topUndocumented ?? [],
+                    topDrift: eventData.summary.topDrift ?? [],
                   };
 
                   await sendEvent('log', {
-                    message: `Found ${summary.exportCount} exports, ${summary.documentedCount} documented`,
+                    message: `Found ${summary.totalExports} exports, ${summary.documentedExports} documented`,
                   });
 
                   await sendEvent('status', {

package/src/routes/github-app.ts

@@ -280,7 +280,7 @@ async function handlePushEvent(payload: {
   const result = await analyzeRemoteRepo(installationId, owner.login, repo, sha);
 
   if (result) {
-    console.log(`[webhook] Analysis complete: ${result.coveragePercent}% coverage`);
+    console.log(`[webhook] Analysis complete: ${result.coverageScore}% coverage`);
 
     // Create check run with analysis results
     await createCheckRun(installationId, owner.login, repo, sha, result);
@@ -289,7 +289,7 @@ async function handlePushEvent(payload: {
     await db
       .updateTable('projects')
       .set({
-        coverageScore: result.coveragePercent,
+        coverageScore: result.coverageScore,
         driftCount: result.driftCount,
         updatedAt: new Date(),
       })
@@ -333,7 +333,7 @@ async function handlePullRequestEvent(payload: {
     return;
   }
 
-  console.log(`[webhook] PR analysis complete: ${headResult.coveragePercent}% coverage`);
+  console.log(`[webhook] PR analysis complete: ${headResult.coverageScore}% coverage`);
 
   // Try to get baseline from database or analyze base
   let diff: ReturnType<typeof computeAnalysisDiff> | null = null;
@@ -349,9 +349,9 @@ async function handlePullRequestEvent(payload: {
     // Use cached baseline for speed
     diff = computeAnalysisDiff(
       {
-        coveragePercent: project.coverageScore,
-        documentedCount: 0,
-        totalCount: 0,
+        coverageScore: project.coverageScore,
+        documentedExports: 0,
+        totalExports: 0,
         driftCount: project.driftCount ?? 0,
         qualityErrors: 0,
         qualityWarnings: 0,