@odavl/guardian 0.1.0-rc1 → 1.0.0

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/drift-detector.js

@@ -0,0 +1,100 @@
+/**
+ * Drift Detection Engine for Journey Results
+ * Deterministic comparison against stored baseline snapshot.
+ */
+
+function buildBaselineFromJourneyResult(result) {
+  const keySteps = (result.executedSteps || []).map(s => ({ id: s.id, success: !!s.success }));
+  const baseline = {
+    decision: result.finalDecision,
+    intent: (result.intentDetection && result.intentDetection.intent) || 'unknown',
+    goalReached: !!(result.goal && result.goal.goalReached),
+    keySteps,
+    timestamp: new Date().toISOString()
+  };
+  return baseline;
+}
+
+function compareAgainstBaseline(baseline, current) {
+  const reasons = [];
+  const currentSteps = {};
+  (current.executedSteps || []).forEach(s => { currentSteps[s.id] = !!s.success; });
+
+  // Decision drift
+  const before = baseline.decision;
+  const after = current.finalDecision;
+  if (before === 'SAFE' && (after === 'RISK' || after === 'DO_NOT_LAUNCH')) {
+    reasons.push(`Decision regressed: ${before} → ${after}`);
+  }
+
+  // Goal drift
+  const baselineGoal = !!baseline.goalReached;
+  const currentGoal = !!(current.goal && current.goal.goalReached);
+  if (baselineGoal && !currentGoal) {
+    reasons.push('Visitors can no longer reach goal');
+  }
+
+  // Intent drift
+  const baselineIntent = (baseline.intent || 'unknown').toLowerCase();
+  const currentIntent = ((current.intentDetection && current.intentDetection.intent) || 'unknown').toLowerCase();
+  if (baselineIntent !== 'unknown' && currentIntent !== 'unknown' && baselineIntent !== currentIntent) {
+    reasons.push(`Site intent changed from ${baselineIntent.toUpperCase()} to ${currentIntent.toUpperCase()}`);
+  }
+
+  // Critical step regression: any step that succeeded before now fails
+  for (const ks of baseline.keySteps || []) {
+    if (ks.success === true) {
+      const now = currentSteps[ks.id];
+      if (now === false || now === undefined) {
+        reasons.push(`Critical step failed: ${ks.id}`);
+      }
+    }
+  }
+
+  return {
+    hasDrift: reasons.length > 0,
+    reasons: reasons
+  };
+}
+
+function classifySeverity(driftInfo, currentResult) {
+  if (!driftInfo || !driftInfo.hasDrift) return 'NONE';
+  
+  const reasons = driftInfo.reasons || [];
+  
+  // CRITICAL conditions:
+  // 1. Decision drifted to DO_NOT_LAUNCH
+  if (currentResult.decision === 'DO_NOT_LAUNCH') {
+    // Exception: if run stability is very low (<50), downgrade to WARN
+    // unless site is unreachable
+    if (!reasons.some(r => r.includes('SITE_UNREACHABLE'))) {
+      const stabilityScore = currentResult.stability?.runStabilityScore || 100;
+      if (stabilityScore < 50) {
+        return 'WARN'; // Downgrade: unstable run, re-check recommended
+      }
+    }
+    return 'CRITICAL';
+  }
+  
+  // 2. Site unreachable - always CRITICAL (do not downgrade)
+  if (reasons.some(r => r.includes('SITE_UNREACHABLE'))) return 'CRITICAL';
+  
+  // 3. Goal drift (visitors can no longer reach goal)
+  if (reasons.some(r => r.includes('goal drift: true → false'))) {
+    // Check stability before deciding
+    const stabilityScore = currentResult.stability?.runStabilityScore || 100;
+    if (stabilityScore < 50) {
+      return 'WARN'; // Downgrade: unstable, suspicious drift
+    }
+    return 'CRITICAL';
+  }
+  
+  // Default: WARN for all other drift
+  return 'WARN';
+}
+
+module.exports = {
+  buildBaselineFromJourneyResult,
+  compareAgainstBaseline,
+  classifySeverity
+};