@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/guardian/success-evaluator.js

@@ -0,0 +1,214 @@
+/**
+ * Wave 1.3 — Outcome-Based Success Evaluator
+ * Deterministic success evaluation for form submissions and key flows.
+ * No reliance on specific confirmation text; uses signals: Network, Navigation, DOM, Errors.
+ */
+
+const URL_SAFE_STATUSES = new Set([200, 201, 202, 204, 302, 303]);
+
+/**
+ * Capture pre-submit state around a submit element's owning form.
+ * @param {import('playwright').Page} page
+ * @param {import('playwright').ElementHandle|null} submitHandle
+ */
+async function captureBeforeState(page, submitHandle) {
+  const url = page.url();
+  const state = await page.evaluate((submitEl) => {
+    const result = {
+      formSelector: null,
+      formExists: false,
+      inputsFilledCount: 0,
+      inputsTotal: 0,
+      ariaInvalidCount: 0,
+      hasAlertRegion: false,
+      alertTextLength: 0,
+      liveRegionTextLength: 0,
+    };
+
+    let form = null;
+    if (submitEl) {
+      form = submitEl.closest('form');
+    } else {
+      form = document.querySelector('form');
+    }
+
+    if (form) {
+      result.formSelector = form.getAttribute('id') ? `#${form.id}` : null;
+      result.formExists = true;
+      const inputs = Array.from(form.querySelectorAll('input, textarea, select'));
+      result.inputsTotal = inputs.length;
+      result.inputsFilledCount = inputs.filter((el) => {
+        const val = (el.value || '').trim();
+        return val.length > 0;
+      }).length;
+      result.ariaInvalidCount = inputs.filter((el) => el.getAttribute('aria-invalid') === 'true').length;
+    }
+
+    // role=alert or [aria-live]
+    const alertEl = document.querySelector('[role="alert"], .alert, .error, .invalid');
+    if (alertEl) {
+      result.hasAlertRegion = true;
+      result.alertTextLength = (alertEl.textContent || '').trim().length;
+    }
+    const liveEl = document.querySelector('[aria-live]');
+    if (liveEl) {
+      result.liveRegionTextLength = (liveEl.textContent || '').trim().length;
+    }
+    return result;
+  }, submitHandle);
+
+  return { url, state };
+}
+
+/**
+ * Capture post-submit state.
+ * @param {import('playwright').Page} page
+ * @param {string|null} originalFormSelector
+ */
+async function captureAfterState(page, originalFormSelector) {
+  const url = page.url();
+  const state = await page.evaluate((formSelector) => {
+    const result = {
+      formExists: false,
+      formDisabled: false,
+      inputsFilledCount: 0,
+      inputsTotal: 0,
+      ariaInvalidCount: 0,
+      hasAlertRegion: false,
+      alertTextLength: 0,
+      liveRegionTextLength: 0,
+    };
+
+    let form = null;
+    if (formSelector) {
+      form = document.querySelector(formSelector);
+    }
+    if (!form) {
+      form = document.querySelector('form');
+    }
+
+    if (form) {
+      result.formExists = true;
+      result.formDisabled = !!form.getAttribute('disabled') || (form.classList.contains('disabled'));
+      const inputs = Array.from(form.querySelectorAll('input, textarea, select'));
+      result.inputsTotal = inputs.length;
+      result.inputsFilledCount = inputs.filter((el) => (el.value || '').trim().length > 0).length;
+      result.ariaInvalidCount = inputs.filter((el) => el.getAttribute('aria-invalid') === 'true').length;
+    }
+
+    const alertEl = document.querySelector('[role="alert"], .alert, .error, .invalid');
+    if (alertEl) {
+      result.hasAlertRegion = true;
+      result.alertTextLength = (alertEl.textContent || '').trim().length;
+    }
+    const liveEl = document.querySelector('[aria-live]');
+    if (liveEl) {
+      result.liveRegionTextLength = (liveEl.textContent || '').trim().length;
+    }
+    return result;
+  }, originalFormSelector);
+
+  return { url, state };
+}
+
+/**
+ * Evaluate success based on signals.
+ * @param {{url:string,state:Object}} before
+ * @param {{url:string,state:Object}} after
+ * @param {{requests:Array,responses:Array,consoleErrors:Array,navChanged:boolean,baseOrigin:string}} events
+ * @returns {{status:'success'|'friction'|'failure',confidence:'high'|'medium'|'low',reasons:string[],evidence:Object}}
+ */
+function evaluateSuccess(before, after, events) {
+  const reasons = [];
+  const evidence = {
+    network: [],
+    urlChanged: before.url !== after.url,
+    formCleared: false,
+    formDisappeared: false,
+    formDisabled: false,
+    alertRegionDelta: 0,
+    liveRegionDelta: 0,
+    ariaInvalidDelta: 0,
+    consoleErrors: events.consoleErrors || [],
+  };
+
+  // A) Network success
+  const baseOrigin = events.baseOrigin;
+  let strongNetworkPositive = false;
+  for (const r of (events.responses || [])) {
+    const req = typeof r.request === 'function' ? r.request() : r.request;
+    if (!req || typeof req.url !== 'function') continue;
+    const url = req.url();
+    const originOk = safeSameOrAllowedOrigin(url, baseOrigin);
+    const method = (typeof req.method === 'function' ? req.method() : '').toUpperCase();
+    const status = typeof r.status === 'function' ? r.status() : r.status;
+    const statusOk = URL_SAFE_STATUSES.has(status);
+    evidence.network.push({ method, url, status, originOk, statusOk });
+    if (originOk && (method === 'POST' || method === 'PUT') && statusOk) {
+      strongNetworkPositive = true;
+    }
+  }
+
+  if (strongNetworkPositive) {
+    reasons.push('Network submit succeeded (safe status and origin)');
+  }
+
+  // B) Navigation
+  const navPositive = !!events.navChanged;
+  if (navPositive) reasons.push('URL changed after submit');
+
+  // C) DOM outcome
+  const beforeState = before.state;
+  const afterState = after.state;
+  evidence.formDisappeared = !!beforeState.formExists && !afterState.formExists;
+  evidence.formDisabled = !!afterState.formDisabled;
+  evidence.formCleared = beforeState.inputsFilledCount > 0 && afterState.inputsFilledCount < beforeState.inputsFilledCount;
+  evidence.alertRegionDelta = (afterState.alertTextLength || 0) - (beforeState.alertTextLength || 0);
+  evidence.liveRegionDelta = (afterState.liveRegionTextLength || 0) - (beforeState.liveRegionTextLength || 0);
+  evidence.ariaInvalidDelta = (afterState.ariaInvalidCount || 0) - (beforeState.ariaInvalidCount || 0);
+
+  const domPositive = evidence.formDisappeared || evidence.formDisabled || evidence.formCleared || evidence.liveRegionDelta > 0;
+  if (domPositive) reasons.push('Form outcome indicates completion (cleared/disabled/disappeared or live region updated)');
+
+  // D) Error outcome
+  const strongNegative = evidence.ariaInvalidDelta > 0 || (afterState.hasAlertRegion && evidence.alertRegionDelta > 0);
+  if (strongNegative) reasons.push('Error markers increased after submit');
+
+  // E) Console errors
+  const consoleNegative = (events.consoleErrors || []).length > 0;
+  if (consoleNegative) reasons.push('Console errors after submit');
+
+  // Decision table
+  let status = 'failure';
+  let confidence = 'low';
+  if (strongNetworkPositive && (navPositive || domPositive) && !strongNegative && !consoleNegative) {
+    status = 'success';
+    confidence = 'high';
+  } else if ((strongNetworkPositive || navPositive || domPositive) && (strongNegative || consoleNegative)) {
+    status = 'friction';
+    confidence = strongNetworkPositive ? 'medium' : 'low';
+  } else if (strongNetworkPositive || navPositive || domPositive) {
+    status = 'success';
+    confidence = 'medium';
+  } else {
+    status = 'failure';
+    confidence = strongNegative ? 'medium' : 'low';
+  }
+
+  return { status, confidence, reasons, evidence };
+}
+
+function safeSameOrAllowedOrigin(url, baseOrigin) {
+  try {
+    const u = new URL(url);
+    return u.origin === baseOrigin;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  captureBeforeState,
+  captureAfterState,
+  evaluateSuccess,
+};

package/src/guardian/template-command.js

@@ -0,0 +1,184 @@
+/**
+ * Template Command
+ * 
+ * Generate minimal config templates:
+ *   guardian template saas
+ *   guardian template shop
+ *   guardian template landing
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATES = {
+  saas: {
+    name: 'SaaS Startup Check',
+    description: 'Verify core SaaS flows: signup, login, dashboard',
+    intent: {
+      category: 'product_type',
+      value: 'saas',
+      confidence: 1.0
+    },
+    journeys: [
+      {
+        id: 'signup_flow',
+        name: 'User Signup',
+        description: 'Verify signup journey completes',
+        steps: [
+          { action: 'navigate', target: '/', name: 'Home' },
+          { action: 'click', target: 'a[href*="/signup"], button:has-text("Sign up")', name: 'Click signup' },
+          { action: 'wait', ms: 2000 },
+          { action: 'screenshot', name: 'Signup form loaded' }
+        ],
+        criticality: 'CRITICAL',
+        onFailure: 'FAIL'
+      },
+      {
+        id: 'landing_page',
+        name: 'Landing Page Load',
+        description: 'Verify homepage loads without errors',
+        steps: [
+          { action: 'navigate', target: '/', name: 'Home' },
+          { action: 'screenshot', name: 'Homepage loaded' }
+        ],
+        criticality: 'CRITICAL',
+        onFailure: 'WARN'
+      }
+    ],
+    policy: {
+      failOnSeverity: 'CRITICAL',
+      maxWarnings: 10,
+      requireBaseline: false
+    }
+  },
+
+  shop: {
+    name: 'E-Commerce Shop Check',
+    description: 'Verify core shop flows: browse, add to cart, checkout',
+    intent: {
+      category: 'product_type',
+      value: 'ecommerce',
+      confidence: 1.0
+    },
+    journeys: [
+      {
+        id: 'browse_products',
+        name: 'Browse Products',
+        description: 'Verify product catalog loads',
+        steps: [
+          { action: 'navigate', target: '/', name: 'Home' },
+          { action: 'click', target: 'a[href*="/shop"], a[href*="/products"], button:has-text("Shop")', name: 'Go to shop' },
+          { action: 'wait', ms: 2000 },
+          { action: 'screenshot', name: 'Products page' }
+        ],
+        criticality: 'CRITICAL',
+        onFailure: 'FAIL'
+      },
+      {
+        id: 'add_to_cart',
+        name: 'Add to Cart',
+        description: 'Verify add-to-cart flow',
+        steps: [
+          { action: 'navigate', target: '/', name: 'Home' },
+          { action: 'click', target: 'a[href*="/shop"], a[href*="/products"]', name: 'Go to shop' },
+          { action: 'wait', ms: 2000 },
+          { action: 'click', target: 'button:has-text("Add"), button:has-text("Cart")', name: 'Add item' },
+          { action: 'screenshot', name: 'Cart updated' }
+        ],
+        criticality: 'CRITICAL',
+        onFailure: 'WARN'
+      }
+    ],
+    policy: {
+      failOnSeverity: 'CRITICAL',
+      maxWarnings: 10,
+      requireBaseline: false
+    }
+  },
+
+  landing: {
+    name: 'Landing Page Check',
+    description: 'Verify landing page loads and core CTAs work',
+    intent: {
+      category: 'product_type',
+      value: 'landing',
+      confidence: 1.0
+    },
+    journeys: [
+      {
+        id: 'page_load',
+        name: 'Page Load',
+        description: 'Verify landing page loads',
+        steps: [
+          { action: 'navigate', target: '/', name: 'Home' },
+          { action: 'screenshot', name: 'Landing page' }
+        ],
+        criticality: 'CRITICAL',
+        onFailure: 'FAIL'
+      },
+      {
+        id: 'cta_click',
+        name: 'Call-to-Action',
+        description: 'Verify main CTA is clickable',
+        steps: [
+          { action: 'navigate', target: '/', name: 'Home' },
+          { action: 'click', target: 'button:has-text("Get started"), button:has-text("Start"), button:has-text("Sign up"), a[href*="/signup"]', name: 'Click CTA' },
+          { action: 'screenshot', name: 'CTA works' }
+        ],
+        criticality: 'CRITICAL',
+        onFailure: 'WARN'
+      }
+    ],
+    policy: {
+      failOnSeverity: 'CRITICAL',
+      maxWarnings: 5,
+      requireBaseline: false
+    }
+  }
+};
+
+/**
+ * Generate config file from template
+ * @param {string} templateName - saas, shop, or landing
+ * @param {object} options - Generation options
+ * @returns {object} Result with generated file path
+ */
+function generateTemplate(templateName, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const outputFile = options.output || `guardian-${templateName}.json`;
+  const outputPath = path.join(cwd, outputFile);
+
+  if (!TEMPLATES[templateName]) {
+    throw new Error(`Unknown template: ${templateName}. Available: ${Object.keys(TEMPLATES).join(', ')}`);
+  }
+
+  const template = TEMPLATES[templateName];
+  const content = JSON.stringify(template, null, 2);
+
+  fs.writeFileSync(outputPath, content, 'utf-8');
+
+  return {
+    success: true,
+    template: templateName,
+    outputPath,
+    message: `Generated ${templateName} template: ${outputFile}`
+  };
+}
+
+/**
+ * List available templates
+ * @returns {array} Array of template names with descriptions
+ */
+function listTemplates() {
+  return Object.entries(TEMPLATES).map(([name, config]) => ({
+    name,
+    description: config.description,
+    journeys: config.journeys.length
+  }));
+}
+
+module.exports = {
+  generateTemplate,
+  listTemplates,
+  TEMPLATES
+};