@vibecheckai/cli 3.4.0 → 3.5.0

package/bin/runners/lib/reality/performance-tracker.js

@@ -0,0 +1,1077 @@
+/**
+ * Performance Regression Detection Engine
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * COMPETITIVE MOAT FEATURE - Automatic Performance Regression Detection
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * This engine tracks Core Web Vitals and performance metrics during Reality Mode
+ * runs, comparing against baselines to detect regressions.
+ * 
+ * Metrics Tracked:
+ * - LCP (Largest Contentful Paint) - Loading performance
+ * - FID (First Input Delay) - Interactivity  
+ * - CLS (Cumulative Layout Shift) - Visual stability
+ * - TTFB (Time to First Byte) - Server response
+ * - FCP (First Contentful Paint) - Initial render
+ * - TTI (Time to Interactive) - Full interactivity
+ * - TBT (Total Blocking Time) - Main thread blocking
+ * - Memory usage - JS heap size
+ * - Bundle impact - Resource loading
+ * 
+ * Features:
+ * - Baseline comparison with configurable thresholds
+ * - Trend analysis (degradation over time)
+ * - Budget enforcement (fail if exceeding budgets)
+ * - Detailed breakdowns (by resource type, domain)
+ * - Interaction performance (click-to-response)
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PERFORMANCE THRESHOLDS (based on Google's recommendations)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const THRESHOLDS = {
+  // Core Web Vitals
+  LCP: {
+    good: 2500,      // ms - Good
+    needsImprovement: 4000,  // ms - Needs improvement
+    poor: Infinity   // ms - Poor
+  },
+  FID: {
+    good: 100,
+    needsImprovement: 300,
+    poor: Infinity
+  },
+  CLS: {
+    good: 0.1,
+    needsImprovement: 0.25,
+    poor: Infinity
+  },
+  
+  // Additional metrics
+  TTFB: {
+    good: 200,
+    needsImprovement: 500,
+    poor: Infinity
+  },
+  FCP: {
+    good: 1800,
+    needsImprovement: 3000,
+    poor: Infinity
+  },
+  TTI: {
+    good: 3800,
+    needsImprovement: 7300,
+    poor: Infinity
+  },
+  TBT: {
+    good: 200,
+    needsImprovement: 600,
+    poor: Infinity
+  },
+  
+  // Memory
+  heapSize: {
+    good: 50 * 1024 * 1024,      // 50MB
+    needsImprovement: 100 * 1024 * 1024,  // 100MB
+    poor: Infinity
+  },
+  
+  // Bundle sizes
+  totalTransfer: {
+    good: 1024 * 1024,           // 1MB
+    needsImprovement: 3 * 1024 * 1024,  // 3MB
+    poor: Infinity
+  },
+  jsSize: {
+    good: 300 * 1024,            // 300KB
+    needsImprovement: 500 * 1024,  // 500KB
+    poor: Infinity
+  }
+};
+
+// Regression thresholds (% increase that triggers alert)
+const REGRESSION_THRESHOLDS = {
+  LCP: 0.2,      // 20% regression
+  FID: 0.25,     // 25% regression
+  CLS: 0.5,      // 50% regression (CLS is more variable)
+  TTFB: 0.3,     // 30% regression
+  FCP: 0.2,      // 20% regression
+  TTI: 0.2,      // 20% regression
+  TBT: 0.25,     // 25% regression
+  heapSize: 0.3, // 30% regression
+  totalTransfer: 0.15,  // 15% regression
+  jsSize: 0.1    // 10% regression (bundle bloat is bad)
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PERFORMANCE TRACKER CLASS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+class PerformanceTracker {
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.baselinePath = options.baselinePath ||
+      path.join(this.projectRoot, ".vibecheck", "performance-baselines");
+    this.historyPath = options.historyPath ||
+      path.join(this.projectRoot, ".vibecheck", "performance-history");
+    this.thresholds = { ...THRESHOLDS, ...options.thresholds };
+    this.regressionThresholds = { ...REGRESSION_THRESHOLDS, ...options.regressionThresholds };
+    this.page = null;
+    this.cdpSession = null;
+    this.metrics = [];
+    this.resources = [];
+  }
+
+  /**
+   * Set the Playwright page and enable performance tracking
+   */
+  async setPage(page) {
+    this.page = page;
+    
+    // Create CDP session for detailed metrics
+    try {
+      this.cdpSession = await page.context().newCDPSession(page);
+      await this.cdpSession.send("Performance.enable");
+    } catch {
+      // CDP not available (e.g., Firefox)
+      this.cdpSession = null;
+    }
+  }
+
+  /**
+   * Start tracking for a page load
+   */
+  async startTracking() {
+    this.metrics = [];
+    this.resources = [];
+    this.startTime = Date.now();
+
+    // Track resource loading
+    if (this.page) {
+      this.page.on("response", this.trackResource.bind(this));
+    }
+  }
+
+  /**
+   * Track individual resource
+   */
+  async trackResource(response) {
+    try {
+      const request = response.request();
+      const timing = await response.timing();
+      
+      this.resources.push({
+        url: request.url(),
+        method: request.method(),
+        resourceType: request.resourceType(),
+        status: response.status(),
+        transferSize: (await response.headers())["content-length"] || 0,
+        timing: {
+          dns: timing?.dnsEnd - timing?.dnsStart || 0,
+          connect: timing?.connectEnd - timing?.connectStart || 0,
+          ssl: timing?.sslEnd - timing?.sslStart || 0,
+          ttfb: timing?.responseStart - timing?.requestStart || 0,
+          download: timing?.responseEnd - timing?.responseStart || 0,
+          total: timing?.responseEnd - timing?.requestStart || 0
+        }
+      });
+    } catch {
+      // Ignore tracking errors
+    }
+  }
+
+  /**
+   * Collect all performance metrics
+   */
+  async collectMetrics() {
+    if (!this.page) {
+      throw new Error("Page not set. Call setPage() first.");
+    }
+
+    const metrics = {
+      timestamp: new Date().toISOString(),
+      url: this.page.url(),
+      
+      // Core Web Vitals
+      coreWebVitals: await this.collectCoreWebVitals(),
+      
+      // Navigation timing
+      navigation: await this.collectNavigationTiming(),
+      
+      // Memory
+      memory: await this.collectMemoryMetrics(),
+      
+      // Resources
+      resources: this.analyzeResources(),
+      
+      // Long tasks (main thread blocking)
+      longTasks: await this.collectLongTasks(),
+      
+      // Layout shifts
+      layoutShifts: await this.collectLayoutShifts()
+    };
+
+    this.metrics.push(metrics);
+    return metrics;
+  }
+
+  /**
+   * Collect Core Web Vitals
+   */
+  async collectCoreWebVitals() {
+    return await this.page.evaluate(() => {
+      return new Promise((resolve) => {
+        const vitals = {
+          LCP: null,
+          FID: null,
+          CLS: 0
+        };
+
+        // LCP
+        new PerformanceObserver((list) => {
+          const entries = list.getEntries();
+          const lastEntry = entries[entries.length - 1];
+          vitals.LCP = lastEntry?.startTime || null;
+        }).observe({ type: "largest-contentful-paint", buffered: true });
+
+        // FID (approximated with first-input if available)
+        new PerformanceObserver((list) => {
+          const entries = list.getEntries();
+          if (entries.length > 0) {
+            vitals.FID = entries[0].processingStart - entries[0].startTime;
+          }
+        }).observe({ type: "first-input", buffered: true });
+
+        // CLS
+        new PerformanceObserver((list) => {
+          for (const entry of list.getEntries()) {
+            if (!entry.hadRecentInput) {
+              vitals.CLS += entry.value;
+            }
+          }
+        }).observe({ type: "layout-shift", buffered: true });
+
+        // Wait a bit for metrics to populate
+        setTimeout(() => resolve(vitals), 1000);
+      });
+    });
+  }
+
+  /**
+   * Collect navigation timing metrics
+   */
+  async collectNavigationTiming() {
+    return await this.page.evaluate(() => {
+      const nav = performance.getEntriesByType("navigation")[0];
+      if (!nav) return null;
+
+      return {
+        TTFB: nav.responseStart - nav.requestStart,
+        FCP: performance.getEntriesByType("paint")
+          .find(e => e.name === "first-contentful-paint")?.startTime || null,
+        domContentLoaded: nav.domContentLoadedEventEnd - nav.startTime,
+        load: nav.loadEventEnd - nav.startTime,
+        
+        // Breakdown
+        dns: nav.domainLookupEnd - nav.domainLookupStart,
+        tcp: nav.connectEnd - nav.connectStart,
+        ssl: nav.secureConnectionStart > 0 
+          ? nav.connectEnd - nav.secureConnectionStart 
+          : 0,
+        request: nav.responseStart - nav.requestStart,
+        response: nav.responseEnd - nav.responseStart,
+        processing: nav.domComplete - nav.responseEnd,
+        
+        // Transfer sizes
+        transferSize: nav.transferSize,
+        encodedBodySize: nav.encodedBodySize,
+        decodedBodySize: nav.decodedBodySize
+      };
+    });
+  }
+
+  /**
+   * Collect memory metrics
+   */
+  async collectMemoryMetrics() {
+    return await this.page.evaluate(() => {
+      if (performance.memory) {
+        return {
+          usedJSHeapSize: performance.memory.usedJSHeapSize,
+          totalJSHeapSize: performance.memory.totalJSHeapSize,
+          jsHeapSizeLimit: performance.memory.jsHeapSizeLimit
+        };
+      }
+      return null;
+    });
+  }
+
+  /**
+   * Analyze collected resources
+   */
+  analyzeResources() {
+    const byType = {};
+    let totalTransfer = 0;
+    let totalRequests = 0;
+
+    for (const resource of this.resources) {
+      const type = resource.resourceType;
+      const size = parseInt(resource.transferSize) || 0;
+
+      if (!byType[type]) {
+        byType[type] = { count: 0, size: 0, avgTiming: 0 };
+      }
+
+      byType[type].count++;
+      byType[type].size += size;
+      byType[type].avgTiming += resource.timing.total;
+      
+      totalTransfer += size;
+      totalRequests++;
+    }
+
+    // Calculate averages
+    for (const type of Object.keys(byType)) {
+      if (byType[type].count > 0) {
+        byType[type].avgTiming /= byType[type].count;
+      }
+    }
+
+    return {
+      totalRequests,
+      totalTransfer,
+      byType,
+      jsSize: byType.script?.size || 0,
+      cssSize: byType.stylesheet?.size || 0,
+      imageSize: byType.image?.size || 0,
+      fontSize: byType.font?.size || 0
+    };
+  }
+
+  /**
+   * Collect long tasks (blocking main thread)
+   */
+  async collectLongTasks() {
+    return await this.page.evaluate(() => {
+      return new Promise((resolve) => {
+        const longTasks = [];
+        
+        new PerformanceObserver((list) => {
+          for (const entry of list.getEntries()) {
+            longTasks.push({
+              startTime: entry.startTime,
+              duration: entry.duration,
+              name: entry.name
+            });
+          }
+        }).observe({ type: "longtask", buffered: true });
+
+        setTimeout(() => {
+          const totalBlockingTime = longTasks
+            .filter(t => t.duration > 50)
+            .reduce((sum, t) => sum + (t.duration - 50), 0);
+          
+          resolve({
+            count: longTasks.length,
+            totalBlockingTime,
+            tasks: longTasks.slice(0, 10) // Top 10
+          });
+        }, 500);
+      });
+    });
+  }
+
+  /**
+   * Collect layout shift details
+   */
+  async collectLayoutShifts() {
+    return await this.page.evaluate(() => {
+      return new Promise((resolve) => {
+        const shifts = [];
+        let cumulativeScore = 0;
+        
+        new PerformanceObserver((list) => {
+          for (const entry of list.getEntries()) {
+            if (!entry.hadRecentInput) {
+              cumulativeScore += entry.value;
+              shifts.push({
+                value: entry.value,
+                startTime: entry.startTime,
+                sources: entry.sources?.map(s => ({
+                  node: s.node?.nodeName,
+                  previousRect: s.previousRect,
+                  currentRect: s.currentRect
+                })) || []
+              });
+            }
+          }
+        }).observe({ type: "layout-shift", buffered: true });
+
+        setTimeout(() => {
+          resolve({
+            cumulativeScore,
+            shiftCount: shifts.length,
+            largestShift: Math.max(...shifts.map(s => s.value), 0),
+            shifts: shifts.slice(0, 5) // Top 5
+          });
+        }, 500);
+      });
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // BASELINE COMPARISON
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Compare metrics against baseline
+   */
+  async compareWithBaseline(metrics, pageName) {
+    const baseline = this.loadBaseline(pageName);
+    
+    if (!baseline) {
+      return {
+        hasBaseline: false,
+        message: "No baseline found. Current metrics will be saved as baseline."
+      };
+    }
+
+    const comparison = {
+      hasBaseline: true,
+      regressions: [],
+      improvements: [],
+      unchanged: [],
+      details: {}
+    };
+
+    // Compare Core Web Vitals
+    this.compareMetric(comparison, "LCP", 
+      metrics.coreWebVitals?.LCP, 
+      baseline.coreWebVitals?.LCP
+    );
+    
+    this.compareMetric(comparison, "FID", 
+      metrics.coreWebVitals?.FID, 
+      baseline.coreWebVitals?.FID
+    );
+    
+    this.compareMetric(comparison, "CLS", 
+      metrics.coreWebVitals?.CLS, 
+      baseline.coreWebVitals?.CLS
+    );
+
+    // Compare navigation timing
+    this.compareMetric(comparison, "TTFB", 
+      metrics.navigation?.TTFB, 
+      baseline.navigation?.TTFB
+    );
+    
+    this.compareMetric(comparison, "FCP", 
+      metrics.navigation?.FCP, 
+      baseline.navigation?.FCP
+    );
+
+    // Compare memory
+    this.compareMetric(comparison, "heapSize", 
+      metrics.memory?.usedJSHeapSize, 
+      baseline.memory?.usedJSHeapSize
+    );
+
+    // Compare bundle sizes
+    this.compareMetric(comparison, "totalTransfer", 
+      metrics.resources?.totalTransfer, 
+      baseline.resources?.totalTransfer
+    );
+    
+    this.compareMetric(comparison, "jsSize", 
+      metrics.resources?.jsSize, 
+      baseline.resources?.jsSize
+    );
+
+    // Compare TBT
+    this.compareMetric(comparison, "TBT", 
+      metrics.longTasks?.totalBlockingTime, 
+      baseline.longTasks?.totalBlockingTime
+    );
+
+    return comparison;
+  }
+
+  /**
+   * Compare individual metric
+   */
+  compareMetric(comparison, name, current, baseline) {
+    if (current === null || current === undefined || 
+        baseline === null || baseline === undefined) {
+      return;
+    }
+
+    const threshold = this.regressionThresholds[name] || 0.2;
+    const change = (current - baseline) / baseline;
+    const changePercent = (change * 100).toFixed(1);
+
+    const detail = {
+      name,
+      current,
+      baseline,
+      change: changePercent + "%",
+      status: "unchanged"
+    };
+
+    // Check if regression
+    if (change > threshold) {
+      detail.status = "regression";
+      detail.severity = this.getSeverity(name, current);
+      comparison.regressions.push(detail);
+    } 
+    // Check if improvement
+    else if (change < -threshold) {
+      detail.status = "improvement";
+      comparison.improvements.push(detail);
+    } 
+    else {
+      comparison.unchanged.push(detail);
+    }
+
+    comparison.details[name] = detail;
+  }
+
+  /**
+   * Get severity based on absolute value vs thresholds
+   */
+  getSeverity(metricName, value) {
+    const threshold = this.thresholds[metricName];
+    if (!threshold) return "WARN";
+
+    if (value <= threshold.good) return "INFO";
+    if (value <= threshold.needsImprovement) return "WARN";
+    return "BLOCK";
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // BASELINE MANAGEMENT
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Save metrics as baseline
+   */
+  saveBaseline(metrics, pageName) {
+    if (!fs.existsSync(this.baselinePath)) {
+      fs.mkdirSync(this.baselinePath, { recursive: true });
+    }
+
+    const fileName = this.sanitizeName(pageName) + ".json";
+    const filePath = path.join(this.baselinePath, fileName);
+
+    fs.writeFileSync(filePath, JSON.stringify({
+      ...metrics,
+      savedAt: new Date().toISOString()
+    }, null, 2));
+
+    return filePath;
+  }
+
+  /**
+   * Load baseline metrics
+   */
+  loadBaseline(pageName) {
+    const fileName = this.sanitizeName(pageName) + ".json";
+    const filePath = path.join(this.baselinePath, fileName);
+
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Save to history for trend analysis
+   */
+  saveToHistory(metrics, pageName) {
+    const historyDir = path.join(this.historyPath, this.sanitizeName(pageName));
+    
+    if (!fs.existsSync(historyDir)) {
+      fs.mkdirSync(historyDir, { recursive: true });
+    }
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const fileName = `${timestamp}.json`;
+    const filePath = path.join(historyDir, fileName);
+
+    fs.writeFileSync(filePath, JSON.stringify(metrics, null, 2));
+
+    // Keep only last 30 entries
+    this.pruneHistory(historyDir, 30);
+
+    return filePath;
+  }
+
+  /**
+   * Prune old history entries
+   */
+  pruneHistory(historyDir, keepCount) {
+    const files = fs.readdirSync(historyDir)
+      .filter(f => f.endsWith(".json"))
+      .sort()
+      .reverse();
+
+    for (const file of files.slice(keepCount)) {
+      fs.unlinkSync(path.join(historyDir, file));
+    }
+  }
+
+  /**
+   * Get trend analysis
+   */
+  getTrendAnalysis(pageName) {
+    const historyDir = path.join(this.historyPath, this.sanitizeName(pageName));
+    
+    if (!fs.existsSync(historyDir)) {
+      return null;
+    }
+
+    const files = fs.readdirSync(historyDir)
+      .filter(f => f.endsWith(".json"))
+      .sort()
+      .reverse()
+      .slice(0, 10); // Last 10 runs
+
+    if (files.length < 2) {
+      return null;
+    }
+
+    const history = files.map(f => {
+      const data = JSON.parse(fs.readFileSync(path.join(historyDir, f), "utf8"));
+      return {
+        timestamp: data.timestamp,
+        LCP: data.coreWebVitals?.LCP,
+        FID: data.coreWebVitals?.FID,
+        CLS: data.coreWebVitals?.CLS,
+        TTFB: data.navigation?.TTFB,
+        jsSize: data.resources?.jsSize,
+        heapSize: data.memory?.usedJSHeapSize
+      };
+    });
+
+    // Calculate trends
+    const trends = {};
+    const metrics = ["LCP", "FID", "CLS", "TTFB", "jsSize", "heapSize"];
+    
+    for (const metric of metrics) {
+      const values = history.map(h => h[metric]).filter(v => v !== null && v !== undefined);
+      if (values.length >= 2) {
+        const recent = values.slice(0, 3).reduce((a, b) => a + b, 0) / Math.min(3, values.length);
+        const older = values.slice(-3).reduce((a, b) => a + b, 0) / Math.min(3, values.length);
+        const change = ((recent - older) / older) * 100;
+        
+        trends[metric] = {
+          direction: change > 5 ? "degrading" : change < -5 ? "improving" : "stable",
+          changePercent: change.toFixed(1),
+          recentAvg: recent,
+          historicalAvg: older
+        };
+      }
+    }
+
+    return {
+      sampleCount: history.length,
+      timeRange: {
+        oldest: history[history.length - 1]?.timestamp,
+        newest: history[0]?.timestamp
+      },
+      trends,
+      history: history.slice(0, 5) // Last 5 for display
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // INTERACTION PERFORMANCE
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Measure interaction performance (click-to-response)
+   */
+  async measureInteraction(selector, action = "click") {
+    if (!this.page) {
+      throw new Error("Page not set");
+    }
+
+    const startTime = Date.now();
+    
+    // Track network requests during interaction
+    const requests = [];
+    const requestHandler = (request) => {
+      requests.push({
+        url: request.url(),
+        type: request.resourceType(),
+        startTime: Date.now() - startTime
+      });
+    };
+    
+    this.page.on("request", requestHandler);
+
+    // Track DOM changes
+    const domChangePromise = this.page.evaluate(() => {
+      return new Promise((resolve) => {
+        const observer = new MutationObserver((mutations) => {
+          observer.disconnect();
+          resolve({
+            changeCount: mutations.length,
+            timestamp: performance.now()
+          });
+        });
+        
+        observer.observe(document.body, {
+          childList: true,
+          subtree: true,
+          attributes: true
+        });
+
+        // Timeout after 5s
+        setTimeout(() => {
+          observer.disconnect();
+          resolve({ changeCount: 0, timeout: true });
+        }, 5000);
+      });
+    });
+
+    // Perform interaction
+    const element = await this.page.$(selector);
+    if (!element) {
+      throw new Error(`Element not found: ${selector}`);
+    }
+
+    if (action === "click") {
+      await element.click();
+    } else if (action === "hover") {
+      await element.hover();
+    }
+
+    // Wait for response
+    const domChange = await domChangePromise;
+    const endTime = Date.now();
+    
+    this.page.off("request", requestHandler);
+
+    return {
+      selector,
+      action,
+      duration: endTime - startTime,
+      domChangeTime: domChange.timestamp,
+      domChangeCount: domChange.changeCount,
+      networkRequests: requests.length,
+      requests: requests.slice(0, 5),
+      rating: this.rateInteractionSpeed(endTime - startTime)
+    };
+  }
+
+  /**
+   * Rate interaction speed
+   */
+  rateInteractionSpeed(duration) {
+    if (duration < 100) return { rating: "instant", color: "green" };
+    if (duration < 300) return { rating: "fast", color: "green" };
+    if (duration < 1000) return { rating: "acceptable", color: "yellow" };
+    if (duration < 3000) return { rating: "slow", color: "orange" };
+    return { rating: "very slow", color: "red" };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // BUDGETS
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Check against performance budgets
+   */
+  checkBudgets(metrics, budgets = {}) {
+    const defaultBudgets = {
+      LCP: 2500,
+      FID: 100,
+      CLS: 0.1,
+      TTFB: 200,
+      totalTransfer: 1024 * 1024, // 1MB
+      jsSize: 300 * 1024,          // 300KB
+      requestCount: 50
+    };
+
+    const effectiveBudgets = { ...defaultBudgets, ...budgets };
+    const violations = [];
+    const passing = [];
+
+    // Check each budget
+    if (metrics.coreWebVitals?.LCP > effectiveBudgets.LCP) {
+      violations.push({
+        metric: "LCP",
+        budget: effectiveBudgets.LCP,
+        actual: metrics.coreWebVitals.LCP,
+        overage: ((metrics.coreWebVitals.LCP / effectiveBudgets.LCP - 1) * 100).toFixed(0) + "%"
+      });
+    } else {
+      passing.push({ metric: "LCP", within: true });
+    }
+
+    if (metrics.coreWebVitals?.CLS > effectiveBudgets.CLS) {
+      violations.push({
+        metric: "CLS",
+        budget: effectiveBudgets.CLS,
+        actual: metrics.coreWebVitals.CLS,
+        overage: ((metrics.coreWebVitals.CLS / effectiveBudgets.CLS - 1) * 100).toFixed(0) + "%"
+      });
+    } else {
+      passing.push({ metric: "CLS", within: true });
+    }
+
+    if (metrics.resources?.totalTransfer > effectiveBudgets.totalTransfer) {
+      violations.push({
+        metric: "Total Transfer",
+        budget: this.formatBytes(effectiveBudgets.totalTransfer),
+        actual: this.formatBytes(metrics.resources.totalTransfer),
+        overage: ((metrics.resources.totalTransfer / effectiveBudgets.totalTransfer - 1) * 100).toFixed(0) + "%"
+      });
+    } else {
+      passing.push({ metric: "Total Transfer", within: true });
+    }
+
+    if (metrics.resources?.jsSize > effectiveBudgets.jsSize) {
+      violations.push({
+        metric: "JS Size",
+        budget: this.formatBytes(effectiveBudgets.jsSize),
+        actual: this.formatBytes(metrics.resources.jsSize),
+        overage: ((metrics.resources.jsSize / effectiveBudgets.jsSize - 1) * 100).toFixed(0) + "%"
+      });
+    } else {
+      passing.push({ metric: "JS Size", within: true });
+    }
+
+    if (metrics.resources?.totalRequests > effectiveBudgets.requestCount) {
+      violations.push({
+        metric: "Request Count",
+        budget: effectiveBudgets.requestCount,
+        actual: metrics.resources.totalRequests,
+        overage: ((metrics.resources.totalRequests / effectiveBudgets.requestCount - 1) * 100).toFixed(0) + "%"
+      });
+    } else {
+      passing.push({ metric: "Request Count", within: true });
+    }
+
+    return {
+      passed: violations.length === 0,
+      violations,
+      passing,
+      summary: `${passing.length}/${passing.length + violations.length} budgets met`
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // REPORTING
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Generate performance report
+   */
+  generateReport(metrics, comparison, budgetCheck) {
+    return {
+      timestamp: new Date().toISOString(),
+      url: metrics.url,
+      
+      // Scores
+      scores: this.calculateScores(metrics),
+      
+      // Core Web Vitals summary
+      coreWebVitals: {
+        LCP: this.formatMetric("LCP", metrics.coreWebVitals?.LCP),
+        FID: this.formatMetric("FID", metrics.coreWebVitals?.FID),
+        CLS: this.formatMetric("CLS", metrics.coreWebVitals?.CLS)
+      },
+      
+      // Comparison with baseline
+      comparison: comparison?.hasBaseline ? {
+        regressions: comparison.regressions,
+        improvements: comparison.improvements,
+        summary: `${comparison.regressions.length} regressions, ${comparison.improvements.length} improvements`
+      } : null,
+      
+      // Budget check
+      budgets: budgetCheck,
+      
+      // Detailed metrics
+      details: {
+        navigation: metrics.navigation,
+        resources: metrics.resources,
+        memory: metrics.memory,
+        longTasks: metrics.longTasks,
+        layoutShifts: metrics.layoutShifts
+      },
+      
+      // Recommendations
+      recommendations: this.generateRecommendations(metrics)
+    };
+  }
+
+  /**
+   * Calculate overall scores
+   */
+  calculateScores(metrics) {
+    const scores = {};
+    
+    // LCP score (0-100)
+    const lcp = metrics.coreWebVitals?.LCP;
+    if (lcp !== null) {
+      if (lcp <= 2500) scores.LCP = 100;
+      else if (lcp <= 4000) scores.LCP = Math.round(100 - ((lcp - 2500) / 1500) * 50);
+      else scores.LCP = Math.max(0, Math.round(50 - ((lcp - 4000) / 4000) * 50));
+    }
+    
+    // CLS score
+    const cls = metrics.coreWebVitals?.CLS;
+    if (cls !== null) {
+      if (cls <= 0.1) scores.CLS = 100;
+      else if (cls <= 0.25) scores.CLS = Math.round(100 - ((cls - 0.1) / 0.15) * 50);
+      else scores.CLS = Math.max(0, Math.round(50 - (cls - 0.25) * 100));
+    }
+    
+    // Overall score
+    const validScores = Object.values(scores).filter(s => s !== undefined);
+    scores.overall = validScores.length > 0 
+      ? Math.round(validScores.reduce((a, b) => a + b, 0) / validScores.length)
+      : null;
+    
+    return scores;
+  }
+
+  /**
+   * Format metric for display
+   */
+  formatMetric(name, value) {
+    if (value === null || value === undefined) {
+      return { value: "N/A", rating: "unknown" };
+    }
+
+    const threshold = this.thresholds[name];
+    let rating = "unknown";
+    
+    if (threshold) {
+      if (value <= threshold.good) rating = "good";
+      else if (value <= threshold.needsImprovement) rating = "needs-improvement";
+      else rating = "poor";
+    }
+
+    let formatted = value;
+    if (name === "CLS") {
+      formatted = value.toFixed(3);
+    } else if (name === "LCP" || name === "FID" || name === "TTFB" || name === "FCP") {
+      formatted = value.toFixed(0) + "ms";
+    }
+
+    return { value: formatted, rating };
+  }
+
+  /**
+   * Generate recommendations based on metrics
+   */
+  generateRecommendations(metrics) {
+    const recommendations = [];
+
+    // LCP recommendations
+    const lcp = metrics.coreWebVitals?.LCP;
+    if (lcp > 4000) {
+      recommendations.push({
+        metric: "LCP",
+        severity: "high",
+        message: "Largest Contentful Paint is poor",
+        suggestions: [
+          "Optimize server response time",
+          "Remove render-blocking resources",
+          "Optimize images with lazy loading",
+          "Use a CDN for static assets"
+        ]
+      });
+    }
+
+    // CLS recommendations
+    const cls = metrics.coreWebVitals?.CLS;
+    if (cls > 0.25) {
+      recommendations.push({
+        metric: "CLS",
+        severity: "high",
+        message: "Cumulative Layout Shift is poor",
+        suggestions: [
+          "Set explicit dimensions on images and videos",
+          "Reserve space for dynamic content",
+          "Avoid inserting content above existing content",
+          "Use CSS transform for animations"
+        ]
+      });
+    }
+
+    // JS size recommendations
+    const jsSize = metrics.resources?.jsSize;
+    if (jsSize > 500 * 1024) {
+      recommendations.push({
+        metric: "JS Size",
+        severity: "medium",
+        message: `JavaScript bundle is large (${this.formatBytes(jsSize)})`,
+        suggestions: [
+          "Enable code splitting",
+          "Remove unused dependencies",
+          "Use tree shaking",
+          "Consider lazy loading non-critical JS"
+        ]
+      });
+    }
+
+    // TBT recommendations
+    const tbt = metrics.longTasks?.totalBlockingTime;
+    if (tbt > 300) {
+      recommendations.push({
+        metric: "TBT",
+        severity: "medium",
+        message: `High Total Blocking Time (${tbt.toFixed(0)}ms)`,
+        suggestions: [
+          "Break up long tasks",
+          "Defer non-critical JavaScript",
+          "Use web workers for heavy computation",
+          "Optimize third-party scripts"
+        ]
+      });
+    }
+
+    return recommendations;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // UTILITIES
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  sanitizeName(name) {
+    return name.replace(/[^a-zA-Z0-9-_]/g, "-").toLowerCase();
+  }
+
+  formatBytes(bytes) {
+    if (bytes < 1024) return bytes + " B";
+    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + " KB";
+    return (bytes / (1024 * 1024)).toFixed(2) + " MB";
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  PerformanceTracker,
+  THRESHOLDS,
+  REGRESSION_THRESHOLDS
+};