@vibecheckai/cli 3.0.4 → 3.0.7

package/bin/runners/lib/reality/semantic-snapshot.js

@@ -0,0 +1,408 @@
+/**
+ * Semantic Snapshot v2
+ * 
+ * Creates stable, lightweight UI fingerprints for meaningful change detection.
+ * Captures accessible DOM features while filtering noise.
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const IGNORE_TAGS = new Set([
+  "script", "style", "link", "meta", "noscript", "template"
+]);
+
+const IGNORE_SELECTORS = [
+  "[data-hydration]",
+  "[data-nextjs-scroll-focus-boundary]",
+  "nextjs-portal",
+  "[data-overlay-container]",
+  "#__next-build-watcher",
+  "#__next-prerender-indicator",
+];
+
+const MEANINGFUL_ROLES = new Set([
+  "button", "link", "textbox", "checkbox", "radio", "combobox",
+  "listbox", "menu", "menuitem", "tab", "tabpanel", "dialog",
+  "alert", "alertdialog", "status", "progressbar", "form",
+  "navigation", "main", "region", "banner", "contentinfo"
+]);
+
+const TIMESTAMP_REGEX = /^\d{1,2}:\d{2}(:\d{2})?\s*(AM|PM)?$/i;
+const TIMER_REGEX = /^\d+(\.\d+)?\s*(s|ms|sec|seconds?)$/i;
+
+// =============================================================================
+// SEMANTIC SNAPSHOT CAPTURE (runs in browser context)
+// =============================================================================
+
+/**
+ * Playwright script to capture semantic snapshot
+ * Inject this into page.evaluate()
+ */
+const CAPTURE_SCRIPT = `
+(function captureSemanticSnapshot(options = {}) {
+  const {
+    regions = ['main', '#__next', '[role="main"]', 'body'],
+    includeDialogs = true,
+    maxTextLength = 80,
+    ignoreTimestamps = true,
+  } = options;
+
+  const IGNORE_TAGS = new Set(['script', 'style', 'link', 'meta', 'noscript', 'template', 'svg']);
+  const TIMESTAMP_RE = /^\\d{1,2}:\\d{2}(:\\d{2})?\\s*(AM|PM)?$/i;
+  const TIMER_RE = /^\\d+(\\.\\d+)?\\s*(s|ms|sec|seconds?)$/i;
+
+  function normalizeText(text) {
+    if (!text) return '';
+    let t = text.trim().replace(/\\s+/g, ' ');
+    if (t.length > maxTextLength) t = t.slice(0, maxTextLength) + '...';
+    return t;
+  }
+
+  function isTimestamp(text) {
+    if (!ignoreTimestamps) return false;
+    return TIMESTAMP_RE.test(text) || TIMER_RE.test(text);
+  }
+
+  function getAccessibleName(el) {
+    // aria-label takes precedence
+    if (el.getAttribute('aria-label')) return normalizeText(el.getAttribute('aria-label'));
+    // aria-labelledby
+    const labelledBy = el.getAttribute('aria-labelledby');
+    if (labelledBy) {
+      const labelEl = document.getElementById(labelledBy);
+      if (labelEl) return normalizeText(labelEl.textContent);
+    }
+    // For inputs, check associated label
+    if (el.id) {
+      const label = document.querySelector('label[for="' + el.id + '"]');
+      if (label) return normalizeText(label.textContent);
+    }
+    // Fallback to text content for buttons/links
+    if (['BUTTON', 'A'].includes(el.tagName)) {
+      return normalizeText(el.textContent);
+    }
+    return '';
+  }
+
+  function getRole(el) {
+    if (el.getAttribute('role')) return el.getAttribute('role');
+    // Infer from tag
+    const tag = el.tagName.toLowerCase();
+    const roleMap = {
+      button: 'button', a: 'link', input: 'textbox',
+      select: 'combobox', textarea: 'textbox', nav: 'navigation',
+      main: 'main', header: 'banner', footer: 'contentinfo',
+      dialog: 'dialog', form: 'form', img: 'img'
+    };
+    if (roleMap[tag]) return roleMap[tag];
+    if (tag === 'input') {
+      const type = el.type?.toLowerCase();
+      if (type === 'checkbox') return 'checkbox';
+      if (type === 'radio') return 'radio';
+      if (type === 'submit' || type === 'button') return 'button';
+    }
+    return null;
+  }
+
+  function extractNode(el) {
+    if (!el || el.nodeType !== 1) return null;
+    if (IGNORE_TAGS.has(el.tagName.toLowerCase())) return null;
+    if (el.hidden || el.getAttribute('aria-hidden') === 'true') return null;
+    
+    const style = window.getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return null;
+
+    const role = getRole(el);
+    const name = getAccessibleName(el);
+    
+    // Skip if text looks like timestamp
+    if (name && isTimestamp(name)) return null;
+
+    const node = {
+      tag: el.tagName.toLowerCase(),
+      role: role,
+      name: name || undefined,
+      disabled: el.disabled || el.getAttribute('aria-disabled') === 'true' || undefined,
+      invalid: el.getAttribute('aria-invalid') === 'true' || undefined,
+      href: el.tagName === 'A' ? el.getAttribute('href')?.split('?')[0] : undefined,
+      type: el.tagName === 'INPUT' ? el.type : undefined,
+      checked: (el.type === 'checkbox' || el.type === 'radio') ? el.checked : undefined,
+      value: el.tagName === 'INPUT' && el.type !== 'password' ? (el.value?.slice(0, 50) || undefined) : undefined,
+    };
+
+    // Clean undefined
+    Object.keys(node).forEach(k => node[k] === undefined && delete node[k]);
+    
+    return node;
+  }
+
+  function walkTree(root, nodes = [], depth = 0) {
+    if (depth > 20) return nodes; // Prevent infinite recursion
+    
+    for (const el of root.children || []) {
+      const node = extractNode(el);
+      if (node && (node.role || node.name)) {
+        nodes.push(node);
+      }
+      walkTree(el, nodes, depth + 1);
+    }
+    return nodes;
+  }
+
+  // Find main region
+  let mainRegion = null;
+  for (const selector of regions) {
+    mainRegion = document.querySelector(selector);
+    if (mainRegion) break;
+  }
+
+  const nodes = [];
+  if (mainRegion) {
+    walkTree(mainRegion, nodes);
+  }
+
+  // Add dialogs/modals
+  if (includeDialogs) {
+    const dialogs = document.querySelectorAll('[role="dialog"], [aria-modal="true"], [data-state="open"]');
+    for (const dialog of dialogs) {
+      walkTree(dialog, nodes);
+    }
+  }
+
+  // Count by role
+  const counts = {};
+  for (const n of nodes) {
+    if (n.role) {
+      counts[n.role] = (counts[n.role] || 0) + 1;
+    }
+  }
+
+  // Count errors
+  const errorCount = nodes.filter(n => n.invalid).length;
+  const disabledCount = nodes.filter(n => n.disabled).length;
+
+  return {
+    nodes: nodes,
+    counts: counts,
+    errorCount: errorCount,
+    disabledCount: disabledCount,
+    region: mainRegion?.tagName?.toLowerCase() || 'body',
+    url: window.location.pathname + window.location.search,
+    timestamp: Date.now(),
+  };
+})
+`;
+
+/**
+ * Compute semantic hash from snapshot
+ */
+function computeSemanticHash(snapshot) {
+  // Create a stable string representation
+  const significantNodes = snapshot.nodes
+    .filter(n => n.role || n.name)
+    .map(n => `${n.role || ""}:${n.name || ""}:${n.disabled ? "d" : ""}:${n.invalid ? "i" : ""}`)
+    .sort();
+
+  const content = JSON.stringify({
+    nodes: significantNodes,
+    counts: snapshot.counts,
+    url: snapshot.url,
+  });
+
+  return "sha256:" + crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+/**
+ * Compare two semantic snapshots and generate diff
+ */
+function diffSnapshots(before, after) {
+  const diff = {
+    added: [],
+    removed: [],
+    changed: [],
+  };
+
+  // Create maps by role+name for comparison
+  const beforeMap = new Map();
+  const afterMap = new Map();
+
+  for (const n of before.nodes || []) {
+    const key = `${n.role || ""}:${n.name || ""}`;
+    beforeMap.set(key, n);
+  }
+
+  for (const n of after.nodes || []) {
+    const key = `${n.role || ""}:${n.name || ""}`;
+    afterMap.set(key, n);
+  }
+
+  // Find added
+  for (const [key, node] of afterMap) {
+    if (!beforeMap.has(key)) {
+      diff.added.push(`${node.role || node.tag}: ${node.name || "(unnamed)"}`);
+    } else {
+      // Check for changes
+      const beforeNode = beforeMap.get(key);
+      const changes = [];
+      if (beforeNode.disabled !== node.disabled) {
+        changes.push(node.disabled ? "disabled" : "enabled");
+      }
+      if (beforeNode.invalid !== node.invalid) {
+        changes.push(node.invalid ? "invalid" : "valid");
+      }
+      if (beforeNode.checked !== node.checked) {
+        changes.push(node.checked ? "checked" : "unchecked");
+      }
+      if (changes.length > 0) {
+        diff.changed.push(`${node.role || node.tag}: ${node.name || "(unnamed)"} -> ${changes.join(", ")}`);
+      }
+    }
+  }
+
+  // Find removed
+  for (const [key, node] of beforeMap) {
+    if (!afterMap.has(key)) {
+      diff.removed.push(`${node.role || node.tag}: ${node.name || "(unnamed)"}`);
+    }
+  }
+
+  // Check for route change
+  diff.routeChanged = before.url !== after.url;
+
+  // Check for error count change
+  diff.errorsChanged = before.errorCount !== after.errorCount;
+  diff.errorDelta = (after.errorCount || 0) - (before.errorCount || 0);
+
+  // Check for dialog changes
+  const beforeDialogCount = before.counts?.dialog || 0;
+  const afterDialogCount = after.counts?.dialog || 0;
+  diff.dialogOpened = afterDialogCount > beforeDialogCount;
+  diff.dialogClosed = afterDialogCount < beforeDialogCount;
+
+  return diff;
+}
+
+/**
+ * Calculate meaningful change score
+ */
+function calculateChangeScore(diff, signals = []) {
+  let score = 0;
+  const reasons = [];
+
+  // Route change is always meaningful
+  if (diff.routeChanged) {
+    score += 1.0;
+    reasons.push("route_changed");
+  }
+
+  // Dialog opened/closed
+  if (diff.dialogOpened) {
+    score += 0.8;
+    reasons.push("dialog_opened");
+  }
+  if (diff.dialogClosed) {
+    score += 0.8;
+    reasons.push("dialog_closed");
+  }
+
+  // Toast signals
+  const toastSuccess = signals.find(s => s.kind === "toast_success");
+  const toastError = signals.find(s => s.kind === "toast_error");
+  const toastAny = signals.find(s => s.kind?.startsWith("toast_"));
+
+  if (toastSuccess) {
+    score += 0.6;
+    reasons.push("toast_success");
+  }
+  if (toastError) {
+    score += 0.6;
+    reasons.push("toast_error");
+  } else if (toastAny && !toastSuccess) {
+    score += 0.5;
+    reasons.push("toast_appeared");
+  }
+
+  // Alert banner (role=alert, aria-live)
+  const alertSignal = signals.find(s => s.kind === "alert_appeared");
+  if (alertSignal) {
+    score += 0.7;
+    reasons.push("alert_banner");
+  }
+
+  // Form errors changed
+  if (diff.errorsChanged) {
+    score += 0.7;
+    reasons.push(diff.errorDelta > 0 ? "form_errors_appeared" : "form_errors_cleared");
+  }
+
+  // Significant semantic diff
+  const significantChanges = diff.added.length + diff.removed.length + diff.changed.length;
+  if (significantChanges > 2) {
+    score += 0.7;
+    reasons.push("semantic_hash_changed");
+  } else if (significantChanges > 0) {
+    score += 0.3;
+    reasons.push("minor_semantic_change");
+  }
+
+  // Key control state changed (disabled/enabled)
+  const controlChanges = diff.changed.filter(c => c.includes("enabled") || c.includes("disabled"));
+  if (controlChanges.length > 0) {
+    score += 0.6;
+    reasons.push("control_state_changed");
+  }
+
+  // Cap at 1.0
+  score = Math.min(score, 1.0);
+
+  return {
+    score,
+    meaningful: score >= 0.6 || diff.routeChanged,
+    reasons,
+  };
+}
+
+/**
+ * Create UI change report from before/after snapshots and signals
+ */
+function createUIChangeReport(before, after, signals = []) {
+  const beforeHash = computeSemanticHash(before);
+  const afterHash = computeSemanticHash(after);
+  const diff = diffSnapshots(before, after);
+  const { score, meaningful, reasons } = calculateChangeScore(diff, signals);
+
+  return {
+    score,
+    meaningful,
+    reasons,
+    beforeSemanticHash: beforeHash,
+    afterSemanticHash: afterHash,
+    semanticDiffSummary: {
+      added: diff.added.slice(0, 10),
+      removed: diff.removed.slice(0, 10),
+      changed: diff.changed.slice(0, 10),
+    },
+    routeChanged: diff.routeChanged,
+    dialogOpened: diff.dialogOpened,
+    dialogClosed: diff.dialogClosed,
+    errorsChanged: diff.errorsChanged,
+    errorDelta: diff.errorDelta,
+  };
+}
+
+module.exports = {
+  CAPTURE_SCRIPT,
+  computeSemanticHash,
+  diffSnapshots,
+  calculateChangeScore,
+  createUIChangeReport,
+  IGNORE_TAGS,
+  IGNORE_SELECTORS,
+  MEANINGFUL_ROLES,
+};