@doccov/api 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @doccov/api
 
+## 0.2.2
+
+### Patch Changes
+
+- feat(cli): add markdown docs impact detection to diff command
+  refactor(cli): consolidate fix functionality into check command
+  refactor(sdk): reuse detection extraction
+  fix(api): bug in api scan
+  fix(api): monorepo detection in scan
+  fix(api): improve scan-stream reliability and ref support
+
 ## 0.2.1
 
 ### Patch Changes

package/api/scan-stream.ts

@@ -1,6 +1,14 @@
 import { Writable } from 'node:stream';
 import type { VercelRequest, VercelResponse } from '@vercel/node';
 import { Sandbox } from '@vercel/sandbox';
+import {
+  SandboxFileSystem,
+  detectBuildInfo,
+  detectMonorepo,
+  detectPackageManager,
+  getInstallCommand,
+  getPrimaryBuildScript,
+} from '@doccov/sdk';
 
 export const config = {
   runtime: 'nodejs',
@@ -13,6 +21,7 @@ interface JobEvent {
   message?: string;
   progress?: number;
   result?: ScanResult;
+  availablePackages?: string[];
 }
 
 interface ScanResult {
@@ -120,6 +129,42 @@ async function runScanWithProgress(
     });
 
     try {
+      // Create filesystem abstraction for SDK detection functions
+      const fs = new SandboxFileSystem(sandbox);
+
+      // Checkout specific ref if not main/master
+      if (options.ref && options.ref !== 'main' && options.ref !== 'master') {
+        sendEvent({
+          type: 'progress',
+          stage: 'cloning',
+          message: `Checking out ${options.ref}...`,
+          progress: 7,
+        });
+
+        const checkoutCapture = createCaptureStream();
+        const checkoutResult = await sandbox.runCommand({
+          cmd: 'git',
+          args: ['checkout', options.ref],
+          stdout: checkoutCapture.stream,
+          stderr: checkoutCapture.stream,
+        });
+
+        if (checkoutResult.exitCode !== 0) {
+          // Try fetching the ref first (might be a tag not fetched by shallow clone)
+          await sandbox.runCommand({
+            cmd: 'git',
+            args: ['fetch', '--depth', '1', 'origin', `refs/tags/${options.ref}:refs/tags/${options.ref}`],
+          });
+          const retryResult = await sandbox.runCommand({
+            cmd: 'git',
+            args: ['checkout', options.ref],
+          });
+          if (retryResult.exitCode !== 0) {
+            throw new Error(`Failed to checkout ${options.ref}: ${checkoutCapture.getOutput()}`);
+          }
+        }
+      }
+
       sendEvent({
         type: 'progress',
         stage: 'detecting',
@@ -127,57 +172,57 @@ async function runScanWithProgress(
         progress: 10,
       });
 
-      // Detect package manager
-      const lsCapture = createCaptureStream();
-      await sandbox.runCommand({
-        cmd: 'ls',
-        args: ['-1'],
-        stdout: lsCapture.stream,
-      });
-      const files = lsCapture.getOutput();
-
-      let installCmd: string;
-      let installArgs: string[];
-      let pm: 'pnpm' | 'bun' | 'npm' = 'npm';
-      let pmMessage = 'Detected npm project';
-
-      if (files.includes('pnpm-lock.yaml')) {
-        pm = 'pnpm';
-        installCmd = 'pnpm';
-        installArgs = ['install', '--frozen-lockfile'];
-        pmMessage = 'Detected pnpm monorepo';
-      } else if (files.includes('bun.lock') || files.includes('bun.lockb')) {
-        pm = 'bun';
-        installCmd = 'bun';
-        installArgs = ['install', '--frozen-lockfile'];
-        pmMessage = 'Detected bun project';
-      } else {
-        installCmd = 'npm';
-        installArgs = ['install', '--ignore-scripts', '--legacy-peer-deps'];
-      }
-
+      // Detect package manager using SDK
+      const pmInfo = await detectPackageManager(fs);
+      const pmMessage = pmInfo.lockfile ? `Detected ${pmInfo.name} project` : 'No lockfile detected';
       sendEvent({ type: 'progress', stage: 'detecting', message: pmMessage, progress: 15 });
 
-      // Install package manager if needed
-      if (pm === 'pnpm') {
+      // Early monorepo detection - fail fast if monorepo without package param
+      if (!options.package) {
+        const mono = await detectMonorepo(fs);
+
+        if (mono.isMonorepo) {
+          sendEvent({
+            type: 'progress',
+            stage: 'detecting',
+            message: 'Monorepo detected, listing packages...',
+            progress: 17,
+          });
+
+          const availablePackages = mono.packages
+            .filter((p) => !p.private)
+            .map((p) => p.name);
+
+          await sandbox.stop();
+          sendEvent({
+            type: 'error',
+            message: `Monorepo detected. Please specify a package to analyze using the 'package' query parameter.`,
+            availablePackages,
+          });
+          return;
+        }
+      }
+
+      // Install package manager if needed (npm and pnpm are pre-installed in node22)
+      if (pmInfo.name === 'bun') {
         sendEvent({
           type: 'progress',
           stage: 'installing',
-          message: 'Installing pnpm...',
+          message: 'Installing bun...',
           progress: 18,
         });
-        await sandbox.runCommand({ cmd: 'npm', args: ['install', '-g', 'pnpm'] });
-      } else if (pm === 'bun') {
+        await sandbox.runCommand({ cmd: 'npm', args: ['install', '-g', 'bun'] });
+      } else if (pmInfo.name === 'yarn') {
         sendEvent({
           type: 'progress',
           stage: 'installing',
-          message: 'Installing bun...',
+          message: 'Installing yarn...',
           progress: 18,
         });
-        await sandbox.runCommand({ cmd: 'npm', args: ['install', '-g', 'bun'] });
+        await sandbox.runCommand({ cmd: 'npm', args: ['install', '-g', 'yarn'] });
       }
 
-      // Install dependencies
+      // Install dependencies with fallback chain
       sendEvent({
         type: 'progress',
         stage: 'installing',
@@ -185,60 +230,99 @@ async function runScanWithProgress(
         progress: 20,
       });
 
+      let installed = false;
+      let activePm = pmInfo.name;
       const installCapture = createCaptureStream();
-      const install = await sandbox.runCommand({
-        cmd: installCmd,
-        args: installArgs,
+
+      // Try primary package manager using SDK's getInstallCommand
+      const primaryCmd = getInstallCommand(pmInfo);
+      const primaryResult = await sandbox.runCommand({
+        cmd: primaryCmd[0],
+        args: primaryCmd.slice(1),
         stdout: installCapture.stream,
         stderr: installCapture.stream,
       });
 
-      if (install.exitCode !== 0) {
-        throw new Error(`${installCmd} install failed: ${installCapture.getOutput().slice(-300)}`);
-      }
-
-      sendEvent({
-        type: 'progress',
-        stage: 'installing',
-        message: 'Dependencies installed',
-        progress: 40,
-      });
-
-      // Check for build script
-      const pkgCapture = createCaptureStream();
-      await sandbox.runCommand({
-        cmd: 'cat',
-        args: ['package.json'],
-        stdout: pkgCapture.stream,
-      });
-
-      try {
-        const pkgJson = JSON.parse(pkgCapture.getOutput()) as { scripts?: Record<string, string> };
-        const scripts = pkgJson.scripts ?? {};
-        const buildScript = scripts.build ? 'build' : scripts.compile ? 'compile' : null;
+      if (primaryResult.exitCode === 0) {
+        installed = true;
+      } else {
+        const errorOutput = installCapture.getOutput();
 
-        if (buildScript) {
+        // Check if it's a workspace:* protocol error - try bun fallback
+        if (errorOutput.includes('workspace:') || errorOutput.includes('EUNSUPPORTEDPROTOCOL')) {
           sendEvent({
             type: 'progress',
-            stage: 'building',
-            message: 'Running build...',
-            progress: 45,
+            stage: 'installing',
+            message: 'Trying bun fallback for workspace protocol...',
+            progress: 25,
           });
 
-          const buildCapture = createCaptureStream();
-          const buildResult = await sandbox.runCommand({
-            cmd: pm === 'npm' ? 'npm' : pm,
-            args: pm === 'npm' ? ['run', buildScript] : [buildScript],
-            stdout: buildCapture.stream,
-            stderr: buildCapture.stream,
+          // Install bun if not already the primary
+          if (pmInfo.name !== 'bun') {
+            await sandbox.runCommand({ cmd: 'npm', args: ['install', '-g', 'bun'] });
+          }
+
+          const bunCapture = createCaptureStream();
+          const bunResult = await sandbox.runCommand({
+            cmd: 'bun',
+            args: ['install'],
+            stdout: bunCapture.stream,
+            stderr: bunCapture.stream,
           });
 
-          const buildMessage =
-            buildResult.exitCode === 0 ? 'Build complete' : 'Build failed (continuing)';
-          sendEvent({ type: 'progress', stage: 'building', message: buildMessage, progress: 55 });
+          if (bunResult.exitCode === 0) {
+            installed = true;
+            activePm = 'bun'; // Update pm for build step
+          }
         }
-      } catch {
-        // Ignore package.json errors
+      }
+
+      if (installed) {
+        sendEvent({
+          type: 'progress',
+          stage: 'installing',
+          message: 'Dependencies installed',
+          progress: 40,
+        });
+      } else {
+        // Graceful degradation - continue with limited analysis
+        sendEvent({
+          type: 'progress',
+          stage: 'installing',
+          message: 'Install failed (continuing with limited analysis)',
+          progress: 40,
+        });
+      }
+
+      // Check for build script using SDK
+      const buildInfo = await detectBuildInfo(fs);
+      const buildScript = getPrimaryBuildScript(buildInfo);
+
+      if (buildScript) {
+        sendEvent({
+          type: 'progress',
+          stage: 'building',
+          message: 'Running build...',
+          progress: 45,
+        });
+
+        const buildCapture = createCaptureStream();
+        // Use activePm (may have changed to bun as fallback)
+        const buildCmd =
+          activePm === 'npm' || activePm === 'yarn'
+            ? [activePm, 'run', buildScript]
+            : [activePm, buildScript];
+
+        const buildResult = await sandbox.runCommand({
+          cmd: buildCmd[0],
+          args: buildCmd.slice(1),
+          stdout: buildCapture.stream,
+          stderr: buildCapture.stream,
+        });
+
+        const buildMessage =
+          buildResult.exitCode === 0 ? 'Build complete' : 'Build failed (continuing)';
+        sendEvent({ type: 'progress', stage: 'building', message: buildMessage, progress: 55 });
       }
 
       // Install doccov CLI
@@ -290,30 +374,54 @@ async function runScanWithProgress(
         progress: 85,
       });
 
-      // Extract summary
+      // Check if spec file was created
+      const checkFileCapture = createCaptureStream();
+      await sandbox.runCommand({
+        cmd: 'cat',
+        args: [specFile],
+        stdout: checkFileCapture.stream,
+        stderr: checkFileCapture.stream,
+      });
+      const specContent = checkFileCapture.getOutput();
+
+      if (!specContent.trim() || specContent.includes('No such file')) {
+        throw new Error(`Spec file not found or empty. Generate output: ${genOutput.slice(-500)}`);
+      }
+
+      // Extract summary with error handling
       const extractScript = `
         const fs = require('fs');
-        const spec = JSON.parse(fs.readFileSync('${specFile}', 'utf-8'));
-        const undocumented = [];
-        const drift = [];
-        for (const exp of spec.exports || []) {
-          const docs = exp.docs;
-          if (!docs) continue;
-          if ((docs.missing?.length || 0) > 0 || (docs.coverageScore || 0) < 100) {
-            undocumented.push(exp.name);
+        try {
+          if (!fs.existsSync('${specFile}')) {
+            console.error('Spec file not found: ${specFile}');
+            process.exit(1);
           }
-          for (const d of docs.drift || []) {
-            drift.push({ export: exp.name, type: d.type, issue: d.issue });
+          const content = fs.readFileSync('${specFile}', 'utf-8');
+          const spec = JSON.parse(content);
+          const undocumented = [];
+          const drift = [];
+          for (const exp of spec.exports || []) {
+            const docs = exp.docs;
+            if (!docs) continue;
+            if ((docs.missing?.length || 0) > 0 || (docs.coverageScore || 0) < 100) {
+              undocumented.push(exp.name);
+            }
+            for (const d of docs.drift || []) {
+              drift.push({ export: exp.name, type: d.type, issue: d.issue });
+            }
           }
+          console.log(JSON.stringify({
+            coverage: spec.docs?.coverageScore || 0,
+            exportCount: spec.exports?.length || 0,
+            typeCount: spec.types?.length || 0,
+            undocumented: undocumented.slice(0, 50),
+            drift: drift.slice(0, 20),
+            driftCount: drift.length,
+          }));
+        } catch (e) {
+          console.error('Extract error:', e.message);
+          process.exit(1);
         }
-        console.log(JSON.stringify({
-          coverage: spec.docs?.coverageScore || 0,
-          exportCount: spec.exports?.length || 0,
-          typeCount: spec.types?.length || 0,
-          undocumented: undocumented.slice(0, 50),
-          drift: drift.slice(0, 20),
-          driftCount: drift.length,
-        }));
       `.replace(/\n/g, ' ');
 
       const nodeCapture = createCaptureStream();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/api",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",