@odavl/guardian 0.1.0-rc1

package/src/guardian/behavioral-signals.js

@@ -0,0 +1,261 @@
+/**
+ * Phase 5 — Behavioral Signal Detector
+ * Detects non-visual but UI-affecting changes that break user trust
+ */
+
+/**
+ * Detect behavioral changes (missing elements, layout shifts, disabled CTAs)
+ */
+class BehavioralSignalDetector {
+  constructor(options = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Check if critical element is visible and accessible
+   */
+  async checkElementVisibility(page, selector) {
+    try {
+      const element = await page.$(selector);
+      if (!element) {
+        return {
+          visible: false,
+          accessible: false,
+          signal: 'ELEMENT_MISSING',
+          severity: 'CRITICAL',
+          description: `Critical element not found: ${selector}`
+        };
+      }
+
+      const boundingBox = await element.boundingBox();
+      if (!boundingBox) {
+        return {
+          visible: false,
+          accessible: false,
+          signal: 'OFFSCREEN_ELEMENT',
+          severity: 'CRITICAL',
+          description: `Element off-screen: ${selector}`
+        };
+      }
+
+      const isHidden = await element.isHidden();
+      if (isHidden) {
+        return {
+          visible: false,
+          accessible: false,
+          signal: 'HIDDEN_ELEMENT',
+          severity: 'CRITICAL',
+          description: `Element hidden: ${selector}`
+        };
+      }
+
+      const isDisabled = await element.isDisabled();
+      if (isDisabled) {
+        return {
+          visible: true,
+          accessible: false,
+          signal: 'DISABLED_ELEMENT',
+          severity: 'WARNING',
+          description: `Element disabled: ${selector}`
+        };
+      }
+
+      return {
+        visible: true,
+        accessible: true,
+        signal: null,
+        severity: 'INFO'
+      };
+    } catch (err) {
+      return {
+        visible: false,
+        accessible: false,
+        signal: 'CHECK_FAILED',
+        severity: 'INFO',
+        description: `Check failed: ${err.message}`
+      };
+    }
+  }
+
+  /**
+   * Detect layout shifts - elements that moved unexpectedly
+   */
+  async detectLayoutShift(page, selectors) {
+    const shifts = [];
+
+    for (const selector of selectors) {
+      try {
+        const element = await page.$(selector);
+        if (!element) continue;
+
+        const boundingBox = await element.boundingBox();
+        if (!boundingBox) continue;
+
+        // Check if element is near viewport edges (shifted)
+        const viewportSize = page.viewportSize();
+        if (viewportSize) {
+          const { x, y, width, height } = boundingBox;
+
+          // Completely off-screen
+          if (x + width <= 0 || x >= viewportSize.width || y + height <= 0 || y >= viewportSize.height) {
+            shifts.push({
+              selector,
+              signal: 'OFFSCREEN_SHIFT',
+              severity: 'CRITICAL',
+              description: `Element shifted off-screen: ${selector}`,
+              position: { x, y, width, height }
+            });
+          }
+          // Partially off-screen
+          else if (x < 0 || y < 0 || x + width > viewportSize.width) {
+            shifts.push({
+              selector,
+              signal: 'PARTIAL_SHIFT',
+              severity: 'WARNING',
+              description: `Element partially shifted: ${selector}`,
+              position: { x, y, width, height }
+            });
+          }
+        }
+      } catch (err) {
+        // Silently skip errors
+      }
+    }
+
+    return shifts;
+  }
+
+  /**
+   * Check if critical CTA (button, link) is clickable
+   */
+  async checkCTAAccessibility(page, selector) {
+    try {
+      const element = await page.$(selector);
+      if (!element) {
+        return {
+          clickable: false,
+          signal: 'CTA_MISSING',
+          severity: 'CRITICAL',
+          description: `Call-to-action not found: ${selector}`
+        };
+      }
+
+      const isDisabled = await element.isDisabled();
+      if (isDisabled) {
+        return {
+          clickable: false,
+          signal: 'CTA_DISABLED',
+          severity: 'CRITICAL',
+          description: `CTA disabled unexpectedly: ${selector}`
+        };
+      }
+
+      const isHidden = await element.isHidden();
+      if (isHidden) {
+        return {
+          clickable: false,
+          signal: 'CTA_HIDDEN',
+          severity: 'CRITICAL',
+          description: `CTA hidden unexpectedly: ${selector}`
+        };
+      }
+
+      const isEnabled = await element.isEnabled();
+      if (!isEnabled) {
+        return {
+          clickable: false,
+          signal: 'CTA_UNAVAILABLE',
+          severity: 'CRITICAL',
+          description: `CTA unavailable: ${selector}`
+        };
+      }
+
+      return {
+        clickable: true,
+        signal: null,
+        severity: 'INFO'
+      };
+    } catch (err) {
+      return {
+        clickable: false,
+        signal: 'CHECK_FAILED',
+        severity: 'INFO',
+        description: `CTA check failed: ${err.message}`
+      };
+    }
+  }
+
+  /**
+   * Detect color/styling changes on critical elements
+   */
+  async detectStyleChanges(page, selector, expectedStyles = {}) {
+    const changes = [];
+
+    try {
+      const element = await page.$(selector);
+      if (!element) return changes;
+
+      for (const [property, expectedValue] of Object.entries(expectedStyles)) {
+        const actualValue = await element.evaluate((el, prop) => {
+          return window.getComputedStyle(el).getPropertyValue(prop);
+        }, property);
+
+        if (actualValue !== expectedValue) {
+          changes.push({
+            selector,
+            property,
+            expectedValue,
+            actualValue,
+            signal: 'STYLE_CHANGE',
+            severity: 'WARNING',
+            description: `Style changed: ${property} from ${expectedValue} to ${actualValue}`
+          });
+        }
+      }
+    } catch (err) {
+      // Silently skip
+    }
+
+    return changes;
+  }
+
+  /**
+   * Comprehensive behavioral audit
+   */
+  async auditBehavior(page, config) {
+    const signals = [];
+
+    // Check critical elements
+    if (config.criticalElements) {
+      for (const selector of config.criticalElements) {
+        const check = await this.checkElementVisibility(page, selector);
+        if (check.signal) signals.push(check);
+      }
+    }
+
+    // Check CTAs
+    if (config.criticalCTAs) {
+      for (const selector of config.criticalCTAs) {
+        const check = await this.checkCTAAccessibility(page, selector);
+        if (check.signal) signals.push(check);
+      }
+    }
+
+    // Check layout shifts
+    if (config.monitoredElements) {
+      const shifts = await this.detectLayoutShift(page, config.monitoredElements);
+      signals.push(...shifts);
+    }
+
+    return {
+      hasSignals: signals.length > 0,
+      signals,
+      criticalCount: signals.filter(s => s.severity === 'CRITICAL').length,
+      warningCount: signals.filter(s => s.severity === 'WARNING').length
+    };
+  }
+}
+
+module.exports = {
+  BehavioralSignalDetector
+};

package/src/guardian/breakage-intelligence.js

@@ -0,0 +1,223 @@
+/**
+ * Phase 4 — Breakage Intelligence
+ * Aggregate failure taxonomy and hints into actionable summaries
+ */
+
+const {
+  BREAK_TYPES,
+  IMPACT_DOMAINS,
+  SEVERITY_LEVELS,
+  getImpactDomain,
+  classifyBreakType,
+  determineSeverity
+} = require('./failure-taxonomy');
+const { deriveRootCauseHints } = require('./root-cause-analysis');
+
+/**
+ * Analyze a single attempt/flow failure and produce intelligence
+ * @param {Object} item - Attempt or flow result with outcome, error, validators, visualDiff, behavioralSignals, etc.
+ * @param {boolean} isFlow - true if this is a flow
+ * @returns {Object} Intelligence object with taxonomy, hints, actions
+ */
+function analyzeFailure(item, isFlow = false) {
+  if (!item || item.outcome === 'SUCCESS') {
+    return null;
+  }
+
+  const domain = getImpactDomain(isFlow ? item.flowId : item.attemptId);
+  const breakType = classifyBreakType(item);
+  const severity = determineSeverity(domain, breakType, isFlow);
+  const { hints, primaryHint } = deriveRootCauseHints(item, breakType);
+
+  // Phase 5: Include visual regression metadata
+  const intelligence = {
+    id: isFlow ? item.flowId : item.attemptId,
+    name: isFlow ? item.flowName : item.attemptName,
+    outcome: item.outcome,
+    breakType,
+    domain,
+    severity,
+    primaryHint,
+    hints,
+    whyItMatters: generateWhyItMatters(domain, severity, breakType),
+    topActions: generateTopActions(breakType, domain)
+  };
+
+  // Phase 5: Add visual regression details if available
+  if (item.visualDiff) {
+    intelligence.visualDiff = {
+      hasDiff: item.visualDiff.hasDiff,
+      percentChange: item.visualDiff.percentChange,
+      reason: item.visualDiff.reason,
+      diffRegions: item.visualDiff.diffRegions
+    };
+  }
+
+  // Phase 5: Add behavioral signals if available
+  if (item.behavioralSignals) {
+    intelligence.behavioralSignals = item.behavioralSignals;
+  }
+
+  return intelligence;
+}
+
+/**
+ * Generate 1–3 bullet "Why It Matters" summary
+ * @param {string} domain - IMPACT_DOMAIN
+ * @param {string} severity - SEVERITY_LEVEL
+ * @returns {string[]} Array of 1–3 bullets
+ */
+function generateWhyItMatters(domain, severity, breakType = null) {
+  const bullets = [];
+
+  // Domain-specific impact
+  if (domain === IMPACT_DOMAINS.REVENUE) {
+    bullets.push('🚨 Revenue impact: Checkout/payment flow is broken. Customers cannot complete purchases.');
+  } else if (domain === IMPACT_DOMAINS.LEAD) {
+    bullets.push('📉 Lead gen impact: Signup/contact flow is broken. Cannot capture customer interest.');
+  } else if (domain === IMPACT_DOMAINS.TRUST) {
+    bullets.push('⚠️  Trust impact: Auth/account flow is broken. Users cannot access their data.');
+  } else {
+    bullets.push('📊 UX impact: Core interaction is broken. User journey degraded.');
+  }
+
+  // Severity escalation
+  if (severity === SEVERITY_LEVELS.CRITICAL) {
+    bullets.push('🔴 CRITICAL: Escalate immediately. Page/API down or core feature broken.');
+  } else if (severity === SEVERITY_LEVELS.WARNING) {
+    bullets.push('🟡 WARNING: High priority. Fix before peak traffic to avoid customer impact.');
+  }
+
+  // Phase 5: Visual regression context
+  if (breakType === BREAK_TYPES.VISUAL) {
+    bullets.push('👁️  Visual regression: UI elements changed from baseline (CSS, layout, or styling).');
+    if (severity === SEVERITY_LEVELS.CRITICAL) {
+      bullets.push('Critical visual change may completely obscure content or block user interaction.');
+    } else if (severity === SEVERITY_LEVELS.WARNING) {
+      bullets.push('Visual change may degrade readability, accessibility, or user experience.');
+    }
+  }
+
+  return bullets;
+}
+
+/**
+ * Generate top 3 actionable next steps
+ * @param {string} breakType - BREAK_TYPE
+ * @param {string} domain - IMPACT_DOMAIN
+ * @returns {string[]} Array of 3 action strings
+ */
+function generateTopActions(breakType, domain) {
+  const actions = [];
+
+  // Break-type-specific actions
+  if (breakType === BREAK_TYPES.NAVIGATION || breakType === BREAK_TYPES.NETWORK) {
+    actions.push('1. Check server status and network logs for errors');
+    actions.push('2. Verify DNS and SSL certificate validity');
+    actions.push('3. Check CDN/load balancer for 5xx errors');
+  } else if (breakType === BREAK_TYPES.TIMEOUT) {
+    actions.push('1. Check server response times and database queries');
+    actions.push('2. Review recent deployments for performance regressions');
+    actions.push('3. Check if rate limiting is too strict');
+  } else if (breakType === BREAK_TYPES.VISUAL) {
+    // Phase 5: Visual-specific diagnostic actions
+    actions.push('1. Compare baseline screenshot to current; identify CSS/layout changes');
+    actions.push('2. Check recent CSS commits, theme changes, or Tailwind/Bootstrap updates');
+    actions.push('3. Validate element positioning using browser DevTools layout analysis');
+  } else if (breakType === BREAK_TYPES.VALIDATION) {
+    actions.push('1. Review frontend code for recent CSS/JS changes');
+    actions.push('2. Check browser console for JavaScript errors');
+    actions.push('3. Verify DOM selectors match current HTML structure');
+  } else if (breakType === BREAK_TYPES.SUBMISSION) {
+    actions.push('1. Check form validation rules and error messages');
+    actions.push('2. Verify backend API endpoint is reachable');
+    actions.push('3. Check for CORS or authentication failures');
+  } else if (breakType === BREAK_TYPES.CONSOLE) {
+    actions.push('1. Review browser console error logs');
+    actions.push('2. Check for third-party script failures');
+    actions.push('3. Verify API endpoints and authentication tokens');
+  } else {
+    actions.push('1. Check application logs for errors');
+    actions.push('2. Verify all dependencies are deployed');
+    actions.push('3. Check recent changes that might affect this flow');
+  }
+
+  return actions;
+}
+
+/**
+ * Aggregate all failures into intelligence summary
+ * @param {Array} attempts - Attempt results
+ * @param {Array} flows - Flow results
+ * @returns {Object} Summary with failures, by-domain counts, escalation signals
+ */
+function aggregateIntelligence(attempts = [], flows = []) {
+  const allFailures = [];
+  const byDomain = {
+    [IMPACT_DOMAINS.REVENUE]: [],
+    [IMPACT_DOMAINS.LEAD]: [],
+    [IMPACT_DOMAINS.TRUST]: [],
+    [IMPACT_DOMAINS.UX]: []
+  };
+  const bySeverity = {
+    [SEVERITY_LEVELS.CRITICAL]: [],
+    [SEVERITY_LEVELS.WARNING]: [],
+    [SEVERITY_LEVELS.INFO]: []
+  };
+
+  // Analyze attempts
+  for (const attempt of attempts) {
+    const intel = analyzeFailure(attempt, false);
+    if (intel) {
+      allFailures.push(intel);
+      byDomain[intel.domain].push(intel);
+      bySeverity[intel.severity].push(intel);
+    }
+  }
+
+  // Analyze flows (higher weight)
+  for (const flow of flows) {
+    const intel = analyzeFailure(flow, true);
+    if (intel) {
+      allFailures.push(intel);
+      byDomain[intel.domain].push(intel);
+      bySeverity[intel.severity].push(intel);
+    }
+  }
+
+  // Escalation signals
+  const escalationSignals = [];
+  if (bySeverity[SEVERITY_LEVELS.CRITICAL].length > 0) {
+    escalationSignals.push('CRITICAL failures detected - immediate action required');
+  }
+  if (byDomain[IMPACT_DOMAINS.REVENUE].length > 0) {
+    escalationSignals.push('REVENUE domain affected - financial impact likely');
+  }
+  if (
+    flows.filter(f => f.outcome === 'FAILURE').length > 0 ||
+    allFailures.filter(f => f.breakType === BREAK_TYPES.NETWORK || f.breakType === BREAK_TYPES.TIMEOUT).length > 0
+  ) {
+    escalationSignals.push('Infrastructure/availability issue indicated');
+  }
+
+  return {
+    totalFailures: allFailures.length,
+    failures: allFailures,
+    byDomain,
+    bySeverity,
+    escalationSignals,
+    criticalCount: bySeverity[SEVERITY_LEVELS.CRITICAL].length,
+    warningCount: bySeverity[SEVERITY_LEVELS.WARNING].length,
+    infoCount: bySeverity[SEVERITY_LEVELS.INFO].length
+  };
+}
+
+module.exports = {
+  analyzeFailure,
+  aggregateIntelligence,
+  generateWhyItMatters,
+  generateTopActions,
+  BREAK_TYPES,
+  IMPACT_DOMAINS,
+  SEVERITY_LEVELS
+};

package/src/guardian/browser.js

@@ -0,0 +1,92 @@
+const { chromium } = require('playwright');
+
+class GuardianBrowser {
+  constructor() {
+    this.browser = null;
+    this.context = null;
+    this.page = null;
+  }
+
+  async launch(timeout = 20000, options = {}) {
+    try {
+      const launchOptions = { 
+        headless: options.headless !== undefined ? options.headless : true,
+        args: options.args || []
+      };
+      
+      this.browser = await chromium.launch(launchOptions);
+      
+      const contextOptions = {
+        ...options,
+      };
+      
+      // Enable HAR recording if requested
+      if (options.recordHar) {
+        // Note: HAR path must be provided in the actual implementation
+        // For now, we'll prepare the context for HAR recording
+        contextOptions.recordHar = options.harPath ? { path: options.harPath } : undefined;
+      }
+      
+      this.context = await this.browser.newContext(contextOptions);
+      this.page = await this.context.newPage();
+      this.page.setDefaultTimeout(timeout);
+      return true;
+    } catch (err) {
+      throw new Error(`Failed to launch browser: ${err.message}`);
+    }
+  }
+
+  async navigate(url, timeout = 20000) {
+    try {
+      const response = await this.page.goto(url, {
+        waitUntil: 'networkidle',
+        timeout
+      });
+      
+      return {
+        success: true,
+        status: response?.status() || 200,
+        url: this.page.url()
+      };
+    } catch (err) {
+      return {
+        success: false,
+        status: null,
+        error: err.message
+      };
+    }
+  }
+
+  async getLinks() {
+    try {
+      const links = await this.page.locator('a[href]').evaluateAll(elements =>
+        elements.map(el => ({
+          href: el.href,
+          text: el.innerText?.trim() || ''
+        }))
+      );
+      return links;
+    } catch (err) {
+      return [];
+    }
+  }
+
+  async takeScreenshot(filePath) {
+    try {
+      await this.page.screenshot({ path: filePath });
+      return true;
+    } catch (err) {
+      return false;
+    }
+  }
+
+  async close() {
+    try {
+      if (this.browser) await this.browser.close();
+    } catch (err) {
+      // Ignore close errors
+    }
+  }
+}
+
+module.exports = { GuardianBrowser };