@veraxhq/verax 0.3.0 → 0.4.0

package/src/cli/util/dom-diff.js

@@ -0,0 +1,226 @@
+/**
+ * DOM Diff Engine
+ * Computes structured differences between HTML snapshots
+ * Distinguishes meaningful changes from noise
+ */
+
+/**
+ * Compute a diff between two HTML documents
+ * Returns a summary of changes without full tree comparison (for performance)
+ * Includes isMeaningful flag to distinguish signal from noise
+ */
+export function computeDOMDiff(htmlBefore, htmlAfter) {
+  const _before = parseHTML(htmlBefore);
+  const _after = parseHTML(htmlAfter);
+  
+  const diff = {
+    htmlLengthBefore: htmlBefore.length,
+    htmlLengthAfter: htmlAfter.length,
+    changed: htmlBefore !== htmlAfter,
+    isMeaningful: false,
+    elementsRemoved: [],
+    elementsAdded: [],
+    attributesChanged: [],
+    contentChanged: [],
+  };
+  
+  if (!diff.changed) {
+    return diff;
+  }
+  
+  // Check if this is only noise (timestamps, random ids, tracking)
+  if (isNoisyChangeOnly(htmlBefore, htmlAfter)) {
+    diff.changed = true;
+    diff.isMeaningful = false;
+    return diff;
+  }
+  
+  // Quick heuristics for specific changes
+  // Check for new elements with specific roles/classes that indicate feedback
+  const feedbackPatterns = [
+    'role="alert"',
+    'role="status"',
+    'aria-live',
+    'class="toast"',
+    'class="error"',
+    'class="success"',
+    'class="modal"',
+    'class="dialog"',
+    '[data-error]',
+    '[data-success]',
+  ];
+  
+  for (const pattern of feedbackPatterns) {
+    if (!htmlBefore.includes(pattern) && htmlAfter.includes(pattern)) {
+      diff.elementsAdded.push(pattern);
+      diff.isMeaningful = true;
+    }
+    if (htmlBefore.includes(pattern) && !htmlAfter.includes(pattern)) {
+      diff.elementsRemoved.push(pattern);
+      diff.isMeaningful = true;
+    }
+  }
+  
+  // Check for attribute changes (disabled, aria-invalid, etc.)
+  const attrPatterns = [
+    'disabled',
+    'aria-invalid',
+    'aria-disabled',
+    'data-loading',
+  ];
+  
+  for (const attr of attrPatterns) {
+    const beforeCount = countOccurrences(htmlBefore, attr);
+    const afterCount = countOccurrences(htmlAfter, attr);
+    
+    if (beforeCount !== afterCount) {
+      diff.attributesChanged.push({
+        attribute: attr,
+        before: beforeCount,
+        after: afterCount,
+      });
+      diff.isMeaningful = true;
+    }
+  }
+  
+  // Check for form state changes (values, structure)
+  if (checkFormStateChange(htmlBefore, htmlAfter)) {
+    diff.isMeaningful = true;
+  }
+  
+  return diff;
+}
+
+/**
+ * Parse HTML and return basic structure info
+ */
+function parseHTML(html) {
+  return {
+    bodyLength: html.length,
+    hasHead: html.includes('<head'),
+    hasBody: html.includes('<body'),
+    formCount: countOccurrences(html, '<form'),
+    inputCount: countOccurrences(html, '<input'),
+    buttonCount: countOccurrences(html, '<button'),
+  };
+}
+
+/**
+ * Count occurrences of a substring
+ */
+function countOccurrences(str, substr) {
+  let count = 0;
+  let pos = 0;
+  while ((pos = str.indexOf(substr, pos)) !== -1) {
+    count++;
+    pos += substr.length;
+  }
+  return count;
+}
+
+/**
+ * Detect if DOM appears to have feedback elements
+ */
+export function hasFeedbackElements(html) {
+  const feedbackIndicators = [
+    'role="alert"',
+    'role="status"',
+    'aria-live="polite"',
+    'aria-live="assertive"',
+    'toast',
+    'error',
+    'success',
+    'validation',
+  ];
+  
+  return feedbackIndicators.some(indicator => 
+    html.includes(indicator)
+  );
+}
+
+/**
+ * Detect if DOM appears to have validation errors
+ */
+export function hasValidationErrors(html) {
+  const errorPatterns = [
+    'aria-invalid="true"',
+    'aria-invalid=\'true\'',
+    'invalid',
+    'error',
+    'required',
+  ];
+  
+  return errorPatterns.some(pattern => html.includes(pattern));
+}
+
+/**
+ * Check if the HTML change is only noise (timestamps, random IDs, tracking pixels)
+ * Returns true if ONLY noise detected, false if meaningful changes exist
+ */
+function isNoisyChangeOnly(htmlBefore, htmlAfter) {
+  // Make a copy and remove known noise patterns
+  let before = htmlBefore;
+  let after = htmlAfter;
+  
+  // Remove timestamps (ISO, Unix, etc.)
+  const timestampPattern = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[^"']*/g;
+  before = before.replace(timestampPattern, '[TIMESTAMP]');
+  after = after.replace(timestampPattern, '[TIMESTAMP]');
+  
+  // Remove UUID-like patterns
+  const uuidPattern = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+  before = before.replace(uuidPattern, '[UUID]');
+  after = after.replace(uuidPattern, '[UUID]');
+  
+  // Remove random hash-like values
+  const hashPattern = /[a-f0-9]{32,}/g;
+  before = before.replace(hashPattern, '[HASH]');
+  after = after.replace(hashPattern, '[HASH]');
+  
+  // Remove tracking params (ga, fbclid, etc.)
+  const trackingPattern = /[?&](ga[a-z_]*|fbclid|utm_[a-z]*|gclid|msclkid)=[^&"']*/g;
+  before = before.replace(trackingPattern, '[TRACKING]');
+  after = after.replace(trackingPattern, '[TRACKING]');
+  
+  // Remove data-testid and similar noise attrs
+  const testIdPattern = /data-testid="[^"]*"/g;
+  before = before.replace(testIdPattern, '');
+  after = after.replace(testIdPattern, '');
+  
+  // If they're now equal, it was only noise
+  return before === after;
+}
+
+/**
+ * Check for meaningful form state changes
+ */
+function checkFormStateChange(htmlBefore, htmlAfter) {
+  // Check for form input value changes (meaningful state change)
+  const beforeInputs = extractInputValues(htmlBefore);
+  const afterInputs = extractInputValues(htmlAfter);
+  
+  if (beforeInputs.size !== afterInputs.size) {
+    return true;
+  }
+  
+  for (const [key, value] of beforeInputs) {
+    if (afterInputs.get(key) !== value) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Extract input name-value pairs from HTML
+ */
+function extractInputValues(html) {
+  const values = new Map();
+  const inputPattern = /<input[^>]*name="([^"]*)"[^>]*value="([^"]*)"/g;
+  let match;
+  while ((match = inputPattern.exec(html)) !== null) {
+    values.set(match[1], match[2]);
+  }
+  return values;
+}

package/src/cli/util/env-url.js

@@ -1,11 +1,7 @@
-import { assertExecutionBootstrapAllowed } from './bootstrap-guard.js';
-
 /**
  * Attempt to infer URL from environment variables and common dev configs
  */
 export function tryResolveUrlFromEnv() {
-  // PHASE 21.6.1: Runtime guard - crash if called during inspection
-  assertExecutionBootstrapAllowed('tryResolveUrlFromEnv');
   // Check common environment variables
   const candidates = [
     process.env.VERCEL_URL,

package/src/cli/util/evidence-engine.js

@@ -0,0 +1,287 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { resolve } from 'path';
+import { computeDOMDiff, hasFeedbackElements as _hasFeedbackElements, hasValidationErrors as _hasValidationErrors } from './dom-diff.js';
+
+/**
+ * Evidence Engine
+ * Captures and bundles evidence for each interaction attempt
+ */
+
+export class EvidenceBundle {
+  constructor(promiseId, expNum, evidencePath) {
+    this.promiseId = promiseId;
+    this.expNum = expNum;
+    this.evidencePath = evidencePath;
+    this.beforeScreenshot = null;
+    this.afterScreenshot = null;
+    this.beforeHTML = null;
+    this.afterHTML = null;
+    this.domDiff = null;
+    this.networkEvents = [];
+    this.networkEventsByTime = new Map(); // For correlation
+    this.consoleErrors = [];
+    this.actionStartTime = null; // When action was executed
+    this.timing = {
+      startedAt: null,
+      endedAt: null,
+    };
+    this.signals = {
+      navigationChanged: false,
+      domChanged: false,
+      feedbackSeen: false,
+      networkActivity: false,
+      consoleErrors: false,
+      meaningfulDomChange: false, // NEW: tracks only meaningful changes
+      correlatedNetworkActivity: false, // NEW: tracks network within action window
+    };
+    this.files = [];
+    this.correlatedRequests = []; // Network requests correlated to this action
+  }
+  
+  /**
+   * Capture before state
+   */
+  async captureBeforeState(page, suffix = '') {
+    try {
+      this.beforeScreenshot = `exp_${this.expNum}_before${suffix}.png`;
+      const screenshotPath = resolve(this.evidencePath, this.beforeScreenshot);
+      await page.screenshot({ path: screenshotPath });
+      this.files.push(this.beforeScreenshot);
+    } catch (e) {
+      this.beforeScreenshot = null;
+    }
+    
+    try {
+      this.beforeHTML = await page.content();
+    } catch (e) {
+      this.beforeHTML = null;
+    }
+  }
+  
+  /**
+   * Capture after state
+   */
+  async captureAfterState(page, suffix = '') {
+    try {
+      this.afterScreenshot = `exp_${this.expNum}_after${suffix}.png`;
+      const screenshotPath = resolve(this.evidencePath, this.afterScreenshot);
+      await page.screenshot({ path: screenshotPath });
+      this.files.push(this.afterScreenshot);
+    } catch (e) {
+      this.afterScreenshot = null;
+    }
+    
+    try {
+      this.afterHTML = await page.content();
+    } catch (e) {
+      this.afterHTML = null;
+    }
+  }
+  
+  /**
+   * Analyze changes between before and after
+   */
+  analyzeChanges(urlBefore, urlAfter) {
+    // Navigation change
+    if (urlBefore && urlAfter && urlBefore !== urlAfter) {
+      this.signals.navigationChanged = true;
+    }
+    
+    // DOM change
+    if (this.beforeHTML && this.afterHTML) {
+      this.domDiff = computeDOMDiff(this.beforeHTML, this.afterHTML);
+      if (this.domDiff.changed) {
+        this.signals.domChanged = true;
+      }
+      
+      // Track meaningful changes separately
+      if (this.domDiff.isMeaningful) {
+        this.signals.meaningfulDomChange = true;
+      }
+      
+      // Check for feedback elements visibility change
+      if (detectNewFeedback(this.beforeHTML, this.afterHTML)) {
+        this.signals.feedbackSeen = true;
+      }
+      
+      // Check for validation error appearance
+      if (detectNewValidationError(this.beforeHTML, this.afterHTML)) {
+        this.signals.feedbackSeen = true;
+      }
+    }
+  }
+  
+  /**
+   * Record network events that occurred during this action
+   */
+  recordNetworkEvent(networkLog) {
+    this.networkEvents.push(networkLog);
+    
+    // Track event time for correlation
+    if (networkLog.startTime) {
+      this.networkEventsByTime.set(networkLog.startTime, networkLog);
+    }
+    
+    if (this.networkEvents.length > 0) {
+      this.signals.networkActivity = true;
+    }
+  }
+  
+  /**
+   * Correlate network events to this action
+   * Captures requests that started within correlation window after action
+   * Window: 0-2500ms after action starts
+   */
+  correlateNetworkRequests() {
+    if (!this.actionStartTime || this.networkEvents.length === 0) {
+      return;
+    }
+    
+    const actionTime = new Date(this.actionStartTime).getTime();
+    const correlationWindow = 2500; // milliseconds
+    
+    for (const event of this.networkEvents) {
+      if (event.startTime) {
+        const eventTime = new Date(event.startTime).getTime();
+        if (eventTime >= actionTime && eventTime <= actionTime + correlationWindow) {
+          this.correlatedRequests.push(event);
+          this.signals.correlatedNetworkActivity = true;
+        }
+      }
+    }
+  }
+  
+  /**
+   * Record console errors
+   */
+  recordConsoleError(error) {
+    this.consoleErrors.push(error);
+    if (this.consoleErrors.length > 0) {
+      this.signals.consoleErrors = true;
+    }
+  }
+  
+  /**
+   * Finalize evidence bundle
+   */
+  finalize(_page) {
+    this.timing.endedAt = new Date().toISOString();
+    
+    // Persist evidence files
+    try {
+      mkdirSync(this.evidencePath, { recursive: true });
+      
+      // Save DOM diff if available
+      if (this.domDiff) {
+        const diffFile = `exp_${this.expNum}_dom_diff.json`;
+        writeFileSync(
+          resolve(this.evidencePath, diffFile),
+          JSON.stringify(this.domDiff, null, 2),
+          'utf-8'
+        );
+        this.files.push(diffFile);
+      }
+      
+      // Save network events if any
+      if (this.networkEvents.length > 0) {
+        const netFile = `exp_${this.expNum}_network.json`;
+        writeFileSync(
+          resolve(this.evidencePath, netFile),
+          JSON.stringify(this.networkEvents, null, 2),
+          'utf-8'
+        );
+        this.files.push(netFile);
+      }
+      
+      // Save console errors if any
+      if (this.consoleErrors.length > 0) {
+        const errFile = `exp_${this.expNum}_console_errors.json`;
+        writeFileSync(
+          resolve(this.evidencePath, errFile),
+          JSON.stringify(this.consoleErrors, null, 2),
+          'utf-8'
+        );
+        this.files.push(errFile);
+      }
+    } catch (e) {
+      // Best effort
+    }
+  }
+  
+  /**
+   * Check if we have meaningful evidence
+   */
+  hasEvidence() {
+    return (
+      this.beforeScreenshot ||
+      this.afterScreenshot ||
+      this.domDiff?.changed ||
+      this.networkEvents.length > 0 ||
+      this.consoleErrors.length > 0 ||
+      Object.values(this.signals).some(v => v === true)
+    );
+  }
+  
+  /**
+   * Summarize signals for observation
+   */
+  getSummary() {
+    return {
+      files: this.files,
+      timing: this.timing,
+      signals: this.signals,
+      hasEvidence: this.hasEvidence(),
+    };
+  }
+}
+
+/**
+ * Create a bundle for a promise
+ */
+export function createEvidenceBundle(promise, expNum, evidencePath) {
+  return new EvidenceBundle(promise.id, expNum, evidencePath);
+}
+
+/**
+ * Detect if new feedback elements appeared
+ */
+function detectNewFeedback(htmlBefore, htmlAfter) {
+  const feedbackPatterns = [
+    'role="alert"',
+    'role="status"',
+    'aria-live="polite"',
+    'aria-live="assertive"',
+    'class="toast"',
+    'class="modal"',
+    'class="dialog"',
+  ];
+  
+  for (const pattern of feedbackPatterns) {
+    if (!htmlBefore.includes(pattern) && htmlAfter.includes(pattern)) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Detect if new validation errors appeared
+ */
+function detectNewValidationError(htmlBefore, htmlAfter) {
+  const errorPatterns = [
+    'aria-invalid="true"',
+    'aria-invalid=\'true\'',
+    'class="error"',
+    'class="invalid"',
+    '[data-error]',
+  ];
+  
+  for (const pattern of errorPatterns) {
+    if (!htmlBefore.includes(pattern) && htmlAfter.includes(pattern)) {
+      return true;
+    }
+  }
+  
+  return false;
+}