@odavl/guardian 0.1.0-rc1

package/src/guardian/reporter.js

@@ -0,0 +1,181 @@
+const fs = require('fs');
+const path = require('path');
+
+class GuardianReporter {
+  /**
+   * Prepare artifacts directory for the current run
+   * @param {string} artifactsDir - Base artifacts directory
+   * @returns {object} { runDir, runId }
+   */
+  prepareArtifactsDir(artifactsDir) {
+    const now = new Date();
+    const dateStr = now.toISOString()
+      .replace(/[:\-]/g, '')
+      .substring(0, 15)
+      .replace('T', '-');
+    const runId = `run-${dateStr}`;
+    
+    const runDir = path.join(artifactsDir, runId);
+    if (!fs.existsSync(runDir)) {
+      fs.mkdirSync(runDir, { recursive: true });
+    }
+    
+    return { runDir, runId };
+  }
+
+  createReport(crawlResult, baseUrl) {
+    const { visited, totalDiscovered, totalVisited } = crawlResult;
+    
+    const coverage = totalDiscovered > 0 
+      ? parseFloat(((totalVisited / totalDiscovered) * 100).toFixed(2))
+      : 0;
+    
+    // Calculate confidence
+    let confidenceLevel = 'LOW';
+    if (coverage >= 85) {
+      confidenceLevel = 'HIGH';
+    } else if (coverage >= 60) {
+      confidenceLevel = 'MEDIUM';
+    }
+    
+    // Calculate decision
+    let decision = 'READY';
+    if (coverage < 30) {
+      decision = 'DO_NOT_LAUNCH';
+    } else if (coverage < 60) {
+      decision = 'INSUFFICIENT_CONFIDENCE';
+    }
+    
+    // Check for critical errors (server errors only, not 404s)
+    const failedPages = visited.filter(p => p.status && p.status >= 500);
+    if (failedPages.length > 0) {
+      decision = 'DO_NOT_LAUNCH';
+    }
+    
+    const reasons = [];
+    if (coverage < 30) reasons.push(`Low coverage (${coverage}%)`);
+    if (failedPages.length > 0) reasons.push(`${failedPages.length} pages failed to load`);
+    if (coverage >= 60) reasons.push(`Coverage is ${coverage}%`);
+    if (failedPages.length === 0 && coverage >= 60) reasons.push('All visited pages loaded successfully');
+    
+    return {
+      version: 'mvp-0.1',
+      timestamp: new Date().toISOString(),
+      baseUrl: baseUrl,
+      summary: {
+        visitedPages: totalVisited,
+        discoveredPages: totalDiscovered,
+        coverage: coverage,
+        failedPages: failedPages.length
+      },
+      confidence: {
+        level: confidenceLevel,
+        reasoning: `Coverage is ${coverage}% with ${failedPages.length} failed pages`
+      },
+      finalJudgment: {
+        decision: decision,
+        reasons: reasons.length > 0 ? reasons : ['All checks passed']
+      },
+      pages: visited.map((p, i) => ({
+        index: i + 1,
+        url: p.url,
+        status: p.status,
+        links: p.linkCount,
+        depth: p.depth,
+        error: p.error || null
+      }))
+    };
+  }
+
+  /**
+   * Create report from flow execution result
+   * @param {object} flowResult - Flow execution result
+   * @param {string} baseUrl - Base URL
+   * @returns {object} Report object
+   */
+  createFlowReport(flowResult, baseUrl) {
+    const { flowId, flowName, success, stepsExecuted, stepsTotal, failedStep, error } = flowResult;
+    
+    const coverage = stepsTotal > 0 
+      ? parseFloat(((stepsExecuted / stepsTotal) * 100).toFixed(2))
+      : 0;
+    
+    // For flows: success = READY, failure = DO_NOT_LAUNCH
+    const decision = success ? 'READY' : 'DO_NOT_LAUNCH';
+    const confidenceLevel = success ? 'HIGH' : 'LOW';
+    
+    const reasons = [];
+    if (success) {
+      reasons.push(`Flow "${flowName}" completed successfully`);
+      reasons.push(`All ${stepsTotal} steps executed`);
+    } else {
+      reasons.push(`Flow "${flowName}" failed at step ${failedStep}`);
+      reasons.push(`Error: ${error}`);
+    }
+    
+    return {
+      version: 'mvp-0.2',
+      timestamp: new Date().toISOString(),
+      baseUrl: baseUrl,
+      mode: 'flow',
+      flow: {
+        id: flowId,
+        name: flowName,
+        stepsTotal: stepsTotal,
+        stepsExecuted: stepsExecuted,
+        failedStep: failedStep || null,
+        error: error || null
+      },
+      summary: {
+        visitedPages: stepsExecuted,
+        discoveredPages: stepsTotal,
+        coverage: coverage,
+        failedPages: success ? 0 : 1
+      },
+      confidence: {
+        level: confidenceLevel,
+        reasoning: success 
+          ? `Flow completed successfully (${stepsExecuted}/${stepsTotal} steps)` 
+          : `Flow failed at step ${failedStep}: ${error}`
+      },
+      finalJudgment: {
+        decision: decision,
+        reasons: reasons
+      },
+      pages: flowResult.screenshots ? flowResult.screenshots.map((screenshot, i) => ({
+        index: i + 1,
+        url: `${baseUrl} (Flow step ${i + 1})`,
+        status: 200,
+        links: 0,
+        screenshot: screenshot
+      })) : []
+    };
+  }
+
+  saveReport(report, artifactsDir) {
+    // Create run directory
+    const now = new Date();
+    const dateStr = now.toISOString()
+      .replace(/[:\-]/g, '')
+      .substring(0, 15)
+      .replace('T', '-');
+    const runId = `run-${dateStr}`;
+    
+    const runDir = path.join(artifactsDir, runId);
+    if (!fs.existsSync(runDir)) {
+      fs.mkdirSync(runDir, { recursive: true });
+    }
+    
+    // Save report.json
+    const reportPath = path.join(runDir, 'report.json');
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+    
+    return {
+      runId: runId,
+      runDir: runDir,
+      reportPath: reportPath
+    };
+  }
+}
+
+module.exports = { GuardianReporter };

package/src/guardian/root-cause-analysis.js

@@ -0,0 +1,171 @@
+/**
+ * Phase 4 — Root-Cause Analysis
+ * Deterministically derive hints from failure evidence
+ */
+
+const { BREAK_TYPES } = require('./failure-taxonomy');
+
+/**
+ * Extract hints from step execution failure
+ * @param {Object} step - { type, target, status, error, duration }
+ * @returns {string[]} Array of hint strings
+ */
+function hintsFromStep(step) {
+  const hints = [];
+
+  if (!step) return hints;
+
+  const error = (step.error || '').toLowerCase();
+  const type = step.type || '';
+
+  // Navigation
+  if (type === 'navigate' && error.includes('timeout')) {
+    hints.push('Server not responding or slow to load');
+  } else if (type === 'navigate' && error.includes('failed')) {
+    hints.push('Navigation failed; verify base URL is correct');
+  }
+
+  // Click failures
+  if (type === 'click') {
+    if (error.includes('selector') || error.includes('found')) {
+      hints.push(`Element selector not found: ${step.target}`);
+    } else if (error.includes('visible')) {
+      hints.push(`Element not visible or clickable: ${step.target}`);
+    } else if (error.includes('timeout')) {
+      hints.push(`Timeout clicking ${step.target}; page may be loading slowly`);
+    }
+  }
+
+  // Type failures
+  if (type === 'type') {
+    if (error.includes('selector') || error.includes('found')) {
+      hints.push(`Input field not found: ${step.target}`);
+    } else if (error.includes('timeout')) {
+      hints.push(`Timeout typing into ${step.target}; page lag detected`);
+    }
+  }
+
+  // WaitFor failures
+  if (type === 'waitFor') {
+    if (error.includes('timeout')) {
+      hints.push(`Success element never appeared: ${step.target}`);
+      hints.push('Submission may have silently failed or redirected');
+    }
+  }
+
+  // Submit failures
+  if (type === 'submit') {
+    hints.push('Form submission did not complete; check form validation');
+  }
+
+  return hints;
+}
+
+/**
+ * Extract hints from validator results
+ * @param {Array} validators - Array of { type, status, message, evidence }
+ * @returns {string[]} Array of hint strings
+ */
+function hintsFromValidators(validators) {
+  const hints = [];
+
+  if (!Array.isArray(validators)) return hints;
+
+  for (const v of validators) {
+    if (v.status === 'FAIL') {
+      if (v.type === 'elementVisible') {
+        hints.push(`Expected element not visible: ${v.evidence?.selector}`);
+      } else if (v.type === 'pageContainsAnyText') {
+        hints.push(`Page text check failed; expected one of: ${v.evidence?.searchTerms?.join(', ')}`);
+      } else if (v.type === 'elementContainsText') {
+        hints.push(`Element text mismatch; expected: ${v.evidence?.expectedText}`);
+      } else if (v.type === 'htmlLangAttribute') {
+        hints.push(`HTML lang attribute unexpected; expected: ${v.evidence?.expected}`);
+      } else if (v.type === 'urlIncludes' || v.type === 'urlMatches') {
+        hints.push(`URL does not match expected pattern: ${v.evidence?.pattern || v.evidence?.expected}`);
+      } else {
+        hints.push(`Validator failed: ${v.type}`);
+      }
+    }
+  }
+
+  return hints;
+}
+
+/**
+ * Extract hints from friction signals
+ * @param {Array} signals - Array of { id, description, threshold, observedValue }
+ * @returns {string[]} Array of hint strings
+ */
+function hintsFromFriction(signals) {
+  const hints = [];
+
+  if (!Array.isArray(signals)) return hints;
+
+  for (const sig of signals) {
+    if (sig.id === 'slow_step_execution') {
+      hints.push(`Step took ${sig.observedValue}ms (threshold ${sig.threshold}ms); network or page lag`);
+    } else if (sig.id === 'multiple_retries_required') {
+      hints.push(`Step needed ${sig.observedValue} retries; interaction unreliable`);
+    } else if (sig.id === 'slow_total_duration') {
+      hints.push(`Total attempt took ${sig.observedValue}ms; slow server response`);
+    }
+  }
+
+  return hints;
+}
+
+/**
+ * Derive root-cause hints from complete failure evidence
+ * @param {Object} failure - Attempt or flow result
+ * @param {string} breakType - BREAK_TYPE
+ * @returns {Object} { hints: string[], primaryHint: string }
+ */
+function deriveRootCauseHints(failure, breakType) {
+  const allHints = new Set();
+
+  // Step-level evidence
+  if (failure.steps && Array.isArray(failure.steps)) {
+    const failedStep = failure.steps.find(s => s.status === 'failed');
+    if (failedStep) {
+      hintsFromStep(failedStep).forEach(h => allHints.add(h));
+    }
+  }
+
+  // Validator evidence
+  if (failure.validators) {
+    hintsFromValidators(failure.validators).forEach(h => allHints.add(h));
+  }
+
+  // Friction signals
+  if (failure.friction && failure.friction.signals) {
+    hintsFromFriction(failure.friction.signals).forEach(h => allHints.add(h));
+  }
+
+  // Fallback hints by break type
+  if (allHints.size === 0) {
+    const fallbacks = {
+      [BREAK_TYPES.NAVIGATION]: 'Server unreachable or incorrect URL',
+      [BREAK_TYPES.SUBMISSION]: 'Form submission did not complete',
+      [BREAK_TYPES.VALIDATION]: 'Success validation did not pass',
+      [BREAK_TYPES.TIMEOUT]: 'Step timed out; slow response or missing element',
+      [BREAK_TYPES.VISUAL]: 'Expected element not found on page',
+      [BREAK_TYPES.CONSOLE]: 'Console error prevented progress',
+      [BREAK_TYPES.NETWORK]: 'Network error or lost connection'
+    };
+    allHints.add(fallbacks[breakType] || 'Unknown failure');
+  }
+
+  const hints = Array.from(allHints);
+  return {
+    hints,
+    primaryHint: hints[0] || 'Unknown failure'
+  };
+}
+
+module.exports = {
+  deriveRootCauseHints,
+  hintsFromStep,
+  hintsFromValidators,
+  hintsFromFriction
+};

package/src/guardian/safety.js

@@ -0,0 +1,248 @@
+/**
+ * Guardian Safety Guards Module
+ * Prevents destructive or dangerous actions during testing
+ */
+
+class GuardianSafety {
+  constructor(options = {}) {
+    // URL patterns to avoid (logout, delete, admin, etc.)
+    this.denyUrlPatterns = options.denyUrlPatterns || [
+      'logout',
+      'signout',
+      'sign-out',
+      'log-out',
+      'delete',
+      'remove',
+      'destroy',
+      'admin',
+      'settings',
+      'account/close',
+      'account/delete',
+      'unsubscribe',
+      'cancel',
+    ];
+
+    // CSS selectors to avoid clicking
+    this.denySelectors = options.denySelectors || [
+      '[data-danger]',
+      '[data-destructive]',
+      '.btn-delete',
+      '.btn-danger',
+      '.delete-button',
+      'button[type="reset"]',
+      'a[href*="logout"]',
+      'a[href*="delete"]',
+      'a[href*="remove"]',
+    ];
+
+    // Form submissions require explicit permission
+    this.blockFormSubmitsByDefault = options.blockFormSubmitsByDefault !== false;
+    
+    // Payment-related actions require explicit permission
+    this.blockPaymentsByDefault = options.blockPaymentsByDefault !== false;
+    
+    // Payment-related keywords
+    this.paymentKeywords = [
+      'payment',
+      'checkout',
+      'purchase',
+      'buy',
+      'pay',
+      'card',
+      'billing',
+      'stripe',
+      'paypal',
+    ];
+  }
+
+  /**
+   * Check if URL is safe to visit
+   * @param {string} url - URL to check
+   * @returns {object} { safe: boolean, reason: string }
+   */
+  isUrlSafe(url) {
+    try {
+      const urlLower = url.toLowerCase();
+      
+      for (const pattern of this.denyUrlPatterns) {
+        if (urlLower.includes(pattern.toLowerCase())) {
+          return {
+            safe: false,
+            reason: `URL contains blocked pattern: "${pattern}"`,
+          };
+        }
+      }
+
+      return { safe: true, reason: null };
+    } catch (error) {
+      return {
+        safe: false,
+        reason: `Invalid URL: ${error.message}`,
+      };
+    }
+  }
+
+  /**
+   * Check if selector is safe to click
+   * @param {string} selector - CSS selector
+   * @returns {object} { safe: boolean, reason: string }
+   */
+  isSelectorSafe(selector) {
+    try {
+      const selectorLower = selector.toLowerCase();
+      
+      for (const denyPattern of this.denySelectors) {
+        if (selectorLower.includes(denyPattern.toLowerCase())) {
+          return {
+            safe: false,
+            reason: `Selector matches blocked pattern: "${denyPattern}"`,
+          };
+        }
+      }
+
+      return { safe: true, reason: null };
+    } catch (error) {
+      return {
+        safe: false,
+        reason: `Invalid selector: ${error.message}`,
+      };
+    }
+  }
+
+  /**
+   * Check if element text suggests dangerous action
+   * @param {string} text - Element text content
+   * @returns {object} { safe: boolean, reason: string }
+   */
+  isTextSafe(text) {
+    if (!text) {
+      return { safe: true, reason: null };
+    }
+
+    const textLower = text.toLowerCase().trim();
+    const dangerousWords = [
+      'logout',
+      'log out',
+      'sign out',
+      'delete',
+      'remove',
+      'destroy',
+      'cancel account',
+      'close account',
+      'unsubscribe',
+    ];
+
+    for (const word of dangerousWords) {
+      if (textLower.includes(word)) {
+        return {
+          safe: false,
+          reason: `Text contains dangerous word: "${word}"`,
+        };
+      }
+    }
+
+    return { safe: true, reason: null };
+  }
+
+  /**
+   * Check if action involves payment
+   * @param {string} context - Context (URL, selector, or text)
+   * @returns {boolean} True if payment-related
+   */
+  isPaymentRelated(context) {
+    if (!context) {
+      return false;
+    }
+
+    const contextLower = context.toLowerCase();
+    
+    for (const keyword of this.paymentKeywords) {
+      if (contextLower.includes(keyword)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if form submission is safe
+   * @param {string} formAction - Form action URL or selector
+   * @param {object} formData - Form data being submitted
+   * @returns {object} { safe: boolean, reason: string }
+   */
+  isFormSubmitSafe(formAction, formData = {}) {
+    // Check if form submissions are globally blocked
+    if (this.blockFormSubmitsByDefault) {
+      return {
+        safe: false,
+        reason: 'Form submissions are blocked by default (safety guard)',
+      };
+    }
+
+    // Check if form action URL is safe
+    if (formAction) {
+      const urlCheck = this.isUrlSafe(formAction);
+      if (!urlCheck.safe) {
+        return urlCheck;
+      }
+
+      // Check if payment-related
+      if (this.blockPaymentsByDefault && this.isPaymentRelated(formAction)) {
+        return {
+          safe: false,
+          reason: 'Form submission appears payment-related (blocked by safety guard)',
+        };
+      }
+    }
+
+    // Check form data for sensitive fields
+    const formDataStr = JSON.stringify(formData).toLowerCase();
+    if (this.blockPaymentsByDefault && this.isPaymentRelated(formDataStr)) {
+      return {
+        safe: false,
+        reason: 'Form data contains payment-related fields (blocked by safety guard)',
+      };
+    }
+
+    return { safe: true, reason: null };
+  }
+
+  /**
+   * Filter URLs to remove unsafe ones
+   * @param {string[]} urls - Array of URLs
+   * @returns {object} { safe: string[], blocked: Array<{url, reason}> }
+   */
+  filterUrls(urls) {
+    const safe = [];
+    const blocked = [];
+
+    for (const url of urls) {
+      const check = this.isUrlSafe(url);
+      if (check.safe) {
+        safe.push(url);
+      } else {
+        blocked.push({ url, reason: check.reason });
+      }
+    }
+
+    return { safe, blocked };
+  }
+
+  /**
+   * Get safety summary (how many URLs/actions were blocked)
+   * @param {object} stats - Statistics object
+   * @returns {object} Safety summary
+   */
+  getSummary(stats = {}) {
+    return {
+      urlsBlocked: stats.urlsBlocked || 0,
+      selectorsBlocked: stats.selectorsBlocked || 0,
+      formsBlocked: stats.formsBlocked || 0,
+      totalBlocked: (stats.urlsBlocked || 0) + (stats.selectorsBlocked || 0) + (stats.formsBlocked || 0),
+      safetyEnabled: true,
+    };
+  }
+}
+
+module.exports = GuardianSafety;

package/src/guardian/scan-presets.js

@@ -0,0 +1,60 @@
+/**
+ * Scan Presets (Phase 6)
+ * Opinionated defaults for one-command scans
+ * Deterministic mappings: attempts, flows, policy thresholds.
+ */
+
+const { getDefaultAttemptIds } = require('./attempt-registry');
+const { getDefaultFlowIds } = require('./flow-registry');
+
+function resolveScanPreset(name = 'landing') {
+  const preset = (name || '').toLowerCase();
+
+  // Defaults: curated attempts + curated flows
+  const defaults = {
+    attempts: getDefaultAttemptIds(),
+    flows: getDefaultFlowIds(),
+    policy: null
+  };
+
+  switch (preset) {
+    case 'landing':
+      return {
+        attempts: ['contact_form', 'language_switch', 'newsletter_signup'],
+        flows: [], // focus on landing conversion, flows optional
+        policy: {
+          // lenient warnings, strict criticals
+          failOnSeverity: 'CRITICAL',
+          maxWarnings: 999,
+          visualGates: { CRITICAL: 0, WARNING: 999, maxDiffPercent: 25 }
+        }
+      };
+    case 'saas':
+      return {
+        attempts: ['language_switch', 'contact_form', 'newsletter_signup'],
+        flows: ['signup_flow', 'login_flow'],
+        policy: {
+          failOnSeverity: 'CRITICAL',
+          maxWarnings: 1,
+          failOnNewRegression: true,
+          visualGates: { CRITICAL: 0, WARNING: 5, maxDiffPercent: 20 }
+        }
+      };
+    case 'shop':
+    case 'ecommerce':
+      return {
+        attempts: ['language_switch', 'contact_form', 'newsletter_signup'],
+        flows: ['checkout_flow'],
+        policy: {
+          failOnSeverity: 'CRITICAL',
+          maxWarnings: 0,
+          failOnNewRegression: true,
+          visualGates: { CRITICAL: 0, WARNING: 0, maxDiffPercent: 15 }
+        }
+      };
+    default:
+      return defaults;
+  }
+}
+
+module.exports = { resolveScanPreset };