@doccov/api 0.5.0 → 0.6.0

package/src/routes/spec.ts

@@ -0,0 +1,186 @@
+/**
+ * Spec routes - session authenticated endpoints for dashboard
+ */
+
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { auth } from '../auth/config';
+import { db } from '../db/client';
+import {
+  computeFullDiff,
+  type DiffOptions,
+  diffSpecs,
+  formatDiffResponse,
+} from '../utils/spec-diff-core';
+
+type Session = Awaited<ReturnType<typeof auth.api.getSession>>;
+
+type Env = {
+  Variables: {
+    session: NonNullable<Session>;
+  };
+};
+
+export const specRoute = new Hono<Env>();
+
+// Middleware: require session auth
+specRoute.use('*', async (c, next) => {
+  const session = await auth.api.getSession({ headers: c.req.raw.headers });
+  if (!session) {
+    return c.json({ error: 'Unauthorized' }, 401);
+  }
+  c.set('session', session);
+  await next();
+});
+
+// Request schemas
+const GitHubDiffSchema = z.object({
+  mode: z.literal('github'),
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+  base: z.string().min(1),
+  head: z.string().min(1),
+  installationId: z.string().optional(),
+  includeDocsImpact: z.boolean().optional(),
+});
+
+const SpecsDiffSchema = z.object({
+  mode: z.literal('specs'),
+  baseSpec: z.object({}).passthrough(),
+  headSpec: z.object({}).passthrough(),
+  markdownFiles: z
+    .array(
+      z.object({
+        path: z.string(),
+        content: z.string(),
+      }),
+    )
+    .optional(),
+});
+
+const DiffRequestSchema = z.discriminatedUnion('mode', [GitHubDiffSchema, SpecsDiffSchema]);
+
+/**
+ * POST /spec/diff - Compare two specs
+ *
+ * Supports two modes:
+ * 1. GitHub refs: Clone and compare specs from GitHub refs
+ * 2. Direct specs: Compare uploaded spec objects
+ */
+specRoute.post('/diff', async (c) => {
+  const session = c.get('session');
+
+  // Parse and validate request body
+  let body: z.infer<typeof DiffRequestSchema>;
+  try {
+    const rawBody = await c.req.json();
+    body = DiffRequestSchema.parse(rawBody);
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      return c.json(
+        {
+          error: 'Invalid request',
+          details: err.errors,
+        },
+        400,
+      );
+    }
+    return c.json({ error: 'Invalid JSON body' }, 400);
+  }
+
+  try {
+    if (body.mode === 'github') {
+      // GitHub mode: need to verify access and get installation
+      const { owner, repo, base, head, installationId, includeDocsImpact } = body;
+
+      // Find installation ID if not provided
+      let resolvedInstallationId = installationId;
+
+      if (!resolvedInstallationId) {
+        // Look up installation from user's orgs
+        const installation = await db
+          .selectFrom('github_installations')
+          .innerJoin('org_members', 'org_members.orgId', 'github_installations.orgId')
+          .where('org_members.userId', '=', session.user.id)
+          .select(['github_installations.installationId'])
+          .executeTakeFirst();
+
+        if (!installation) {
+          return c.json(
+            {
+              error: 'No GitHub App installation found for this repository',
+              hint: 'Install the DocCov GitHub App to compare repos',
+            },
+            403,
+          );
+        }
+
+        resolvedInstallationId = installation.installationId;
+      }
+
+      // Compute diff with timeout
+      const diffOptions: DiffOptions = {
+        includeDocsImpact,
+      };
+
+      const result = await Promise.race([
+        computeFullDiff(
+          { owner, repo, ref: base, installationId: resolvedInstallationId },
+          { owner, repo, ref: head, installationId: resolvedInstallationId },
+          diffOptions,
+        ),
+        new Promise<never>((_, reject) => setTimeout(() => reject(new Error('TIMEOUT')), 60_000)),
+      ]);
+
+      return c.json(formatDiffResponse(result));
+    }
+
+    // Specs mode: direct comparison
+    const { baseSpec, headSpec, markdownFiles } = body;
+
+    const diff = diffSpecs(
+      baseSpec as Parameters<typeof diffSpecs>[0],
+      headSpec as Parameters<typeof diffSpecs>[1],
+      markdownFiles,
+    );
+
+    return c.json({
+      // Core diff fields
+      breaking: diff.breaking,
+      nonBreaking: diff.nonBreaking,
+      docsOnly: diff.docsOnly,
+      coverageDelta: diff.coverageDelta,
+      oldCoverage: diff.oldCoverage,
+      newCoverage: diff.newCoverage,
+      driftIntroduced: diff.driftIntroduced,
+      driftResolved: diff.driftResolved,
+      newUndocumented: diff.newUndocumented,
+      improvedExports: diff.improvedExports,
+      regressedExports: diff.regressedExports,
+
+      // Extended fields
+      memberChanges: diff.memberChanges,
+      categorizedBreaking: diff.categorizedBreaking,
+      docsImpact: diff.docsImpact,
+
+      // Metadata
+      generatedAt: new Date().toISOString(),
+      cached: false,
+    });
+  } catch (err) {
+    if (err instanceof Error) {
+      if (err.message === 'TIMEOUT') {
+        return c.json({ error: 'Spec generation timed out' }, 408);
+      }
+      if (err.message.includes('not found') || err.message.includes('404')) {
+        return c.json({ error: 'Repository or ref not found' }, 404);
+      }
+      if (err.message.includes('No token')) {
+        return c.json({ error: 'GitHub App access required' }, 403);
+      }
+    }
+
+    console.error('Spec diff error:', err);
+    return c.json({ error: 'Failed to compute diff' }, 500);
+  }
+});

package/src/utils/github-checks.ts

@@ -2,12 +2,13 @@
  * GitHub Check Runs and PR Comments
  */
 
+import type { SpecDiffWithDocs } from '@doccov/sdk';
 import { getTokenByInstallationId } from './github-app';
 
 interface AnalysisResult {
-  coveragePercent: number;
-  documentedCount: number;
-  totalCount: number;
+  coverageScore: number;
+  documentedExports: number;
+  totalExports: number;
   driftCount: number;
   qualityErrors?: number;
   qualityWarnings?: number;
@@ -20,6 +21,15 @@ interface AnalysisDiff {
   driftDelta: number;
 }
 
+/**
+ * Rich diff result from spec-diff-core
+ */
+export interface RichDiffResult {
+  diff: SpecDiffWithDocs;
+  base: { ref: string; sha: string };
+  head: { ref: string; sha: string };
+}
+
 /**
  * Format a delta value with sign and styling
  */
@@ -49,14 +59,14 @@ export async function createCheckRun(
   const hasIssues = result.driftCount > 0 || (result.qualityErrors ?? 0) > 0;
   const conclusion = hasIssues ? 'neutral' : 'success';
 
-  const title = `Coverage: ${result.coveragePercent.toFixed(1)}%${coverageDelta}`;
+  const title = `Coverage: ${result.coverageScore.toFixed(1)}%${coverageDelta}`;
 
   const summaryLines = [
     `## Documentation Coverage`,
     '',
     `\`\`\``,
-    `Coverage: ${result.coveragePercent.toFixed(1)}%${coverageDelta}`,
-    `├─ Documented: ${result.documentedCount}/${result.totalCount} exports`,
+    `Coverage: ${result.coverageScore.toFixed(1)}%${coverageDelta}`,
+    `├─ Documented: ${result.documentedExports}/${result.totalExports} exports`,
     `├─ Drift: ${result.driftCount} issue${result.driftCount !== 1 ? 's' : ''}${diff ? formatDelta(-diff.driftDelta) : ''}`,
   ];
 
@@ -153,13 +163,13 @@ export async function postPRComment(
     bodyLines.push('| Metric | This PR | Base | Δ |');
     bodyLines.push('|--------|---------|------|---|');
     bodyLines.push(
-      `| Coverage | **${result.coveragePercent.toFixed(1)}%** | ${(result.coveragePercent - diff.coverageDelta).toFixed(1)}% | ${diff.coverageDelta >= 0 ? '+' : ''}${diff.coverageDelta.toFixed(1)}% |`,
+      `| Coverage | **${result.coverageScore.toFixed(1)}%** | ${(result.coverageScore - diff.coverageDelta).toFixed(1)}% | ${diff.coverageDelta >= 0 ? '+' : ''}${diff.coverageDelta.toFixed(1)}% |`,
     );
     bodyLines.push(
-      `| Documented | ${result.documentedCount} | ${result.documentedCount - diff.documentedDelta} | ${diff.documentedDelta >= 0 ? '+' : ''}${diff.documentedDelta} |`,
+      `| Documented | ${result.documentedExports} | ${result.documentedExports - diff.documentedDelta} | ${diff.documentedDelta >= 0 ? '+' : ''}${diff.documentedDelta} |`,
     );
     bodyLines.push(
-      `| Total exports | ${result.totalCount} | ${result.totalCount - diff.totalDelta} | ${diff.totalDelta >= 0 ? '+' : ''}${diff.totalDelta} |`,
+      `| Total exports | ${result.totalExports} | ${result.totalExports - diff.totalDelta} | ${diff.totalDelta >= 0 ? '+' : ''}${diff.totalDelta} |`,
     );
     const baseDrift = result.driftCount - diff.driftDelta;
     const driftSign = diff.driftDelta >= 0 ? '+' : '';
@@ -169,8 +179,8 @@ export async function postPRComment(
   } else {
     bodyLines.push('| Metric | Value |');
     bodyLines.push('|--------|-------|');
-    bodyLines.push(`| Coverage | **${result.coveragePercent.toFixed(1)}%** |`);
-    bodyLines.push(`| Documented | ${result.documentedCount} / ${result.totalCount} |`);
+    bodyLines.push(`| Coverage | **${result.coverageScore.toFixed(1)}%** |`);
+    bodyLines.push(`| Documented | ${result.documentedExports} / ${result.totalExports} |`);
     bodyLines.push(`| Drift issues | ${result.driftCount} |`);
   }
 
@@ -276,3 +286,213 @@ async function findExistingComment(
     return null;
   }
 }
+
+/**
+ * Post enhanced PR comment with breaking changes and member changes
+ */
+export async function postEnhancedPRComment(
+  installationId: string,
+  owner: string,
+  repo: string,
+  prNumber: number,
+  richDiff: RichDiffResult,
+): Promise<boolean> {
+  const token = await getTokenByInstallationId(installationId);
+  if (!token) return false;
+
+  const { diff, base, head } = richDiff;
+
+  const coverageEmoji = diff.coverageDelta > 0 ? '📈' : diff.coverageDelta < 0 ? '📉' : '➡️';
+
+  const bodyLines = [`## ${coverageEmoji} DocCov Report`, ''];
+
+  // Coverage summary
+  bodyLines.push('### Coverage');
+  bodyLines.push('| Metric | This PR | Base | Δ |');
+  bodyLines.push('|--------|---------|------|---|');
+  bodyLines.push(
+    `| Coverage | **${diff.newCoverage.toFixed(1)}%** | ${diff.oldCoverage.toFixed(1)}% | ${diff.coverageDelta >= 0 ? '+' : ''}${diff.coverageDelta.toFixed(1)}% |`,
+  );
+
+  if (diff.driftIntroduced > 0 || diff.driftResolved > 0) {
+    const driftChange = diff.driftIntroduced - diff.driftResolved;
+    bodyLines.push(
+      `| Drift | ${diff.driftIntroduced > 0 ? `+${diff.driftIntroduced} new` : '0 new'} | ${diff.driftResolved > 0 ? `${diff.driftResolved} fixed` : '0 fixed'} | ${driftChange >= 0 ? '+' : ''}${driftChange} |`,
+    );
+  }
+
+  bodyLines.push('');
+
+  // Breaking changes section
+  if (diff.breaking.length > 0) {
+    bodyLines.push('### ⚠️ Breaking Changes');
+    bodyLines.push('');
+
+    // Group by severity if available
+    if (diff.categorizedBreaking && diff.categorizedBreaking.length > 0) {
+      const high = diff.categorizedBreaking.filter((b) => b.severity === 'high');
+      const medium = diff.categorizedBreaking.filter((b) => b.severity === 'medium');
+      const low = diff.categorizedBreaking.filter((b) => b.severity === 'low');
+
+      if (high.length > 0) {
+        bodyLines.push(`**🔴 High Impact (${high.length})**`);
+        for (const b of high.slice(0, 5)) {
+          bodyLines.push(`- \`${b.name}\` - ${b.reason}`);
+        }
+        if (high.length > 5) bodyLines.push(`- ...and ${high.length - 5} more`);
+        bodyLines.push('');
+      }
+
+      if (medium.length > 0) {
+        bodyLines.push(`**🟡 Medium Impact (${medium.length})**`);
+        for (const b of medium.slice(0, 5)) {
+          bodyLines.push(`- \`${b.name}\` - ${b.reason}`);
+        }
+        if (medium.length > 5) bodyLines.push(`- ...and ${medium.length - 5} more`);
+        bodyLines.push('');
+      }
+
+      if (low.length > 0) {
+        bodyLines.push(`**🟢 Low Impact (${low.length})**`);
+        for (const b of low.slice(0, 3)) {
+          bodyLines.push(`- \`${b.name}\` - ${b.reason}`);
+        }
+        if (low.length > 3) bodyLines.push(`- ...and ${low.length - 3} more`);
+        bodyLines.push('');
+      }
+    } else {
+      // Simple list (breaking is string[])
+      for (const b of diff.breaking.slice(0, 10)) {
+        bodyLines.push(`- \`${b}\``);
+      }
+      if (diff.breaking.length > 10) {
+        bodyLines.push(`- ...and ${diff.breaking.length - 10} more`);
+      }
+      bodyLines.push('');
+    }
+  }
+
+  // Member-level changes section
+  if (diff.memberChanges && diff.memberChanges.length > 0) {
+    bodyLines.push('### Method/Property Changes');
+    bodyLines.push('');
+
+    const removed = diff.memberChanges.filter((m) => m.changeType === 'removed');
+    const changed = diff.memberChanges.filter((m) => m.changeType === 'signature-changed');
+    const added = diff.memberChanges.filter((m) => m.changeType === 'added');
+
+    if (removed.length > 0) {
+      bodyLines.push(`**Removed (${removed.length})**`);
+      for (const m of removed.slice(0, 5)) {
+        bodyLines.push(`- \`${m.className}.${m.memberName}\``);
+      }
+      if (removed.length > 5) bodyLines.push(`- ...and ${removed.length - 5} more`);
+      bodyLines.push('');
+    }
+
+    if (changed.length > 0) {
+      bodyLines.push(`**Signature Changed (${changed.length})**`);
+      for (const m of changed.slice(0, 5)) {
+        bodyLines.push(`- \`${m.className}.${m.memberName}\``);
+      }
+      if (changed.length > 5) bodyLines.push(`- ...and ${changed.length - 5} more`);
+      bodyLines.push('');
+    }
+
+    if (added.length > 0) {
+      bodyLines.push(`**Added (${added.length})**`);
+      for (const m of added.slice(0, 3)) {
+        bodyLines.push(`- \`${m.className}.${m.memberName}\``);
+      }
+      if (added.length > 3) bodyLines.push(`- ...and ${added.length - 3} more`);
+      bodyLines.push('');
+    }
+  }
+
+  // New exports section
+  if (diff.nonBreaking.length > 0) {
+    bodyLines.push(`### ✨ New Exports (${diff.nonBreaking.length})`);
+    for (const name of diff.nonBreaking.slice(0, 5)) {
+      bodyLines.push(`- \`${name}\``);
+    }
+    if (diff.nonBreaking.length > 5) {
+      bodyLines.push(`- ...and ${diff.nonBreaking.length - 5} more`);
+    }
+    bodyLines.push('');
+  }
+
+  // New undocumented exports warning
+  if (diff.newUndocumented.length > 0) {
+    bodyLines.push(`### ⚠️ New Undocumented Exports (${diff.newUndocumented.length})`);
+    bodyLines.push('');
+    bodyLines.push('These new exports are missing documentation:');
+    for (const name of diff.newUndocumented.slice(0, 5)) {
+      bodyLines.push(`- \`${name}\``);
+    }
+    if (diff.newUndocumented.length > 5) {
+      bodyLines.push(`- ...and ${diff.newUndocumented.length - 5} more`);
+    }
+    bodyLines.push('');
+  }
+
+  // Status message
+  if (diff.breaking.length > 0) {
+    bodyLines.push('❌ **Breaking changes detected.** Review carefully before merging.');
+  } else if (diff.newUndocumented.length > 0) {
+    bodyLines.push('⚠️ New exports need documentation. Run `doccov check --fix --generate`.');
+  } else if (diff.coverageDelta < 0) {
+    bodyLines.push('⚠️ Coverage decreased. Consider adding documentation.');
+  } else {
+    bodyLines.push('✅ No breaking changes. Documentation is in sync.');
+  }
+
+  bodyLines.push('');
+  bodyLines.push(
+    `<sub>Comparing \`${base.ref}\` (${base.sha.slice(0, 7)}) → \`${head.ref}\` (${head.sha.slice(0, 7)})</sub>`,
+  );
+  bodyLines.push('');
+  bodyLines.push('---');
+  bodyLines.push('*Generated by [DocCov](https://doccov.com)*');
+
+  const body = bodyLines.join('\n');
+
+  try {
+    const existingId = await findExistingComment(token, owner, repo, prNumber);
+
+    if (existingId) {
+      const response = await fetch(
+        `https://api.github.com/repos/${owner}/${repo}/issues/comments/${existingId}`,
+        {
+          method: 'PATCH',
+          headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({ body }),
+        },
+      );
+      return response.ok;
+    }
+
+    const response = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/issues/${prNumber}/comments`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: 'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ body }),
+      },
+    );
+
+    return response.ok;
+  } catch (err) {
+    console.error('Error posting enhanced PR comment:', err);
+    return false;
+  }
+}

package/src/utils/remote-analyzer.ts

@@ -13,9 +13,9 @@ import { getTokenByInstallationId } from './github-app';
  * Result from remote analysis.
  */
 export interface RemoteAnalysisResult {
-  coveragePercent: number;
-  documentedCount: number;
-  totalCount: number;
+  coverageScore: number;
+  documentedExports: number;
+  totalExports: number;
   driftCount: number;
   qualityErrors: number;
   qualityWarnings: number;
@@ -190,9 +190,9 @@ export async function analyzeRemoteRepo(
 
     // Extract metrics
     const docs = enriched.docs;
-    const coveragePercent = docs?.coverageScore ?? 0;
-    const documentedCount = docs?.documented ?? 0;
-    const totalCount = docs?.total ?? 0;
+    const coverageScore = docs?.coverageScore ?? 0;
+    const documentedExports = docs?.documented ?? 0;
+    const totalExports = docs?.total ?? 0;
     const driftCount = docs?.drift?.length ?? 0;
 
     // Count quality issues
@@ -207,9 +207,9 @@ export async function analyzeRemoteRepo(
     }
 
     return {
-      coveragePercent,
-      documentedCount,
-      totalCount,
+      coverageScore,
+      documentedExports,
+      totalExports,
       driftCount,
       qualityErrors,
       qualityWarnings,
@@ -243,9 +243,9 @@ export function computeAnalysisDiff(
   driftDelta: number;
 } {
   return {
-    coverageDelta: Number((head.coveragePercent - base.coveragePercent).toFixed(1)),
-    documentedDelta: head.documentedCount - base.documentedCount,
-    totalDelta: head.totalCount - base.totalCount,
+    coverageDelta: Number((head.coverageScore - base.coverageScore).toFixed(1)),
+    documentedDelta: head.documentedExports - base.documentedExports,
+    totalDelta: head.totalExports - base.totalExports,
     driftDelta: head.driftCount - base.driftCount,
   };
 }

package/src/utils/spec-cache.ts

@@ -0,0 +1,131 @@
+/**
+ * In-memory LRU cache for specs and diffs.
+ * TTL: 1 hour, Max entries: 100 per cache
+ */
+
+import type { SpecDiffWithDocs } from '@doccov/sdk';
+import type { OpenPkg } from '@openpkg-ts/spec';
+
+interface CacheEntry<T> {
+  value: T;
+  createdAt: number;
+}
+
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+const MAX_ENTRIES = 100;
+
+// Spec cache: key = `${owner}/${repo}/${sha}`
+const specCache = new Map<string, CacheEntry<OpenPkg>>();
+
+// Diff cache: key = `${baseSha}_${headSha}`
+const diffCache = new Map<string, CacheEntry<SpecDiffWithDocs>>();
+
+/**
+ * Evict oldest entries if cache exceeds max size
+ */
+function evictOldest<T>(cache: Map<string, CacheEntry<T>>): void {
+  if (cache.size <= MAX_ENTRIES) return;
+
+  // Find and delete oldest entry
+  let oldestKey: string | null = null;
+  let oldestTime = Infinity;
+
+  for (const [key, entry] of cache) {
+    if (entry.createdAt < oldestTime) {
+      oldestTime = entry.createdAt;
+      oldestKey = key;
+    }
+  }
+
+  if (oldestKey) {
+    cache.delete(oldestKey);
+  }
+}
+
+/**
+ * Check if entry is still valid (not expired)
+ */
+function isValid<T>(entry: CacheEntry<T> | undefined): entry is CacheEntry<T> {
+  if (!entry) return false;
+  return Date.now() - entry.createdAt < CACHE_TTL_MS;
+}
+
+/**
+ * Generate cache key for spec
+ */
+export function specCacheKey(owner: string, repo: string, sha: string): string {
+  return `${owner}/${repo}/${sha}`;
+}
+
+/**
+ * Generate cache key for diff
+ */
+export function diffCacheKey(baseSha: string, headSha: string): string {
+  return `${baseSha}_${headSha}`;
+}
+
+/**
+ * Get cached spec if available and not expired
+ */
+export function getCachedSpec(owner: string, repo: string, sha: string): OpenPkg | null {
+  const key = specCacheKey(owner, repo, sha);
+  const entry = specCache.get(key);
+
+  if (!isValid(entry)) {
+    if (entry) specCache.delete(key);
+    return null;
+  }
+
+  return entry.value;
+}
+
+/**
+ * Cache a spec
+ */
+export function setCachedSpec(owner: string, repo: string, sha: string, spec: OpenPkg): void {
+  const key = specCacheKey(owner, repo, sha);
+  specCache.set(key, { value: spec, createdAt: Date.now() });
+  evictOldest(specCache);
+}
+
+/**
+ * Get cached diff if available and not expired
+ */
+export function getCachedDiff(baseSha: string, headSha: string): SpecDiffWithDocs | null {
+  const key = diffCacheKey(baseSha, headSha);
+  const entry = diffCache.get(key);
+
+  if (!isValid(entry)) {
+    if (entry) diffCache.delete(key);
+    return null;
+  }
+
+  return entry.value;
+}
+
+/**
+ * Cache a diff result
+ */
+export function setCachedDiff(baseSha: string, headSha: string, diff: SpecDiffWithDocs): void {
+  const key = diffCacheKey(baseSha, headSha);
+  diffCache.set(key, { value: diff, createdAt: Date.now() });
+  evictOldest(diffCache);
+}
+
+/**
+ * Clear all caches (for testing)
+ */
+export function clearCaches(): void {
+  specCache.clear();
+  diffCache.clear();
+}
+
+/**
+ * Get cache stats (for monitoring)
+ */
+export function getCacheStats(): { specCount: number; diffCount: number } {
+  return {
+    specCount: specCache.size,
+    diffCount: diffCache.size,
+  };
+}