@doccov/api 0.4.0 → 0.6.0

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 {
+  coverageScore: number;
+  documentedExports: number;
+  totalExports: 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 coverageScore = docs?.coverageScore ?? 0;
+    const documentedExports = docs?.documented ?? 0;
+    const totalExports = 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 {
+      coverageScore,
+      documentedExports,
+      totalExports,
+      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.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,
+  };
+}