@odavl/guardian 0.1.0-rc1 → 0.2.0

package/src/guardian/cli-summary.js

@@ -9,9 +9,10 @@
  * Generate final CLI summary
  * @param {object} snapshot - Guardian snapshot
  * @param {object} policyEval - Policy evaluation result
+ * @param {object} baselineCheckResult - Optional baseline check result
  * @returns {string} Formatted CLI summary
  */
-function generateCliSummary(snapshot, policyEval) {
+function generateCliSummary(snapshot, policyEval, baselineCheckResult) {
   if (!snapshot) {
     return 'No snapshot data available.';
   }
@@ -68,17 +69,62 @@ function generateCliSummary(snapshot, policyEval) {
   }
 
   // Attempt Summary
+  // Phase 7.4: Include SKIPPED in summary
   const successfulAttempts = attempts.filter(a => a.outcome === 'SUCCESS').length;
+  const skippedAttempts = attempts.filter(a => a.outcome === 'SKIPPED').length;
   const totalAttempts = attempts.length;
   if (totalAttempts > 0) {
     output += '🎯 Attempts:\n';
     output += `   ${successfulAttempts}/${totalAttempts} successful`;
     if (successfulAttempts < totalAttempts) {
-      output += ` (${totalAttempts - successfulAttempts} failed)`;
+      const failed = totalAttempts - successfulAttempts - skippedAttempts;
+      if (failed > 0) output += ` (${failed} failed)`;
+      if (skippedAttempts > 0) output += ` (${skippedAttempts} skipped)`;
     }
     output += '\n\n';
   }
 
+  // Flow Submit Outcomes (Wave 1.3)
+  const flows = snapshot.flows || [];
+  const flowsWithEval = flows.filter(f => f.successEval);
+  if (flowsWithEval.length > 0) {
+    output += '🚦 Submit Outcomes:\n';
+    flowsWithEval.slice(0, 5).forEach(f => {
+      const status = (f.successEval.status || 'unknown').toUpperCase();
+      const confidence = f.successEval.confidence || 'low';
+      output += `   ${f.flowName}: ${status} (confidence: ${confidence})\n`;
+      const reasons = (f.successEval.reasons || []).slice(0, 3);
+      if (reasons.length) {
+        output += '     Reasons:\n';
+        reasons.forEach(r => { output += `       - ${r}\n`; });
+      }
+      // Compact evidence summary
+      const ev = f.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 = (() => {
+        if (!primary) return null;
+        try { const p = new URL(primary.url); return `request: ${primary.method} ${p.pathname} → ${primary.status}`; }
+        catch { return `request: ${primary.method} ${primary.url} → ${primary.status}`; }
+      })();
+      const navLine = ev.urlChanged ? (() => {
+        try { const from = new URL(snapshot.meta.url).pathname; const to = ''; return `navigation: changed`; }
+        catch { return `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 evidenceLines = [reqLine, navLine, formLine].filter(Boolean);
+      if (evidenceLines.length) {
+        output += '     Evidence:\n';
+        evidenceLines.slice(0, 2).forEach(line => { output += `       - ${line}\n`; });
+      }
+    });
+    output += '\n';
+  }
+
   // Discovery Summary
   if (discovery.pagesVisitedCount > 0) {
     output += '🔍 Discovery:\n';
@@ -104,6 +150,73 @@ function generateCliSummary(snapshot, policyEval) {
     output += `   Exit code: ${policyEval.exitCode || 0}\n\n`;
   }
 
+  // Baseline Comparison (Phase 3.2)
+  if (baselineCheckResult) {
+    const verdict = baselineCheckResult.overallRegressionVerdict || 'NO_BASELINE';
+    
+    if (verdict === 'NO_BASELINE') {
+      output += '📊 Baseline Comparison: not found (no comparison)\n\n';
+    } else if (verdict === 'BASELINE_UNUSABLE') {
+      output += '📊 Baseline Comparison: unusable (skipped)\n\n';
+    } else {
+      const emoji = verdict === 'NO_REGRESSION' ? '✅' : 
+                    verdict === 'REGRESSION_FRICTION' ? '🟡' :
+                    '🔴';
+      
+      output += '📊 Baseline Comparison:\n';
+      output += `   ${emoji} ${verdict.replace(/_/g, ' ')}\n`;
+      
+      // Show per-attempt changes
+      const comparisons = baselineCheckResult.comparisons || [];
+      const regressions = comparisons.filter(c => c.regressionType !== 'NO_REGRESSION');
+      const improvements = comparisons.filter(c => c.improvements && c.improvements.length > 0);
+      
+      if (regressions.length > 0) {
+        output += '   \n';
+        output += '   Regressions detected:\n';
+        regressions.slice(0, 3).forEach(r => {
+          const label = r.attemptId || 'unknown';
+          const type = r.regressionType.replace(/_/g, ' ');
+          const reasons = r.regressionReasons.slice(0, 1).join('; ') || 'See report';
+          output += `     • ${label}: ${type}\n`;
+          output += `       ${reasons}\n`;
+        });
+        if (regressions.length > 3) {
+          output += `     ... and ${regressions.length - 3} more regressions\n`;
+        }
+      }
+      
+      if (improvements.length > 0) {
+        output += '   \n';
+        output += '   Improvements detected:\n';
+        improvements.slice(0, 3).forEach(i => {
+          const label = i.attemptId || 'unknown';
+          const improvementText = i.improvements.slice(0, 1).join('; ') || 'Improved';
+          output += `     • ${label}: ${improvementText}\n`;
+        });
+        if (improvements.length > 3) {
+          output += `     ... and ${improvements.length - 3} more improvements\n`;
+        }
+      }
+      
+      // Show per-flow changes
+      const flowComparisons = baselineCheckResult.flowComparisons || [];
+      const flowRegressions = flowComparisons.filter(c => c.regressionType !== 'NO_REGRESSION');
+      
+      if (flowRegressions.length > 0) {
+        output += '   \n';
+        output += '   Flow regressions:\n';
+        flowRegressions.forEach(f => {
+          const label = f.flowId || 'unknown';
+          const type = f.regressionType.replace(/_/g, ' ');
+          output += `     • ${label}: ${type}\n`;
+        });
+      }
+      
+      output += '\n';
+    }
+  }
+
   // Next Action
   output += '👉 Next Action:\n';
   if (counts.CRITICAL > 0) {
@@ -130,8 +243,8 @@ function generateCliSummary(snapshot, policyEval) {
 /**
  * Print summary to console
  */
-function printCliSummary(snapshot, policyEval) {
-  const summary = generateCliSummary(snapshot, policyEval);
+function printCliSummary(snapshot, policyEval, baselineCheckResult) {
+  const summary = generateCliSummary(snapshot, policyEval, baselineCheckResult);
   console.log(summary);
 }
 

package/src/guardian/data-guardian-detector.js

@@ -0,0 +1,189 @@
+/**
+ * Data Guardian Attribute Detector
+ * 
+ * Deterministic detection of data-guardian attributes for stable element targeting.
+ * Supports attribute variants and tokenized values.
+ * 
+ * LAYER 1 in the detection priority hierarchy (highest priority).
+ */
+
+const { normalizeText } = require('./semantic-targets');
+
+/**
+ * Supported data-guardian attribute targets
+ */
+const GUARDIAN_TARGETS = {
+  CONTACT: 'contact',
+  ABOUT: 'about',
+  FORM: 'form',
+  SUBMIT: 'submit'
+};
+
+/**
+ * Find elements by data-guardian attribute
+ * 
+ * @param {Page} page - Playwright page object
+ * @param {string} target - Target to search for (contact, about, form, submit)
+ * @returns {Promise<Array>} Array of matching elements with metadata
+ */
+async function findByGuardianAttribute(page, target) {
+  if (!GUARDIAN_TARGETS[target.toUpperCase()]) {
+    throw new Error(`Unsupported guardian target: ${target}`);
+  }
+
+  const normalizedTarget = target.toLowerCase();
+
+  try {
+    const results = await page.evaluate((targetName) => {
+      const elements = [];
+
+      // Rule 1: Exact match on data-guardian attribute
+      const exactMatches = document.querySelectorAll(`[data-guardian="${targetName}"]`);
+      for (const el of exactMatches) {
+        elements.push({
+          element: el,
+          tagName: el.tagName.toLowerCase(),
+          text: el.textContent?.trim() || '',
+          href: el.href || el.getAttribute('href') || '',
+          ariaLabel: el.getAttribute('aria-label') || '',
+          title: el.getAttribute('title') || '',
+          dataGuardian: el.getAttribute('data-guardian'),
+          dataGuardianVariant: null,
+          matchType: 'exact', // Exact attribute match
+          confidence: 'high'
+        });
+      }
+
+      // Rule 2: Tokenized match (e.g., "contact primary" contains "contact")
+      const allGuardianElements = document.querySelectorAll('[data-guardian]');
+      for (const el of allGuardianElements) {
+        const dataGuardian = el.getAttribute('data-guardian') || '';
+        const tokens = dataGuardian.split(/[\s\-_]+/).map(t => t.toLowerCase());
+
+        if (tokens.includes(targetName)) {
+          // Only add if not already in exact matches
+          const alreadyFound = Array.from(exactMatches).includes(el);
+          if (!alreadyFound) {
+            elements.push({
+              element: el,
+              tagName: el.tagName.toLowerCase(),
+              text: el.textContent?.trim() || '',
+              href: el.href || el.getAttribute('href') || '',
+              ariaLabel: el.getAttribute('aria-label') || '',
+              title: el.getAttribute('title') || '',
+              dataGuardian: el.getAttribute('data-guardian'),
+              dataGuardianVariant: null,
+              matchType: 'tokenized', // Tokenized match
+              confidence: 'high'
+            });
+          }
+        }
+      }
+
+      // Rule 3: Variant attributes (e.g., data-guardian-role="contact")
+      const variantAttr = `data-guardian-${targetName}`;
+      const variantMatches = document.querySelectorAll(`[${variantAttr}]`);
+      for (const el of variantMatches) {
+        const variantValue = el.getAttribute(variantAttr);
+        elements.push({
+          element: el,
+          tagName: el.tagName.toLowerCase(),
+          text: el.textContent?.trim() || '',
+          href: el.href || el.getAttribute('href') || '',
+          ariaLabel: el.getAttribute('aria-label') || '',
+          title: el.getAttribute('title') || '',
+          dataGuardian: el.getAttribute('data-guardian'),
+          dataGuardianVariant: variantAttr, // Track the variant attribute name
+          matchType: 'variant', // Variant attribute match
+          confidence: 'medium'
+        });
+      }
+
+      return elements;
+    }, normalizedTarget);
+
+    return results;
+  } catch (error) {
+    console.warn(`Failed to find elements by guardian attribute: ${error.message}`);
+    return [];
+  }
+}
+
+/**
+ * Check if element has any data-guardian attribute
+ * Returns the attribute value and match type
+ */
+async function getGuardianAttribute(page, selector) {
+  try {
+    const result = await page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) return null;
+
+      const dataGuardian = el.getAttribute('data-guardian');
+      const allAttrs = el.attributes;
+      let variantAttr = null;
+
+      // Check for variant attributes
+      for (const attr of allAttrs) {
+        if (attr.name.startsWith('data-guardian-')) {
+          variantAttr = {
+            name: attr.name,
+            value: attr.value
+          };
+          break;
+        }
+      }
+
+      return {
+        dataGuardian: dataGuardian,
+        variantAttribute: variantAttr,
+        hasGuardianAttr: !!dataGuardian || !!variantAttr
+      };
+    }, selector);
+
+    return result;
+  } catch (error) {
+    console.warn(`Failed to get guardian attribute: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Build CSS selector for a data-guardian attribute
+ */
+function buildGuardianSelector(target, variant = null) {
+  if (variant) {
+    // Variant attribute selector
+    return `[data-guardian-${target}]`;
+  } else {
+    // Standard data-guardian attribute selector
+    return `[data-guardian="${target}"]`;
+  }
+}
+
+/**
+ * Check if an element's data-guardian value matches a target
+ */
+function matchesGuardianTarget(elementDataGuardian, target) {
+  if (!elementDataGuardian) return false;
+
+  const normalized = normalizeText(elementDataGuardian);
+  const normalizedTarget = normalizeText(target);
+
+  // Exact match
+  if (normalized === normalizedTarget) return true;
+
+  // Tokenized match (split by whitespace/hyphens)
+  const tokens = normalized.split(/[\s\-_]+/);
+  if (tokens.includes(normalizedTarget)) return true;
+
+  return false;
+}
+
+module.exports = {
+  findByGuardianAttribute,
+  getGuardianAttribute,
+  buildGuardianSelector,
+  matchesGuardianTarget,
+  GUARDIAN_TARGETS
+};

package/src/guardian/detection-layers.js

@@ -0,0 +1,271 @@
+/**
+ * Detection Priority Layers
+ * 
+ * Implements deterministic, layered detection with strict priority order:
+ * LAYER 0: profile overrides (highest)
+ * LAYER 1: data-guardian attributes
+ * LAYER 2: semantic href matching
+ * LAYER 3: semantic visible text matching
+ * LAYER 4: structural heuristics (nav/footer proximity)
+ * 
+ * Each detection includes metadata: target, source layer, confidence, evidence.
+ */
+
+const { findByGuardianAttribute, matchesGuardianTarget, buildGuardianSelector } = require('./data-guardian-detector');
+const { detectContactCandidates, DETECTION_SOURCE, CONFIDENCE } = require('./semantic-contact-detection');
+const { resolveProfileForUrl } = require('./profile-loader');
+
+/**
+ * Detection layer names (for reporting)
+ */
+const LAYER = {
+  PROFILE: 'profile',
+  DATA_GUARDIAN: 'data-guardian',
+  HREF: 'href',
+  TEXT: 'text',
+  STRUCTURE: 'structure'
+};
+
+/**
+ * Detect element by layer, respecting strict priority
+ * 
+ * @param {Page} page - Playwright page object
+ * @param {string} target - Target to detect (contact, about, form, submit)
+ * @param {string} baseUrl - Base URL for relative links
+ * @returns {Promise<Object>} Detection result with layer, confidence, evidence
+ */
+async function detectByLayers(page, target, baseUrl = '') {
+  const result = {
+    target: target,
+    found: false,
+    layer: null,
+    confidence: null,
+    evidence: null,
+    candidates: [],
+    primaryCandidate: null,
+    reason: ''
+  };
+
+  try {
+    const profile = resolveProfileForUrl(baseUrl || page.url());
+    if (profile) {
+      console.log(`🔧 Loaded profile for ${profile.site}`);
+      const profileSelector = (profile.selectors || {})[target];
+      if (profileSelector) {
+        let nodes = [];
+        try {
+          nodes = await page.$$(profileSelector);
+        } catch (err) {
+          console.log(`   ❌ Profile selector error for ${target}: ${err.message}`);
+          return {
+            ...result,
+            layer: LAYER.PROFILE,
+            reason: `Profile selector error for ${target}: ${err.message}`,
+            profileSite: profile.site,
+            hardFailure: true
+          };
+        }
+
+        if (!nodes || nodes.length === 0) {
+          console.log(`   ❌ Profile selector for ${target} not found on page (${profile.site})`);
+          return {
+            ...result,
+            layer: LAYER.PROFILE,
+            reason: `Profile selector for ${target} not found (${profileSelector})`,
+            profileSite: profile.site,
+            hardFailure: true
+          };
+        }
+
+        console.log(`   🎯 Using profile selector for ${target}: ${profileSelector}`);
+        const candidates = [{
+          selector: profileSelector,
+          matchedText: null,
+          matchedToken: target,
+          source: 'profile',
+          confidence: CONFIDENCE.HIGH,
+          href: null,
+          ariaLabel: null,
+          tagName: nodes[0] ? await nodes[0].evaluate(el => el.tagName.toLowerCase()).catch(() => undefined) : undefined
+        }];
+        return {
+          ...result,
+          found: true,
+          layer: LAYER.PROFILE,
+          confidence: CONFIDENCE.HIGH,
+          candidates,
+          primaryCandidate: candidates[0],
+          evidence: `Profile selector ${profileSelector}`,
+          reason: `Detected via profile override (site: ${profile.site})`,
+          profileSite: profile.site
+        };
+      } else {
+        console.log(`   🔧 Profile loaded for ${profile.site} (no selector for ${target}, falling back)`);
+      }
+    }
+
+    // LAYER 1: data-guardian attributes (HIGHEST priority)
+    const guardianResults = await detectLayer1DataGuardian(page, target);
+    if (guardianResults.length > 0) {
+      result.found = true;
+      result.layer = LAYER.DATA_GUARDIAN;
+      result.confidence = CONFIDENCE.HIGH;
+      result.candidates = guardianResults;
+      result.primaryCandidate = guardianResults[0];
+      result.evidence = `Exact data-guardian="${target}" attribute match`;
+      result.reason = 'Highest priority layer matched: data-guardian attribute provides guaranteed stability.';
+      return result;
+    }
+
+    // LAYER 2: semantic href matching
+    const hrefResults = await detectLayer2Href(page, target, baseUrl);
+    if (hrefResults.length > 0) {
+      result.found = true;
+      result.layer = LAYER.HREF;
+      result.confidence = CONFIDENCE.HIGH;
+      result.candidates = hrefResults;
+      result.primaryCandidate = hrefResults[0];
+      result.evidence = hrefResults[0].matchedToken;
+      result.reason = 'Matched via href attribute using semantic tokens (e.g., "/kontakt" matches German token "kontakt").';
+      return result;
+    }
+
+    // LAYER 3: semantic visible text matching
+    const textResults = await detectLayer3Text(page, target, baseUrl);
+    if (textResults.length > 0) {
+      result.found = true;
+      result.layer = LAYER.TEXT;
+      result.confidence = textResults[0].confidence; // medium or high if in nav/footer
+      result.candidates = textResults;
+      result.primaryCandidate = textResults[0];
+      result.evidence = `Text "${textResults[0].matchedText}" matched token "${textResults[0].matchedToken}"`;
+      result.reason = `Matched via visible text using semantic tokens. ${
+        result.confidence === CONFIDENCE.HIGH ? 
+        'Located in navigation/footer (high confidence).' :
+        'Consider adding data-guardian="' + target + '" for guaranteed stability.'
+      }`;
+      return result;
+    }
+
+    // LAYER 4: structural heuristics (LOWEST priority)
+    const structureResults = await detectLayer4Structure(page, target, baseUrl);
+    if (structureResults.length > 0) {
+      result.found = true;
+      result.layer = LAYER.STRUCTURE;
+      result.confidence = CONFIDENCE.LOW;
+      result.candidates = structureResults;
+      result.primaryCandidate = structureResults[0];
+      result.evidence = `Located in ${structureResults[0].source} based on page structure`;
+      result.reason = `Heuristic detection only (low confidence). Add data-guardian="${target}" attribute for guaranteed stability.`;
+      return result;
+    }
+
+    // Nothing found
+    result.reason = `No ${target} element detected. Consider:
+1. Adding data-guardian="${target}" attribute
+2. Using semantic-friendly text (e.g., "Contact", "Kontakt", "Contacto")
+3. Using semantic-friendly href (e.g., "/contact", "/kontakt")`;
+
+    return result;
+  } catch (error) {
+    console.warn(`Detection by layers failed: ${error.message}`);
+    result.reason = `Detection error: ${error.message}`;
+    return result;
+  }
+}
+
+/**
+ * LAYER 1: data-guardian attribute detection (HIGHEST priority)
+ */
+async function detectLayer1DataGuardian(page, target) {
+  try {
+    const elements = await findByGuardianAttribute(page, target);
+    return elements.map(el => ({
+      selector: buildGuardianSelector(target),
+      matchedText: el.text || el.dataGuardian,
+      matchedToken: target,
+      source: DETECTION_SOURCE.DATA_GUARDIAN,
+      confidence: CONFIDENCE.HIGH,
+      href: el.href,
+      ariaLabel: el.ariaLabel,
+      tagName: el.tagName
+    }));
+  } catch (error) {
+    // Guardian target not supported or error occurred
+    return [];
+  }
+}
+
+/**
+ * LAYER 2: semantic href matching (semantic + deterministic)
+ */
+async function detectLayer2Href(page, target, baseUrl) {
+  try {
+    // Use Wave 1.1 semantic detection but filter by target and href-only
+    const allCandidates = await detectContactCandidates(page, baseUrl);
+    
+    // Filter: only href-based matches for the requested target
+    const hrefMatches = allCandidates.filter(c => 
+      c.source === DETECTION_SOURCE.HREF &&
+      isTargetMatch(target, c.matchedToken)
+    );
+
+    return hrefMatches;
+  } catch (error) {
+    console.warn(`Layer 2 href detection failed: ${error.message}`);
+    return [];
+  }
+}
+
+/**
+ * LAYER 3: semantic visible text matching
+ */
+async function detectLayer3Text(page, target, baseUrl) {
+  try {
+    // Use Wave 1.1 semantic detection but filter by target and text source
+    const allCandidates = await detectContactCandidates(page, baseUrl);
+    
+    // Filter: text-based or nav/footer matches for the requested target
+    const textMatches = allCandidates.filter(c => 
+      (c.source === DETECTION_SOURCE.TEXT || c.source === DETECTION_SOURCE.NAV_FOOTER) &&
+      isTargetMatch(target, c.matchedToken)
+    );
+
+    return textMatches;
+  } catch (error) {
+    console.warn(`Layer 3 text detection failed: ${error.message}`);
+    return [];
+  }
+}
+
+/**
+ * LAYER 4: structural heuristics (LOWEST priority, fallback only)
+ */
+async function detectLayer4Structure(page, target, baseUrl) {
+  // Structural heuristics would look for elements in footer, nav, etc.
+  // by position alone (no semantic matching)
+  // Currently a placeholder — can be enhanced in future waves
+  return [];
+}
+
+/**
+ * Check if a matched token corresponds to the requested target
+ * (e.g., "kontakt" token matches "contact" target in German)
+ */
+function isTargetMatch(target, matchedToken) {
+  // For Wave 1.2, we simplify: contact tokens match contact target, etc.
+  // This can be expanded to support token-to-target mappings if needed
+  if (target.toLowerCase() === 'contact') {
+    // Wave 1.1 already groups all contact tokens under 'contact'
+    return matchedToken && matchedToken.toLowerCase() !== 'about';
+  }
+  // Extend as needed for other targets
+  return false;
+}
+
+module.exports = {
+  detectByLayers,
+  LAYER,
+  DETECTION_SOURCE,
+  CONFIDENCE
+};

package/src/guardian/first-run.js

@@ -0,0 +1,49 @@
+/**
+ * Guardian First-Run Detection & Initialization
+ * Deterministically detects first run and coordinates welcome behavior.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STATE_FILE = '.odavl-guardian/.first-run-state.json';
+
+function hasRunBefore(stateDir = '.odavl-guardian') {
+  try {
+    const filePath = path.join(stateDir, '.first-run-state.json');
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function markAsRun(stateDir = '.odavl-guardian') {
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    const filePath = path.join(stateDir, '.first-run-state.json');
+    fs.writeFileSync(filePath, JSON.stringify({ firstRunAt: new Date().toISOString() }, null, 2));
+  } catch (e) {
+    // Silently ignore state write failures (e.g., permission issues)
+  }
+}
+
+function isFirstRun(stateDir = '.odavl-guardian') {
+  return !hasRunBefore(stateDir);
+}
+
+function printWelcome(label = 'ODAVL Guardian') {
+  const lines = [
+    '',
+    `Welcome to ${label}!`,
+    'Running first-time setup…',
+    ''
+  ];
+  console.log(lines.join('\n'));
+}
+
+module.exports = {
+  isFirstRun,
+  hasRunBefore,
+  markAsRun,
+  printWelcome
+};