vibecheck-ai 2.0.2 → 5.0.0

package/bin/runners/lib/reality/safety-rails.js

@@ -0,0 +1,463 @@
+/**
+ * Safety Rails v2
+ * 
+ * False-positive prevention for UI change detection.
+ * Handles hydration suppression, action stabilization, duplicate filtering.
+ */
+
+"use strict";
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+const DEFAULT_CONFIG = {
+  // Hydration suppression
+  hydration: {
+    suppressionWindowMs: 2000,    // Ignore changes in first 2s after navigation
+    ignoreInitialRender: true,
+  },
+  
+  // Action stabilization
+  stabilization: {
+    quietMs: 300,                 // Wait for no DOM mutations
+    settleMs: 250,                // Wait after action before snapshot
+    actionWindowMs: 8000,         // Max wait for action effects
+    networkIdleMs: 500,           // Wait for network idle
+  },
+  
+  // Duplicate filtering
+  duplicates: {
+    debounceMs: 100,              // Ignore repeated clicks within 100ms
+    sameElementDebounceMs: 500,   // Same element clicks
+  },
+  
+  // Toast filtering
+  toast: {
+    maxLifetimeMs: 15000,         // Ignore persistent banners
+    minVisibleMs: 100,            // Ignore flash toasts
+  },
+  
+  // Ignore selectors (user configurable)
+  ignoreSelectors: [
+    "[data-hydration]",
+    "[data-nextjs-scroll-focus-boundary]",
+    "nextjs-portal",
+    "#__next-build-watcher",
+    "#__next-prerender-indicator",
+    ".dev-overlay",
+    "[data-hot-reload]",
+  ],
+  
+  // Text noise patterns (timestamps, counters)
+  textNoisePatterns: [
+    /^\d{1,2}:\d{2}(:\d{2})?\s*(AM|PM)?$/i,     // 12:34, 12:34:56, 12:34 PM
+    /^\d+(\.\d+)?\s*(s|ms|sec|seconds?)$/i,      // 3s, 100ms
+    /^(just now|now|ago|\d+\s*(min|hour|day)s?\s*ago)$/i,
+    /^\d+$/,                                      // Pure numbers
+  ],
+};
+
+// =============================================================================
+// HYDRATION SUPPRESSION
+// =============================================================================
+
+/**
+ * Create hydration tracker for a page
+ */
+function createHydrationTracker(options = {}) {
+  const config = { ...DEFAULT_CONFIG.hydration, ...options };
+  
+  return {
+    navigationTime: null,
+    isHydrating: false,
+    
+    /**
+     * Mark navigation start
+     */
+    startNavigation() {
+      this.navigationTime = Date.now();
+      this.isHydrating = true;
+    },
+    
+    /**
+     * Check if still in hydration window
+     */
+    inHydrationWindow() {
+      if (!this.navigationTime || !config.ignoreInitialRender) {
+        return false;
+      }
+      const elapsed = Date.now() - this.navigationTime;
+      return elapsed < config.suppressionWindowMs;
+    },
+    
+    /**
+     * Mark hydration complete (e.g., after first meaningful paint)
+     */
+    markHydrationComplete() {
+      this.isHydrating = false;
+    },
+    
+    /**
+     * Should suppress this change?
+     */
+    shouldSuppress(change) {
+      if (!this.inHydrationWindow()) return false;
+      
+      // During hydration, suppress semantic-only changes
+      // Still allow route changes and toasts
+      if (change.routeChanged) return false;
+      if (change.reasons?.includes("toast_success") || change.reasons?.includes("toast_error")) {
+        return false;
+      }
+      
+      return true;
+    },
+  };
+}
+
+// =============================================================================
+// ACTION STABILIZATION
+// =============================================================================
+
+/**
+ * Create action stabilizer for DOM mutations
+ */
+function createActionStabilizer(page, options = {}) {
+  const config = { ...DEFAULT_CONFIG.stabilization, ...options };
+  
+  return {
+    mutationCount: 0,
+    lastMutationTime: 0,
+    pendingRequests: new Set(),
+    
+    /**
+     * Wait for DOM to be quiet before action
+     */
+    async waitForQuiet() {
+      const startTime = Date.now();
+      
+      while (Date.now() - startTime < config.quietMs * 3) {
+        // Check if DOM has been quiet
+        const timeSinceLastMutation = Date.now() - this.lastMutationTime;
+        const hasPendingRequests = this.pendingRequests.size > 0;
+        
+        if (timeSinceLastMutation >= config.quietMs && !hasPendingRequests) {
+          return { stable: true, waitedMs: Date.now() - startTime };
+        }
+        
+        await sleep(50);
+      }
+      
+      return { stable: false, waitedMs: Date.now() - startTime };
+    },
+    
+    /**
+     * Wait for effects after action
+     */
+    async waitForSettle() {
+      await sleep(config.settleMs);
+      
+      // Additional wait if network is active
+      if (this.pendingRequests.size > 0) {
+        const networkStart = Date.now();
+        while (this.pendingRequests.size > 0 && Date.now() - networkStart < config.networkIdleMs) {
+          await sleep(50);
+        }
+      }
+    },
+    
+    /**
+     * Record mutation
+     */
+    recordMutation() {
+      this.mutationCount++;
+      this.lastMutationTime = Date.now();
+    },
+    
+    /**
+     * Track request start
+     */
+    trackRequestStart(requestId) {
+      this.pendingRequests.add(requestId);
+    },
+    
+    /**
+     * Track request end
+     */
+    trackRequestEnd(requestId) {
+      this.pendingRequests.delete(requestId);
+    },
+    
+    /**
+     * Reset for new action
+     */
+    reset() {
+      this.mutationCount = 0;
+      this.lastMutationTime = Date.now();
+    },
+  };
+}
+
+// =============================================================================
+// DUPLICATE ACTION FILTERING
+// =============================================================================
+
+/**
+ * Create duplicate action filter
+ */
+function createDuplicateFilter(options = {}) {
+  const config = { ...DEFAULT_CONFIG.duplicates, ...options };
+  const recentActions = [];
+  
+  return {
+    /**
+     * Check if action is duplicate
+     */
+    isDuplicate(action) {
+      const now = Date.now();
+      
+      // Clean old entries
+      while (recentActions.length > 0 && now - recentActions[0].time > config.sameElementDebounceMs) {
+        recentActions.shift();
+      }
+      
+      // Check for duplicate
+      const isDupe = recentActions.some(recent => {
+        const timeDiff = now - recent.time;
+        
+        // Same element within debounce window
+        if (recent.selector === action.selector && timeDiff < config.sameElementDebounceMs) {
+          return true;
+        }
+        
+        // Any click within short debounce
+        if (timeDiff < config.debounceMs) {
+          return true;
+        }
+        
+        return false;
+      });
+      
+      // Record this action
+      recentActions.push({
+        selector: action.selector,
+        type: action.type,
+        time: now,
+      });
+      
+      return isDupe;
+    },
+    
+    /**
+     * Clear history
+     */
+    clear() {
+      recentActions.length = 0;
+    },
+  };
+}
+
+// =============================================================================
+// TOAST FALSE-POSITIVE FILTERING
+// =============================================================================
+
+/**
+ * Filter toast false positives
+ */
+function filterToastFalsePositives(toasts, options = {}) {
+  const config = { ...DEFAULT_CONFIG.toast, ...options };
+  
+  return toasts.filter(toast => {
+    // Ignore if visible too long (persistent banner)
+    if (toast.visibleDuration && toast.visibleDuration > config.maxLifetimeMs) {
+      return false;
+    }
+    
+    // Ignore if flash (too short to be intentional)
+    if (toast.visibleDuration && toast.visibleDuration < config.minVisibleMs) {
+      return false;
+    }
+    
+    // Ignore common false positive patterns
+    const text = (toast.message || "").toLowerCase();
+    const falsePositivePatterns = [
+      /cookie.*consent/i,
+      /accept.*cookies/i,
+      /privacy.*policy/i,
+      /subscribe.*newsletter/i,
+      /sign.*up.*newsletter/i,
+      /promotional/i,
+    ];
+    
+    if (falsePositivePatterns.some(p => p.test(text))) {
+      return false;
+    }
+    
+    return true;
+  });
+}
+
+// =============================================================================
+// TEXT NOISE FILTERING
+// =============================================================================
+
+/**
+ * Check if text is noise (timestamp, counter, etc.)
+ */
+function isTextNoise(text, options = {}) {
+  const patterns = options.textNoisePatterns || DEFAULT_CONFIG.textNoisePatterns;
+  
+  const trimmed = (text || "").trim();
+  if (!trimmed) return true;
+  
+  return patterns.some(pattern => pattern.test(trimmed));
+}
+
+/**
+ * Filter noise from semantic diff
+ */
+function filterSemanticDiffNoise(diff, options = {}) {
+  const filtered = {
+    added: diff.added?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
+    removed: diff.removed?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
+    changed: diff.changed?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
+  };
+  
+  // Preserve original flags
+  filtered.routeChanged = diff.routeChanged;
+  filtered.dialogOpened = diff.dialogOpened;
+  filtered.dialogClosed = diff.dialogClosed;
+  filtered.errorsChanged = diff.errorsChanged;
+  filtered.errorDelta = diff.errorDelta;
+  
+  return filtered;
+}
+
+function extractTextFromDiffItem(item) {
+  // "button: Save" -> "Save"
+  const match = item.match(/:\s*(.+)$/);
+  return match ? match[1] : item;
+}
+
+// =============================================================================
+// SELECTOR IGNORE LIST
+// =============================================================================
+
+/**
+ * Check if element should be ignored
+ */
+function shouldIgnoreElement(selector, options = {}) {
+  const ignoreSelectors = options.ignoreSelectors || DEFAULT_CONFIG.ignoreSelectors;
+  
+  if (!selector) return false;
+  
+  return ignoreSelectors.some(pattern => {
+    if (pattern.startsWith("[") || pattern.startsWith("#") || pattern.startsWith(".")) {
+      return selector.includes(pattern);
+    }
+    return selector === pattern;
+  });
+}
+
+/**
+ * Build ignore selector for Playwright
+ */
+function buildIgnoreSelector(options = {}) {
+  const ignoreSelectors = options.ignoreSelectors || DEFAULT_CONFIG.ignoreSelectors;
+  return ignoreSelectors.map(s => `:not(${s})`).join("");
+}
+
+// =============================================================================
+// MEANINGFUL CHANGE VALIDATION
+// =============================================================================
+
+/**
+ * Validate that a UI change is truly meaningful (with safety rails applied)
+ */
+function validateMeaningfulChange(uiChange, options = {}) {
+  const {
+    hydrationTracker = null,
+    meaningfulScoreThreshold = 0.6,
+  } = options;
+  
+  // Check hydration suppression
+  if (hydrationTracker?.shouldSuppress(uiChange)) {
+    return {
+      valid: false,
+      suppressed: true,
+      reason: "hydration_window",
+      original: uiChange,
+    };
+  }
+  
+  // Filter noise from diff
+  if (uiChange.semanticDiffSummary) {
+    uiChange.semanticDiffSummary = filterSemanticDiffNoise(uiChange.semanticDiffSummary, options);
+  }
+  
+  // Recalculate score after filtering
+  const filteredDiffSize = (uiChange.semanticDiffSummary?.added?.length || 0) +
+                           (uiChange.semanticDiffSummary?.removed?.length || 0) +
+                           (uiChange.semanticDiffSummary?.changed?.length || 0);
+  
+  // If only minor changes remain after filtering, downgrade
+  if (!uiChange.routeChanged && 
+      !uiChange.dialogOpened && 
+      !uiChange.dialogClosed &&
+      !uiChange.reasons?.some(r => r.startsWith("toast_")) &&
+      filteredDiffSize === 0) {
+    return {
+      valid: false,
+      suppressed: true,
+      reason: "noise_only",
+      original: uiChange,
+    };
+  }
+  
+  return {
+    valid: uiChange.meaningful || uiChange.score >= meaningfulScoreThreshold,
+    suppressed: false,
+    uiChange,
+  };
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+module.exports = {
+  // Configuration
+  DEFAULT_CONFIG,
+  
+  // Hydration
+  createHydrationTracker,
+  
+  // Stabilization
+  createActionStabilizer,
+  
+  // Duplicates
+  createDuplicateFilter,
+  
+  // Toast filtering
+  filterToastFalsePositives,
+  
+  // Text noise
+  isTextNoise,
+  filterSemanticDiffNoise,
+  
+  // Selector ignore
+  shouldIgnoreElement,
+  buildIgnoreSelector,
+  
+  // Validation
+  validateMeaningfulChange,
+};