@doccov/api 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @doccov/api
 
+## 0.6.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @doccov/sdk@0.20.0
+
+## 0.6.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @doccov/sdk@0.19.0
+
 ## 0.6.0
 
 ### Minor Changes

package/api/coverage/projects/[projectId]/history.ts

@@ -0,0 +1,174 @@
+import type { VercelResponse } from '@vercel/node';
+import { db } from '../../../_db/client';
+import { getPlanLimits, type Plan } from '../../../_db/limits';
+import { createHandler } from '../../../_lib/handler';
+import { type SessionRequest, withSession } from '../../../_lib/middleware/with-session';
+
+export const config = { runtime: 'nodejs', maxDuration: 30 };
+
+interface Snapshot {
+  version: string | null;
+  coverageScore: number;
+  documentedExports: number;
+  totalExports: number;
+  driftCount: number;
+}
+
+interface Insight {
+  type: 'improvement' | 'regression' | 'prediction' | 'milestone';
+  message: string;
+  severity: 'info' | 'warning' | 'success';
+}
+
+function generateInsights(snapshots: Snapshot[]): Insight[] {
+  const insights: Insight[] = [];
+  if (snapshots.length < 2) return insights;
+
+  const first = snapshots[0];
+  const last = snapshots[snapshots.length - 1];
+  const diff = last.coverageScore - first.coverageScore;
+
+  if (diff > 0) {
+    insights.push({
+      type: 'improvement',
+      message: `Coverage increased ${diff.toFixed(0)}% since ${first.version || 'first snapshot'}`,
+      severity: 'success',
+    });
+  } else if (diff < 0) {
+    insights.push({
+      type: 'regression',
+      message: `Coverage decreased ${Math.abs(diff).toFixed(0)}% since ${first.version || 'first snapshot'}`,
+      severity: 'warning',
+    });
+  }
+
+  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);
+      insights.push({
+        type: 'prediction',
+        message: `At current pace, 100% coverage in ~${snapshotsToComplete} releases`,
+        severity: 'info',
+      });
+    }
+  }
+
+  const milestones = [50, 75, 90, 100];
+  for (const milestone of milestones) {
+    const crossedAt = snapshots.findIndex(
+      (s, i) => i > 0 && s.coverageScore >= milestone && snapshots[i - 1].coverageScore < milestone,
+    );
+    if (crossedAt > 0) {
+      insights.push({
+        type: 'milestone',
+        message: `Reached ${milestone}% coverage at ${snapshots[crossedAt].version || `snapshot ${crossedAt + 1}`}`,
+        severity: 'success',
+      });
+    }
+  }
+
+  return insights.slice(0, 5);
+}
+
+function detectRegression(
+  snapshots: Snapshot[],
+): { fromVersion: string; toVersion: string; coverageDrop: number; exportsLost: number } | null {
+  if (snapshots.length < 2) return null;
+
+  const recent = snapshots.slice(-5);
+  for (let i = 1; i < recent.length; i++) {
+    const prev = recent[i - 1];
+    const curr = recent[i];
+    const drop = prev.coverageScore - curr.coverageScore;
+
+    if (drop >= 3) {
+      return {
+        fromVersion: prev.version || `v${i}`,
+        toVersion: curr.version || `v${i + 1}`,
+        coverageDrop: Math.round(drop),
+        exportsLost: prev.documentedExports - curr.documentedExports,
+      };
+    }
+  }
+
+  return null;
+}
+
+export default createHandler({
+  GET: withSession(async (req: SessionRequest, res: VercelResponse) => {
+    const { projectId } = req.query as { projectId: string };
+    const range = (req.query.range as string) || '30d';
+    const limit = (req.query.limit as string) || '50';
+
+    const projectWithOrg = await db
+      .selectFrom('projects')
+      .innerJoin('org_members', 'org_members.orgId', 'projects.orgId')
+      .innerJoin('organizations', 'organizations.id', 'projects.orgId')
+      .where('projects.id', '=', projectId)
+      .where('org_members.userId', '=', req.session.user.id)
+      .select(['projects.id', 'projects.name', 'organizations.plan'])
+      .executeTakeFirst();
+
+    if (!projectWithOrg) {
+      return res.status(404).json({ error: 'Project not found' });
+    }
+
+    const planLimits = getPlanLimits(projectWithOrg.plan as Plan);
+    if (planLimits.historyDays === 0) {
+      return res.status(403).json({
+        error: 'Coverage trends require Team plan or higher',
+        upgrade: 'https://doccov.com/pricing',
+      });
+    }
+
+    let dateFilter: Date | null = null;
+    const now = new Date();
+    const maxDays = planLimits.historyDays;
+
+    const rangeDays: Record<string, number> = {
+      '7d': Math.min(7, maxDays),
+      '30d': Math.min(30, maxDays),
+      '90d': Math.min(90, maxDays),
+    };
+
+    if (range in rangeDays) {
+      const days = rangeDays[range];
+      dateFilter = new Date(now.getTime() - days * 24 * 60 * 60 * 1000);
+    } else if (range === 'all' || range === 'versions') {
+      dateFilter = new Date(now.getTime() - maxDays * 24 * 60 * 60 * 1000);
+    }
+
+    let query = db
+      .selectFrom('coverage_snapshots')
+      .where('projectId', '=', projectId)
+      .orderBy('createdAt', 'desc')
+      .limit(parseInt(limit, 10));
+
+    if (dateFilter) {
+      query = query.where('createdAt', '>=', dateFilter);
+    }
+
+    const snapshots = await query
+      .select([
+        'id',
+        'version',
+        'branch',
+        'commitSha',
+        'coverageScore',
+        'documentedExports',
+        'totalExports',
+        'driftCount',
+        'source',
+        'createdAt',
+      ])
+      .execute();
+
+    const chronological = snapshots.reverse();
+    const insights = generateInsights(chronological);
+    const regression = detectRegression(chronological);
+
+    res.json({ snapshots: chronological, insights, regression });
+  }),
+});

package/api/coverage/projects/[projectId]/snapshots.ts

@@ -0,0 +1,65 @@
+import type { VercelResponse } from '@vercel/node';
+import { nanoid } from 'nanoid';
+import { db } from '../../../_db/client';
+import { createHandler } from '../../../_lib/handler';
+import { type SessionRequest, withSession } from '../../../_lib/middleware/with-session';
+
+export const config = { runtime: 'nodejs', maxDuration: 30 };
+
+export default createHandler({
+  POST: withSession(async (req: SessionRequest, res: VercelResponse) => {
+    const { projectId } = req.query as { projectId: string };
+    const body = req.body as {
+      version?: string;
+      branch?: string;
+      commitSha?: string;
+      coverageScore: number;
+      documentedExports: number;
+      totalExports: number;
+      driftCount?: number;
+      source?: 'ci' | 'manual' | 'scheduled';
+    };
+
+    const membership = await db
+      .selectFrom('projects')
+      .innerJoin('org_members', 'org_members.orgId', 'projects.orgId')
+      .where('projects.id', '=', projectId)
+      .where('org_members.userId', '=', req.session.user.id)
+      .where('org_members.role', 'in', ['owner', 'admin'])
+      .select(['projects.id'])
+      .executeTakeFirst();
+
+    if (!membership) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+
+    const snapshot = await db
+      .insertInto('coverage_snapshots')
+      .values({
+        id: nanoid(21),
+        projectId,
+        version: body.version || null,
+        branch: body.branch || null,
+        commitSha: body.commitSha || null,
+        coverageScore: body.coverageScore,
+        documentedExports: body.documentedExports,
+        totalExports: body.totalExports,
+        driftCount: body.driftCount || 0,
+        source: body.source || 'manual',
+      })
+      .returningAll()
+      .executeTakeFirst();
+
+    await db
+      .updateTable('projects')
+      .set({
+        coverageScore: body.coverageScore,
+        driftCount: body.driftCount || 0,
+        lastAnalyzedAt: new Date(),
+      })
+      .where('id', '=', projectId)
+      .execute();
+
+    res.status(201).json({ snapshot });
+  }),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/api",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^2.0.55",
-    "@doccov/sdk": "^0.18.0",
+    "@doccov/sdk": "^0.20.0",
     "@hono/node-server": "^1.14.3",
     "@openpkg-ts/spec": "^0.10.0",
     "@polar-sh/hono": "^0.5.3",

package/src/index.ts

@@ -2,22 +2,10 @@ import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { logger } from 'hono/logger';
 import { anonymousRateLimit } from './middleware/anonymous-rate-limit';
-import { requireApiKey } from './middleware/api-key-auth';
-import { orgRateLimit } from './middleware/org-rate-limit';
 import { rateLimit } from './middleware/rate-limit';
-import { aiRoute } from './routes/ai';
-import { apiKeysRoute } from './routes/api-keys';
-import { authRoute } from './routes/auth';
 import { badgeRoute } from './routes/badge';
-import { billingRoute } from './routes/billing';
-import { coverageRoute } from './routes/coverage';
 import { demoRoute } from './routes/demo';
-import { githubAppRoute } from './routes/github-app';
-import { invitesRoute } from './routes/invites';
-import { orgsRoute } from './routes/orgs';
-import { planRoute } from './routes/plan';
 import { specRoute } from './routes/spec';
-import { specV1Route } from './routes/spec-v1';
 
 const app = new Hono();
 
@@ -31,36 +19,15 @@ app.use(
   }),
 );
 
-// Rate limit /plan endpoint: 10 requests per minute per IP
-app.use(
-  '/plan',
-  rateLimit({
-    windowMs: 60 * 1000,
-    max: 10,
-    message: 'Too many plan requests. Please try again in a minute.',
-  }),
-);
-
 // Health check
 app.get('/', (c) => {
   return c.json({
     name: 'DocCov API',
     version: '0.5.0',
     endpoints: {
-      auth: '/auth/*',
-      apiKeys: '/api-keys/*',
       badge: '/badge/:owner/:repo',
-      billing: '/billing/*',
-      coverage: '/coverage/*',
-      github: '/github/* (App install, webhooks)',
-      invites: '/invites/:token',
-      orgs: '/orgs/*',
-      plan: '/plan',
-      spec: '/spec/diff (POST, session auth)',
-      v1: {
-        ai: '/v1/ai/generate (POST), /v1/ai/quota (GET)',
-        spec: '/v1/spec/diff (POST, API key)',
-      },
+      demo: '/demo/plan, /demo/execute',
+      spec: '/spec/:owner/:repo',
       health: '/health',
     },
   });
@@ -70,41 +37,30 @@ app.get('/health', (c) => {
   return c.json({ status: 'ok', timestamp: new Date().toISOString() });
 });
 
-// Public endpoints (no auth)
-// Anonymous rate limit: 10 requests per day per IP
+// Badge endpoint (public, rate-limited)
 app.use(
   '/badge/*',
   anonymousRateLimit({
     windowMs: 24 * 60 * 60 * 1000, // 24 hours
-    max: 10,
-    message: 'Rate limit reached. Sign up free for 100/day.',
-    upgradeUrl: 'https://doccov.com/signup',
+    max: 100,
+    message: 'Rate limit reached.',
   }),
 );
 app.route('/badge', badgeRoute);
 
-// Semi-public endpoints (invite info is public, acceptance requires auth)
-app.route('/invites', invitesRoute);
-
-// GitHub App (install/callback need auth, webhook is public)
-app.route('/github', githubAppRoute);
-
 // Demo endpoint (public, rate-limited)
+app.use(
+  '/demo/*',
+  rateLimit({
+    windowMs: 60 * 1000,
+    max: 10,
+    message: 'Too many requests. Please try again in a minute.',
+  }),
+);
 app.route('/demo', demoRoute);
 
-// Dashboard endpoints (session auth)
-app.route('/auth', authRoute);
-app.route('/api-keys', apiKeysRoute);
-app.route('/billing', billingRoute);
-app.route('/coverage', coverageRoute);
-app.route('/orgs', orgsRoute);
-app.route('/plan', planRoute);
+// Spec endpoint (public, cached)
 app.route('/spec', specRoute);
 
-// API endpoints (API key required)
-app.use('/v1/*', requireApiKey(), orgRateLimit());
-app.route('/v1/ai', aiRoute);
-app.route('/v1/spec', specV1Route);
-
 // Vercel serverless handler + Bun auto-serves this export
 export default app;

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';
+}