@vibecheckai/cli 3.3.0 → 3.5.0

package/bin/runners/lib/reality-profiler.js

@@ -0,0 +1,717 @@
+/**
+ * Reality Profiler - World-Class Performance & Coverage Analysis
+ * 
+ * Provides:
+ * 1. Core Web Vitals tracking (LCP, FID, CLS, TTFB)
+ * 2. Coverage Map visualization
+ * 3. User Journey Analysis
+ * 4. Evidence Pack generation
+ * 5. Performance Budget checking
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CORE WEB VITALS TRACKING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const PERFORMANCE_BUDGETS = {
+  lcp: { good: 2500, needsWork: 4000 }, // Largest Contentful Paint (ms)
+  fid: { good: 100, needsWork: 300 },    // First Input Delay (ms)
+  cls: { good: 0.1, needsWork: 0.25 },   // Cumulative Layout Shift
+  ttfb: { good: 800, needsWork: 1800 },  // Time to First Byte (ms)
+  fcp: { good: 1800, needsWork: 3000 },  // First Contentful Paint (ms)
+  tti: { good: 3800, needsWork: 7300 },  // Time to Interactive (ms)
+  tbt: { good: 200, needsWork: 600 },    // Total Blocking Time (ms)
+};
+
+/**
+ * Track Core Web Vitals from a Playwright page
+ */
+async function trackWebVitals(page, url) {
+  const metrics = {
+    url,
+    timestamp: new Date().toISOString(),
+    navigationStart: Date.now(),
+    vitals: {},
+    resources: [],
+    errors: [],
+  };
+
+  try {
+    // Inject web-vitals tracking script
+    await page.addInitScript(() => {
+      window.__webVitals = {
+        lcp: null,
+        fid: null,
+        cls: 0,
+        fcp: null,
+        ttfb: null,
+      };
+
+      // Observe LCP
+      new PerformanceObserver((list) => {
+        const entries = list.getEntries();
+        window.__webVitals.lcp = entries[entries.length - 1]?.renderTime || 
+                                  entries[entries.length - 1]?.loadTime;
+      }).observe({ type: "largest-contentful-paint", buffered: true });
+
+      // Observe FID
+      new PerformanceObserver((list) => {
+        const entry = list.getEntries()[0];
+        window.__webVitals.fid = entry?.processingStart - entry?.startTime;
+      }).observe({ type: "first-input", buffered: true });
+
+      // Observe CLS
+      new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          if (!entry.hadRecentInput) {
+            window.__webVitals.cls += entry.value;
+          }
+        }
+      }).observe({ type: "layout-shift", buffered: true });
+
+      // Navigation timing
+      window.addEventListener("load", () => {
+        const timing = performance.getEntriesByType("navigation")[0];
+        if (timing) {
+          window.__webVitals.ttfb = timing.responseStart - timing.requestStart;
+          window.__webVitals.fcp = timing.domContentLoadedEventEnd - timing.startTime;
+        }
+      });
+    });
+
+    // Navigate and wait for load
+    const response = await page.goto(url, { 
+      waitUntil: "networkidle",
+      timeout: 30000,
+    });
+
+    // Wait for LCP to stabilize
+    await page.waitForTimeout(2000);
+
+    // Collect metrics
+    metrics.vitals = await page.evaluate(() => window.__webVitals);
+    metrics.statusCode = response?.status() || 0;
+    metrics.loadTime = Date.now() - metrics.navigationStart;
+
+    // Collect resource timing
+    metrics.resources = await page.evaluate(() => {
+      return performance.getEntriesByType("resource").map((r) => ({
+        name: r.name,
+        type: r.initiatorType,
+        size: r.transferSize,
+        duration: r.duration,
+      }));
+    });
+
+    // Calculate derived metrics
+    metrics.totalResourceSize = metrics.resources.reduce((sum, r) => sum + (r.size || 0), 0);
+    metrics.resourceCount = metrics.resources.length;
+
+  } catch (error) {
+    metrics.errors.push(error.message);
+  }
+
+  return metrics;
+}
+
+/**
+ * Grade a metric against budget
+ */
+function gradeMetric(value, budget) {
+  if (value === null || value === undefined) return "unknown";
+  if (value <= budget.good) return "good";
+  if (value <= budget.needsWork) return "needs-improvement";
+  return "poor";
+}
+
+/**
+ * Analyze performance metrics
+ */
+function analyzePerformance(metrics) {
+  const analysis = {
+    overall: "good",
+    grades: {},
+    issues: [],
+    recommendations: [],
+  };
+
+  // Grade each vital
+  for (const [key, budget] of Object.entries(PERFORMANCE_BUDGETS)) {
+    const value = metrics.vitals?.[key];
+    const grade = gradeMetric(value, budget);
+    analysis.grades[key] = { value, grade, budget };
+
+    if (grade === "poor") {
+      analysis.overall = "poor";
+      analysis.issues.push({
+        metric: key,
+        value,
+        threshold: budget.needsWork,
+        severity: "BLOCK",
+      });
+    } else if (grade === "needs-improvement" && analysis.overall !== "poor") {
+      analysis.overall = "needs-improvement";
+      analysis.issues.push({
+        metric: key,
+        value,
+        threshold: budget.good,
+        severity: "WARN",
+      });
+    }
+  }
+
+  // Generate recommendations
+  if (analysis.grades.lcp?.grade !== "good") {
+    analysis.recommendations.push({
+      metric: "LCP",
+      suggestion: "Optimize largest image/text block, use lazy loading, preload critical resources",
+    });
+  }
+  if (analysis.grades.cls?.grade !== "good") {
+    analysis.recommendations.push({
+      metric: "CLS",
+      suggestion: "Add explicit dimensions to images/videos, avoid inserting content above existing content",
+    });
+  }
+  if (analysis.grades.ttfb?.grade !== "good") {
+    analysis.recommendations.push({
+      metric: "TTFB",
+      suggestion: "Optimize server response time, use CDN, enable caching",
+    });
+  }
+
+  return analysis;
+}
+
+/**
+ * Render performance report
+ */
+function renderPerformanceReport(metrics, analysis) {
+  const lines = [];
+  const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    cyan: "\x1b[36m",
+  };
+
+  const gradeColor = (grade) => {
+    if (grade === "good") return c.green;
+    if (grade === "needs-improvement") return c.yellow;
+    return c.red;
+  };
+
+  const gradeIcon = (grade) => {
+    if (grade === "good") return "✓";
+    if (grade === "needs-improvement") return "◐";
+    if (grade === "poor") return "✗";
+    return "?";
+  };
+
+  lines.push("╭" + "─".repeat(68) + "╮");
+  lines.push("│" + " ".repeat(20) + `${c.bold}⚡ PERFORMANCE PROFILE${c.reset}` + " ".repeat(20) + "│");
+  lines.push("├" + "─".repeat(68) + "┤");
+
+  // Core Web Vitals
+  const vitals = [
+    { key: "lcp", name: "Largest Contentful Paint", unit: "ms" },
+    { key: "fid", name: "First Input Delay", unit: "ms" },
+    { key: "cls", name: "Cumulative Layout Shift", unit: "" },
+    { key: "ttfb", name: "Time to First Byte", unit: "ms" },
+    { key: "fcp", name: "First Contentful Paint", unit: "ms" },
+  ];
+
+  for (const vital of vitals) {
+    const data = analysis.grades[vital.key];
+    if (!data) continue;
+
+    const color = gradeColor(data.grade);
+    const icon = gradeIcon(data.grade);
+    const value = data.value !== null ? `${Math.round(data.value)}${vital.unit}` : "N/A";
+    const name = vital.name.padEnd(28);
+
+    lines.push(`│  ${color}${icon}${c.reset} ${name} ${value.padStart(10)} ${c.dim}(< ${data.budget.good}${vital.unit})${c.reset}`.padEnd(78) + "│");
+  }
+
+  lines.push("├" + "─".repeat(68) + "┤");
+
+  // Summary
+  const overallColor = gradeColor(analysis.overall);
+  const overallIcon = analysis.overall === "good" ? "🎉" : analysis.overall === "poor" ? "🔴" : "🟡";
+  lines.push(`│  ${overallIcon} Overall: ${overallColor}${c.bold}${analysis.overall.toUpperCase()}${c.reset}`.padEnd(78) + "│");
+
+  // Resources summary
+  const sizeKB = Math.round(metrics.totalResourceSize / 1024);
+  lines.push(`│  📦 Resources: ${metrics.resourceCount} files, ${sizeKB}KB transferred`.padEnd(69) + "│");
+  lines.push(`│  ⏱️  Load Time: ${metrics.loadTime}ms`.padEnd(69) + "│");
+
+  lines.push("╰" + "─".repeat(68) + "╯");
+
+  // Recommendations
+  if (analysis.recommendations.length > 0) {
+    lines.push("");
+    lines.push(`  ${c.bold}💡 Recommendations:${c.reset}`);
+    for (const rec of analysis.recommendations) {
+      lines.push(`     ${c.cyan}${rec.metric}:${c.reset} ${rec.suggestion}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// COVERAGE MAP
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate coverage map from crawled routes
+ */
+function generateCoverageMap(visitedRoutes, allRoutes, truthpack = {}) {
+  const coverage = {
+    visited: new Set(visitedRoutes),
+    expected: new Set(allRoutes),
+    fromTruthpack: new Set(truthpack.routes?.map((r) => r.path) || []),
+    covered: [],
+    missing: [],
+    unexpected: [],
+    stats: {},
+  };
+
+  // Calculate coverage
+  for (const route of coverage.expected) {
+    if (coverage.visited.has(route)) {
+      coverage.covered.push(route);
+    } else {
+      coverage.missing.push(route);
+    }
+  }
+
+  // Find unexpected routes (visited but not in expected)
+  for (const route of coverage.visited) {
+    if (!coverage.expected.has(route) && !coverage.fromTruthpack.has(route)) {
+      coverage.unexpected.push(route);
+    }
+  }
+
+  // Calculate stats
+  coverage.stats = {
+    total: coverage.expected.size,
+    covered: coverage.covered.length,
+    missing: coverage.missing.length,
+    unexpected: coverage.unexpected.length,
+    percentage: coverage.expected.size > 0
+      ? Math.round((coverage.covered.length / coverage.expected.size) * 100)
+      : 100,
+  };
+
+  return coverage;
+}
+
+/**
+ * Render ASCII coverage map
+ */
+function renderCoverageMap(coverage) {
+  const lines = [];
+  const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    cyan: "\x1b[36m",
+  };
+
+  lines.push("╭" + "─".repeat(68) + "╮");
+  lines.push("│" + " ".repeat(22) + `${c.bold}🗺️  COVERAGE MAP${c.reset}` + " ".repeat(22) + "│");
+  lines.push("├" + "─".repeat(68) + "┤");
+
+  // Coverage bar
+  const barWidth = 40;
+  const filledWidth = Math.round((coverage.stats.percentage / 100) * barWidth);
+  const bar = "█".repeat(filledWidth) + "░".repeat(barWidth - filledWidth);
+  const pctColor = coverage.stats.percentage >= 80 ? c.green : coverage.stats.percentage >= 50 ? c.yellow : c.red;
+
+  lines.push(`│  Coverage: ${pctColor}${bar}${c.reset} ${coverage.stats.percentage}%`.padEnd(78) + "│");
+  lines.push("├" + "─".repeat(68) + "┤");
+
+  // Stats
+  lines.push(`│  ${c.green}✓${c.reset} Covered:    ${coverage.stats.covered} routes`.padEnd(69) + "│");
+  lines.push(`│  ${c.red}✗${c.reset} Missing:    ${coverage.stats.missing} routes`.padEnd(69) + "│");
+  if (coverage.stats.unexpected > 0) {
+    lines.push(`│  ${c.yellow}?${c.reset} Unexpected: ${coverage.stats.unexpected} routes`.padEnd(69) + "│");
+  }
+
+  // Show some missing routes
+  if (coverage.missing.length > 0) {
+    lines.push("├" + "─".repeat(68) + "┤");
+    lines.push(`│  ${c.dim}Missing routes:${c.reset}`.padEnd(69) + "│");
+    for (const route of coverage.missing.slice(0, 5)) {
+      lines.push(`│    ${c.red}✗${c.reset} ${route}`.padEnd(69) + "│");
+    }
+    if (coverage.missing.length > 5) {
+      lines.push(`│    ${c.dim}... and ${coverage.missing.length - 5} more${c.reset}`.padEnd(69) + "│");
+    }
+  }
+
+  lines.push("╰" + "─".repeat(68) + "╯");
+
+  return lines.join("\n");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// USER JOURNEY ANALYSIS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const COMMON_JOURNEYS = {
+  signup: {
+    name: "User Signup",
+    icon: "👤",
+    steps: [
+      { action: "visit", target: "/signup", description: "Visit signup page" },
+      { action: "fill", target: "email", description: "Enter email" },
+      { action: "fill", target: "password", description: "Enter password" },
+      { action: "click", target: "submit", description: "Submit form" },
+      { action: "verify", target: "/dashboard", description: "Redirected to dashboard" },
+    ],
+  },
+  login: {
+    name: "User Login",
+    icon: "🔐",
+    steps: [
+      { action: "visit", target: "/login", description: "Visit login page" },
+      { action: "fill", target: "email", description: "Enter email" },
+      { action: "fill", target: "password", description: "Enter password" },
+      { action: "click", target: "submit", description: "Submit form" },
+      { action: "verify", target: "/dashboard", description: "Redirected to dashboard" },
+    ],
+  },
+  checkout: {
+    name: "Checkout Flow",
+    icon: "💳",
+    steps: [
+      { action: "visit", target: "/pricing", description: "Visit pricing page" },
+      { action: "click", target: "plan", description: "Select plan" },
+      { action: "verify", target: "/checkout", description: "Redirected to checkout" },
+      { action: "fill", target: "card", description: "Enter payment details" },
+      { action: "click", target: "pay", description: "Submit payment" },
+      { action: "verify", target: "/success", description: "Payment confirmed" },
+    ],
+  },
+};
+
+/**
+ * Analyze user journey results
+ */
+function analyzeJourney(journey, results) {
+  const analysis = {
+    journey: journey.name,
+    icon: journey.icon,
+    steps: [],
+    success: true,
+    failedAt: null,
+    duration: 0,
+  };
+
+  for (let i = 0; i < results.length; i++) {
+    const step = journey.steps[i];
+    const result = results[i];
+
+    analysis.steps.push({
+      ...step,
+      success: result.success,
+      duration: result.duration,
+      error: result.error,
+    });
+
+    analysis.duration += result.duration || 0;
+
+    if (!result.success && analysis.success) {
+      analysis.success = false;
+      analysis.failedAt = i;
+    }
+  }
+
+  return analysis;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EVIDENCE PACK GENERATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a comprehensive evidence pack
+ */
+async function generateEvidencePack(options = {}) {
+  const {
+    projectPath = ".",
+    outputDir = ".vibecheck",
+    findings = [],
+    coverage = {},
+    performance = {},
+    journeys = [],
+    screenshots = [],
+    videos = [],
+    traces = [],
+  } = options;
+
+  const packId = `evidence_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
+  const packDir = path.join(outputDir, "evidence-packs", packId);
+
+  // Create pack directory
+  fs.mkdirSync(packDir, { recursive: true });
+
+  // Generate manifest
+  const manifest = {
+    id: packId,
+    timestamp: new Date().toISOString(),
+    project: path.basename(projectPath),
+    contents: {
+      findings: findings.length,
+      screenshots: screenshots.length,
+      videos: videos.length,
+      traces: traces.length,
+    },
+    coverage: coverage.stats,
+    performance: {
+      overall: performance.overall,
+      lcp: performance.grades?.lcp?.value,
+      cls: performance.grades?.cls?.value,
+    },
+    journeys: journeys.map((j) => ({
+      name: j.journey,
+      success: j.success,
+    })),
+  };
+
+  // Save manifest
+  fs.writeFileSync(
+    path.join(packDir, "manifest.json"),
+    JSON.stringify(manifest, null, 2)
+  );
+
+  // Save findings
+  fs.writeFileSync(
+    path.join(packDir, "findings.json"),
+    JSON.stringify(findings, null, 2)
+  );
+
+  // Save coverage
+  fs.writeFileSync(
+    path.join(packDir, "coverage.json"),
+    JSON.stringify(coverage, null, 2)
+  );
+
+  // Save performance
+  fs.writeFileSync(
+    path.join(packDir, "performance.json"),
+    JSON.stringify(performance, null, 2)
+  );
+
+  // Copy screenshots
+  const screenshotsDir = path.join(packDir, "screenshots");
+  if (screenshots.length > 0) {
+    fs.mkdirSync(screenshotsDir, { recursive: true });
+    for (const screenshot of screenshots) {
+      if (fs.existsSync(screenshot)) {
+        fs.copyFileSync(
+          screenshot,
+          path.join(screenshotsDir, path.basename(screenshot))
+        );
+      }
+    }
+  }
+
+  // Copy videos
+  const videosDir = path.join(packDir, "videos");
+  if (videos.length > 0) {
+    fs.mkdirSync(videosDir, { recursive: true });
+    for (const video of videos) {
+      if (fs.existsSync(video)) {
+        fs.copyFileSync(video, path.join(videosDir, path.basename(video)));
+      }
+    }
+  }
+
+  // Generate HTML report
+  const htmlReport = generateHtmlEvidenceReport(manifest, findings, coverage, performance);
+  fs.writeFileSync(path.join(packDir, "report.html"), htmlReport);
+
+  return {
+    packId,
+    packDir,
+    manifest,
+    reportPath: path.join(packDir, "report.html"),
+  };
+}
+
+/**
+ * Generate HTML evidence report
+ */
+function generateHtmlEvidenceReport(manifest, findings, coverage, performance) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Vibecheck Evidence Pack - ${manifest.project}</title>
+  <style>
+    :root {
+      --bg: #0a0a0f;
+      --card-bg: #12121a;
+      --border: #2a2a3a;
+      --text: #e0e0e0;
+      --text-dim: #808090;
+      --accent: #6366f1;
+      --success: #22c55e;
+      --warning: #f59e0b;
+      --error: #ef4444;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      line-height: 1.6;
+      padding: 2rem;
+    }
+    .container { max-width: 1200px; margin: 0 auto; }
+    h1 { font-size: 2rem; margin-bottom: 0.5rem; }
+    .meta { color: var(--text-dim); margin-bottom: 2rem; }
+    .card {
+      background: var(--card-bg);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+    .card h2 { font-size: 1.25rem; margin-bottom: 1rem; color: var(--accent); }
+    .stat-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+      gap: 1rem;
+    }
+    .stat {
+      text-align: center;
+      padding: 1rem;
+      background: rgba(99, 102, 241, 0.1);
+      border-radius: 8px;
+    }
+    .stat-value { font-size: 2rem; font-weight: bold; color: var(--accent); }
+    .stat-label { font-size: 0.875rem; color: var(--text-dim); }
+    .progress-bar {
+      height: 8px;
+      background: var(--border);
+      border-radius: 4px;
+      overflow: hidden;
+      margin: 0.5rem 0;
+    }
+    .progress-fill { height: 100%; background: var(--success); transition: width 0.3s; }
+    .finding {
+      padding: 1rem;
+      border-left: 3px solid var(--border);
+      margin-bottom: 0.5rem;
+      background: rgba(0,0,0,0.2);
+    }
+    .finding.BLOCK { border-color: var(--error); }
+    .finding.WARN { border-color: var(--warning); }
+    .badge {
+      display: inline-block;
+      padding: 0.25rem 0.5rem;
+      border-radius: 4px;
+      font-size: 0.75rem;
+      font-weight: bold;
+    }
+    .badge.BLOCK { background: var(--error); }
+    .badge.WARN { background: var(--warning); color: #000; }
+    .badge.good { background: var(--success); }
+    .badge.poor { background: var(--error); }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>📋 Evidence Pack</h1>
+    <p class="meta">${manifest.project} • ${manifest.timestamp}</p>
+    
+    <div class="card">
+      <h2>📊 Summary</h2>
+      <div class="stat-grid">
+        <div class="stat">
+          <div class="stat-value">${findings.length}</div>
+          <div class="stat-label">Findings</div>
+        </div>
+        <div class="stat">
+          <div class="stat-value">${coverage.stats?.percentage || 0}%</div>
+          <div class="stat-label">Coverage</div>
+        </div>
+        <div class="stat">
+          <div class="stat-value">${performance.grades?.lcp?.value ? Math.round(performance.grades.lcp.value) + 'ms' : 'N/A'}</div>
+          <div class="stat-label">LCP</div>
+        </div>
+        <div class="stat">
+          <div class="stat-value">${manifest.contents.screenshots}</div>
+          <div class="stat-label">Screenshots</div>
+        </div>
+      </div>
+    </div>
+
+    <div class="card">
+      <h2>🎯 Coverage</h2>
+      <div class="progress-bar">
+        <div class="progress-fill" style="width: ${coverage.stats?.percentage || 0}%"></div>
+      </div>
+      <p>${coverage.stats?.covered || 0} of ${coverage.stats?.total || 0} routes verified</p>
+    </div>
+
+    <div class="card">
+      <h2>⚡ Performance</h2>
+      <p>Overall: <span class="badge ${performance.overall || 'unknown'}">${(performance.overall || 'unknown').toUpperCase()}</span></p>
+    </div>
+
+    <div class="card">
+      <h2>🔍 Top Findings</h2>
+      ${findings.slice(0, 10).map(f => `
+        <div class="finding ${f.severity}">
+          <span class="badge ${f.severity}">${f.severity}</span>
+          <strong>${f.title || f.message}</strong>
+          <br><small>${f.file}:${f.line}</small>
+        </div>
+      `).join('')}
+    </div>
+  </div>
+</body>
+</html>`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Performance
+  trackWebVitals,
+  analyzePerformance,
+  renderPerformanceReport,
+  PERFORMANCE_BUDGETS,
+
+  // Coverage
+  generateCoverageMap,
+  renderCoverageMap,
+
+  // User Journeys
+  analyzeJourney,
+  COMMON_JOURNEYS,
+
+  // Evidence Pack
+  generateEvidencePack,
+  generateHtmlEvidenceReport,
+};