@odavl/guardian 0.1.0-rc1 → 0.2.0

package/src/guardian/market-reporter.js

@@ -121,6 +121,21 @@ class MarketReporter {
     const flowRows = flows.map((flow, idx) => {
       const color = flow.outcome === 'SUCCESS' ? '#10b981' : '#ef4444';
       const badge = flow.outcome === 'SUCCESS' ? '✅ SUCCESS' : '❌ FAILURE';
+      const evalSummary = flow.successEval ? (() => {
+        const reasons = (flow.successEval.reasons || []).slice(0, 3).map(r => `• ${r}`).join('<br/>');
+        const ev = flow.successEval.evidence || {};
+        const net = Array.isArray(ev.network) ? ev.network : [];
+        const primary = net.find(n => (n.method === 'POST' || n.method === 'PUT') && n.status != null) || net[0];
+        const reqLine = primary ? (() => { try { const p = new URL(primary.url); return `${primary.method} ${p.pathname} → ${primary.status}`; } catch { return `${primary.method} ${primary.url} → ${primary.status}`; } })() : null;
+        const navLine = ev.urlChanged ? 'navigation: changed' : null;
+        const formStates = [];
+        if (ev.formCleared) formStates.push('cleared');
+        if (ev.formDisabled) formStates.push('disabled');
+        if (ev.formDisappeared) formStates.push('disappeared');
+        const formLine = formStates.length ? `form: ${formStates.join(', ')}` : null;
+        const evidences = [reqLine, navLine, formLine].filter(Boolean).map(e => `• ${e}`).join('<br/>' );
+        return `<div><strong>Reasons:</strong><br/>${reasons || '—'}<br/><strong>Evidence:</strong><br/>${evidences || '—'}</div>`;
+      })() : '';
       return `
         <tr>
           <td>${idx + 1}</td>
@@ -128,7 +143,7 @@ class MarketReporter {
           <td>${flow.flowName || ''}</td>
           <td><span class="badge" style="background:${color}">${badge}</span></td>
           <td>${flow.stepsExecuted || 0}/${flow.stepsTotal || 0}</td>
-          <td>${flow.error || ''}</td>
+          <td>${flow.error || evalSummary || ''}</td>
         </tr>
       `;
     }).join('');

package/src/guardian/parallel-executor.js

@@ -0,0 +1,116 @@
+/**
+ * Phase 7.2 - Parallel Executor
+ * Controlled parallel execution of attempts with bounded concurrency
+ */
+
+/**
+ * Execute attempts with bounded parallelism
+ * @param {Array} attempts - Array of attempts to execute
+ * @param {Function} executeAttemptFn - Async function(attempt) => result
+ * @param {number} maxConcurrency - Max concurrent attempts (must be >= 1)
+ * @param {Object} options - { shouldStop?: Function }
+ * @returns {Promise<Array>} Results in original input order
+ */
+async function executeParallel(attempts, executeAttemptFn, maxConcurrency = 1, options = {}) {
+  if (maxConcurrency < 1) {
+    throw new Error('maxConcurrency must be >= 1');
+  }
+
+  // Handle empty queue immediately
+  if (!attempts || attempts.length === 0) {
+    return [];
+  }
+
+  const results = new Array(attempts.length);
+  const queue = attempts.map((attempt, index) => ({ attempt, index }));
+  let executing = 0;
+  let queueIndex = 0;
+  let shouldStop = false;
+
+  return new Promise((resolve, reject) => {
+    const processNext = async () => {
+      // Check if we should stop (e.g., fail-fast triggered)
+      if (options.shouldStop && options.shouldStop()) {
+        shouldStop = true;
+      }
+
+      // If no more work and nothing executing, we're done
+      if (queueIndex >= queue.length && executing === 0) {
+        resolve(results);
+        return;
+      }
+
+      // If we've hit the concurrency limit or have no more items, wait
+      if (executing >= maxConcurrency || queueIndex >= queue.length) {
+        return;
+      }
+
+      // Get next item from queue
+      const { attempt, index } = queue[queueIndex];
+      queueIndex++;
+      executing++;
+
+      try {
+        // Only execute if we haven't stopped
+        if (!shouldStop) {
+          results[index] = await executeAttemptFn(attempt);
+        } else {
+          // Mark as skipped if we stopped
+          results[index] = { skipped: true };
+        }
+      } catch (err) {
+        results[index] = { error: err, skipped: false };
+      } finally {
+        executing--;
+        // Process next item(s)
+        processNext();
+        if (executing < maxConcurrency && queueIndex < queue.length && !shouldStop) {
+          processNext();
+        }
+      }
+    };
+
+    // Start workers
+    for (let i = 0; i < Math.min(maxConcurrency, queue.length); i++) {
+      processNext();
+    }
+  });
+}
+
+/**
+ * Validate parallel concurrency value
+ * @param {number|string} value - Value to validate
+ * @returns {{ valid: boolean, parallel?: number, error?: string, hint?: string }}
+ */
+function validateParallel(value) {
+  if (value === undefined || value === null) {
+    return { valid: true, parallel: 1 };
+  }
+
+  const num = parseInt(value, 10);
+
+  // Check for NaN
+  if (isNaN(num)) {
+    return {
+      valid: false,
+      error: `Invalid --parallel value: '${value}' (expected integer >= 1)`,
+      hint: 'Example: --parallel 2'
+    };
+  }
+
+  // Check if less than 1
+  if (num < 1) {
+    return {
+      valid: false,
+      error: `Invalid --parallel value: ${num} (must be >= 1)`,
+      hint: 'Example: --parallel 2'
+    };
+  }
+
+  return { valid: true, parallel: num };
+}
+
+module.exports = {
+  executeParallel,
+  validateParallel
+};

package/src/guardian/prerequisite-checker.js

@@ -0,0 +1,101 @@
+/**
+ * Phase 7.4: Prerequisite Checker
+ * 
+ * Validates hard prerequisites before executing attempts.
+ * Enables early skip of impossible attempts to save time.
+ */
+
+/**
+ * Define prerequisites for each attempt type
+ * Returns deterministic checks that can fail fast
+ */
+const ATTEMPT_PREREQUISITES = {
+  checkout: {
+    description: 'Checkout requires accessible checkout page or cart',
+    checks: [
+      {
+        type: 'elementExists',
+        selector: 'a[href*="checkout"], a[href*="cart"], [data-guardian="checkout-link"], [data-guardian="cart-link"]',
+        reason: 'No checkout/cart link found on page'
+      }
+    ]
+  },
+  login: {
+    description: 'Login requires accessible login page',
+    checks: [
+      {
+        type: 'elementExists',
+        selector: 'a[href*="login"], a[href*="signin"], a:has-text("Login"), a:has-text("Sign in"), [data-guardian="account-login-link"], input[type="email"][id*="login"], input[type="email"][name*="login"]',
+        reason: 'No login link or login form found'
+      }
+    ]
+  },
+  newsletter_signup: {
+    description: 'Newsletter requires email input',
+    checks: [
+      {
+        type: 'elementExists',
+        selector: 'input[type="email"], input[placeholder*="email" i], input[name*="email"], [data-guardian="email-input"]',
+        reason: 'No email input found for newsletter'
+      }
+    ]
+  },
+  signup: {
+    description: 'Signup requires accessible signup page',
+    checks: [
+      {
+        type: 'elementExists',
+        selector: 'a[href*="signup"], a[href*="register"], a:has-text("Sign up"), a:has-text("Register"), [data-guardian="signup-link"]',
+        reason: 'No signup/register link found'
+      }
+    ]
+  }
+};
+
+/**
+ * Check if an attempt's prerequisites are met
+ * @param {Page} page - Playwright page
+ * @param {string} attemptId - Attempt identifier
+ * @param {number} timeout - Max time to check (short, e.g., 2000ms)
+ * @returns {Promise<{canProceed: boolean, reason: string|null}>}
+ */
+async function checkPrerequisites(page, attemptId, timeout = 2000) {
+  const prereqs = ATTEMPT_PREREQUISITES[attemptId];
+  
+  // No prerequisites defined = can proceed
+  if (!prereqs || !prereqs.checks || prereqs.checks.length === 0) {
+    return { canProceed: true, reason: null };
+  }
+
+  // Check each prerequisite
+  for (const check of prereqs.checks) {
+    if (check.type === 'elementExists') {
+      try {
+        // Quick check with short timeout
+        const exists = await page.locator(check.selector).first().isVisible({ timeout });
+        if (!exists) {
+          return { canProceed: false, reason: check.reason };
+        }
+      } catch (err) {
+        // Element not found = prerequisite failed
+        return { canProceed: false, reason: check.reason };
+      }
+    }
+  }
+
+  return { canProceed: true, reason: null };
+}
+
+/**
+ * Get list of attempt IDs that have prerequisites defined
+ * @returns {string[]}
+ */
+function getAttemptsWithPrerequisites() {
+  return Object.keys(ATTEMPT_PREREQUISITES);
+}
+
+module.exports = {
+  checkPrerequisites,
+  getAttemptsWithPrerequisites,
+  ATTEMPT_PREREQUISITES
+};

package/src/guardian/preset-loader.js

@@ -71,20 +71,26 @@ function parsePolicyOption(policyOption) {
   }
 
   // Otherwise, treat as file path
-  if (fs.existsSync(optionStr)) {
-    try {
-      const content = fs.readFileSync(optionStr, 'utf-8');
-      const policy = JSON.parse(content);
-      console.log(`✅ Loaded policy from: ${optionStr}`);
-      return policy;
-    } catch (error) {
-      console.error(`⚠️  Failed to load policy from ${optionStr}: ${error.message}`);
-      return null;
-    }
+  // Fix for Wave 0.5: Validate policy file exists BEFORE attempting to load
+  if (!fs.existsSync(optionStr)) {
+    console.error(`Error: Policy file not found: ${optionStr}`);
+    console.error('');
+    console.error('Please provide a valid policy file or use a preset:');
+    console.error('  --policy preset:startup     (Permissive for fast-moving startups)');
+    console.error('  --policy preset:saas        (Balanced for SaaS products)');
+    console.error('  --policy preset:enterprise  (Strict for enterprise deployments)');
+    process.exit(1);
   }
 
-  console.warn(`⚠️  Policy file not found: ${optionStr}`);
-  return null;
+  try {
+    const content = fs.readFileSync(optionStr, 'utf-8');
+    const policy = JSON.parse(content);
+    console.log(`✅ Loaded policy from: ${optionStr}`);
+    return policy;
+  } catch (error) {
+    console.error(`Error: Failed to load policy from ${optionStr}: ${error.message}`);
+    process.exit(1);
+  }
 }
 
 /**

package/src/guardian/profile-loader.js

@@ -0,0 +1,96 @@
+const fs = require('fs');
+const path = require('path');
+
+const PROFILE_PATH = path.join(__dirname, '../../data/guardian-profiles.json');
+let cachedProfiles = null;
+let cachedMtime = null;
+
+function normalizeOrigin(value) {
+  if (!value) return null;
+  try {
+    const url = value.startsWith('http://') || value.startsWith('https://')
+      ? new URL(value)
+      : new URL(`http://${value}`);
+    return url.origin;
+  } catch (err) {
+    return null;
+  }
+}
+
+function loadProfilesFile() {
+  try {
+    if (!fs.existsSync(PROFILE_PATH)) {
+      return [];
+    }
+    const stat = fs.statSync(PROFILE_PATH);
+    if (cachedProfiles && cachedMtime === stat.mtimeMs) {
+      return cachedProfiles;
+    }
+    const raw = fs.readFileSync(PROFILE_PATH, 'utf8');
+    const data = JSON.parse(raw);
+    const profiles = [];
+
+    if (Array.isArray(data)) {
+      data.forEach((entry) => {
+        const origin = normalizeOrigin(entry.origin || entry.site);
+        if (!origin || !entry.selectors) return;
+        profiles.push({ site: origin, selectors: entry.selectors, navigation: entry.navigation });
+      });
+    } else if (data && typeof data === 'object') {
+      Object.keys(data).forEach((key) => {
+        const origin = normalizeOrigin(key);
+        if (!origin) return;
+        const entry = data[key];
+        if (!entry || typeof entry !== 'object') return;
+        profiles.push({ site: origin, selectors: entry.selectors || entry, navigation: entry.navigation });
+      });
+    }
+
+    cachedProfiles = profiles;
+    cachedMtime = stat.mtimeMs;
+    return profiles;
+  } catch (err) {
+    console.log(`⚠️  Failed to load profiles: ${err.message}`);
+    return [];
+  }
+}
+
+function resolveProfileForUrl(url) {
+  if (!url) return null;
+  let origin = null;
+  let host = null;
+  try {
+    const u = new URL(url);
+    origin = u.origin;
+    host = u.hostname;
+  } catch (err) {
+    return null;
+  }
+
+  const profiles = loadProfilesFile();
+  if (profiles.length === 0) {
+    return null;
+  }
+
+  const exact = profiles.find((p) => p.site === origin);
+  if (exact) return exact;
+
+  const hostMatch = profiles.find((p) => {
+    try {
+      const u = new URL(p.site);
+      if (u.port && u.port !== '80') {
+        return u.hostname === host && u.port === (new URL(origin)).port;
+      }
+      return u.hostname === host;
+    } catch {
+      return false;
+    }
+  });
+
+  return hostMatch || null;
+}
+
+module.exports = {
+  resolveProfileForUrl,
+  loadProfilesFile,
+};