@odavl/guardian 0.1.0-rc1 → 0.2.0

package/src/guardian/semantic-contact-detection.js

@@ -0,0 +1,255 @@
+/**
+ * Semantic Contact Detection
+ * 
+ * Deterministic, multilingual detection of contact links and elements.
+ * Returns ranked candidates with source, confidence, and matched tokens.
+ */
+
+const { getTokensForTarget, normalizeText, getMatchedToken } = require('./semantic-targets');
+
+/**
+ * Confidence levels
+ */
+const CONFIDENCE = {
+  HIGH: 'high',
+  MEDIUM: 'medium',
+  LOW: 'low'
+};
+
+/**
+ * Detection sources
+ */
+const DETECTION_SOURCE = {
+  DATA_GUARDIAN: 'data-guardian',
+  ARIA: 'aria',
+  HREF: 'href',
+  TEXT: 'text',
+  NAV_FOOTER: 'nav/footer',
+  HEURISTIC: 'heuristic'
+};
+
+/**
+ * Detect contact candidates on page
+ * 
+ * @param {Page} page - Playwright page object
+ * @param {string} baseUrl - Base URL for relative link resolution
+ * @returns {Promise<Array>} Array of contact candidates, ranked by confidence
+ */
+async function detectContactCandidates(page, baseUrl = '') {
+  const candidates = [];
+
+  try {
+    const pageData = await page.evaluate(async () => {
+      const results = [];
+
+      // Find all clickable/linkable elements
+      const elements = document.querySelectorAll('a, button, [role="link"], [role="button"], [data-guardian], .nav a, footer a');
+
+      for (const el of elements) {
+        const data = {
+          tagName: el.tagName.toLowerCase(),
+          text: el.textContent?.trim() || '',
+          href: el.href || el.getAttribute('href') || '',
+          dataGuardian: el.getAttribute('data-guardian') || '',
+          ariaLabel: el.getAttribute('aria-label') || '',
+          title: el.getAttribute('title') || '',
+          className: el.className,
+          isInNav: !!el.closest('nav, [role="navigation"]'),
+          isInFooter: !!el.closest('footer, [role="contentinfo"]')
+        };
+
+        results.push(data);
+      }
+
+      return results;
+    });
+
+    // Process each element
+    for (const element of pageData) {
+      const contactCandidates = evaluateElement(element, baseUrl);
+      candidates.push(...contactCandidates);
+    }
+
+    // Sort by confidence (high > medium > low) and then by detection order
+    candidates.sort((a, b) => {
+      const confidenceOrder = { high: 0, medium: 1, low: 2 };
+      return confidenceOrder[a.confidence] - confidenceOrder[b.confidence];
+    });
+
+    // Remove duplicates (same href or same text)
+    const seen = new Set();
+    const deduplicated = [];
+
+    for (const candidate of candidates) {
+      const key = `${candidate.matchedText}:${candidate.href}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        deduplicated.push(candidate);
+      }
+    }
+
+    return deduplicated;
+  } catch (error) {
+    console.warn(`Failed to detect contact candidates: ${error.message}`);
+    return candidates;
+  }
+}
+
+/**
+ * Evaluate a single element for contact relevance
+ */
+function evaluateElement(element, baseUrl = '') {
+  const candidates = [];
+  const contactTokens = getTokensForTarget('contact');
+
+  // Rule A: data-guardian attribute (highest priority)
+  if (element.dataGuardian) {
+    const normalized = normalizeText(element.dataGuardian);
+    if (normalized.includes('contact')) {
+      candidates.push({
+        selector: buildSelector(element),
+        matchedText: element.text || element.dataGuardian,
+        matchedToken: 'contact',
+        source: DETECTION_SOURCE.DATA_GUARDIAN,
+        confidence: CONFIDENCE.HIGH,
+        href: element.href,
+        ariaLabel: element.ariaLabel
+      });
+      return candidates;
+    }
+  }
+
+  // Rule B: href-based detection
+  if (element.href) {
+    const normalizedHref = normalizeText(element.href);
+    const matchedToken = getMatchedToken(normalizedHref, contactTokens);
+
+    if (matchedToken) {
+      candidates.push({
+        selector: buildSelector(element),
+        matchedText: element.text || element.href,
+        matchedToken: matchedToken,
+        source: DETECTION_SOURCE.HREF,
+        confidence: CONFIDENCE.HIGH,
+        href: element.href,
+        ariaLabel: element.ariaLabel
+      });
+    }
+  }
+
+  // Rule C: visible text-based detection
+  if (element.text) {
+    const normalizedText = normalizeText(element.text);
+    const matchedToken = getMatchedToken(normalizedText, contactTokens);
+
+    if (matchedToken) {
+      // Higher confidence if in nav or footer
+      let confidence = CONFIDENCE.MEDIUM;
+      let source = DETECTION_SOURCE.TEXT;
+
+      if (element.isInNav || element.isInFooter) {
+        confidence = CONFIDENCE.HIGH;
+        source = element.isInNav ? DETECTION_SOURCE.NAV_FOOTER : DETECTION_SOURCE.NAV_FOOTER;
+      }
+
+      candidates.push({
+        selector: buildSelector(element),
+        matchedText: element.text,
+        matchedToken: matchedToken,
+        source: source,
+        confidence: confidence,
+        href: element.href,
+        ariaLabel: element.ariaLabel
+      });
+    }
+  }
+
+  // Rule D: aria-label or title attribute
+  if (element.ariaLabel || element.title) {
+    const textToCheck = element.ariaLabel || element.title;
+    const normalizedText = normalizeText(textToCheck);
+    const matchedToken = getMatchedToken(normalizedText, contactTokens);
+
+    if (matchedToken) {
+      candidates.push({
+        selector: buildSelector(element),
+        matchedText: textToCheck,
+        matchedToken: matchedToken,
+        source: DETECTION_SOURCE.ARIA,
+        confidence: CONFIDENCE.MEDIUM,
+        href: element.href,
+        ariaLabel: element.ariaLabel
+      });
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * Build a CSS selector for an element
+ */
+function buildSelector(element) {
+  // Prefer data-guardian if available
+  if (element.dataGuardian) {
+    return `[data-guardian="${element.dataGuardian}"]`;
+  }
+
+  // For links/buttons, use href or text
+  if (element.tagName === 'a' && element.href) {
+    // Use href in selector
+    return `a[href*="${normalizeHrefForSelector(element.href)}"]`;
+  }
+
+  if (element.ariaLabel) {
+    return `${element.tagName}[aria-label*="${element.ariaLabel}"]`;
+  }
+
+  // Fallback
+  return `${element.tagName}`;
+}
+
+/**
+ * Normalize href for use in CSS selector
+ */
+function normalizeHrefForSelector(href) {
+  // Extract path portion
+  try {
+    const url = new URL(href, 'http://localhost');
+    return url.pathname.split('/').filter(p => p)[0] || '';
+  } catch {
+    // If URL parsing fails, extract first path component
+    return href.split('/')[1] || '';
+  }
+}
+
+/**
+ * Format detection result for human-readable output
+ */
+function formatDetectionResult(candidate, language = 'unknown') {
+  const languageStr = language !== 'unknown' ? `lang=${language}` : 'lang=unknown';
+  const parts = [
+    `Contact detected`,
+    `(${languageStr}`,
+    `source=${candidate.source}`,
+    `token=${candidate.matchedToken}`,
+    `confidence=${candidate.confidence})`
+  ];
+
+  return parts.join(', ');
+}
+
+/**
+ * Get hint message if contact not found
+ */
+function getNoContactFoundHint() {
+  return 'No contact found. Consider adding a stable marker like data-guardian="contact" or ensure contact link text/href is recognizable.';
+}
+
+module.exports = {
+  detectContactCandidates,
+  formatDetectionResult,
+  getNoContactFoundHint,
+  CONFIDENCE,
+  DETECTION_SOURCE
+};

package/src/guardian/semantic-contact-finder.js

@@ -0,0 +1,200 @@
+/**
+ * Semantic Contact Finder Integration
+ * 
+ * Integrates semantic contact detection into the scanning flow.
+ * Works with Playwright to find contact links/forms in real pages.
+ * 
+ * Now includes Wave 1.2 detection layers with data-guardian attribute support.
+ */
+
+const { detectLanguage, getPrimaryLanguage, getLanguageName } = require('./language-detection');
+const { detectContactCandidates, formatDetectionResult, getNoContactFoundHint } = require('./semantic-contact-detection');
+const { getTokensForTarget, normalizeText } = require('./semantic-targets');
+const { detectByLayers, LAYER, CONFIDENCE } = require('./detection-layers');
+
+/**
+ * Find contact elements on a page using semantic detection
+ * 
+ * @param {Page} page - Playwright page object
+ * @param {string} baseUrl - Base URL for relative links
+ * @returns {Promise<Object>} Detection result with language, candidates, and recommendations
+ */
+async function findContactOnPage(page, baseUrl = '') {
+  const result = {
+    language: 'unknown',
+    languageName: 'Unknown',
+    candidates: [],
+    found: false,
+    hint: ''
+  };
+
+  try {
+    // Detect language
+    result.language = await detectLanguage(page);
+    result.languageName = getLanguageName(result.language);
+
+    // Find contact candidates
+    const candidates = await detectContactCandidates(page, baseUrl);
+    result.candidates = candidates;
+
+    if (candidates.length > 0) {
+      result.found = true;
+      result.primaryCandidate = candidates[0]; // Highest confidence
+    } else {
+      result.hint = getNoContactFoundHint();
+    }
+
+    return result;
+  } catch (error) {
+    console.warn(`Contact detection failed: ${error.message}`);
+    result.hint = `Contact detection failed: ${error.message}. Fallback to default selectors.`;
+    return result;
+  }
+}
+
+/**
+ * Generate Playwright selectors from semantic candidates
+ * Returns a fallback selector chain compatible with attempt registry
+ */
+function generateSelectorsFromCandidates(candidates) {
+  if (!candidates || candidates.length === 0) {
+    return null;
+  }
+
+  // Take top 3 candidates, prefer high confidence
+  const topCandidates = candidates.slice(0, 3);
+
+  // Build selector chain
+  const selectors = topCandidates
+    .map(c => c.selector)
+    .filter(Boolean)
+    .join(', ');
+
+  return selectors || null;
+}
+
+/**
+ * Find contact elements using Wave 1.2 detection layers
+ * Respects priority: data-guardian > href > text > structure
+ * 
+ * @param {Page} page - Playwright page object
+ * @param {string} target - Detection target (contact, form, submit, about)
+ * @param {string} baseUrl - Base URL for relative links
+ * @returns {Promise<Object>} Detection result with layer, confidence, reason
+ */
+async function findElementByLayers(page, target, baseUrl = '') {
+  const result = {
+    language: 'unknown',
+    languageName: 'Unknown',
+    target: target,
+    found: false,
+    layer: null,
+    confidence: null,
+    candidates: [],
+    primaryCandidate: null,
+    reason: '',
+    hint: ''
+  };
+
+  try {
+    // Detect language
+    result.language = await detectLanguage(page);
+    result.languageName = getLanguageName(result.language);
+
+    // Use Wave 1.2 detection layers
+    const layerResult = await detectByLayers(page, target, baseUrl);
+
+    result.found = layerResult.found;
+    result.layer = layerResult.layer;
+    result.confidence = layerResult.confidence;
+    result.candidates = layerResult.candidates;
+    result.primaryCandidate = layerResult.primaryCandidate;
+    result.evidence = layerResult.evidence;
+    result.reason = layerResult.reason;
+
+    if (!result.found) {
+      result.hint = `No ${target} detected. Consider adding data-guardian="${target}" attribute for guaranteed stability.`;
+    }
+
+    return result;
+  } catch (error) {
+    console.warn(`Detection by layers failed: ${error.message}`);
+    result.reason = `Detection error: ${error.message}`;
+    result.hint = 'Fallback to manual configuration or heuristic detection.';
+    return result;
+  }
+}
+
+/**
+ * Generate Playwright selectors from semantic candidates
+ * Returns a fallback selector chain compatible with attempt registry
+ */
+function generateSelectorsFromCandidates(candidates) {
+  if (!candidates || candidates.length === 0) {
+    return null;
+  }
+
+  // Take top 3 candidates, prefer high confidence
+  const topCandidates = candidates.slice(0, 3);
+
+  // Build selector chain
+  const selectors = topCandidates
+    .map(c => c.selector)
+    .filter(Boolean)
+    .join(', ');
+
+  return selectors || null;
+}
+
+/**
+ * Format detection output for CLI reporting (Wave 1.2 enhanced)
+ * Shows which layer was used and how to improve stability
+ */
+function formatDetectionForReport(detectionResult) {
+  const lines = [];
+
+  lines.push(`🌍 Language Detection: ${detectionResult.languageName}`);
+  lines.push(`   (lang=${detectionResult.language})`);
+
+  if (detectionResult.found && detectionResult.candidates.length > 0) {
+    lines.push('');
+    
+    // Show detection layer (Wave 1.2)
+    if (detectionResult.layer) {
+      lines.push(`📍 Detection Layer: ${detectionResult.layer} (confidence: ${detectionResult.confidence})`);
+      lines.push(`   ${detectionResult.reason}`);
+      lines.push('');
+    }
+
+    lines.push(`✅ ${detectionResult.target} Detection Results (${detectionResult.candidates.length} candidate${detectionResult.candidates.length > 1 ? 's' : ''})`);
+
+    detectionResult.candidates.forEach((candidate, idx) => {
+      const formatted = formatDetectionResult(candidate, detectionResult.language);
+      lines.push(`   ${idx + 1}. ${formatted}`);
+      if (candidate.matchedText) {
+        lines.push(`      Text: "${candidate.matchedText}"`);
+      }
+      if (candidate.href) {
+        lines.push(`      Link: ${candidate.href}`);
+      }
+    });
+  } else {
+    lines.push('');
+    lines.push(`❌ No ${detectionResult.target || 'target'} found`);
+    if (detectionResult.reason) {
+      lines.push(`   Reason: ${detectionResult.reason}`);
+    }
+    if (detectionResult.hint) {
+      lines.push(`   💡 ${detectionResult.hint}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  findContactOnPage,
+  findElementByLayers,
+  generateSelectorsFromCandidates,
+  formatDetectionForReport
+};

package/src/guardian/semantic-targets.js

@@ -0,0 +1,234 @@
+/**
+ * Semantic Targets & Multilingual Dictionary
+ * 
+ * Provides deterministic, language-independent detection of semantic targets
+ * (contact, about, etc.) using normalized tokens from multiple languages.
+ */
+
+/**
+ * Multilingual dictionary for semantic targets
+ * Keys: target names, Values: arrays of normalized token variants
+ */
+const SEMANTIC_DICTIONARY = {
+  contact: [
+    // English
+    'contact', 'contactus', 'contact-us', 'contact us', 'get in touch', 'getintouch',
+    'reach out', 'reachout', 'contact form', 'contactform', 'contact page', 'contactpage',
+    'inquiry', 'inquiries', 'message us', 'messageus', 'write to us', 'writetus',
+    // German
+    'kontakt', 'kontaktieren', 'kontaktaufnahme', 'kontaktformular', 'kontakten',
+    'kontakts', 'kontakt formular', 'kontakt-formular', 'anfrage', 'anfragen',
+    // Spanish
+    'contacto', 'contactanos', 'contacta', 'formulario de contacto',
+    'pongase en contacto', 'ponte en contacto', 'escribenos', 'escriba',
+    // French
+    'contact', 'contactez', 'contactez-nous', 'formulaire de contact',
+    'nous contacter', 'nous ecrire',
+    // Portuguese
+    'contato', 'contacto', 'formulario de contato', 'entre em contato',
+    'fale conosco', 'escreva para nos',
+    // Italian
+    'contatti', 'contatto', 'contattaci', 'modulo di contatto',
+    'modulo contatti', 'mettersi in contatto',
+    // Dutch
+    'contact', 'contacteer', 'contact opnemen', 'contactformulier',
+    // Swedish
+    'kontakt', 'kontakta', 'kontaktformular',
+    // Arabic
+    'تواصل', 'اتصل', 'استفسار', 'استفسارات', 'نموذج الاتصال', 'نموذج تواصل',
+    // Chinese
+    '联系', '联系我们', '联系表单', '留言', '反馈'
+  ],
+  about: [
+    // English
+    'about', 'about us', 'aboutus', 'our story', 'about-us',
+    'company', 'team', 'who we are', 'whoweare', 'more about us',
+    // German
+    'uber', 'über', 'ueber', 'uber uns', 'über uns', 'ueber uns',
+    'uber unsere', 'über unsere', 'ueber unsere', 'team', 'unternehmen',
+    // Spanish
+    'acerca', 'acerca de', 'acerca de nosotros', 'sobre nosotros',
+    'quienes somos', 'quiénes somos', 'nuestra empresa',
+    // French
+    'a propos', 'à propos', 'a propos de nous', 'à propos de nous',
+    'qui sommes nous', 'qui nous sommes', 'notre histoire',
+    // Portuguese
+    'sobre', 'sobre nos', 'sobre nós', 'quem somos',
+    // Italian
+    'chi siamo', 'chi siamo noi', 'la nostra storia',
+    // Dutch
+    'over', 'over ons', 'wie zijn we',
+    // Swedish
+    'om', 'om oss', 'var historia',
+    // Arabic
+    'عن', 'عننا', 'عن الشركة', 'فريقنا', 'قصتنا'
+  ],
+  form: [
+    // English
+    'form', 'form submission', 'contact form', 'feedback form', 'inquiry form',
+    'form page', 'form element', 'form section', 'form area',
+    // German
+    'formular', 'form', 'kontaktformular', 'feedback formular',
+    // Spanish
+    'formulario', 'formulario de contacto', 'formulario de envio',
+    // French
+    'formulaire', 'formulaire de contact', 'formulaire d envoi',
+    // Portuguese
+    'formulario', 'formulario de contato', 'formulario de envio',
+    // Italian
+    'modulo', 'modulo di contatto', 'modulo di invio',
+    // Dutch
+    'formulier', 'contactformulier', 'formulier voor contact',
+    // Swedish
+    'formular', 'kontaktformular', 'feedback formular'
+  ],
+  submit: [
+    // English
+    'submit', 'send', 'send message', 'send form', 'submit form',
+    'submit button', 'send button', 'post', 'publish', 'share',
+    // German
+    'senden', 'absenden', 'abschicken', 'submit', 'ubermitteln',
+    // Spanish
+    'enviar', 'enviar formulario', 'enviar mensaje', 'publicar',
+    // French
+    'envoyer', 'soumettre', 'publier', 'partager',
+    // Portuguese
+    'enviar', 'enviar formulario', 'enviar mensagem', 'publicar',
+    // Italian
+    'inviare', 'inviare modulo', 'inviare messaggio', 'pubblicare',
+    // Dutch
+    'verzenden', 'verstuur', 'verstuur formulier', 'publiceren',
+    // Swedish
+    'skicka', 'skicka formular', 'publicera'
+  ]
+};
+
+/**
+ * Normalize text for comparison
+ * - Lowercase
+ * - Trim whitespace
+ * - Remove diacritics (é → e, ü → u, etc.)
+ * - Remove punctuation
+ * - Collapse multiple spaces
+ */
+function normalizeText(text) {
+  if (typeof text !== 'string') {
+    return '';
+  }
+
+  // Lowercase
+  let normalized = text.toLowerCase();
+
+  // Remove diacritics using Unicode normalization
+  // NFD: decompose accented characters, then filter combining marks
+  normalized = normalized
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '');
+
+  // Remove punctuation and special characters, keep spaces
+  normalized = normalized.replace(/[^\w\s]/g, ' ');
+
+  // Collapse multiple spaces
+  normalized = normalized.replace(/\s+/g, ' ').trim();
+
+  return normalized;
+}
+
+/**
+ * Check if normalized text includes any token from the list
+ * Matches whole words/tokens at word boundaries where appropriate
+ */
+function includesAnyToken(normalizedText, tokenList) {
+  if (!normalizedText || !Array.isArray(tokenList)) {
+    return false;
+  }
+
+  // Check each token
+  for (const token of tokenList) {
+    // Normalize the token
+    const normalizedToken = normalizeText(token);
+
+    if (!normalizedToken) {
+      continue;
+    }
+
+    // For very short tokens (<=4 chars), require word boundary
+    // For longer tokens (>4 chars), allow substring matching
+    if (normalizedToken.length <= 4) {
+      // Word boundary match
+      const wordBoundaryRegex = new RegExp(`\\b${normalizedToken}\\b`);
+      if (wordBoundaryRegex.test(normalizedText)) {
+        return true;
+      }
+    } else {
+      // Substring match
+      if (normalizedText.includes(normalizedToken)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get the best matching token from a list for a given text
+ * Returns the token that was matched, or null
+ */
+function getMatchedToken(normalizedText, tokenList) {
+  if (!normalizedText || !Array.isArray(tokenList)) {
+    return null;
+  }
+
+  for (const token of tokenList) {
+    const normalizedToken = normalizeText(token);
+
+    if (!normalizedToken) {
+      continue;
+    }
+
+    if (normalizedToken.length <= 4) {
+      const wordBoundaryRegex = new RegExp(`\\b${normalizedToken}\\b`);
+      if (wordBoundaryRegex.test(normalizedText)) {
+        return token;
+      }
+    } else {
+      if (normalizedText.includes(normalizedToken)) {
+        return token;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get all target names available in dictionary
+ */
+function getAvailableTargets() {
+  return Object.keys(SEMANTIC_DICTIONARY);
+}
+
+/**
+ * Check if a semantic target exists in dictionary
+ */
+function isValidTarget(targetName) {
+  return targetName in SEMANTIC_DICTIONARY;
+}
+
+/**
+ * Get token list for a specific target
+ */
+function getTokensForTarget(targetName) {
+  return SEMANTIC_DICTIONARY[targetName] || [];
+}
+
+module.exports = {
+  SEMANTIC_DICTIONARY,
+  normalizeText,
+  includesAnyToken,
+  getMatchedToken,
+  getAvailableTargets,
+  isValidTarget,
+  getTokensForTarget
+};