@doccov/api 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @doccov/api
 
+## 0.6.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @doccov/sdk@0.19.0
+
+## 0.6.0
+
+### Minor Changes
+
+- feat: add spec routes with caching/diff, auth system, cleanup unused pages
+
 ## 0.5.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/api/index.ts

@@ -12,9 +12,10 @@ import type {
   BuildPlanStep,
   BuildPlanStepResult,
   BuildPlanTarget,
+  EnrichedOpenPkg,
   GitHubProjectContext,
 } from '@doccov/sdk';
-import { fetchGitHubContext, parseScanGitHubUrl } from '@doccov/sdk';
+import { enrichSpec, fetchGitHubContext, parseScanGitHubUrl } from '@doccov/sdk';
 import type { OpenPkg } from '@openpkg-ts/spec';
 import type { VercelRequest, VercelResponse } from '@vercel/node';
 import { Sandbox } from '@vercel/sandbox';
@@ -163,6 +164,9 @@ const LOCAL_BINARIES = new Set([
   'publint',
   'attw',
   'are-the-types-wrong',
+  // Monorepo tools
+  'lerna',
+  'nx',
 ]);
 
 /**
@@ -213,28 +217,53 @@ interface SpecSummary {
   types: number;
   documented: number;
   undocumented: number;
+  driftCount: number;
+  topUndocumented: string[];
+  topDrift: Array<{ name: string; issue: string }>;
 }
 
 function createSpecSummary(spec: OpenPkg): SpecSummary {
-  const exports = spec.exports?.length ?? 0;
-  const types = spec.types?.length ?? 0;
+  // Enrich spec to get coverage and drift data
+  const enriched = enrichSpec(spec) as EnrichedOpenPkg;
 
-  // Count documented vs undocumented exports
-  const documented =
-    spec.exports?.filter((e) => e.description && e.description.trim().length > 0).length ?? 0;
-  const undocumented = exports - documented;
+  const totalExports = enriched.exports?.length ?? 0;
+  const types = enriched.types?.length ?? 0;
 
-  // Calculate coverage (documented / total * 100)
-  const coverage = exports > 0 ? Math.round((documented / exports) * 100) : 0;
+  // Use SDK coverage data
+  const coverageScore = enriched.docs?.coverageScore ?? 0;
+  const documented = enriched.docs?.documented ?? 0;
+  const undocumented = totalExports - documented;
+
+  // Collect drift issues from enriched exports
+  const driftItems: Array<{ name: string; issue: string }> = [];
+  const undocumentedNames: string[] = [];
+
+  for (const exp of enriched.exports ?? []) {
+    // Collect undocumented exports (no description)
+    if (!exp.description || exp.description.trim().length === 0) {
+      undocumentedNames.push(exp.name);
+    }
+
+    // Collect drift issues
+    for (const drift of exp.docs?.drift ?? []) {
+      driftItems.push({
+        name: exp.name,
+        issue: drift.issue ?? 'Documentation drift detected',
+      });
+    }
+  }
 
   return {
-    name: spec.meta?.name ?? 'unknown',
-    version: spec.meta?.version ?? '0.0.0',
-    coverage,
-    exports,
+    name: enriched.meta?.name ?? 'unknown',
+    version: enriched.meta?.version ?? '0.0.0',
+    coverage: coverageScore,
+    exports: totalExports,
     types,
     documented,
     undocumented,
+    driftCount: driftItems.length,
+    topUndocumented: undocumentedNames.slice(0, 5),
+    topDrift: driftItems.slice(0, 5),
   };
 }
 
@@ -345,6 +374,27 @@ Install Commands by Package Manager:
 - bun with lockfile: ["bun", "install", "--frozen-lockfile"]
 - bun without lockfile: ["bun", "install"]
 
+Monorepo Build Strategy (CRITICAL):
+When a target package is specified in a monorepo, ONLY build that package and its dependencies:
+
+- Lerna monorepos: Use "lerna run build --scope=<package-name> --include-dependencies"
+  Example for @stacks/transactions: ["lerna", "run", "build", "--scope=@stacks/transactions", "--include-dependencies"]
+
+- Turbo monorepos: Use "turbo run build --filter=<package-name>"
+  Example: ["turbo", "run", "build", "--filter=@stacks/transactions"]
+
+- Nx monorepos: Use "nx run <project>:build"
+  Example: ["nx", "run", "transactions:build"]
+
+- pnpm workspaces: Use "pnpm --filter <package-name> run build"
+  Example: ["pnpm", "--filter", "@stacks/transactions", "run", "build"]
+
+- yarn workspaces: Use "yarn workspace <package-name> run build"
+  Example: ["yarn", "workspace", "@stacks/transactions", "run", "build"]
+
+NEVER run a full monorepo build (npm run build at root) when a target package is specified.
+This avoids building 20+ packages when we only need one.
+
 General Guidelines:
 - For TypeScript projects, look for "types" or "exports" fields in package.json
 - For monorepos, focus on the target package if specified
@@ -386,11 +436,22 @@ function transformToBuildPlan(
   context: GitHubProjectContext,
   options: GenerateBuildPlanOptions,
 ): BuildPlan {
+  // Derive package directory from entry points (e.g., "packages/transactions/src/index.ts" -> "packages/transactions")
+  let rootPath: string | undefined;
+  if (options.targetPackage && output.entryPoints.length > 0) {
+    const firstEntry = output.entryPoints[0];
+    // Match patterns like "packages/foo/src/..." or "packages/foo/dist/..."
+    const match = firstEntry.match(/^(packages\/[^/]+)\//);
+    if (match) {
+      rootPath = match[1];
+    }
+  }
+
   const target: BuildPlanTarget = {
     type: 'github',
     repoUrl: `https://github.com/${context.metadata.owner}/${context.metadata.repo}`,
     ref: context.ref,
-    rootPath: options.targetPackage,
+    rootPath,
     entryPoints: output.entryPoints,
   };
 
@@ -745,13 +806,22 @@ async function handleExecute(req: VercelRequest, res: VercelResponse): Promise<v
     const specFilePath = plan.target.rootPath
       ? `${plan.target.rootPath}/openpkg.json`
       : 'openpkg.json';
-    const specStream = await sandbox.readFile({ path: specFilePath });
-    const chunks: Buffer[] = [];
-    for await (const chunk of specStream as AsyncIterable<Buffer>) {
-      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+
+    let spec: OpenPkg;
+    try {
+      const specStream = await sandbox.readFile({ path: specFilePath });
+      const chunks: Buffer[] = [];
+      for await (const chunk of specStream as AsyncIterable<Buffer>) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      }
+      const specContent = Buffer.concat(chunks).toString('utf-8');
+      spec = JSON.parse(specContent) as OpenPkg;
+    } catch (readError) {
+      console.error(`Failed to read ${specFilePath}:`, readError);
+      throw new Error(
+        `Failed to read spec file (${specFilePath}): ${readError instanceof Error ? readError.message : 'Unknown error'}`,
+      );
     }
-    const specContent = Buffer.concat(chunks).toString('utf-8');
-    const spec = JSON.parse(specContent) as OpenPkg;
     const summary = createSpecSummary(spec);
 
     const result = {
@@ -931,13 +1001,22 @@ async function handleExecuteStream(req: VercelRequest, res: VercelResponse): Pro
     const specFilePath = plan.target.rootPath
       ? `${plan.target.rootPath}/openpkg.json`
       : 'openpkg.json';
-    const specStream = await sandbox.readFile({ path: specFilePath });
-    const chunks: Buffer[] = [];
-    for await (const chunk of specStream as AsyncIterable<Buffer>) {
-      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+
+    let spec: OpenPkg;
+    try {
+      const specStream = await sandbox.readFile({ path: specFilePath });
+      const chunks: Buffer[] = [];
+      for await (const chunk of specStream as AsyncIterable<Buffer>) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      }
+      const specContent = Buffer.concat(chunks).toString('utf-8');
+      spec = JSON.parse(specContent) as OpenPkg;
+    } catch (readError) {
+      console.error(`Failed to read ${specFilePath}:`, readError);
+      throw new Error(
+        `Failed to read spec file (${specFilePath}): ${readError instanceof Error ? readError.message : 'Unknown error'}`,
+      );
     }
-    const specContent = Buffer.concat(chunks).toString('utf-8');
-    const spec = JSON.parse(specContent) as OpenPkg;
     const summary = createSpecSummary(spec);
 
     const result = {

package/migrations/005_coverage_sdk_field_names.ts

@@ -0,0 +1,41 @@
+import type { Kysely } from 'kysely';
+
+/**
+ * Create coverage_snapshots table with SDK-aligned field names.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+  await db.schema
+    .createTable('coverage_snapshots')
+    .addColumn('id', 'text', (col) => col.primaryKey())
+    .addColumn('project_id', 'text', (col) =>
+      col.notNull().references('projects.id').onDelete('cascade'),
+    )
+    .addColumn('version', 'text')
+    .addColumn('branch', 'text')
+    .addColumn('commit_sha', 'text')
+    // SDK-aligned field names
+    .addColumn('coverage_score', 'integer', (col) => col.notNull())
+    .addColumn('documented_exports', 'integer', (col) => col.notNull())
+    .addColumn('total_exports', 'integer', (col) => col.notNull())
+    .addColumn('drift_count', 'integer', (col) => col.notNull().defaultTo(0))
+    .addColumn('source', 'text', (col) => col.notNull().defaultTo('manual'))
+    .addColumn('created_at', 'timestamptz', (col) => col.defaultTo(db.fn('now')))
+    .execute();
+
+  // Index for efficient project history queries
+  await db.schema
+    .createIndex('idx_coverage_snapshots_project_id')
+    .on('coverage_snapshots')
+    .column('project_id')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_coverage_snapshots_created_at')
+    .on('coverage_snapshots')
+    .column('created_at')
+    .execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+  await db.schema.dropTable('coverage_snapshots').execute();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/api",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",
@@ -29,8 +29,7 @@
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^2.0.55",
-    "@doccov/db": "workspace:*",
-    "@doccov/sdk": "^0.18.0",
+    "@doccov/sdk": "^0.19.0",
     "@hono/node-server": "^1.14.3",
     "@openpkg-ts/spec": "^0.10.0",
     "@polar-sh/hono": "^0.5.3",
@@ -42,6 +41,7 @@
     "ms": "^2.1.3",
     "nanoid": "^5.0.0",
     "pg": "^8.13.0",
+    "vercel": "^50.1.3",
     "zod": "^3.25.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -2,20 +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';
 
 const app = new Hono();
 
@@ -29,34 +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',
-      v1: {
-        ai: '/v1/ai/generate (POST), /v1/ai/quota (GET)',
-      },
+      demo: '/demo/plan, /demo/execute',
+      spec: '/spec/:owner/:repo',
       health: '/health',
     },
   });
@@ -66,39 +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);
-
-// API endpoints (API key required)
-app.use('/v1/*', requireApiKey(), orgRateLimit());
-app.route('/v1/ai', aiRoute);
+// Spec endpoint (public, cached)
+app.route('/spec', specRoute);
 
 // Vercel serverless handler + Bun auto-serves this export
 export default app;