@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/core/perf/perf.enforcer.js

@@ -0,0 +1,91 @@
+/**
+ * PHASE 21.9 — Performance Enforcer
+ * 
+ * Records performance violations in failure ledger and blocks GA/Release.
+ */
+
+import { loadPerformanceReport } from './perf.report.js';
+import { createInternalFailure } from '../failures/failure.factory.js';
+import { FAILURE_CODE, EXECUTION_PHASE } from '../failures/failure.types.js';
+
+/**
+ * Record performance violations in failure ledger
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} failureLedger - Failure ledger instance
+ */
+export function recordPerformanceViolations(projectDir, runId, failureLedger) {
+  const report = loadPerformanceReport(projectDir, runId);
+  
+  if (!report) {
+    return;
+  }
+  
+  // Record BLOCKING violations
+  for (const violation of report.violations) {
+    const failure = createInternalFailure(
+      FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+      violation.message,
+      'perf.enforcer',
+      {
+        type: violation.type,
+        actual: violation.actual,
+        budget: violation.budget,
+        excess: violation.excess
+      },
+      EXECUTION_PHASE.RUNTIME
+    );
+    failureLedger.record(failure);
+  }
+  
+  // Record DEGRADED warnings
+  for (const warning of report.warnings) {
+    const failure = createInternalFailure(
+      FAILURE_CODE.INTERNAL_UNEXPECTED_ERROR,
+      warning.message,
+      'perf.enforcer',
+      {
+        type: warning.type,
+        actual: warning.actual,
+        budget: warning.budget,
+        excess: warning.excess
+      },
+      EXECUTION_PHASE.RUNTIME
+    );
+    failure.severity = 'DEGRADED';
+    failureLedger.record(failure);
+  }
+}
+
+/**
+ * Check performance status for GA/Release
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object} Performance status
+ */
+export function checkPerformanceStatus(projectDir, runId) {
+  const report = loadPerformanceReport(projectDir, runId);
+  
+  if (!report) {
+    return {
+      exists: false,
+      ok: false,
+      verdict: 'UNKNOWN',
+      blockers: ['Performance report not found']
+    };
+  }
+  
+  const hasBlocking = report.violations.length > 0;
+  const hasDegraded = report.warnings.length > 0;
+  
+  return {
+    exists: true,
+    ok: !hasBlocking,
+    verdict: report.verdict,
+    blockers: hasBlocking ? report.violations.map(v => v.message) : [],
+    warnings: hasDegraded ? report.warnings.map(w => w.message) : []
+  };
+}
+

package/src/verax/core/perf/perf.monitor.js

@@ -0,0 +1,209 @@
+/**
+ * PHASE 21.9 — Performance Monitor
+ * 
+ * Monitors runtime, memory, event loop delay, and execution counters.
+ * Records timestamped samples and peak values.
+ */
+
+import { performance } from 'perf_hooks';
+
+/**
+ * Performance Monitor
+ */
+export class PerformanceMonitor {
+  constructor() {
+    this.startTime = performance.now();
+    this.startMemory = process.memoryUsage();
+    this.samples = [];
+    this.peakMemoryRSS = this.startMemory.rss;
+    this.peakMemoryHeapUsed = this.startMemory.heapUsed;
+    this.peakMemoryHeapTotal = this.startMemory.heapTotal;
+    this.peakEventLoopDelay = 0;
+    
+    // Counters
+    this.pagesVisited = 0;
+    this.interactionsExecuted = 0;
+    
+    // Phase tracking
+    this.phaseStartTimes = {};
+    this.phaseDurations = {};
+    
+    // Event loop monitoring
+    this.eventLoopMonitor = null;
+    this.lastEventLoopCheck = performance.now();
+    this.eventLoopDelays = [];
+    
+    this.startEventLoopMonitoring();
+  }
+  
+  /**
+   * Start event loop delay monitoring
+   */
+  startEventLoopMonitoring() {
+    const checkInterval = 100; // Check every 100ms
+    
+    this.eventLoopMonitor = setInterval(() => {
+      const now = performance.now();
+      const delay = now - this.lastEventLoopCheck - checkInterval;
+      
+      if (delay > 0) {
+        this.eventLoopDelays.push(delay);
+        if (delay > this.peakEventLoopDelay) {
+          this.peakEventLoopDelay = delay;
+        }
+      }
+      
+      this.lastEventLoopCheck = now;
+    }, checkInterval);
+  }
+  
+  /**
+   * Record a sample
+   */
+  sample(phase = null) {
+    const now = performance.now();
+    const memory = process.memoryUsage();
+    
+    // Update peaks
+    if (memory.rss > this.peakMemoryRSS) {
+      this.peakMemoryRSS = memory.rss;
+    }
+    if (memory.heapUsed > this.peakMemoryHeapUsed) {
+      this.peakMemoryHeapUsed = memory.heapUsed;
+    }
+    if (memory.heapTotal > this.peakMemoryHeapTotal) {
+      this.peakMemoryHeapTotal = memory.heapTotal;
+    }
+    
+    // Calculate average event loop delay
+    const avgEventLoopDelay = this.eventLoopDelays.length > 0
+      ? this.eventLoopDelays.reduce((a, b) => a + b, 0) / this.eventLoopDelays.length
+      : 0;
+    
+    this.samples.push({
+      timestamp: now,
+      elapsedMs: now - this.startTime,
+      phase,
+      memory: {
+        rss: memory.rss,
+        heapUsed: memory.heapUsed,
+        heapTotal: memory.heapTotal,
+        external: memory.external
+      },
+      eventLoopDelay: avgEventLoopDelay,
+      pagesVisited: this.pagesVisited,
+      interactionsExecuted: this.interactionsExecuted
+    });
+    
+    // Keep only last 1000 samples to avoid memory bloat
+    if (this.samples.length > 1000) {
+      this.samples.shift();
+    }
+    
+    // Reset event loop delays array periodically
+    if (this.eventLoopDelays.length > 100) {
+      this.eventLoopDelays = this.eventLoopDelays.slice(-50);
+    }
+  }
+  
+  /**
+   * Start a phase
+   */
+  startPhase(phaseName) {
+    this.phaseStartTimes[phaseName] = performance.now();
+  }
+  
+  /**
+   * End a phase
+   */
+  endPhase(phaseName) {
+    if (this.phaseStartTimes[phaseName]) {
+      const duration = performance.now() - this.phaseStartTimes[phaseName];
+      this.phaseDurations[phaseName] = (this.phaseDurations[phaseName] || 0) + duration;
+      delete this.phaseStartTimes[phaseName];
+    }
+  }
+  
+  /**
+   * Increment pages visited
+   */
+  incrementPages() {
+    this.pagesVisited++;
+    this.sample('PAGE_VISIT');
+  }
+  
+  /**
+   * Increment interactions executed
+   */
+  incrementInteractions() {
+    this.interactionsExecuted++;
+    this.sample('INTERACTION');
+  }
+  
+  /**
+   * Get current metrics
+   */
+  getCurrentMetrics() {
+    const now = performance.now();
+    const memory = process.memoryUsage();
+    const avgEventLoopDelay = this.eventLoopDelays.length > 0
+      ? this.eventLoopDelays.reduce((a, b) => a + b, 0) / this.eventLoopDelays.length
+      : 0;
+    
+    return {
+      runtimeMs: now - this.startTime,
+      memoryRSS: memory.rss,
+      memoryHeapUsed: memory.heapUsed,
+      memoryHeapTotal: memory.heapTotal,
+      peakMemoryRSS: this.peakMemoryRSS,
+      peakMemoryHeapUsed: this.peakMemoryHeapUsed,
+      peakEventLoopDelay: this.peakEventLoopDelay,
+      avgEventLoopDelay: avgEventLoopDelay,
+      pagesVisited: this.pagesVisited,
+      interactionsExecuted: this.interactionsExecuted,
+      phaseDurations: { ...this.phaseDurations }
+    };
+  }
+  
+  /**
+   * Get final report
+   */
+  getFinalReport() {
+    const metrics = this.getCurrentMetrics();
+    
+    // Find slow phases
+    const slowPhases = Object.entries(this.phaseDurations)
+      .filter(([_, duration]) => duration > 5000) // Phases > 5s
+      .map(([phase, duration]) => ({
+        phase,
+        durationMs: duration,
+        percentage: (duration / metrics.runtimeMs) * 100
+      }))
+      .sort((a, b) => b.durationMs - a.durationMs);
+    
+    return {
+      ...metrics,
+      slowPhases,
+      sampleCount: this.samples.length,
+      samples: this.samples.slice(-100) // Last 100 samples only
+    };
+  }
+  
+  /**
+   * Stop monitoring
+   */
+  stop() {
+    if (this.eventLoopMonitor) {
+      clearInterval(this.eventLoopMonitor);
+      this.eventLoopMonitor = null;
+    }
+  }
+}
+
+/**
+ * Create a performance monitor instance
+ */
+export function createPerformanceMonitor() {
+  return new PerformanceMonitor();
+}
+

package/src/verax/core/perf/perf.report.js

@@ -0,0 +1,200 @@
+/**
+ * PHASE 21.9 — Performance Report
+ * 
+ * Generates performance.report.json with budgets, actual usage, peaks, and violations.
+ */
+
+import { readFileSync, existsSync, writeFileSync, mkdirSync, statSync, readdirSync } from 'fs';
+import { resolve } from 'path';
+import { getPerfBudget, evaluatePerfBudget } from './perf.contract.js';
+
+/**
+ * Calculate artifacts size
+ * 
+ * @param {string} runDir - Run directory
+ * @returns {number} Size in MB
+ */
+function calculateArtifactsSize(runDir) {
+  let totalSize = 0;
+  
+  function scanDirectory(dir) {
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = resolve(dir, entry.name);
+        
+        if (entry.isDirectory()) {
+          scanDirectory(fullPath);
+        } else if (entry.isFile()) {
+          try {
+            const stats = statSync(fullPath);
+            totalSize += stats.size;
+          } catch {
+            // Skip unreadable files
+          }
+        }
+      }
+    } catch {
+      // Skip inaccessible directories
+    }
+  }
+  
+  if (existsSync(runDir)) {
+    scanDirectory(runDir);
+  }
+  
+  return totalSize / (1024 * 1024); // Convert to MB
+}
+
+/**
+ * Load pipeline stage timings from run.meta.json
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Stage timings or null
+ */
+function loadPipelineStageTimings(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const metaPath = resolve(runDir, 'run.meta.json');
+  
+  if (!existsSync(metaPath)) {
+    return null;
+  }
+  
+  try {
+  // @ts-expect-error - readFileSync with encoding returns string
+    const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
+    return meta.pipelineStages || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate performance report
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} monitorReport - Monitor report from PerformanceMonitor
+ * @param {string} profile - Budget profile name
+ * @returns {Object} Performance report
+ */
+export function generatePerformanceReport(projectDir, runId, monitorReport, profile = 'STANDARD') {
+  const budget = getPerfBudget(profile);
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  const artifactsSizeMB = calculateArtifactsSize(runDir);
+  
+  // Load pipeline stage timings
+  const pipelineStages = loadPipelineStageTimings(projectDir, runId);
+  
+  const actual = {
+    runtimeMs: monitorReport.runtimeMs,
+    memoryRSS: monitorReport.memoryRSS,
+    pagesVisited: monitorReport.pagesVisited,
+    interactionsExecuted: monitorReport.interactionsExecuted,
+    artifactsSizeMB: artifactsSizeMB,
+    eventLoopDelayMs: monitorReport.avgEventLoopDelay || 0
+  };
+  
+  const evaluation = evaluatePerfBudget(actual, budget);
+  
+  // Extract stage timings if available
+  const stageTimings = {};
+  if (pipelineStages) {
+    for (const [stageName, stageData] of Object.entries(pipelineStages)) {
+      if (stageData.durationMs !== null && stageData.durationMs !== undefined) {
+        stageTimings[stageName] = {
+          durationMs: stageData.durationMs,
+          startedAt: stageData.startedAt,
+          completedAt: stageData.completedAt,
+          status: stageData.status
+        };
+      }
+    }
+  }
+  
+  const report = {
+    contractVersion: 1,
+    runId,
+    profile,
+    budget: {
+      maxRuntimeMs: budget.maxRuntimeMs,
+      maxMemoryRSS: budget.maxMemoryRSS,
+      maxPagesVisited: budget.maxPagesVisited,
+      maxInteractionsExecuted: budget.maxInteractionsExecuted,
+      maxArtifactsSizeMB: budget.maxArtifactsSizeMB,
+      maxEventLoopDelayMs: budget.maxEventLoopDelayMs
+    },
+    actual,
+    peaks: {
+      memoryRSS: monitorReport.peakMemoryRSS,
+      memoryHeapUsed: monitorReport.peakMemoryHeapUsed,
+      memoryHeapTotal: monitorReport.peakMemoryHeapTotal,
+      eventLoopDelay: monitorReport.peakEventLoopDelay
+    },
+    stageTimings: Object.keys(stageTimings).length > 0 ? stageTimings : null,
+    networkRequests: monitorReport.networkRequests || 0,
+    violations: evaluation.violations,
+    warnings: evaluation.warnings,
+    verdict: evaluation.verdict,
+    ok: evaluation.ok,
+    summary: {
+      ...evaluation.summary,
+      runtimeMs: actual.runtimeMs,
+      memoryRSSMB: (actual.memoryRSS / (1024 * 1024)).toFixed(2),
+      pagesVisited: actual.pagesVisited,
+      networkRequests: monitorReport.networkRequests || 0,
+      interactionsExecuted: actual.interactionsExecuted,
+      artifactsSizeMB: actual.artifactsSizeMB.toFixed(2),
+      slowPhases: monitorReport.slowPhases || []
+    },
+    generatedAt: new Date().toISOString()
+  };
+  
+  return report;
+}
+
+/**
+ * Write performance report
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @param {Object} report - Performance report
+ * @returns {string} Path to written file
+ */
+export function writePerformanceReport(projectDir, runId, report) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  if (!existsSync(runDir)) {
+    mkdirSync(runDir, { recursive: true });
+  }
+  
+  const outputPath = resolve(runDir, 'performance.report.json');
+  writeFileSync(outputPath, JSON.stringify(report, null, 2), 'utf-8');
+  
+  return outputPath;
+}
+
+/**
+ * Load performance report
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Performance report or null
+ */
+export function loadPerformanceReport(projectDir, runId) {
+  const reportPath = resolve(projectDir, '.verax', 'runs', runId, 'performance.report.json');
+  
+  if (!existsSync(reportPath)) {
+    return null;
+  }
+  
+  try {
+    const content = readFileSync(reportPath, 'utf-8');
+  // @ts-expect-error - readFileSync with encoding returns string
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+