@odavl/guardian 0.1.0-rc1

package/src/guardian/snapshot.js

@@ -0,0 +1,327 @@
+/**
+ * Market Reality Snapshot Builder
+ * Assembles crawl results, attempt results, evidence, and signals into a snapshot
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createEmptySnapshot, validateSnapshot } = require('./snapshot-schema');
+
+class SnapshotBuilder {
+  constructor(baseUrl, runId, toolVersion) {
+    this.snapshot = createEmptySnapshot(baseUrl, runId, toolVersion);
+  }
+
+  /**
+   * Add crawl results to snapshot
+   */
+  addCrawlResults(crawlResult) {
+    if (!crawlResult) return;
+
+    this.snapshot.crawl = {
+      discoveredUrls: (crawlResult.visited || []).map(p => p.url),
+      visitedCount: crawlResult.totalVisited || 0,
+      failedCount: (crawlResult.visited || []).filter(p => p.error).length,
+      safetyBlockedCount: crawlResult.safetyStats?.urlsBlocked || 0,
+      httpFailures: (crawlResult.visited || [])
+        .filter(p => p.error)
+        .map(p => ({
+          url: p.url,
+          error: p.error,
+          timestamp: p.timestamp
+        })),
+      notes: `Discovered ${crawlResult.totalDiscovered || 0} URLs, visited ${crawlResult.totalVisited || 0}`
+    };
+  }
+
+  /**
+   * Add attempt result to snapshot
+   */
+  addAttempt(attemptResult, artifactDir) {
+    const signal = {
+      id: `attempt_${attemptResult.attemptId}`,
+      severity: attemptResult.outcome === 'FAILURE' ? 'high' : 'medium',
+      type: attemptResult.outcome === 'FAILURE' ? 'failure' : 'friction',
+      description: `${attemptResult.attemptName}: ${attemptResult.outcome}`,
+      affectedAttemptId: attemptResult.attemptId
+    };
+
+    if (attemptResult.outcome === 'FAILURE' && attemptResult.error) {
+      signal.details = attemptResult.error;
+    }
+
+    this.snapshot.attempts.push({
+      attemptId: attemptResult.attemptId,
+      attemptName: attemptResult.attemptName,
+      goal: attemptResult.goal,
+      outcome: attemptResult.outcome,
+      totalDurationMs: attemptResult.attemptResult?.totalDurationMs || 0,
+      stepCount: (attemptResult.steps || []).length,
+      failedStepIndex: (attemptResult.steps || []).findIndex(s => s.status === 'failed'),
+      friction: attemptResult.friction || null
+    });
+
+    // Track artifacts
+    if (artifactDir) {
+      this.snapshot.evidence.attemptArtifacts[attemptResult.attemptId] = {
+        reportJson: path.join(attemptResult.attemptId, 'attempt-report.json'),
+        reportHtml: path.join(attemptResult.attemptId, 'attempt-report.html'),
+        screenshotDir: path.join(attemptResult.attemptId, 'attempt-screenshots')
+      };
+    }
+
+    // Add signal
+    this.snapshot.signals.push(signal);
+  }
+
+  /**
+   * Add market reality results (from executeReality)
+   */
+  addMarketResults(marketResults, runDir) {
+    if (!marketResults || !marketResults.attemptResults) return;
+
+    // Add individual attempt results
+    for (const result of marketResults.attemptResults) {
+      this.addAttempt(result, runDir);
+    }
+
+    // Add intent flow results
+    if (marketResults.flowResults && Array.isArray(marketResults.flowResults)) {
+      for (const flow of marketResults.flowResults) {
+        this.addFlow(flow, runDir);
+      }
+    }
+
+    // Track market report files
+    if (marketResults.marketJsonPath) {
+      this.snapshot.evidence.marketReportJson = path.relative(runDir, marketResults.marketJsonPath);
+    }
+    if (marketResults.marketHtmlPath) {
+      this.snapshot.evidence.marketReportHtml = path.relative(runDir, marketResults.marketHtmlPath);
+    }
+  }
+
+  /**
+   * Set artifact directory
+   */
+  setArtifactDir(artifactDir) {
+    this.snapshot.evidence.artifactDir = artifactDir;
+  }
+
+  /**
+   * Add flow results to snapshot
+   */
+  addFlow(flowResult, runDir) {
+    if (!flowResult) return;
+
+    this.snapshot.flows.push({
+      flowId: flowResult.flowId,
+      flowName: flowResult.flowName,
+      outcome: flowResult.outcome,
+      riskCategory: flowResult.riskCategory || 'TRUST/UX',
+      stepsExecuted: flowResult.stepsExecuted || 0,
+      stepsTotal: flowResult.stepsTotal || 0,
+      durationMs: flowResult.durationMs || 0,
+      failedStep: flowResult.failedStep || null,
+      error: flowResult.error || null
+    });
+
+    if (runDir) {
+      this.snapshot.evidence.flowArtifacts[flowResult.flowId] = {
+        screenshots: flowResult.screenshots || [],
+        artifactDir: path.join('flows', flowResult.flowId)
+      };
+    }
+
+    if (flowResult.outcome === 'FAILURE') {
+      this.snapshot.signals.push({
+        id: `flow_${flowResult.flowId}_failed`,
+        severity: 'high',
+        type: 'failure',
+        description: `Flow ${flowResult.flowName} failed`,
+        affectedAttemptId: flowResult.flowId
+      });
+    }
+  }
+
+  /**
+   * Add trace path if available
+   */
+  setTracePath(tracePath) {
+    if (tracePath) {
+      this.snapshot.evidence.traceZip = tracePath;
+    }
+  }
+
+  /**
+   * Set baseline information
+   */
+  setBaseline(baselineInfo) {
+    if (!baselineInfo) return;
+
+    this.snapshot.baseline = {
+      ...this.snapshot.baseline,
+      ...baselineInfo
+    };
+  }
+
+  /**
+   * Set market impact summary (Phase 3)
+   */
+  setMarketImpactSummary(marketImpactSummary) {
+    if (!marketImpactSummary) return;
+
+    this.snapshot.marketImpactSummary = {
+      highestSeverity: marketImpactSummary.highestSeverity || 'INFO',
+      totalRiskCount: marketImpactSummary.totalRiskCount || 0,
+      countsBySeverity: marketImpactSummary.countsBySeverity || { CRITICAL: 0, WARNING: 0, INFO: 0 },
+      topRisks: (marketImpactSummary.topRisks || []).slice(0, 10)
+    };
+  }
+
+  /**
+   * Set discovery results (Phase 4)
+   */
+  setDiscoveryResults(discoveryResult) {
+    if (!discoveryResult) return;
+
+    this.snapshot.discovery = {
+      pagesVisited: discoveryResult.pagesVisited || [],
+      pagesVisitedCount: discoveryResult.pagesVisitedCount || 0,
+      interactionsDiscovered: discoveryResult.interactionsDiscovered || 0,
+      interactionsExecuted: discoveryResult.interactionsExecuted || 0,
+      interactionsByType: discoveryResult.interactionsByType || { NAVIGATE: 0, CLICK: 0, FORM_FILL: 0 },
+      interactionsByRisk: discoveryResult.interactionsByRisk || { safe: 0, risky: 0 },
+      results: (discoveryResult.results || []).slice(0, 20), // Top 20 results
+      summary: discoveryResult.summary || ''
+    };
+  }
+
+  /**
+   * Add breakage intelligence (Phase 4)
+   */
+  addIntelligence(intelligence) {
+    if (!intelligence) return;
+
+    this.snapshot.intelligence = {
+      totalFailures: intelligence.totalFailures || 0,
+      failures: (intelligence.failures || []).slice(0, 50), // Top 50 failures
+      byDomain: intelligence.byDomain || {},
+      bySeverity: intelligence.bySeverity || {},
+      escalationSignals: intelligence.escalationSignals || [],
+      summary: intelligence.summary || ''
+    };
+  }
+
+  /**
+   * Add regression detection results
+   */
+  addDiff(diffResult) {
+    if (!diffResult) return;
+
+    this.snapshot.baseline.diff = {
+      regressions: diffResult.regressions || [],
+      improvements: diffResult.improvements || [],
+      attemptsDriftCount: diffResult.attemptsDriftCount || 0
+    };
+
+    // Add regression signals
+    if (diffResult.regressions && Object.keys(diffResult.regressions).length > 0) {
+      for (const [attemptId, regression] of Object.entries(diffResult.regressions)) {
+        this.snapshot.signals.push({
+          id: `regression_${attemptId}`,
+          severity: 'high',
+          type: 'regression',
+          description: `Regression in ${attemptId}: ${regression.reason}`,
+          affectedAttemptId: attemptId,
+          details: regression
+        });
+      }
+    }
+  }
+
+  /**
+   * Set market impact summary (Phase 3)
+   */
+  setMarketImpactSummary(marketImpactSummary) {
+    if (!marketImpactSummary) return;
+
+    this.snapshot.marketImpactSummary = {
+      highestSeverity: marketImpactSummary.highestSeverity || 'INFO',
+      totalRiskCount: marketImpactSummary.totalRiskCount || 0,
+      countsBySeverity: marketImpactSummary.countsBySeverity || {
+        CRITICAL: 0,
+        WARNING: 0,
+        INFO: 0
+      },
+      topRisks: (marketImpactSummary.topRisks || []).slice(0, 10) // Keep top 10
+    };
+  }
+
+  /**
+   * Get the built snapshot
+   */
+  getSnapshot() {
+    return this.snapshot;
+  }
+
+  /**
+   * Validate snapshot and return validation result
+   */
+  validate() {
+    return validateSnapshot(this.snapshot);
+  }
+
+  /**
+   * Convert to JSON
+   */
+  toJSON() {
+    return JSON.stringify(this.snapshot, null, 2);
+  }
+}
+
+/**
+ * Save snapshot to file atomically (write temp, rename)
+ */
+async function saveSnapshot(snapshot, filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tempPath = `${filePath}.tmp`;
+  const json = typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2);
+
+  return new Promise((resolve, reject) => {
+    fs.writeFile(tempPath, json, 'utf8', (err) => {
+      if (err) return reject(err);
+
+      fs.rename(tempPath, filePath, (err) => {
+        if (err) return reject(err);
+        resolve(filePath);
+      });
+    });
+  });
+}
+
+/**
+ * Load snapshot from file
+ */
+function loadSnapshot(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const json = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(json);
+  } catch (err) {
+    throw new Error(`Failed to load snapshot from ${filePath}: ${err.message}`);
+  }
+}
+
+module.exports = {
+  SnapshotBuilder,
+  saveSnapshot,
+  loadSnapshot
+};

package/src/guardian/validators.js

@@ -0,0 +1,323 @@
+/**
+ * Market Reality Validators Framework
+ * 
+ * Pure deterministic checks that detect soft failures:
+ * - Interactions technically succeeded (no Playwright exception)
+ * - But user would NOT succeed (no confirmation, wrong state, etc)
+ * 
+ * Validators return: { id, type, status: PASS|FAIL|WARN, message, evidence? }
+ */
+
+const validator = {
+  PASS: 'PASS',
+  FAIL: 'FAIL',
+  WARN: 'WARN'
+};
+
+/**
+ * URL includes substring
+ */
+function urlIncludes(page, substring) {
+  try {
+    const url = page.url();
+    return {
+      id: `url_includes_${substring}`,
+      type: 'urlIncludes',
+      status: url.includes(substring) ? validator.PASS : validator.FAIL,
+      message: url.includes(substring) 
+        ? `URL contains "${substring}"` 
+        : `URL does not contain "${substring}". Current: ${url}`,
+      evidence: { url, expected: substring }
+    };
+  } catch (err) {
+    return {
+      id: `url_includes_${substring}`,
+      type: 'urlIncludes',
+      status: validator.FAIL,
+      message: `Error checking URL: ${err.message}`,
+      evidence: { error: err.message }
+    };
+  }
+}
+
+/**
+ * URL matches regex pattern
+ */
+function urlMatches(page, pattern) {
+  try {
+    const url = page.url();
+    const regex = new RegExp(pattern);
+    return {
+      id: `url_matches_${pattern}`,
+      type: 'urlMatches',
+      status: regex.test(url) ? validator.PASS : validator.FAIL,
+      message: regex.test(url)
+        ? `URL matches pattern "${pattern}"`
+        : `URL does not match pattern "${pattern}". Current: ${url}`,
+      evidence: { url, pattern }
+    };
+  } catch (err) {
+    return {
+      id: `url_matches_${pattern}`,
+      type: 'urlMatches',
+      status: validator.FAIL,
+      message: `Error checking URL pattern: ${err.message}`,
+      evidence: { error: err.message }
+    };
+  }
+}
+
+/**
+ * Element is visible (exists and not hidden)
+ */
+async function elementVisible(page, selector) {
+  try {
+    const element = page.locator(selector);
+    const visible = await element.isVisible().catch(() => false);
+    
+    return {
+      id: `element_visible_${selector}`,
+      type: 'elementVisible',
+      status: visible ? validator.PASS : validator.FAIL,
+      message: visible
+        ? `Element visible: ${selector}`
+        : `Element not visible: ${selector}`,
+      evidence: { selector, visible }
+    };
+  } catch (err) {
+    return {
+      id: `element_visible_${selector}`,
+      type: 'elementVisible',
+      status: validator.FAIL,
+      message: `Error checking element visibility: ${err.message}`,
+      evidence: { selector, error: err.message }
+    };
+  }
+}
+
+/**
+ * Element is NOT visible
+ */
+async function elementNotVisible(page, selector) {
+  try {
+    const element = page.locator(selector);
+    const visible = await element.isVisible().catch(() => false);
+    
+    return {
+      id: `element_not_visible_${selector}`,
+      type: 'elementNotVisible',
+      status: !visible ? validator.PASS : validator.FAIL,
+      message: !visible
+        ? `Element not visible: ${selector}`
+        : `Element is visible but should not be: ${selector}`,
+      evidence: { selector, visible }
+    };
+  } catch (err) {
+    return {
+      id: `element_not_visible_${selector}`,
+      type: 'elementNotVisible',
+      status: validator.PASS, // If element doesn't exist, that's good
+      message: `Element not found (expected)`,
+      evidence: { selector }
+    };
+  }
+}
+
+/**
+ * Element contains text
+ */
+async function elementContainsText(page, selector, expectedText) {
+  try {
+    const element = page.locator(selector);
+    const text = await element.textContent().catch(() => '');
+    const contains = text.includes(expectedText);
+    
+    return {
+      id: `element_contains_${selector}_${expectedText}`,
+      type: 'elementContainsText',
+      status: contains ? validator.PASS : validator.FAIL,
+      message: contains
+        ? `Element contains "${expectedText}"`
+        : `Element text does not contain "${expectedText}". Found: "${text}"`,
+      evidence: { selector, expectedText, actualText: text }
+    };
+  } catch (err) {
+    return {
+      id: `element_contains_${selector}_${expectedText}`,
+      type: 'elementContainsText',
+      status: validator.FAIL,
+      message: `Error checking element text: ${err.message}`,
+      evidence: { selector, expectedText, error: err.message }
+    };
+  }
+}
+
+/**
+ * Page contains ANY of the provided text strings
+ * Useful for language detection or success keywords
+ */
+async function pageContainsAnyText(page, textList) {
+  try {
+    const pageText = await page.content();
+    const found = textList.find(text => pageText.includes(text));
+    
+    return {
+      id: `page_contains_any_${textList.join('_')}`,
+      type: 'pageContainsAnyText',
+      status: found ? validator.PASS : validator.FAIL,
+      message: found
+        ? `Page contains expected text: "${found}"`
+        : `Page does not contain any of: ${textList.join(', ')}`,
+      evidence: { searchTerms: textList, found }
+    };
+  } catch (err) {
+    return {
+      id: `page_contains_any_${textList.join('_')}`,
+      type: 'pageContainsAnyText',
+      status: validator.FAIL,
+      message: `Error checking page content: ${err.message}`,
+      evidence: { searchTerms: textList, error: err.message }
+    };
+  }
+}
+
+/**
+ * HTML lang attribute matches (for language detection)
+ */
+async function htmlLangAttribute(page, expectedLang) {
+  try {
+    const lang = await page.locator('html').getAttribute('lang');
+    const matches = lang === expectedLang;
+    
+    return {
+      id: `html_lang_${expectedLang}`,
+      type: 'htmlLangAttribute',
+      status: matches ? validator.PASS : validator.FAIL,
+      message: matches
+        ? `HTML lang attribute is "${expectedLang}"`
+        : `HTML lang is "${lang}", expected "${expectedLang}"`,
+      evidence: { attribute: 'lang', expected: expectedLang, actual: lang }
+    };
+  } catch (err) {
+    return {
+      id: `html_lang_${expectedLang}`,
+      type: 'htmlLangAttribute',
+      status: validator.FAIL,
+      message: `Error checking lang attribute: ${err.message}`,
+      evidence: { error: err.message }
+    };
+  }
+}
+
+/**
+ * No console errors above severity level
+ * Requires console messages to be captured during attempt
+ */
+function noConsoleErrorsAbove(consoleMessages, minSeverity = 'error') {
+  const severities = { log: 0, warning: 1, error: 2 };
+  const minLevel = severities[minSeverity] || 2;
+  
+  const violatingMessages = consoleMessages.filter(msg => 
+    severities[msg.type] >= minLevel
+  );
+  
+  return {
+    id: `no_console_errors_${minSeverity}`,
+    type: 'noConsoleErrorsAbove',
+    status: violatingMessages.length === 0 ? validator.PASS : validator.FAIL,
+    message: violatingMessages.length === 0
+      ? `No console errors (threshold: ${minSeverity})`
+      : `Found ${violatingMessages.length} console errors: ${violatingMessages.map(m => m.text).join('; ')}`,
+    evidence: { minSeverity, count: violatingMessages.length, messages: violatingMessages }
+  };
+}
+
+/**
+ * Validator runner: execute all validators and return results
+ */
+async function runValidators(validatorSpecs, context) {
+  const results = [];
+  
+  for (const spec of validatorSpecs) {
+    try {
+      let result;
+      
+      switch (spec.type) {
+        case 'urlIncludes':
+          result = urlIncludes(context.page, spec.param);
+          break;
+        case 'urlMatches':
+          result = urlMatches(context.page, spec.param);
+          break;
+        case 'elementVisible':
+          result = await elementVisible(context.page, spec.selector);
+          break;
+        case 'elementNotVisible':
+          result = await elementNotVisible(context.page, spec.selector);
+          break;
+        case 'elementContainsText':
+          result = await elementContainsText(context.page, spec.selector, spec.text);
+          break;
+        case 'pageContainsAnyText':
+          result = await pageContainsAnyText(context.page, spec.textList);
+          break;
+        case 'htmlLangAttribute':
+          result = await htmlLangAttribute(context.page, spec.lang);
+          break;
+        case 'noConsoleErrorsAbove':
+          result = noConsoleErrorsAbove(context.consoleMessages || [], spec.minSeverity);
+          break;
+        default:
+          result = {
+            id: spec.type,
+            type: spec.type,
+            status: validator.WARN,
+            message: `Unknown validator type: ${spec.type}`
+          };
+      }
+      
+      results.push(result);
+    } catch (err) {
+      results.push({
+        id: spec.type,
+        type: spec.type,
+        status: validator.FAIL,
+        message: `Validator error: ${err.message}`,
+        evidence: { error: err.message }
+      });
+    }
+  }
+  
+  return results;
+}
+
+/**
+ * Determine if validators indicate a soft failure
+ * Returns: { hasSoftFailure: boolean, failureCount: number, warnCount: number }
+ */
+function analyzeSoftFailures(validatorResults) {
+  const failures = validatorResults.filter(r => r.status === validator.FAIL);
+  const warnings = validatorResults.filter(r => r.status === validator.WARN);
+  
+  return {
+    hasSoftFailure: failures.length > 0,
+    failureCount: failures.length,
+    warnCount: warnings.length,
+    failedValidators: failures,
+    warnedValidators: warnings
+  };
+}
+
+module.exports = {
+  validator,
+  urlIncludes,
+  urlMatches,
+  elementVisible,
+  elementNotVisible,
+  elementContainsText,
+  pageContainsAnyText,
+  htmlLangAttribute,
+  noConsoleErrorsAbove,
+  runValidators,
+  analyzeSoftFailures
+};