vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/runReport.js

@@ -0,0 +1,726 @@
+/**
+ * vibecheck report - World-Class Enterprise Reports
+ * 
+ * TIER ENFORCEMENT:
+ * - FREE: HTML, MD formats only
+ * - STARTER: + SARIF, CSV formats
+ * - PRO: + compliance packs, PDF export, redaction templates
+ * 
+ * Enterprise-grade report generation with:
+ * - Beautiful interactive HTML with modern design
+ * - Multiple export formats (HTML, MD, JSON, SARIF, CSV, PDF)
+ * - Executive, Technical, Compliance report types
+ * - Historical trends and fix time estimates
+ * - Print-optimized layouts
+ * - White-label customization
+ */
+
+const path = require("path");
+const fs = require("fs");
+const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
+const { EXIT } = require("./lib/exit-codes");
+const { ensureScanResults } = require("./lib/prerequisites");
+
+// Entitlements enforcement
+let entitlements;
+try {
+  entitlements = require("./lib/entitlements-v2");
+} catch {
+  // Fallback: allow all features if entitlements not available
+  entitlements = {
+    getLimits: () => ({ reportFormats: ["html", "md", "json", "sarif", "csv", "pdf"] }),
+    getTier: async () => "pro",
+    enforce: async () => ({ allowed: true }),
+    EXIT_FEATURE_NOT_ALLOWED: 1,
+  };
+}
+
+// Report modules
+let reportEngine, reportHtml, reportTemplates;
+try {
+  reportEngine = require("./lib/report-engine");
+} catch (e) {
+  console.error("Warning: report-engine not found:", e.message);
+}
+try {
+  reportHtml = require("./lib/report-html");
+} catch (e) {
+  console.error("Warning: report-html not found:", e.message);
+}
+try {
+  reportTemplates = require("./lib/report-templates");
+} catch (e) {
+  console.error("Warning: report-templates not found:", e.message);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENHANCED TERMINAL UI & OUTPUT MODULES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const {
+  ansi,
+  colors,
+  icons,
+  Spinner,
+  renderSection,
+  formatDuration,
+} = require("./lib/terminal-ui");
+
+const {
+  BANNER,
+  formatHelp,
+  renderReportInfo,
+  renderSuccess,
+  renderError,
+} = require("./lib/report-output");
+
+function parseArgs(args) {
+  // Parse global flags first
+  const { flags: globalFlags, cleanArgs } = parseGlobalFlags(args);
+  
+  const opts = {
+    type: "technical",
+    format: "html",
+    path: globalFlags.path || ".",
+    output: globalFlags.output || null,
+    logo: null,
+    company: null,
+    theme: "dark",
+    framework: "SOC2",
+    includeVerify: false,
+    includeTrends: false,
+    redactPaths: false,
+    maxFindings: 50,
+    open: false,
+    help: globalFlags.help || false,
+    quiet: globalFlags.quiet || false,
+    json: globalFlags.json || false,
+    noBanner: globalFlags.noBanner || false,
+    ci: globalFlags.ci || false,
+    verbose: globalFlags.verbose || false,
+  };
+
+  // Parse command-specific args
+  for (let i = 0; i < cleanArgs.length; i++) {
+    const a = cleanArgs[i];
+    if (a === "--type" || a === "-t") opts.type = cleanArgs[++i];
+    if (a === "--format" || a === "-f") opts.format = cleanArgs[++i];
+    if (a === "--output" || a === "-o") opts.output = cleanArgs[++i];
+    if (a === "--logo") opts.logo = cleanArgs[++i];
+    if (a === "--company") opts.company = cleanArgs[++i];
+    if (a === "--theme") opts.theme = cleanArgs[++i];
+    if (a === "--framework") opts.framework = args[++i];
+    if (a === "--light") opts.theme = "light";
+    if (a === "--dark") opts.theme = "dark";
+    if (a === "--include-verify") opts.includeVerify = true;
+    if (a === "--include-trends" || a === "--trends") opts.includeTrends = true;
+    if (a === "--redact-paths" || a === "--redact") opts.redactPaths = true;
+    if (a === "--max-findings") opts.maxFindings = parseInt(args[++i]) || 50;
+    if (a.startsWith("--path=")) opts.path = a.split("=")[1];
+    if (a === "--path" || a === "-p") opts.path = args[++i];
+    if (a === "--open") opts.open = true;
+    if (a === "--quiet" || a === "-q") opts.quiet = true;
+    if (a === "--help" || a === "-h") opts.help = true;
+  }
+
+  return opts;
+}
+
+function printHelp(showBanner = true) {
+  if (showBanner && shouldShowBanner({})) {
+    console.log(BANNER);
+  }
+  console.log(formatHelp());
+}
+
+async function runReport(args) {
+  const opts = parseArgs(args);
+
+  if (opts.help) {
+    printHelp(shouldShowBanner(opts));
+    return 0;
+  }
+
+  const projectPath = path.resolve(opts.path);
+  const outputDir = path.join(projectPath, ".vibecheck");
+  const projectName = path.basename(projectPath);
+
+  // TIER ENFORCEMENT
+  const format = opts.format.toLowerCase();
+  const tier = await entitlements.getTier({ projectPath });
+  const limits = entitlements.getLimits(tier);
+  const allowedFormats = limits.reportFormats || ["html", "md"];
+
+  // Check format access
+  if (!allowedFormats.includes(format) && format !== "json") {
+    if (format === "sarif" || format === "csv") {
+      const access = await entitlements.enforce("report.sarif_csv", {
+        projectPath,
+        silent: false,
+      });
+      if (!access.allowed) {
+        console.log(`\n  ${colors.warning}${icons.warning}${ansi.reset} ${ansi.dim}HTML and MD formats are available on FREE tier${ansi.reset}`);
+        console.log(`  ${ansi.dim}Upgrade to STARTER for SARIF/CSV export${ansi.reset}\n`);
+        return entitlements.EXIT_FEATURE_NOT_ALLOWED;
+      }
+    }
+    
+    if (format === "pdf") {
+      const access = await entitlements.enforce("report.pdf_export", {
+        projectPath,
+        silent: false,
+      });
+      if (!access.allowed) {
+        console.log(`\n  ${colors.warning}${icons.warning}${ansi.reset} ${ansi.dim}PDF export requires PRO tier${ansi.reset}`);
+        console.log(`  ${ansi.dim}HTML reports can be printed to PDF from browser${ansi.reset}\n`);
+        return entitlements.EXIT_FEATURE_NOT_ALLOWED;
+      }
+    }
+  }
+
+  // Compliance reports require PRO
+  if (opts.type === "compliance") {
+    const access = await entitlements.enforce("report.compliance_packs", {
+      projectPath,
+      silent: false,
+    });
+    if (!access.allowed) {
+      console.log(`\n  ${colors.warning}${icons.warning}${ansi.reset} ${ansi.dim}Executive and technical reports available on lower tiers${ansi.reset}`);
+      return entitlements.EXIT_FEATURE_NOT_ALLOWED;
+    }
+  }
+
+  // Display banner and report info
+  if (!opts.quiet) {
+    if (shouldShowBanner(opts)) {
+      console.log(BANNER);
+      console.log(renderReportInfo(opts.type, opts.format, null));
+      console.log('');
+    }
+  }
+
+  // Progress spinner
+  const spinner = new Spinner({ color: colors.accent });
+  spinner.start(`Generating ${opts.type} report`);
+
+  // Auto-run scan if results are missing (unless in CI or explicitly disabled)
+  const scanPrereq = await ensureScanResults(projectPath, {
+    quiet: opts.quiet,
+    json: opts.json,
+    ci: opts.ci,
+    colors,
+    icons,
+    ansi,
+  });
+  
+  if (scanPrereq.ran && !scanPrereq.success && !opts.quiet) {
+    spinner.warn("Auto-run scan failed - continuing with available data");
+  }
+
+  // Load ship results (prefer ship results, fall back to scan results)
+  let shipResults = loadShipResults(projectPath, outputDir);
+  
+  // If no ship results, try to load scan results
+  if (!shipResults) {
+    const scanResultsPath = path.join(projectPath, ".vibecheck", "results", "latest.json");
+    if (fs.existsSync(scanResultsPath)) {
+      try {
+        const scanData = JSON.parse(fs.readFileSync(scanResultsPath, "utf8"));
+        shipResults = {
+          score: scanData.result?.score || scanData.score || 0,
+          verdict: scanData.result?.verdict || scanData.verdict || "UNKNOWN",
+          findings: scanData.result?.findings || scanData.findings || [],
+          truthpack: scanData.truthpack || null,
+        };
+      } catch {}
+    }
+  }
+
+  if (!shipResults) {
+    spinner.warn("No scan results found - using demo data");
+    if (!opts.quiet) {
+      console.log(`  ${ansi.dim}Tip: Run 'vibecheck scan' first for real results.${ansi.reset}\n`);
+    }
+    shipResults = getDemoData();
+  }
+
+  // Build comprehensive report data
+  spinner.update("Processing findings");
+  let reportData;
+  if (reportEngine) {
+    reportData = reportEngine.buildReportData(shipResults, {
+      projectName,
+      repoRoot: projectPath,
+      includeTrends: opts.includeTrends,
+    });
+  } else {
+    reportData = buildBasicReportData(shipResults, projectName);
+  }
+
+  // Generate report content
+  spinner.update(`Rendering ${format.toUpperCase()} output`);
+  let reportContent = "";
+  let fileExtension = format;
+
+  try {
+    switch (format) {
+      case "html":
+        // Debug: Log which HTML generator will be used
+        if (opts.verbose || opts.type === "technical") {
+          if (reportHtml && typeof reportHtml.generateWorldClassHTML === 'function') {
+            console.log(`  ${ansi.dim}Using world-class HTML generator${ansi.reset}`);
+          } else {
+            console.log(`  ${ansi.dim}Using basic HTML generator (report-html module not available)${ansi.reset}`);
+          }
+        }
+        reportContent = generateHTMLReport(reportData, opts);
+        break;
+      case "md":
+      case "markdown":
+        reportContent = generateMarkdownReport(reportData, opts);
+        fileExtension = "md";
+        break;
+      case "json":
+        reportContent = generateJSONReport(reportData, opts);
+        break;
+      case "sarif":
+        reportContent = generateSARIFReport(reportData, opts);
+        break;
+      case "csv":
+        reportContent = generateCSVReport(reportData, opts);
+        break;
+      case "pdf":
+        // PDF requires HTML first, then conversion
+        reportContent = await generatePDFReport(reportData, opts, outputDir);
+        break;
+      default:
+        spinner.fail(`Unknown format: ${format}`);
+        console.log(`  ${ansi.dim}Supported: html, md, json, sarif, csv, pdf${ansi.reset}`);
+        return EXIT.USER_ERROR;
+    }
+  } catch (err) {
+    spinner.fail(`Failed to generate report: ${err.message}`);
+    return EXIT.INTERNAL_ERROR;
+  }
+
+  // Determine output path
+  const outputFileName = opts.output || path.join(outputDir, `report.${fileExtension}`);
+  const outputDirPath = path.dirname(outputFileName);
+
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDirPath)) {
+    fs.mkdirSync(outputDirPath, { recursive: true });
+  }
+
+  // Write report (always overwrite to ensure fresh content)
+  spinner.update("Writing report");
+  fs.writeFileSync(outputFileName, reportContent, 'utf8');
+  
+  // If this is the default report.html, also update the timestamp to help with cache busting
+  if (!opts.output && fileExtension === 'html') {
+    try {
+      // Touch the file to update its modification time
+      const now = new Date();
+      fs.utimesSync(outputFileName, now, now);
+    } catch {
+      // Ignore errors on utimes
+    }
+  }
+
+  // Save report history for trend analysis
+  saveReportHistory(outputDir, reportData);
+
+  spinner.succeed("Report generated");
+  console.log("");
+  
+  // Print success message using design system
+  console.log(renderSuccess(outputFileName, opts.format));
+
+  // Open in browser if requested
+  if (opts.open && format === "html") {
+    openInBrowser(outputFileName);
+  }
+
+  return 0;
+}
+
+// ============================================================================
+// DATA LOADING
+// ============================================================================
+
+function loadShipResults(projectPath, outputDir) {
+  const sources = [
+    path.join(outputDir, "ship_report.json"),
+    path.join(outputDir, "report.json"),
+    path.join(outputDir, "truth", "truthpack.json"),
+  ];
+
+  let results = null;
+  for (const src of sources) {
+    if (fs.existsSync(src)) {
+      try {
+        results = JSON.parse(fs.readFileSync(src, "utf8"));
+        break;
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  // Also load reality report if available
+  const realitySources = [
+    path.join(outputDir, "reality", "last_reality.json"),
+    path.join(outputDir, "reality_report.json"),
+  ];
+
+  for (const src of realitySources) {
+    if (fs.existsSync(src)) {
+      try {
+        const realityData = JSON.parse(fs.readFileSync(src, "utf8"));
+        if (results) {
+          results.reality = realityData;
+        } else {
+          results = { reality: realityData };
+        }
+        break;
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  return results;
+}
+
+function getDemoData() {
+  return {
+    score: 72,
+    verdict: "WARN",
+    findings: [
+      { id: "SEC001", severity: "BLOCK", type: "secret", message: "API key exposed in source code", title: "Exposed API Key", file: "src/config.ts", line: 42, fix: "Move to environment variable" },
+      { id: "AUTH001", severity: "BLOCK", type: "auth", message: "Authentication bypass in admin route", title: "Auth Bypass Vulnerability", file: "src/routes/admin.ts", line: 15, fix: "Add auth middleware" },
+      { id: "MOCK001", severity: "WARN", type: "mock", message: "Mock data used in production path", title: "Mock Data in Production", file: "src/api/users.ts", line: 88, fix: "Remove mock data fallback" },
+      { id: "ERR001", severity: "WARN", type: "error", message: "Empty catch block in payment flow", title: "Swallowed Exception", file: "src/billing/checkout.ts", line: 156, fix: "Add error handling" },
+      { id: "CFG001", severity: "INFO", type: "config", message: "Hardcoded timeout value", title: "Hardcoded Configuration", file: "src/utils/http.ts", line: 23, fix: "Move to config" },
+      { id: "DBG001", severity: "INFO", type: "quality", message: "Console.log statement", title: "Debug Statement", file: "src/debug.ts", line: 5, fix: "Remove or use logger" },
+    ],
+    categoryScores: { security: 65, auth: 50, billing: 90, quality: 75 },
+    truthpack: {
+      routes: { server: Array(12).fill({}) },
+      env: { vars: Array(8).fill("") },
+    },
+    reality: {
+      coverage: { clientCallsMapped: 87, uiActionsVerified: 95, authRoutes: 100 },
+      latencyP95: 412,
+      brokenFlows: [
+        {
+          title: "User cannot complete checkout flow",
+          severity: "BLOCK",
+          steps: [
+            { type: "ui", label: "Click 'Add to Cart'" },
+            { type: "api", label: "POST /api/cart" },
+            { type: "ui", label: "Click 'Checkout'" },
+            { type: "api", label: "POST /api/orders" },
+            { type: "error", label: "500 Internal Server Error" },
+          ],
+        },
+      ],
+    },
+  };
+}
+
+function buildBasicReportData(shipResults, projectName) {
+  const findings = shipResults?.findings || [];
+  const reality = shipResults?.reality || null;
+
+  return {
+    meta: {
+      projectName,
+      generatedAt: new Date().toISOString(),
+      version: "2.0.0",
+      reportId: `VC-${Date.now().toString(36).toUpperCase()}`,
+    },
+    summary: {
+      score: shipResults?.score || 0,
+      verdict: shipResults?.verdict || (shipResults?.canShip ? "SHIP" : "WARN"),
+      totalFindings: findings.length,
+      severityCounts: {
+        critical: findings.filter(f => f.severity === "BLOCK" || f.severity === "critical").length,
+        high: findings.filter(f => f.severity === "high").length,
+        medium: findings.filter(f => f.severity === "WARN" || f.severity === "medium").length,
+        low: findings.filter(f => f.severity === "low" || f.severity === "INFO").length,
+      },
+      categoryScores: shipResults?.categoryScores || {},
+    },
+    findings: findings.map((f, i) => ({ ...f, id: f.id || `F${String(i + 1).padStart(3, "0")}` })),
+    fixEstimates: { humanReadable: calculateFixTime(findings), totalMinutes: 120 },
+    truthpack: shipResults?.truthpack || null,
+    reality: reality,
+  };
+}
+
+// ============================================================================
+// REPORT GENERATORS
+// ============================================================================
+
+function generateHTMLReport(reportData, opts) {
+  // Route to appropriate template based on type
+  switch (opts.type) {
+    case "executive":
+      if (reportTemplates?.generateEnhancedExecutiveReport) {
+        return reportTemplates.generateEnhancedExecutiveReport(
+          convertToLegacyFormat(reportData),
+          opts
+        );
+      }
+      // Fall through if template not available
+      break;
+    case "compliance":
+      if (reportTemplates?.generateEnhancedComplianceReport) {
+        return reportTemplates.generateEnhancedComplianceReport(
+          convertToLegacyFormat(reportData),
+          opts
+        );
+      }
+      // Fall through if template not available
+      break;
+    default:
+      // Technical report - ALWAYS use world-class HTML generator
+      if (reportHtml && typeof reportHtml.generateWorldClassHTML === 'function') {
+        try {
+          // Ensure reportData has required structure
+          if (!reportData.meta) {
+            reportData.meta = { projectName: 'Unknown', generatedAt: new Date().toISOString(), version: '2.0.0' };
+          }
+          if (!reportData.summary) {
+            reportData.summary = { score: 0, verdict: 'WARN', totalFindings: 0, severityCounts: {} };
+          }
+          if (!reportData.findings) {
+            reportData.findings = [];
+          }
+          
+          return reportHtml.generateWorldClassHTML(reportData, opts);
+        } catch (err) {
+          console.error(`\n  ${colors.error}${icons.error}${ansi.reset} Error generating world-class HTML: ${err.message}`);
+          if (opts.verbose) {
+            console.error(err.stack);
+          }
+          // Fall through to basic HTML only on error
+        }
+      } else {
+        console.warn(`\n  ${colors.warning}${icons.warning}${ansi.reset} report-html module not available, using basic HTML template`);
+      }
+      break;
+  }
+
+  // Fallback to basic HTML only if world-class generator failed or not available
+  console.warn(`  ${ansi.dim}Using basic HTML fallback${ansi.reset}`);
+  return generateBasicHTML(reportData, opts);
+}
+
+function generateMarkdownReport(reportData, opts) {
+  if (reportEngine?.exportToMarkdown) {
+    return reportEngine.exportToMarkdown(reportData, opts);
+  }
+  return generateBasicMarkdown(reportData, opts);
+}
+
+function generateJSONReport(reportData, opts) {
+  if (reportEngine?.exportToJSON) {
+    return reportEngine.exportToJSON(reportData);
+  }
+  return JSON.stringify(reportData, null, 2);
+}
+
+function generateSARIFReport(reportData, opts) {
+  if (reportEngine?.exportToSARIF) {
+    return JSON.stringify(reportEngine.exportToSARIF(reportData), null, 2);
+  }
+  // Basic SARIF fallback
+  return JSON.stringify({
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [{
+      tool: { driver: { name: "vibecheck", version: "2.0.0" } },
+      results: reportData.findings.map(f => ({
+        ruleId: f.id,
+        level: f.severity === "critical" ? "error" : "warning",
+        message: { text: f.title || f.message },
+      })),
+    }],
+  }, null, 2);
+}
+
+function generateCSVReport(reportData, opts) {
+  if (reportEngine?.exportToCSV) {
+    return reportEngine.exportToCSV(reportData);
+  }
+  // Basic CSV fallback
+  const headers = ["ID", "Severity", "Title", "File", "Line", "Fix"];
+  const rows = reportData.findings.map(f => [
+    f.id || "",
+    f.severity || "",
+    `"${(f.title || f.message || "").replace(/"/g, '""')}"`,
+    f.file || "",
+    f.line || "",
+    `"${(f.fix || "").replace(/"/g, '""')}"`,
+  ]);
+  return [headers.join(","), ...rows.map(r => r.join(","))].join("\n");
+}
+
+async function generatePDFReport(reportData, opts, outputDir) {
+  // Generate HTML first
+  const htmlContent = generateHTMLReport(reportData, { ...opts, format: "html" });
+  const tempHtmlPath = path.join(outputDir, "temp_report.html");
+  fs.writeFileSync(tempHtmlPath, htmlContent);
+
+  // Try to use puppeteer for PDF generation
+  try {
+    const puppeteer = require("puppeteer");
+    const browser = await puppeteer.launch({ headless: "new" });
+    const page = await browser.newPage();
+    await page.setContent(htmlContent, { waitUntil: "networkidle0" });
+    const pdf = await page.pdf({
+      format: "Letter",
+      printBackground: true,
+      margin: { top: "0.5in", right: "0.5in", bottom: "0.5in", left: "0.5in" },
+    });
+    await browser.close();
+    
+    // Clean up temp file
+    try { fs.unlinkSync(tempHtmlPath); } catch {}
+    
+    return pdf;
+  } catch (e) {
+    // Clean up temp file
+    try { fs.unlinkSync(tempHtmlPath); } catch {}
+    
+    throw new Error(
+      `PDF generation requires puppeteer. Install with: npm install puppeteer\n` +
+      `Or use --format=html and print to PDF from your browser.`
+    );
+  }
+}
+
+function convertToLegacyFormat(reportData) {
+  return {
+    projectName: reportData.meta.projectName,
+    generatedAt: reportData.meta.generatedAt,
+    reportId: reportData.meta.reportId,
+    score: reportData.summary.score,
+    verdict: reportData.summary.verdict,
+    findings: reportData.findings,
+    categoryScores: reportData.summary.categoryScores,
+    reality: reportData.reality,
+  };
+}
+
+// ============================================================================
+// FALLBACK GENERATORS
+// ============================================================================
+
+function generateBasicHTML(reportData, opts) {
+  const { meta, summary } = reportData;
+  const verdictColor = summary.verdict === "SHIP" ? "#10b981" : summary.verdict === "WARN" ? "#f59e0b" : "#ef4444";
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>VibeCheck Report - ${meta.projectName}</title>
+  <style>
+    body { font-family: -apple-system, sans-serif; max-width: 800px; margin: 0 auto; padding: 40px; background: #0f172a; color: #f8fafc; }
+    .header { border-bottom: 2px solid #334155; padding-bottom: 20px; margin-bottom: 30px; }
+    .score { font-size: 4rem; font-weight: 800; text-align: center; margin: 40px 0; color: ${verdictColor}; }
+    .verdict { display: inline-block; padding: 12px 24px; border-radius: 50px; font-weight: 600; background: ${verdictColor}22; color: ${verdictColor}; }
+    .section { margin: 30px 0; }
+    h2 { color: #94a3b8; font-size: 0.875rem; text-transform: uppercase; letter-spacing: 0.1em; }
+    .finding { background: #1e293b; padding: 16px; border-radius: 8px; margin: 12px 0; border-left: 4px solid #3b82f6; }
+    .footer { margin-top: 60px; text-align: center; color: #64748b; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>Ship Readiness Report</h1>
+    <p>Project: ${meta.projectName} · ${new Date(meta.generatedAt).toLocaleString()}</p>
+  </div>
+  <div class="score">${summary.score}</div>
+  <div style="text-align: center;"><span class="verdict">${summary.verdict}</span></div>
+  <div class="section">
+    <h2>Findings (${summary.totalFindings})</h2>
+    ${reportData.findings.slice(0, 10).map(f => `
+      <div class="finding">
+        <strong>${(f.severity || 'WARN').toUpperCase()}</strong>: ${f.title || f.message}
+        ${f.file ? `<br><code>${f.file}${f.line ? `:${f.line}` : ""}</code>` : ""}
+      </div>
+    `).join("")}
+  </div>
+  <div class="footer">Generated by VibeCheck · ${meta.reportId}</div>
+</body>
+</html>`;
+}
+
+function generateBasicMarkdown(reportData, opts) {
+  const { meta, summary, findings } = reportData;
+  return `# VibeCheck Report
+
+**Project:** ${meta.projectName}  
+**Generated:** ${new Date(meta.generatedAt).toLocaleString()}  
+**Score:** ${summary.score}/100  
+**Verdict:** ${summary.verdict}
+
+## Findings (${summary.totalFindings})
+
+${findings.slice(0, 20).map(f => `- **${(f.severity || 'WARN').toUpperCase()}**: ${f.title || f.message}${f.file ? ` (\`${f.file}\`)` : ""}`).join("\n")}
+
+---
+*Generated by VibeCheck · ${meta.reportId}*
+`;
+}
+
+// ============================================================================
+// UTILITIES
+// ============================================================================
+
+function calculateFixTime(findings) {
+  if (!findings || findings.length === 0) return "0h";
+
+  const minutes = findings.reduce((total, f) => {
+    const sev = (f.severity || "").toLowerCase();
+    const time = { block: 60, critical: 60, high: 45, warn: 20, medium: 20, info: 10, low: 10 };
+    return total + (time[sev] || 15);
+  }, 0);
+
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60 * 10) / 10;
+  return hours > 8 ? `${Math.ceil(hours / 8)}d` : `${hours}h`;
+}
+
+function saveReportHistory(outputDir, reportData) {
+  try {
+    const historyDir = path.join(outputDir, "history");
+    if (!fs.existsSync(historyDir)) {
+      fs.mkdirSync(historyDir, { recursive: true });
+    }
+
+    const timestamp = new Date().toISOString().split("T")[0];
+    const historyFile = path.join(historyDir, `${timestamp}.json`);
+
+    fs.writeFileSync(historyFile, JSON.stringify({
+      meta: reportData.meta,
+      summary: reportData.summary,
+    }, null, 2));
+  } catch {
+    // Silently fail history saving
+  }
+}
+
+function openInBrowser(filePath) {
+  const { exec } = require("child_process");
+  const cmd = process.platform === "darwin" ? "open" :
+              process.platform === "win32" ? "start" : "xdg-open";
+  exec(`${cmd} "${filePath}"`);
+}
+
+module.exports = { runReport };