@doccov/api 0.3.4 → 0.3.6

package/src/routes/scan.ts

@@ -1,240 +0,0 @@
-import { spawn } from 'node:child_process';
-import * as path from 'node:path';
-import { Hono } from 'hono';
-import { isSandboxAvailable, runScanInSandbox } from '../sandbox-runner';
-import { type ScanJob, type ScanResult, scanJobStore } from '../scan-worker';
-import { scanRequestSchema } from '../schemas/scan';
-
-export const scanRoute = new Hono();
-
-/**
- * POST /scan
- * Start a new scan job
- */
-scanRoute.post('/', async (c) => {
-  // Parse JSON with error handling
-  let rawBody: unknown;
-  try {
-    rawBody = await c.req.json();
-  } catch {
-    return c.json({ error: 'Invalid JSON' }, 400);
-  }
-
-  // Validate request body with Zod schema
-  const parsed = scanRequestSchema.safeParse(rawBody);
-  if (!parsed.success) {
-    return c.json(
-      {
-        error: 'Validation failed',
-        details: parsed.error.issues.map((i) => i.message),
-      },
-      400,
-    );
-  }
-
-  const body = parsed.data;
-
-  // Generate job ID
-  const jobId = `scan-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-
-  // Check cache first
-  const cacheKey = buildCacheKey(body.url, body.ref, body.package);
-  const cached = scanJobStore.getFromCache(cacheKey);
-  if (cached) {
-    return c.json({
-      jobId,
-      status: 'complete',
-      cached: true,
-      result: cached,
-    });
-  }
-
-  // Create job
-  const job: ScanJob = {
-    id: jobId,
-    status: 'pending',
-    url: body.url,
-    ref: body.ref,
-    package: body.package,
-    createdAt: Date.now(),
-  };
-
-  scanJobStore.set(jobId, job);
-
-  // Start background worker (sandbox or local based on environment)
-  startScanWorker(job, cacheKey);
-
-  return c.json({
-    jobId,
-    status: 'pending',
-    pollUrl: `/scan/${jobId}`,
-  });
-});
-
-/**
- * GET /scan/:jobId
- * Get scan job status and result
- */
-scanRoute.get('/:jobId', (c) => {
-  const jobId = c.req.param('jobId');
-  const job = scanJobStore.get(jobId);
-
-  if (!job) {
-    return c.json({ error: 'Job not found' }, 404);
-  }
-
-  if (job.status === 'complete') {
-    return c.json({
-      jobId,
-      status: 'complete',
-      result: job.result,
-    });
-  }
-
-  if (job.status === 'failed') {
-    return c.json({
-      jobId,
-      status: 'failed',
-      error: job.error,
-    });
-  }
-
-  return c.json({
-    jobId,
-    status: job.status,
-    startedAt: job.startedAt,
-  });
-});
-
-/**
- * Build cache key from scan parameters
- */
-function buildCacheKey(url: string, ref?: string, pkg?: string): string {
-  const parts = [url, ref ?? 'main'];
-  if (pkg) parts.push(pkg);
-  return parts.join('::');
-}
-
-/**
- * Start background scan worker
- * Uses Vercel Sandbox in production, local spawn in development
- */
-function startScanWorker(job: ScanJob, cacheKey: string): void {
-  if (isSandboxAvailable()) {
-    runSandboxScan(job, cacheKey);
-  } else {
-    runLocalScan(job, cacheKey);
-  }
-}
-
-/**
- * Run scan in Vercel Sandbox (production)
- */
-async function runSandboxScan(job: ScanJob, cacheKey: string): Promise<void> {
-  job.status = 'running';
-  job.startedAt = Date.now();
-  scanJobStore.set(job.id, job);
-
-  try {
-    const result = await runScanInSandbox({
-      url: job.url,
-      ref: job.ref,
-      package: job.package,
-    });
-
-    job.status = 'complete';
-    job.result = result;
-    job.completedAt = Date.now();
-    scanJobStore.setCache(cacheKey, result);
-  } catch (error) {
-    job.status = 'failed';
-    job.error = error instanceof Error ? error.message : String(error);
-  }
-
-  scanJobStore.set(job.id, job);
-}
-
-/**
- * Run scan locally via CLI spawn (development fallback)
- */
-function runLocalScan(job: ScanJob, cacheKey: string): void {
-  // Update job status
-  job.status = 'running';
-  job.startedAt = Date.now();
-  scanJobStore.set(job.id, job);
-
-  // Get monorepo root (packages/api/src/routes -> root)
-  const monorepoRoot = path.resolve(import.meta.dirname, '..', '..', '..', '..');
-  const cliPath = path.join(monorepoRoot, 'packages/cli/src/cli.ts');
-
-  // Build command args
-  const args = [cliPath, 'scan', job.url, '--output', 'json'];
-  if (job.ref) {
-    args.push('--ref', job.ref);
-  }
-  if (job.package) {
-    args.push('--package', job.package);
-  }
-
-  // Spawn doccov scan process
-  const proc = spawn('bun', args, {
-    cwd: monorepoRoot,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-
-  let stdout = '';
-  let stderr = '';
-
-  proc.stdout.on('data', (data) => {
-    stdout += data.toString();
-  });
-
-  proc.stderr.on('data', (data) => {
-    stderr += data.toString();
-  });
-
-  proc.on('close', (code) => {
-    if (code === 0) {
-      try {
-        // Extract JSON from output (skip any non-JSON lines)
-        const jsonMatch = stdout.match(/\{[\s\S]*\}/);
-        if (jsonMatch) {
-          const result = JSON.parse(jsonMatch[0]) as ScanResult;
-          job.status = 'complete';
-          job.result = result;
-          job.completedAt = Date.now();
-
-          // Cache result
-          scanJobStore.setCache(cacheKey, result);
-        } else {
-          job.status = 'failed';
-          job.error = 'No JSON output from scan';
-        }
-      } catch (parseError) {
-        job.status = 'failed';
-        job.error = `Failed to parse scan output: ${parseError instanceof Error ? parseError.message : parseError}`;
-      }
-    } else {
-      job.status = 'failed';
-      job.error = stderr || `Scan exited with code ${code}`;
-    }
-
-    scanJobStore.set(job.id, job);
-  });
-
-  proc.on('error', (err) => {
-    job.status = 'failed';
-    job.error = `Process error: ${err.message}`;
-    scanJobStore.set(job.id, job);
-  });
-
-  // Timeout after 3 minutes
-  setTimeout(() => {
-    if (job.status === 'running') {
-      proc.kill();
-      job.status = 'failed';
-      job.error = 'Scan timed out after 3 minutes';
-      scanJobStore.set(job.id, job);
-    }
-  }, 180000);
-}

package/src/sandbox-runner.ts

@@ -1,82 +0,0 @@
-/**
- * Vercel Sandbox runner for isolated repo scanning
- */
-
-import type { ScanResult } from '@doccov/sdk';
-import { Sandbox } from '@vercel/sandbox';
-import ms from 'ms';
-
-export interface ScanOptions {
-  url: string;
-  ref?: string;
-  package?: string;
-}
-
-/**
- * Run a documentation coverage scan in an isolated Vercel Sandbox.
- *
- * The sandbox:
- * 1. Clones the repository (automatic via source.url)
- * 2. Installs dependencies (with --ignore-scripts for security)
- * 3. Installs @doccov/cli globally
- * 4. Runs doccov scan with --skip-install (deps already installed)
- * 5. Returns the scan result
- */
-export async function runScanInSandbox(options: ScanOptions): Promise<ScanResult> {
-  const sandbox = await Sandbox.create({
-    source: {
-      url: options.url,
-      type: 'git',
-    },
-    resources: { vcpus: 4 },
-    timeout: ms('5m'),
-    runtime: 'node22',
-  });
-
-  try {
-    // Install project dependencies (with security flags)
-    await sandbox.runCommand({
-      cmd: 'npm',
-      args: ['install', '--ignore-scripts', '--legacy-peer-deps'],
-    });
-
-    // Install doccov CLI globally
-    await sandbox.runCommand({
-      cmd: 'npm',
-      args: ['install', '-g', '@doccov/cli'],
-    });
-
-    // Build the scan command args
-    const scanArgs = ['scan', '.', '--output', 'json', '--skip-install'];
-    if (options.package) {
-      scanArgs.push('--package', options.package);
-    }
-
-    // Run the scan
-    const result = await sandbox.runCommand({
-      cmd: 'doccov',
-      args: scanArgs,
-    });
-
-    // Parse and return the JSON result
-    // The output may contain spinner text before the JSON, so extract JSON portion
-    const stdout = result.stdout ?? '';
-    const jsonMatch = stdout.match(/\{[\s\S]*\}/);
-
-    if (!jsonMatch) {
-      throw new Error('No JSON output from scan');
-    }
-
-    return JSON.parse(jsonMatch[0]) as ScanResult;
-  } finally {
-    // Always stop the sandbox to clean up resources
-    await sandbox.stop();
-  }
-}
-
-/**
- * Check if Vercel Sandbox is available (OIDC token present)
- */
-export function isSandboxAvailable(): boolean {
-  return process.env.VERCEL_OIDC_TOKEN !== undefined;
-}

package/src/scan-worker.ts

@@ -1,122 +0,0 @@
-/**
- * Scan job store and caching layer
- */
-
-import type { ScanResult } from '@doccov/sdk';
-import type { JobStore } from './stores/job-store.interface';
-
-// Re-export ScanResult for backwards compatibility
-export type { ScanResult } from '@doccov/sdk';
-
-export interface ScanJob {
-  id: string;
-  status: 'pending' | 'running' | 'complete' | 'failed';
-  url: string;
-  ref?: string;
-  package?: string;
-  createdAt: number;
-  startedAt?: number;
-  completedAt?: number;
-  result?: ScanResult;
-  error?: string;
-}
-
-interface CacheEntry {
-  result: ScanResult;
-  cachedAt: number;
-}
-
-const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
-const JOB_TTL_MS = 10 * 60 * 1000; // 10 minutes
-
-/**
- * In-memory job store with caching
- * Implements JobStore interface for easy swap to Redis/KV
- */
-class ScanJobStore implements JobStore {
-  private jobs = new Map<string, ScanJob>();
-  private cache = new Map<string, CacheEntry>();
-
-  /**
-   * Get a job by ID
-   */
-  get(jobId: string): ScanJob | undefined {
-    return this.jobs.get(jobId);
-  }
-
-  /**
-   * Set/update a job
-   */
-  set(jobId: string, job: ScanJob): void {
-    this.jobs.set(jobId, job);
-  }
-
-  /**
-   * Get cached result
-   */
-  getFromCache(key: string): ScanResult | undefined {
-    const entry = this.cache.get(key);
-    if (!entry) return undefined;
-
-    // Check TTL
-    if (Date.now() - entry.cachedAt > CACHE_TTL_MS) {
-      this.cache.delete(key);
-      return undefined;
-    }
-
-    return entry.result;
-  }
-
-  /**
-   * Set cache entry
-   */
-  setCache(key: string, result: ScanResult): void {
-    this.cache.set(key, {
-      result,
-      cachedAt: Date.now(),
-    });
-  }
-
-  /**
-   * Clean up old jobs and cache entries
-   */
-  cleanup(): void {
-    const now = Date.now();
-
-    // Clean old jobs
-    for (const [id, job] of this.jobs.entries()) {
-      if (now - job.createdAt > JOB_TTL_MS) {
-        this.jobs.delete(id);
-      }
-    }
-
-    // Clean expired cache
-    for (const [key, entry] of this.cache.entries()) {
-      if (now - entry.cachedAt > CACHE_TTL_MS) {
-        this.cache.delete(key);
-      }
-    }
-  }
-
-  /**
-   * Get store stats for monitoring
-   */
-  stats(): { jobs: number; cache: number } {
-    return {
-      jobs: this.jobs.size,
-      cache: this.cache.size,
-    };
-  }
-}
-
-// Singleton instance
-export const scanJobStore = new ScanJobStore();
-
-// Periodic cleanup every 5 minutes
-// Use .unref() to prevent keeping the process alive
-setInterval(
-  () => {
-    scanJobStore.cleanup();
-  },
-  5 * 60 * 1000,
-).unref();

package/src/stores/job-store.interface.ts

@@ -1,25 +0,0 @@
-import type { ScanJob, ScanResult } from '../scan-worker';
-
-/**
- * Interface for scan job storage
- * Allows swapping in-memory store for Redis/KV in production
- */
-export interface JobStore {
-  /** Get a job by ID */
-  get(jobId: string): ScanJob | undefined | Promise<ScanJob | undefined>;
-
-  /** Set/update a job */
-  set(jobId: string, job: ScanJob): void | Promise<void>;
-
-  /** Get cached scan result */
-  getFromCache(key: string): ScanResult | undefined | Promise<ScanResult | undefined>;
-
-  /** Cache a scan result */
-  setCache(key: string, result: ScanResult): void | Promise<void>;
-
-  /** Cleanup expired entries */
-  cleanup(): void | Promise<void>;
-
-  /** Get store statistics */
-  stats(): { jobs: number; cache: number } | Promise<{ jobs: number; cache: number }>;
-}