@doccov/api 0.4.0 → 0.5.0

package/src/utils/github-checks.ts

@@ -0,0 +1,278 @@
+/**
+ * GitHub Check Runs and PR Comments
+ */
+
+import { getTokenByInstallationId } from './github-app';
+
+interface AnalysisResult {
+  coveragePercent: number;
+  documentedCount: number;
+  totalCount: number;
+  driftCount: number;
+  qualityErrors?: number;
+  qualityWarnings?: number;
+}
+
+interface AnalysisDiff {
+  coverageDelta: number;
+  documentedDelta: number;
+  totalDelta: number;
+  driftDelta: number;
+}
+
+/**
+ * Format a delta value with sign and styling
+ */
+function formatDelta(delta: number, suffix = ''): string {
+  if (delta === 0) return '';
+  const sign = delta > 0 ? '+' : '';
+  return ` (${sign}${delta}${suffix})`;
+}
+
+/**
+ * Create or update a check run
+ */
+export async function createCheckRun(
+  installationId: string,
+  owner: string,
+  repo: string,
+  sha: string,
+  result: AnalysisResult,
+  diff?: AnalysisDiff | null,
+): Promise<boolean> {
+  const token = await getTokenByInstallationId(installationId);
+  if (!token) return false;
+
+  const coverageDelta = diff ? formatDelta(diff.coverageDelta, '%') : '';
+
+  // Determine conclusion based on drift and quality
+  const hasIssues = result.driftCount > 0 || (result.qualityErrors ?? 0) > 0;
+  const conclusion = hasIssues ? 'neutral' : 'success';
+
+  const title = `Coverage: ${result.coveragePercent.toFixed(1)}%${coverageDelta}`;
+
+  const summaryLines = [
+    `## Documentation Coverage`,
+    '',
+    `\`\`\``,
+    `Coverage: ${result.coveragePercent.toFixed(1)}%${coverageDelta}`,
+    `├─ Documented: ${result.documentedCount}/${result.totalCount} exports`,
+    `├─ Drift: ${result.driftCount} issue${result.driftCount !== 1 ? 's' : ''}${diff ? formatDelta(-diff.driftDelta) : ''}`,
+  ];
+
+  const qualityIssues = (result.qualityErrors ?? 0) + (result.qualityWarnings ?? 0);
+  if (qualityIssues > 0) {
+    summaryLines.push(
+      `└─ Quality: ${result.qualityErrors ?? 0} error${(result.qualityErrors ?? 0) !== 1 ? 's' : ''}, ${result.qualityWarnings ?? 0} warning${(result.qualityWarnings ?? 0) !== 1 ? 's' : ''}`,
+    );
+  } else {
+    summaryLines.push(`└─ Quality: ✓ No issues`);
+  }
+
+  summaryLines.push(`\`\`\``);
+
+  if (diff) {
+    summaryLines.push('', '### Changes vs base');
+    summaryLines.push('| Metric | Delta |');
+    summaryLines.push('|--------|-------|');
+    summaryLines.push(
+      `| Coverage | ${diff.coverageDelta >= 0 ? '📈' : '📉'} ${diff.coverageDelta >= 0 ? '+' : ''}${diff.coverageDelta.toFixed(1)}% |`,
+    );
+    if (diff.documentedDelta !== 0) {
+      summaryLines.push(
+        `| Documented | ${diff.documentedDelta >= 0 ? '+' : ''}${diff.documentedDelta} |`,
+      );
+    }
+    if (diff.driftDelta !== 0) {
+      const driftChange = -diff.driftDelta; // Positive driftDelta means drift increased (bad)
+      summaryLines.push(`| Drift issues | ${driftChange >= 0 ? '+' : ''}${driftChange} |`);
+    }
+  }
+
+  summaryLines.push('', `[View full report →](https://doccov.com/r/${owner}/${repo}/${sha})`);
+
+  try {
+    const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/check-runs`, {
+      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({
+        name: 'DocCov',
+        head_sha: sha,
+        status: 'completed',
+        conclusion,
+        output: {
+          title,
+          summary: summaryLines.join('\n'),
+        },
+      }),
+    });
+
+    if (!response.ok) {
+      console.error('Failed to create check run:', await response.text());
+      return false;
+    }
+
+    return true;
+  } catch (err) {
+    console.error('Error creating check run:', err);
+    return false;
+  }
+}
+
+/**
+ * Post or update a PR comment
+ */
+export async function postPRComment(
+  installationId: string,
+  owner: string,
+  repo: string,
+  prNumber: number,
+  result: AnalysisResult,
+  diff?: AnalysisDiff | null,
+): Promise<boolean> {
+  const token = await getTokenByInstallationId(installationId);
+  if (!token) return false;
+
+  const coverageEmoji = diff
+    ? diff.coverageDelta > 0
+      ? '📈'
+      : diff.coverageDelta < 0
+        ? '📉'
+        : '➡️'
+    : '📊';
+
+  const bodyLines = [`## ${coverageEmoji} DocCov Report`, ''];
+
+  // Summary table
+  if (diff) {
+    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)}% |`,
+    );
+    bodyLines.push(
+      `| Documented | ${result.documentedCount} | ${result.documentedCount - diff.documentedDelta} | ${diff.documentedDelta >= 0 ? '+' : ''}${diff.documentedDelta} |`,
+    );
+    bodyLines.push(
+      `| Total exports | ${result.totalCount} | ${result.totalCount - diff.totalDelta} | ${diff.totalDelta >= 0 ? '+' : ''}${diff.totalDelta} |`,
+    );
+    const baseDrift = result.driftCount - diff.driftDelta;
+    const driftSign = diff.driftDelta >= 0 ? '+' : '';
+    bodyLines.push(
+      `| Drift issues | ${result.driftCount} | ${baseDrift} | ${driftSign}${diff.driftDelta} |`,
+    );
+  } else {
+    bodyLines.push('| Metric | Value |');
+    bodyLines.push('|--------|-------|');
+    bodyLines.push(`| Coverage | **${result.coveragePercent.toFixed(1)}%** |`);
+    bodyLines.push(`| Documented | ${result.documentedCount} / ${result.totalCount} |`);
+    bodyLines.push(`| Drift issues | ${result.driftCount} |`);
+  }
+
+  bodyLines.push('');
+
+  // Quality summary
+  const qualityErrors = result.qualityErrors ?? 0;
+  const qualityWarnings = result.qualityWarnings ?? 0;
+  if (qualityErrors > 0 || qualityWarnings > 0) {
+    bodyLines.push(
+      `**Quality**: ${qualityErrors} error${qualityErrors !== 1 ? 's' : ''}, ${qualityWarnings} warning${qualityWarnings !== 1 ? 's' : ''}`,
+    );
+    bodyLines.push('');
+  }
+
+  // Status message
+  if (result.driftCount > 0) {
+    bodyLines.push('⚠️ Documentation drift detected. Run `doccov check --fix` to update.');
+  } else if (qualityErrors > 0) {
+    bodyLines.push('❌ Quality errors found. Run `doccov check` for details.');
+  } else {
+    bodyLines.push('✅ Documentation is in sync.');
+  }
+
+  bodyLines.push('');
+  bodyLines.push('---');
+  bodyLines.push('*Generated by [DocCov](https://doccov.com)*');
+
+  const body = bodyLines.join('\n');
+
+  try {
+    // Check for existing comment
+    const existingId = await findExistingComment(token, owner, repo, prNumber);
+
+    if (existingId) {
+      // Update existing comment
+      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;
+    }
+
+    // Create new comment
+    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 PR comment:', err);
+    return false;
+  }
+}
+
+/**
+ * Find existing DocCov comment on a PR
+ */
+async function findExistingComment(
+  token: string,
+  owner: string,
+  repo: string,
+  prNumber: number,
+): Promise<number | null> {
+  try {
+    const response = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/issues/${prNumber}/comments`,
+      {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: 'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28',
+        },
+      },
+    );
+
+    if (!response.ok) return null;
+
+    const comments = (await response.json()) as Array<{ id: number; body: string }>;
+    const existing = comments.find((c) => c.body.includes('DocCov Report'));
+
+    return existing?.id ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/utils/remote-analyzer.ts

@@ -0,0 +1,251 @@
+/**
+ * Remote repository analyzer - runs DocCov analysis on GitHub repos via webhooks.
+ * Uses shallow clone to temp dir for full TypeScript resolution.
+ */
+
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DocCov, enrichSpec, type OpenPkgSpec } from '@doccov/sdk';
+import { getTokenByInstallationId } from './github-app';
+
+/**
+ * Result from remote analysis.
+ */
+export interface RemoteAnalysisResult {
+  coveragePercent: number;
+  documentedCount: number;
+  totalCount: number;
+  driftCount: number;
+  qualityErrors: number;
+  qualityWarnings: number;
+  /** Full spec for detailed reports */
+  spec?: OpenPkgSpec;
+}
+
+/**
+ * Shallow clone a GitHub repo to a temp directory.
+ */
+async function cloneRepo(
+  owner: string,
+  repo: string,
+  ref: string,
+  authToken: string,
+): Promise<string> {
+  const tmpDir = join(tmpdir(), `doccov-${owner}-${repo}-${Date.now()}`);
+
+  // Use authenticated HTTPS URL for private repos
+  const cloneUrl = `https://x-access-token:${authToken}@github.com/${owner}/${repo}.git`;
+
+  const proc = Bun.spawn(['git', 'clone', '--depth', '1', '--branch', ref, cloneUrl, tmpDir], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+
+    // Try fetching specific SHA if branch clone fails
+    if (ref.length === 40) {
+      // Looks like a SHA
+      const shallowProc = Bun.spawn(['git', 'clone', '--depth', '1', cloneUrl, tmpDir], {
+        stdout: 'pipe',
+        stderr: 'pipe',
+      });
+      await shallowProc.exited;
+
+      const fetchProc = Bun.spawn(['git', '-C', tmpDir, 'fetch', 'origin', ref], {
+        stdout: 'pipe',
+        stderr: 'pipe',
+      });
+      await fetchProc.exited;
+
+      const checkoutProc = Bun.spawn(['git', '-C', tmpDir, 'checkout', ref], {
+        stdout: 'pipe',
+        stderr: 'pipe',
+      });
+      const checkoutExit = await checkoutProc.exited;
+
+      if (checkoutExit !== 0) {
+        throw new Error(`Failed to checkout ${ref}: ${stderr}`);
+      }
+    } else {
+      throw new Error(`Failed to clone ${owner}/${repo}@${ref}: ${stderr}`);
+    }
+  }
+
+  return tmpDir;
+}
+
+/**
+ * Detect the entry point for a package.
+ */
+async function detectEntryPoint(repoDir: string): Promise<string | null> {
+  try {
+    const packageJsonPath = join(repoDir, 'package.json');
+    const packageJson = await Bun.file(packageJsonPath).json();
+
+    // Check exports first (modern packages)
+    if (packageJson.exports) {
+      const mainExport = packageJson.exports['.'];
+      if (typeof mainExport === 'string') {
+        return mainExport.replace(/^\.\//, '');
+      }
+      if (mainExport?.import) {
+        const importPath =
+          typeof mainExport.import === 'string' ? mainExport.import : mainExport.import.default;
+        if (importPath) return importPath.replace(/^\.\//, '');
+      }
+      if (mainExport?.types) {
+        return mainExport.types.replace(/^\.\//, '');
+      }
+    }
+
+    // Check types field
+    if (packageJson.types) {
+      return packageJson.types.replace(/^\.\//, '');
+    }
+
+    // Check main field
+    if (packageJson.main) {
+      // Convert .js to .ts if applicable
+      const main = packageJson.main.replace(/^\.\//, '');
+      const tsMain = main.replace(/\.js$/, '.ts');
+      const tsxMain = main.replace(/\.js$/, '.tsx');
+
+      // Check if TS version exists
+      const tsFile = Bun.file(join(repoDir, tsMain));
+      if (await tsFile.exists()) return tsMain;
+
+      const tsxFile = Bun.file(join(repoDir, tsxMain));
+      if (await tsxFile.exists()) return tsxMain;
+
+      return main;
+    }
+
+    // Common fallbacks
+    const fallbacks = ['src/index.ts', 'src/index.tsx', 'index.ts', 'lib/index.ts'];
+    for (const fallback of fallbacks) {
+      const file = Bun.file(join(repoDir, fallback));
+      if (await file.exists()) return fallback;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Analyze a remote GitHub repository.
+ *
+ * @param installationId - GitHub App installation ID
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @param ref - Git ref (branch, tag, or SHA)
+ * @param includeSpec - Whether to include full spec in result
+ * @returns Analysis result or null if failed
+ */
+export async function analyzeRemoteRepo(
+  installationId: string,
+  owner: string,
+  repo: string,
+  ref: string,
+  includeSpec = false,
+): Promise<RemoteAnalysisResult | null> {
+  // Get installation token
+  const token = await getTokenByInstallationId(installationId);
+  if (!token) {
+    console.error(`No token for installation ${installationId}`);
+    return null;
+  }
+
+  let tmpDir: string | null = null;
+
+  try {
+    // Clone repo to temp dir
+    tmpDir = await cloneRepo(owner, repo, ref, token);
+
+    // Detect entry point
+    const entryPoint = await detectEntryPoint(tmpDir);
+    if (!entryPoint) {
+      console.error(`No entry point found for ${owner}/${repo}`);
+      return null;
+    }
+
+    const entryPath = join(tmpDir, entryPoint);
+
+    // Run analysis
+    const doccov = new DocCov({
+      resolveExternalTypes: false, // Skip for speed
+      useCache: false, // No caching for webhook analysis
+    });
+
+    const result = await doccov.analyzeFileWithDiagnostics(entryPath);
+
+    // Enrich with coverage metrics
+    const enriched = enrichSpec(result.spec);
+
+    // Extract metrics
+    const docs = enriched.docs;
+    const coveragePercent = docs?.coverageScore ?? 0;
+    const documentedCount = docs?.documented ?? 0;
+    const totalCount = docs?.total ?? 0;
+    const driftCount = docs?.drift?.length ?? 0;
+
+    // Count quality issues
+    let qualityErrors = 0;
+    let qualityWarnings = 0;
+
+    if (docs?.quality) {
+      for (const item of docs.quality) {
+        if (item.severity === 'error') qualityErrors++;
+        else if (item.severity === 'warning') qualityWarnings++;
+      }
+    }
+
+    return {
+      coveragePercent,
+      documentedCount,
+      totalCount,
+      driftCount,
+      qualityErrors,
+      qualityWarnings,
+      spec: includeSpec ? enriched : undefined,
+    };
+  } catch (err) {
+    console.error(`Analysis failed for ${owner}/${repo}@${ref}:`, err);
+    return null;
+  } finally {
+    // Cleanup temp dir
+    if (tmpDir) {
+      try {
+        await rm(tmpDir, { recursive: true, force: true });
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+}
+
+/**
+ * Compute diff between two analysis results.
+ */
+export function computeAnalysisDiff(
+  base: RemoteAnalysisResult,
+  head: RemoteAnalysisResult,
+): {
+  coverageDelta: number;
+  documentedDelta: number;
+  totalDelta: number;
+  driftDelta: number;
+} {
+  return {
+    coverageDelta: Number((head.coveragePercent - base.coveragePercent).toFixed(1)),
+    documentedDelta: head.documentedCount - base.documentedCount,
+    totalDelta: head.totalCount - base.totalCount,
+    driftDelta: head.driftCount - base.driftCount,
+  };
+}

package/src/utils/github.ts

@@ -1,5 +0,0 @@
-/**
- * Re-export GitHub utilities from SDK for backwards compatibility.
- * @deprecated Import directly from '@doccov/sdk' instead.
- */
-export { fetchSpec as fetchSpecFromGitHub } from '@doccov/sdk';