@doccov/api 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @doccov/api
 
+## 0.6.0
+
+### Minor Changes
+
+- feat: add spec routes with caching/diff, auth system, cleanup unused pages
+
 ## 0.5.0
 
 ### Minor Changes

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.0",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",
@@ -29,7 +29,6 @@
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^2.0.55",
-    "@doccov/db": "workspace:*",
     "@doccov/sdk": "^0.18.0",
     "@hono/node-server": "^1.14.3",
     "@openpkg-ts/spec": "^0.10.0",
@@ -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

@@ -16,6 +16,8 @@ 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();
 
@@ -54,8 +56,10 @@ app.get('/', (c) => {
       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)',
       },
       health: '/health',
     },
@@ -95,10 +99,12 @@ app.route('/billing', billingRoute);
 app.route('/coverage', coverageRoute);
 app.route('/orgs', orgsRoute);
 app.route('/plan', planRoute);
+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/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,
       };
     }
   }