@doccov/api 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @doccov/api
 
+## 0.6.0
+
+### Minor Changes
+
+- feat: add spec routes with caching/diff, auth system, cleanup unused pages
+
+## 0.5.0
+
+### Minor Changes
+
+- Enhanced quality rules, filtering, github context, analysis reports, new API routes (ai, billing, demo, github-app, invites, orgs), trends command, diff capabilities
+
+### Patch Changes
+
+- Updated dependencies
+  - @doccov/sdk@0.18.0
+  - @openpkg-ts/spec@0.10.0
+  - @doccov/db@0.1.0
+
 ## 0.4.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.4.0",
+  "version": "0.6.0",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",
@@ -29,10 +29,9 @@
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^2.0.55",
-    "@doccov/db": "workspace:*",
-    "@doccov/sdk": "^0.15.0",
+    "@doccov/sdk": "^0.18.0",
     "@hono/node-server": "^1.14.3",
-    "@openpkg-ts/spec": "^0.9.0",
+    "@openpkg-ts/spec": "^0.10.0",
     "@polar-sh/hono": "^0.5.3",
     "@vercel/sandbox": "^1.0.3",
     "ai": "^5.0.111",
@@ -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

@@ -1,16 +1,23 @@
 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();
 
@@ -45,9 +52,15 @@ app.get('/', (c) => {
       badge: '/badge/:owner/:repo',
       billing: '/billing/*',
       coverage: '/coverage/*',
+      github: '/github/* (App install, webhooks)',
+      invites: '/invites/:token',
       orgs: '/orgs/*',
       plan: '/plan',
-      v1: '/v1/* (API key required)',
+      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',
     },
   });
@@ -58,8 +71,27 @@ app.get('/health', (c) => {
 });
 
 // Public endpoints (no auth)
+// Anonymous rate limit: 10 requests per day per IP
+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',
+  }),
+);
 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.route('/demo', demoRoute);
+
 // Dashboard endpoints (session auth)
 app.route('/auth', authRoute);
 app.route('/api-keys', apiKeysRoute);
@@ -67,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());
-// TODO: app.route('/v1/analyze', analyzeRoute);
+app.route('/v1/ai', aiRoute);
+app.route('/v1/spec', specV1Route);
 
 // Vercel serverless handler + Bun auto-serves this export
 export default app;

package/src/middleware/anonymous-rate-limit.ts

@@ -0,0 +1,131 @@
+import type { Context, MiddlewareHandler, Next } from 'hono';
+
+interface AnonymousRateLimitOptions {
+  /** Time window in milliseconds (default: 24 hours) */
+  windowMs: number;
+  /** Max requests per window */
+  max: number;
+  /** Message to return when rate limited */
+  message?: string;
+  /** URL for upgrade CTA */
+  upgradeUrl?: string;
+}
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * In-memory store for anonymous rate limiting
+ */
+class AnonymousRateLimitStore {
+  private store = new Map<string, RateLimitEntry>();
+
+  get(key: string): RateLimitEntry | undefined {
+    const entry = this.store.get(key);
+    if (entry && Date.now() > entry.resetAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry;
+  }
+
+  increment(key: string, windowMs: number): RateLimitEntry {
+    const now = Date.now();
+    const existing = this.get(key);
+
+    if (existing) {
+      existing.count++;
+      return existing;
+    }
+
+    const entry: RateLimitEntry = {
+      count: 1,
+      resetAt: now + windowMs,
+    };
+    this.store.set(key, entry);
+    return entry;
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (now > entry.resetAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+}
+
+const store = new AnonymousRateLimitStore();
+
+// Cleanup expired entries every minute
+setInterval(() => store.cleanup(), 60 * 1000).unref();
+
+/**
+ * Get client IP from request headers
+ */
+function getClientIp(c: Context): string {
+  const forwarded = c.req.header('x-forwarded-for');
+  if (forwarded) {
+    return forwarded.split(',')[0].trim();
+  }
+
+  const realIp = c.req.header('x-real-ip');
+  if (realIp) {
+    return realIp;
+  }
+
+  const vercelIp = c.req.header('x-vercel-forwarded-for');
+  if (vercelIp) {
+    return vercelIp.split(',')[0].trim();
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Anonymous IP-based rate limiting middleware
+ * Skips authenticated requests (with API key)
+ * Returns upgrade CTA when limit reached
+ */
+export function anonymousRateLimit(options: AnonymousRateLimitOptions): MiddlewareHandler {
+  const {
+    windowMs,
+    max,
+    message = 'Rate limit reached. Sign up free for 100/day.',
+    upgradeUrl = 'https://doccov.com/signup',
+  } = options;
+
+  return async (c: Context, next: Next) => {
+    // Skip if authenticated (has API key)
+    if (c.get('apiKey')) {
+      return next();
+    }
+
+    const ip = getClientIp(c);
+    const key = `anon:${ip}`;
+
+    const entry = store.increment(key, windowMs);
+
+    // Set rate limit headers
+    c.header('X-RateLimit-Limit', String(max));
+    c.header('X-RateLimit-Remaining', String(Math.max(0, max - entry.count)));
+    c.header('X-RateLimit-Reset', String(Math.ceil(entry.resetAt / 1000)));
+
+    if (entry.count > max) {
+      return c.json(
+        {
+          error: message,
+          limit: max,
+          resetAt: new Date(entry.resetAt).toISOString(),
+          upgrade: upgradeUrl,
+        },
+        429,
+      );
+    }
+
+    await next();
+  };
+}