@doccov/api 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @doccov/api
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @openpkg-ts/spec@0.3.0

package/README.md

@@ -1,153 +1,42 @@
 # @doccov/api
 
-DocCov API server for badge generation and coverage services.
+DocCov API server for badges, widgets, and scanning.
 
 ## Endpoints
 
-### Badge Endpoint
+| Endpoint | Description |
+|----------|-------------|
+| `GET /badge/:owner/:repo` | Coverage badge SVG |
+| `GET /widget/:owner/:repo` | Coverage widget SVG |
+| `GET /leaderboard` | Public rankings |
+| `GET /scan-stream` | SSE repo scanning |
+| `POST /api/examples/run` | Execute code |
 
-```
-GET /badge/:owner/:repo
-```
-
-Returns an SVG badge showing the documentation coverage percentage.
-
-**Query Parameters:**
-- `branch` - Git branch to fetch from (default: `main`)
-
-**Example:**
-```
-https://api.doccov.com/badge/tanstack/query
-```
+## Badge
 
-**Embed in README:**
 ```markdown
-![DocCov](https://api.doccov.com/badge/your-org/your-repo)
-```
-
-### Scan Endpoint
-
-```
-POST /scan
+![DocCov](https://api.doccov.com/badge/YOUR_ORG/YOUR_REPO)
 ```
 
-Scans a public GitHub repository for documentation coverage.
-
-**Request Body:**
-```json
-{
-  "url": "https://github.com/owner/repo",
-  "ref": "main",
-  "package": "@scope/package-name"
-}
-```
-
-**Response:**
-```json
-{
-  "jobId": "scan-123456-abc",
-  "status": "pending",
-  "pollUrl": "/scan/scan-123456-abc"
-}
-```
-
-Poll the `pollUrl` to get results when the scan completes.
-
-### Health Check
-
-```
-GET /health
-```
-
-Returns API health status.
-
 ## Development
 
 ```bash
-# Install dependencies
-bun install
-
-# Run in development mode (uses local CLI spawn)
+cd packages/api
 bun run dev
-
-# Start production server
-bun run start
 ```
 
-### Local Development
-
-In local development, the scan endpoint spawns the `doccov` CLI directly. No additional setup required.
-
-### Production (Vercel Sandbox)
-
-In production on Vercel, scans run in isolated [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) VMs for security and consistency.
-
-**Setup:**
-
-1. Link to your Vercel project:
-   ```bash
-   cd packages/api
-   vercel link
-   ```
-
-2. Pull environment variables (includes OIDC token):
-   ```bash
-   vercel env pull
-   ```
-
-The SDK automatically uses the `VERCEL_OIDC_TOKEN` when available. When deployed to Vercel, tokens are provided automatically.
-
-## Environment Variables
-
-- `PORT` - Server port (default: 3000)
-- `VERCEL_OIDC_TOKEN` - Vercel OIDC token for sandbox authentication (auto-provided on Vercel)
-
 ## Deployment
 
-### Deploy to Vercel
-
-1. **Link the project** (first time only):
-   ```bash
-   cd packages/api
-   vercel link
-   ```
-
-2. **Deploy to preview**:
-   ```bash
-   vercel deploy
-   ```
-
-3. **Deploy to production**:
-   ```bash
-   vercel deploy --prod
-   ```
-
-### Vercel Project Settings
-
-When linking, use these settings:
-- **Framework Preset**: Other
-- **Build Command**: (leave empty, no build needed)
-- **Output Directory**: (leave empty)
-- **Install Command**: `bun install`
-
-### Vercel Sandbox
-
-The `/scan` endpoint uses [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) for isolated execution:
-- Automatic OIDC authentication when deployed to Vercel
-- Each scan runs in a fresh `node22` VM
-- 4 vCPUs, 5-minute timeout per scan
-- ~$0.01-0.05 per scan (see [pricing](https://vercel.com/docs/vercel-sandbox/pricing))
-
-### Requirements for Sandbox
-
-Before sandbox scans work, `@doccov/cli` must be published to npm:
 ```bash
-npm publish --access public
+vercel --prod
 ```
 
-The sandbox installs the CLI via `npm install -g @doccov/cli`.
+## Documentation
+
+- [API Overview](../../docs/api/overview.md)
+- [Endpoints](../../docs/api/endpoints/)
+- [Self-Hosting](../../docs/api/self-hosting.md)
 
 ## License
 
 MIT
-

package/api/examples/run.ts

@@ -0,0 +1,252 @@
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import { Sandbox } from '@vercel/sandbox';
+
+export const config = {
+  runtime: 'nodejs',
+  maxDuration: 30,
+};
+
+interface RunExampleRequest {
+  packageName: string;
+  packageVersion?: string;
+  code: string;
+}
+
+interface RunExampleResponse {
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  duration: number;
+}
+
+/**
+ * Check if running on Vercel (use sandbox) vs local dev (use spawn)
+ */
+function isVercelEnvironment(): boolean {
+  return process.env.VERCEL === '1';
+}
+
+/**
+ * Run example code locally via Node spawn (development fallback)
+ */
+async function runExampleLocal(
+  code: string,
+  packageName: string,
+  packageVersion?: string,
+): Promise<RunExampleResponse> {
+  const tmpDir = os.tmpdir();
+  const workDir = path.join(
+    tmpDir,
+    `doccov-example-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  const codeFile = path.join(workDir, 'example.ts');
+
+  try {
+    fs.mkdirSync(workDir, { recursive: true });
+
+    // Create package.json
+    const pkgJson = {
+      name: 'example-runner',
+      type: 'module',
+      dependencies: {
+        [packageName]: packageVersion || 'latest',
+      },
+    };
+    fs.writeFileSync(path.join(workDir, 'package.json'), JSON.stringify(pkgJson, null, 2));
+
+    // Write example code
+    fs.writeFileSync(codeFile, code);
+
+    const startTime = Date.now();
+
+    // Install dependencies
+    await new Promise<void>((resolve, reject) => {
+      const proc = spawn('npm', ['install', '--silent'], { cwd: workDir, timeout: 15000 });
+      proc.on('close', (code) =>
+        code === 0 ? resolve() : reject(new Error('npm install failed')),
+      );
+      proc.on('error', reject);
+    });
+
+    // Run the example
+    return await new Promise<RunExampleResponse>((resolve) => {
+      let stdout = '';
+      let stderr = '';
+
+      const proc = spawn('node', ['--experimental-strip-types', codeFile], {
+        cwd: workDir,
+        timeout: 5000,
+      });
+
+      proc.stdout?.on('data', (data) => {
+        stdout += data.toString();
+      });
+      proc.stderr?.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on('close', (exitCode) => {
+        resolve({
+          success: exitCode === 0,
+          stdout,
+          stderr,
+          exitCode: exitCode ?? 1,
+          duration: Date.now() - startTime,
+        });
+      });
+
+      proc.on('error', (error) => {
+        resolve({
+          success: false,
+          stdout,
+          stderr: error.message,
+          exitCode: 1,
+          duration: Date.now() - startTime,
+        });
+      });
+    });
+  } finally {
+    // Cleanup
+    try {
+      fs.rmSync(workDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Run example code in Vercel Sandbox (production)
+ */
+async function runExampleInSandbox(
+  code: string,
+  packageName: string,
+  packageVersion?: string,
+): Promise<RunExampleResponse> {
+  const startTime = Date.now();
+  const versionSpec = packageVersion ? `${packageName}@${packageVersion}` : packageName;
+
+  const sandbox = await Sandbox.create({
+    resources: { vcpus: 2 },
+    timeout: 30 * 1000,
+    runtime: 'node22',
+  });
+
+  try {
+    // Create working directory and cd into it
+    const workDir = '/tmp/doccov-run';
+    await sandbox.runCommand({
+      cmd: 'mkdir',
+      args: ['-p', workDir],
+    });
+
+    // Initialize npm project with ESM support
+    await sandbox.runCommand({
+      cmd: 'sh',
+      args: ['-c', `echo '{"type":"module"}' > ${workDir}/package.json`],
+    });
+
+    // Install the target package
+    const installResult = await sandbox.runCommand({
+      cmd: 'npm',
+      args: ['install', versionSpec, '--ignore-scripts', '--legacy-peer-deps'],
+      cwd: workDir,
+    });
+
+    if (installResult.exitCode !== 0) {
+      const installErr = (await installResult.stderr?.()) ?? 'Unknown install error';
+      return {
+        success: false,
+        stdout: '',
+        stderr: `Failed to install ${versionSpec}: ${installErr.slice(-200)}`,
+        exitCode: installResult.exitCode ?? 1,
+        duration: Date.now() - startTime,
+      };
+    }
+
+    // Write example code to working directory
+    const exampleFile = `${workDir}/example.ts`;
+    await sandbox.runCommand({
+      cmd: 'sh',
+      args: ['-c', `cat > ${exampleFile} << 'DOCCOV_EOF'\n${code}\nDOCCOV_EOF`],
+    });
+
+    // Run the example from the working directory
+    const runResult = await sandbox.runCommand({
+      cmd: 'node',
+      args: ['--experimental-strip-types', exampleFile],
+      cwd: workDir,
+    });
+
+    // Note: Vercel Sandbox returns stdout/stderr as async functions
+    const stdout = (await runResult.stdout?.()) ?? '';
+    const stderr = (await runResult.stderr?.()) ?? '';
+
+    return {
+      success: runResult.exitCode === 0,
+      stdout,
+      stderr,
+      exitCode: runResult.exitCode ?? 1,
+      duration: Date.now() - startTime,
+    };
+  } finally {
+    await sandbox.stop();
+  }
+}
+
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+  // CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    return res.status(200).end();
+  }
+
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  const body = req.body as RunExampleRequest;
+
+  if (!body.packageName) {
+    return res.status(400).json({ error: 'packageName is required' });
+  }
+
+  if (!body.code) {
+    return res.status(400).json({ error: 'code is required' });
+  }
+
+  // Strip markdown code block markers if present
+  const cleanCode = body.code
+    .replace(/^```(?:ts|typescript|js|javascript)?\n?/i, '')
+    .replace(/\n?```$/i, '')
+    .trim();
+
+  try {
+    let result: RunExampleResponse;
+
+    if (isVercelEnvironment()) {
+      result = await runExampleInSandbox(cleanCode, body.packageName, body.packageVersion);
+    } else {
+      result = await runExampleLocal(cleanCode, body.packageName, body.packageVersion);
+    }
+
+    return res.status(200).json(result);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return res.status(500).json({
+      success: false,
+      stdout: '',
+      stderr: message,
+      exitCode: 1,
+      duration: 0,
+    });
+  }
+}

package/api/index.ts

@@ -0,0 +1,218 @@
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { handle } from 'hono/vercel';
+
+export const config = {
+  runtime: 'edge',
+};
+
+const app = new Hono().basePath('/');
+
+// Middleware
+app.use('*', cors());
+
+// Types
+type BadgeColor =
+  | 'brightgreen'
+  | 'green'
+  | 'yellowgreen'
+  | 'yellow'
+  | 'orange'
+  | 'red'
+  | 'lightgrey';
+
+interface OpenPkgSpec {
+  docs?: {
+    coverageScore?: number;
+  };
+  [key: string]: unknown;
+}
+
+// Badge helpers
+function getColorForScore(score: number): BadgeColor {
+  if (score >= 90) return 'brightgreen';
+  if (score >= 80) return 'green';
+  if (score >= 70) return 'yellowgreen';
+  if (score >= 60) return 'yellow';
+  if (score >= 50) return 'orange';
+  return 'red';
+}
+
+function generateBadgeSvg(label: string, message: string, color: BadgeColor): string {
+  const colors: Record<BadgeColor, string> = {
+    brightgreen: '#4c1',
+    green: '#97ca00',
+    yellowgreen: '#a4a61d',
+    yellow: '#dfb317',
+    orange: '#fe7d37',
+    red: '#e05d44',
+    lightgrey: '#9f9f9f',
+  };
+
+  const bgColor = colors[color];
+  const labelWidth = label.length * 7 + 10;
+  const messageWidth = message.length * 7 + 10;
+  const totalWidth = labelWidth + messageWidth;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${label}: ${message}">
+  <title>${label}: ${message}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r">
+    <rect width="${totalWidth}" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${labelWidth}" height="20" fill="#555"/>
+    <rect x="${labelWidth}" width="${messageWidth}" height="20" fill="${bgColor}"/>
+    <rect width="${totalWidth}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="11">
+    <text aria-hidden="true" x="${labelWidth / 2}" y="15" fill="#010101" fill-opacity=".3">${label}</text>
+    <text x="${labelWidth / 2}" y="14">${label}</text>
+    <text aria-hidden="true" x="${labelWidth + messageWidth / 2}" y="15" fill="#010101" fill-opacity=".3">${message}</text>
+    <text x="${labelWidth + messageWidth / 2}" y="14">${message}</text>
+  </g>
+</svg>`;
+}
+
+async function fetchSpecFromGitHub(
+  owner: string,
+  repo: string,
+  ref = 'main',
+): Promise<OpenPkgSpec | null> {
+  const urls = [
+    `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/openpkg.json`,
+    ...(ref === 'main'
+      ? [`https://raw.githubusercontent.com/${owner}/${repo}/master/openpkg.json`]
+      : []),
+  ];
+
+  for (const url of urls) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return (await response.json()) as OpenPkgSpec;
+      }
+    } catch {
+      // Try next URL
+    }
+  }
+  return null;
+}
+
+// Root
+app.get('/', (c) => {
+  return c.json({
+    name: 'DocCov API',
+    version: '0.2.0',
+    endpoints: {
+      health: '/health',
+      badge: '/badge/:owner/:repo',
+      spec: '/spec/:owner/:repo/:ref?',
+      specPr: '/spec/:owner/:repo/pr/:pr',
+      scan: '/scan (POST)',
+      scanStream: '/scan-stream (GET)',
+    },
+  });
+});
+
+// Health check
+app.get('/health', (c) => {
+  return c.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+// GET /badge/:owner/:repo
+app.get('/badge/:owner/:repo', async (c) => {
+  const { owner, repo } = c.req.param();
+  const branch = c.req.query('branch') ?? 'main';
+
+  try {
+    const spec = await fetchSpecFromGitHub(owner, repo, branch);
+
+    if (!spec) {
+      const svg = generateBadgeSvg('docs', 'not found', 'lightgrey');
+      return c.body(svg, 404, {
+        'Content-Type': 'image/svg+xml',
+        'Cache-Control': 'no-cache',
+      });
+    }
+
+    const coverageScore = spec.docs?.coverageScore ?? 0;
+    const svg = generateBadgeSvg('docs', `${coverageScore}%`, getColorForScore(coverageScore));
+
+    return c.body(svg, 200, {
+      'Content-Type': 'image/svg+xml',
+      'Cache-Control': 'public, max-age=300',
+    });
+  } catch {
+    const svg = generateBadgeSvg('docs', 'error', 'red');
+    return c.body(svg, 500, {
+      'Content-Type': 'image/svg+xml',
+      'Cache-Control': 'no-cache',
+    });
+  }
+});
+
+// GET /badge/:owner/:repo.svg (alias)
+app.get('/badge/:owner/:repo.svg', async (c) => {
+  const owner = c.req.param('owner');
+  const repoWithSvg = c.req.param('repo.svg') ?? '';
+  const repoName = repoWithSvg.replace(/\.svg$/, '');
+  return c.redirect(`/badge/${owner}/${repoName}`);
+});
+
+// GET /spec/:owner/:repo/pr/:pr - Must be before the :ref route
+app.get('/spec/:owner/:repo/pr/:pr', async (c) => {
+  const { owner, repo, pr } = c.req.param();
+
+  try {
+    // Get PR head SHA from GitHub API
+    const prResponse = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${pr}`, {
+      headers: { 'User-Agent': 'DocCov' },
+    });
+
+    if (!prResponse.ok) {
+      return c.json({ error: 'PR not found' }, 404);
+    }
+
+    const prData = (await prResponse.json()) as { head: { sha: string } };
+    const headSha = prData.head.sha;
+
+    // Fetch spec from PR head
+    const specUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${headSha}/openpkg.json`;
+    const specResponse = await fetch(specUrl);
+
+    if (!specResponse.ok) {
+      return c.json({ error: 'Spec not found in PR' }, 404);
+    }
+
+    const spec = await specResponse.json();
+    return c.json(spec, 200, {
+      'Cache-Control': 'no-cache',
+    });
+  } catch {
+    return c.json({ error: 'Failed to fetch PR spec' }, 500);
+  }
+});
+
+// GET /spec/:owner/:repo/:ref? (default ref = main)
+app.get('/spec/:owner/:repo/:ref?', async (c) => {
+  const { owner, repo } = c.req.param();
+  const ref = c.req.param('ref') ?? 'main';
+
+  const spec = await fetchSpecFromGitHub(owner, repo, ref);
+
+  if (!spec) {
+    return c.json({ error: 'Spec not found' }, 404);
+  }
+
+  return c.json(spec, 200, {
+    'Cache-Control': 'public, max-age=300',
+  });
+});
+
+// Note: /scan and /scan-stream are handled by separate Node.js functions
+
+export default handle(app);