qa360 2.2.20 → 2.3.1

package/dist/core/crawler/intelligent-selector-generator.js

@@ -0,0 +1,612 @@
+/**
+ * QA360 Intelligent Selector Generator
+ *
+ * Generates optimal CSS selectors by adapting to the detected site profile.
+ * Follows Testing Library best practices with configurable strategies.
+ *
+ * Philosophy: "The more your tests resemble the way your software is used,
+ *              the more confidence they can give you." - Kent C. Dodds
+ */
+/**
+ * Selector strategies by site profile
+ *
+ * Each profile has a different priority order (tiers) for selector generation.
+ * Higher tier = higher priority = checked first.
+ */
+const SELECTOR_STRATEGIES = {
+    // ═══════════════════════════════════════════════════════════════════════════════
+    // PROFIL_MODERN: Site with data-testid (React Testing Library, Cypress)
+    // Examples: Modern React/Vue apps, SaaS, tech startups
+    // ═══════════════════════════════════════════════════════════════════════════════
+    PROFIL_MODERN: [
+        { tier: 1, name: 'testId', fn: 'getByTestId', weight: 100 },
+        { tier: 2, name: 'role+name', fn: 'getByRole', weight: 90 },
+        { tier: 3, name: 'label', fn: 'getByLabelText', weight: 85 },
+        { tier: 4, name: 'placeholder', fn: 'getByPlaceholder', weight: 70 },
+        { tier: 5, name: 'text', fn: 'getByText', weight: 65 },
+        { tier: 6, name: 'altText', fn: 'getByAltText', weight: 60 },
+        { tier: 7, name: 'title', fn: 'getByTitle', weight: 50 },
+        { tier: 8, name: 'id', fn: 'getById', weight: 40 },
+        { tier: 9, name: 'css', fn: 'getByCss', weight: 20 },
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════════
+    // PROFIL_ACCESSIBLE: Accessible site without testids
+    // Examples: Government sites, banks, enterprise sites
+    // Follows Testing Library (role first)
+    // ═══════════════════════════════════════════════════════════════════════════════
+    PROFIL_ACCESSIBLE: [
+        { tier: 1, name: 'role+name', fn: 'getByRole', weight: 100 },
+        { tier: 2, name: 'label', fn: 'getByLabelText', weight: 95 },
+        { tier: 3, name: 'placeholder', fn: 'getByPlaceholder', weight: 85 },
+        { tier: 4, name: 'text', fn: 'getByText', weight: 80 },
+        { tier: 5, name: 'altText', fn: 'getByAltText', weight: 75 },
+        { tier: 6, name: 'title', fn: 'getByTitle', weight: 60 },
+        { tier: 7, name: 'testId', fn: 'getByTestId', weight: 50 },
+        { tier: 8, name: 'id', fn: 'getById', weight: 40 },
+        { tier: 9, name: 'css', fn: 'getByCss', weight: 20 },
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════════
+    // PROFIL_LEGACY: Legacy site with few attributes
+    // Examples: ASP.NET, old PHP, classic WordPress
+    // ═══════════════════════════════════════════════════════════════════════════════
+    PROFIL_LEGACY: [
+        { tier: 1, name: 'id', fn: 'getById', weight: 100 },
+        { tier: 2, name: 'name', fn: 'getByName', weight: 95 },
+        { tier: 3, name: 'text', fn: 'getByText', weight: 85 },
+        { tier: 4, name: 'value', fn: 'getByValue', weight: 75 },
+        { tier: 5, name: 'placeholder', fn: 'getByPlaceholder', weight: 70 },
+        { tier: 6, name: 'role+name', fn: 'getByRole', weight: 60 },
+        { tier: 7, name: 'css', fn: 'getByCss', weight: 50 },
+        { tier: 8, name: 'position', fn: 'getByPosition', weight: 30 },
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════════
+    // PROFIL_MINIMAL: Minimalist or hybrid sites
+    // Examples: Landing pages, static sites, blogs
+    // ═══════════════════════════════════════════════════════════════════════════════
+    PROFIL_MINIMAL: [
+        { tier: 1, name: 'text', fn: 'getByText', weight: 100 },
+        { tier: 2, name: 'role+name', fn: 'getByRole', weight: 90 },
+        { tier: 3, name: 'placeholder', fn: 'getByPlaceholder', weight: 80 },
+        { tier: 4, name: 'altText', fn: 'getByAltText', weight: 75 },
+        { tier: 5, name: 'id', fn: 'getById', weight: 65 },
+        { tier: 6, name: 'testId', fn: 'getByTestId', weight: 60 },
+        { tier: 7, name: 'css', fn: 'getByCss', weight: 40 },
+    ],
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// GENERATED ID PATTERNS (to filter out)
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Patterns for auto-generated IDs (NOT stable)
+ */
+const GENERATED_ID_PATTERNS = [
+    // === Existing ===
+    /^\w+_\d+$/, // react_123
+    /^(ember|ember)\d+$/, // ember1234
+    /^yui_[^_]+_\d+$/, // yui_gen_123
+    /^\w+-\w+-\w+$/, // random-hash
+    /^[a-f0-9]{8,}$/, // hex hashes
+    // === NEW - JavaScript Frameworks ===
+    /^_ngcontent-\w+-\d+$/, // Angular
+    /^_nghost-\w+-\d+$/, // Angular
+    /^_ngcontent\d+$/, // Angular
+    /^cdk-\w+-\d+$/, // Angular CDK
+    /^mat-\w+-\d+$/, // Angular Material
+    /^data-v-[a-f0-9]+$/, // Vue scoped
+    /^svelte-[a-z0-9]+$/i, // Svelte
+    /^s-[a-z0-9]+$/i, // Svelte short
+    // === NEW - UI Libraries ===
+    /^mui-\d+$/, // Material UI
+    /^:r[a-z0-9]+:$/, // MUI v5
+    /^css-[a-z0-9]+-\w+$/, // Emotion/styled-components
+    /^radix-\w+-\d+$/, // Radix UI
+    /^chakra-\w+-\d+$/, // Chakra UI
+    // === NEW - Legacy/Enterprise ===
+    /^ctl\d+_/, // ASP.NET
+    /^__\w+$/, // ASP.NET ViewState
+    /^MainContent_/, // ASP.NET
+    /^j_id[_:]?\d+$/, // JSF (Java)
+    /^form[_:]\w+$/, // JSF
+    /^gwt-uid-\d+$/, // GWT
+    /^ext-(gen|comp|element)-?\d+$/, // ExtJS
+    // === NEW - CMS ===
+    /^w-node-[a-f0-9-]+$/, // Webflow
+    /^post-\d+$/, // WordPress
+    /^comment-\d+$/, // WordPress
+    /^menu-item-\d+$/, // WordPress
+    /^edit-\w+-\d+-\w+$/, // Drupal
+    /^node-\d+$/, // Drupal
+    // === NEW - Generic ===
+    /^[a-f0-9]{8}-[a-f0-9]{4}-/, // UUID prefix
+    /^\w+-[a-f0-9]{6,}$/, // name-hash
+    /^_?[a-zA-Z]+_[a-z0-9]{5,}$/, // CSS Modules
+    /^[a-f0-9]{32}$/, // MD5 hash
+    /^[a-f0-9]{40}$/, // SHA1 hash
+];
+/**
+ * Semantic ID patterns (TO KEEP)
+ * These IDs describe the PURPOSE, not the implementation
+ */
+const SEMANTIC_ID_PATTERNS = [
+    // Actions
+    /^(login|signin|signup|register|logout|signout|submit|cancel|save|delete|edit|create|add|remove)[-_]?(btn|button|form|modal|dialog)?$/i,
+    /^(search|filter|sort|pagination)[-_]?(input|box|field|bar)?$/i,
+    // Form fields
+    /^(email|password|username|firstname|lastname|fullname|phone|address|city|zip|postal|country|state|region)[-_]?(input|field)?$/i,
+    /^(subject|message|comment|content|body|description)[-_]?(input|field|textarea)?$/i,
+    // Page zones
+    /^(header|footer|sidebar|nav|navigation|main|content|menu|hero|banner|wrapper|container)[-_]?\w*$/i,
+    // E-commerce
+    /^(cart|checkout|payment|shipping|billing|product|price|quantity|order|invoice)[-_]?\w*$/i,
+    // Modals/Dialogs
+    /^(modal|dialog|popup|overlay|drawer|lightbox)[-_]?(close|open|content|title|body)?$/i,
+    // Common patterns
+    /^\w{3,}-?\w{3,}/, // At least 3 chars - 3 chars (meaningful)
+];
+/**
+ * Check if ID is auto-generated (NOT stable)
+ */
+export function isGeneratedId(id) {
+    if (!id || id.length < 2)
+        return true;
+    return GENERATED_ID_PATTERNS.some(pattern => pattern.test(id));
+}
+/**
+ * Check if ID is semantic (describes the PURPOSE)
+ */
+export function isSemanticId(id) {
+    if (!id || id.length < 2)
+        return false;
+    return SEMANTIC_ID_PATTERNS.some(p => p.test(id));
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// UTILITY CLASS PATTERNS (to filter out)
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Patterns for utility classes (Tailwind, Bootstrap, Foundation, generic frameworks)
+ *
+ * These patterns identify CSS classes that are:
+ * - Framework utilities (styling-only, not semantic)
+ * - Auto-generated by build tools
+ * - Too generic to be reliable selectors
+ */
+const UTILITY_CLASS_PATTERNS = [
+    // === GENERIC FRAMEWORK PREFIXES (Universal detection) ===
+    // Single letter prefixes + hyphen (common in many frameworks)
+    /^[a-z]-[a-z][a-z0-9-]*$/, // x-nav-link, b-button, t-link
+    /^x-[a-z][a-z0-9-]*$/, // Foundation-style: x-nav-link, x-card
+    // Common framework suffixes (modifiers, not semantic)
+    /[a-z]--(primary|secondary|success|danger|warning|info|light|dark|sm|md|lg|xl|logo|icon)$/,
+    // === TAILWIND CSS ===
+    /^-?(m|p)(x|y|t|r|b|l|s|e)?-(\d+|px|auto|\[.+\])$/,
+    /^(w|h|min-w|max-w|min-h|max-h)-/,
+    /^(flex|inline-flex|block|inline-block|grid|hidden|contents|table|table-row|table-cell)$/,
+    /^(items|justify|content|place|self)-(start|end|center|between|around|evenly|stretch|baseline)$/,
+    /^(gap|space)-(x|y)-?\d+$/,
+    /^(text|font|leading|tracking)-(xs|sm|base|lg|xl|\d+|left|center|right|bold|medium|normal|light)$/,
+    /^(bg|text|border|ring|shadow|outline)-(transparent|current|inherit|black|white|\w+-\d+)$/,
+    /^(border|rounded)(-none|-sm|-md|-lg|-xl|-2xl|-3xl|-full)?$/,
+    /^(opacity|z)-(\d+|auto)$/,
+    /^(overflow|whitespace|truncate|break)-/,
+    /^(cursor|pointer-events|user-select|resize)-/,
+    /^(transition|duration|ease|delay|animate)-/,
+    /^(hover|focus|active|disabled|visited|group-hover|peer-\w+|dark|md|lg|xl|sm|2xl|3xl):/,
+    /^\[.+\]$/, // Arbitrary values
+    /^!/, // Important modifier
+    // === BOOTSTRAP ===
+    /^(col|offset|order)-(xs|sm|md|lg|xl|xxl)?-?\d*$/,
+    /^(d|align|justify)-(none|flex|block|inline|center|start|end)$/,
+    /^(m|p)(t|b|s|e|x|y)?-\d+$/,
+    /^(text|bg|border|btn)-(primary|secondary|success|danger|warning|info|light|dark)$/,
+    // === FOUNDATION (Zurb) ===
+    /^x-[a-z]+(-[a-z]+)*$/, // x-nav-link, x-column, x-row
+    // === BULMA ===
+    /^is-(active|info|success|warning|danger|link|loading|white|black|light|dark)$/,
+    /^has-(text|icon|addons)(-\w+)?$/, // has-text, has-icon-*, etc.
+    // === MATERIAL UI ===
+    /^Mui[A-Z]\w*(-\w+)*$/,
+    /^css-[a-z0-9]+$/,
+    /^jss\d+$/,
+    // === ANT DESIGN ===
+    /^ant-[a-z]+(-[a-z]+)*$/,
+    // === CHAKRA UI ===
+    /^css-[a-z0-9-]+$/,
+    // === GENERIC UTILITY CLASSES (Too common to be reliable) ===
+    // Single-word very common classes
+    /^(btn|button|link|nav|card|header|footer|sidebar|content|body|main|wrapper|container)$/,
+    /^(row|col|column|section|article|aside|div|span|text|title|heading)$/,
+    /^(left|right|top|bottom|center|middle|icon|logo|image|img)$/,
+    /^(small|medium|large|big|tiny|mini|micro|xs|sm|md|lg|xl)$/,
+    // Very short classes (less than 4 chars) - likely utilities
+    /^[a-z]{1,3}$/,
+    // === GENERIC STATE ===
+    /^(show|hide|active|inactive|selected|disabled|enabled|loading)$/,
+    /^(visible|invisible|hidden|collapsed|expanded|open|closed)$/,
+    /^(first|last|odd|even|current)$/,
+    // === CSS MODULES (hashed) ===
+    /^_[a-zA-Z]+_[a-z0-9]{5,}$/,
+    /^[a-zA-Z]+_[a-z0-9]{8,}$/,
+];
+/**
+ * Check if class is a utility class (should be filtered out)
+ */
+export function isUtilityClass(cls) {
+    if (!cls)
+        return true;
+    return UTILITY_CLASS_PATTERNS.some(pattern => pattern.test(cls));
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// INTELLIGENT SELECTOR GENERATOR
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Intelligent Selector Generator
+ *
+ * Adapts selector generation strategy based on detected site profile.
+ */
+export class IntelligentSelectorGenerator {
+    siteProfile = null;
+    siteAnalysis = null;
+    strategy = null;
+    /**
+     * Initialize the generator with site analysis
+     */
+    initialize(analysis) {
+        this.siteAnalysis = analysis;
+        this.siteProfile = this.determineProfile(analysis);
+        this.strategy = SELECTOR_STRATEGIES[this.siteProfile];
+        this.logProfile();
+    }
+    /**
+     * Get the current site profile
+     */
+    getProfile() {
+        return this.siteProfile;
+    }
+    /**
+     * Get the current strategy
+     */
+    getStrategy() {
+        return this.strategy;
+    }
+    /**
+     * Determine site profile from analysis
+     */
+    determineProfile(analysis) {
+        const testIdRatio = analysis.totalElements > 0
+            ? analysis.hasTestIds / analysis.totalElements
+            : 0;
+        // PROFIL_MODERN: >30% data-testid
+        if (testIdRatio > 0.3) {
+            return 'PROFIL_MODERN';
+        }
+        const a11yRatio = analysis.totalElements > 0
+            ? analysis.hasAriaLabels / analysis.totalElements
+            : 0;
+        // PROFIL_ACCESSIBLE: Good ARIA but few testids
+        if (a11yRatio > 0.6 && testIdRatio < 0.1) {
+            return 'PROFIL_ACCESSIBLE';
+        }
+        // PROFIL_LEGACY: Poor accessibility and no testids
+        if (analysis.accessibilityScore < 30 && testIdRatio < 0.05) {
+            return 'PROFIL_LEGACY';
+        }
+        // PROFIL_MINIMAL: Other cases
+        return 'PROFIL_MINIMAL';
+    }
+    /**
+     * Log the detected profile to console
+     */
+    logProfile() {
+        if (!this.siteProfile || !this.siteAnalysis || !this.strategy)
+            return;
+        console.log('\n' + '═'.repeat(70));
+        console.log('🎯 QA360 SITE PROFILER - Stratégie Adaptative');
+        console.log('═'.repeat(70));
+        console.log(`   Profil détecté:     ${this.siteProfile}`);
+        console.log(`   Framework JS:       ${this.siteAnalysis.framework || 'non détecté'}`);
+        console.log(`   Framework CSS:      ${this.siteAnalysis.cssFramework || 'non détecté'}`);
+        console.log(`   Score Testabilité:  ${this.siteAnalysis.testabilityScore}%`);
+        console.log(`   Score Accessibilité: ${this.siteAnalysis.accessibilityScore}%`);
+        console.log(`   data-testid:         ${this.siteAnalysis.hasTestIds} éléments`);
+        console.log(`   ARIA labels:         ${this.siteAnalysis.hasAriaLabels} éléments`);
+        console.log('');
+        console.log(`   ➡️  TIER 1 (priorité): ${this.strategy[0].name} (${this.strategy[0].weight} points)`);
+        console.log('═'.repeat(70) + '\n');
+    }
+    /**
+     * Generate optimal selector for an element
+     */
+    generateSelector(element) {
+        // Use default strategy if not initialized
+        if (!this.strategy) {
+            this.strategy = SELECTOR_STRATEGIES.PROFIL_ACCESSIBLE;
+        }
+        // Try each tier in order
+        for (const tier of this.strategy) {
+            const selector = this.trySelector(element, tier.name);
+            if (selector) {
+                return {
+                    selector,
+                    tier: tier.tier,
+                    type: tier.name,
+                    weight: tier.weight,
+                };
+            }
+        }
+        // Fallback: tag only
+        return {
+            selector: element.tagName || '*',
+            tier: 99,
+            type: 'fallback',
+            weight: 0,
+        };
+    }
+    /**
+     * Try to generate a selector for a specific type
+     */
+    trySelector(element, type) {
+        const { tagName, id, className, attributes = {}, textContent, role, name, value } = element;
+        switch (type) {
+            case 'testId':
+                return this.getTestIdSelector(attributes);
+            case 'role+name':
+                return this.getRoleNameSelector(role, attributes, name);
+            case 'label':
+                return this.getLabelSelector(attributes);
+            case 'placeholder':
+                return this.getPlaceholderSelector(tagName, attributes);
+            case 'text':
+                return this.getTextSelector(tagName, role, textContent);
+            case 'altText':
+                return this.getAltTextSelector(tagName, attributes);
+            case 'title':
+                return this.getTitleSelector(attributes);
+            case 'id':
+                return this.getIdSelector(id);
+            case 'name':
+                return this.getNameSelector(tagName, name);
+            case 'value':
+                return this.getValueSelector(tagName, attributes, value);
+            case 'css':
+                return this.getCssSelector(tagName, className);
+            case 'position':
+                return null; // Last resort, avoid
+            default:
+                return null;
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════════
+    // SELECTOR GENERATION METHODS
+    // ═══════════════════════════════════════════════════════════════════════════════
+    /**
+     * TIER 1/7 - Get test ID selector
+     */
+    getTestIdSelector(attributes) {
+        const testIdAttrs = [
+            'data-testid', 'data-cy', 'data-test', 'data-test-id',
+            'data-qa', 'data-automation', 'data-e2e', 'data-selenium'
+        ];
+        for (const attr of testIdAttrs) {
+            if (attributes[attr]) {
+                return `[${attr}="${escapeCss(attributes[attr])}"]`;
+            }
+        }
+        return null;
+    }
+    /**
+     * TIER 2/6 - Get role + name selector (ARIA)
+     */
+    getRoleNameSelector(role, attributes, name) {
+        // role + aria-label (BEST semantic selector)
+        if (role && attributes['aria-label']) {
+            return `[role="${role}"][aria-label="${escapeCss(attributes['aria-label'])}"]`;
+        }
+        // role + name attribute (for forms)
+        if (role && name) {
+            return `[role="${role}"][name="${escapeCss(name)}"]`;
+        }
+        return null;
+    }
+    /**
+     * TIER 3 - Get label selector
+     */
+    getLabelSelector(attributes) {
+        if (attributes['aria-label']) {
+            return `[aria-label="${escapeCss(attributes['aria-label'])}"]`;
+        }
+        if (attributes['aria-labelledby']) {
+            return `[aria-labelledby="${escapeCss(attributes['aria-labelledby'])}"]`;
+        }
+        return null;
+    }
+    /**
+     * TIER 4 - Get placeholder selector
+     */
+    getPlaceholderSelector(tagName, attributes) {
+        if (!attributes.placeholder || !isFormElement(tagName)) {
+            return null;
+        }
+        const type = attributes.type || 'text';
+        return `${tagName}[type="${type}"][placeholder="${escapeCss(attributes.placeholder)}"]`;
+    }
+    /**
+     * TIER 5/1 - Get text selector
+     */
+    getTextSelector(tagName, role, textContent) {
+        if (!textContent?.trim() || !isStableTextElement(tagName)) {
+            return null;
+        }
+        const text = textContent.trim();
+        // Only if text is short and meaningful
+        if (text.length < 2 || text.length > 50) {
+            return null;
+        }
+        // Prefer role + text pattern for interactive elements
+        if (role) {
+            return `[role="${role}"]:has-text("${escapeCss(text)}")`;
+        }
+        return `${tagName}:has-text("${escapeCss(text)}")`;
+    }
+    /**
+     * TIER 6/4 - Get alt text selector (images)
+     */
+    getAltTextSelector(tagName, attributes) {
+        if (tagName === 'img' && attributes.alt) {
+            return `img[alt="${escapeCss(attributes.alt)}"]`;
+        }
+        return null;
+    }
+    /**
+     * TIER 7 - Get title selector
+     */
+    getTitleSelector(attributes) {
+        if (attributes.title) {
+            return `[title="${escapeCss(attributes.title)}"]`;
+        }
+        return null;
+    }
+    /**
+     * TIER 8/1 - Get ID selector (semantic only)
+     */
+    getIdSelector(id) {
+        if (id && !isGeneratedId(id)) {
+            return `#${escapeCss(id)}`;
+        }
+        return null;
+    }
+    /**
+     * TIER 2 - Get name selector (for forms)
+     */
+    getNameSelector(tagName, name) {
+        if (name && isFormElement(tagName)) {
+            return `${tagName}[name="${escapeCss(name)}"]`;
+        }
+        return null;
+    }
+    /**
+     * TIER 4 - Get value selector (submit buttons, etc.)
+     */
+    getValueSelector(tagName, attributes, value) {
+        if (attributes.type === 'submit' && isFormElement(tagName)) {
+            return `${tagName}[type="submit"]`;
+        }
+        return null;
+    }
+    /**
+     * TIER 9/7 - Get CSS selector (MAX 2 semantic classes)
+     */
+    getCssSelector(tagName, className) {
+        if (!className)
+            return null;
+        const semanticClasses = extractSemanticClasses(className);
+        if (semanticClasses.length > 0) {
+            const selected = semanticClasses.slice(0, 2); // MAX 2 classes
+            const classesStr = selected.map(c => `.${escapeCss(c)}`).join('');
+            return tagName ? `${tagName}${classesStr}` : classesStr;
+        }
+        return null;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Escape special CSS characters
+ */
+function escapeCss(str) {
+    if (!str)
+        return '';
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n');
+}
+/**
+ * Check if element has stable/significant text content
+ */
+function isStableTextElement(tagName) {
+    if (!tagName)
+        return false;
+    const stable = ['button', 'a', 'label', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'th', 'legend', 'summary'];
+    return stable.includes(tagName.toLowerCase());
+}
+/**
+ * Check if element is a form element
+ */
+function isFormElement(tagName) {
+    if (!tagName)
+        return false;
+    const formElements = ['input', 'select', 'textarea', 'button'];
+    return formElements.includes(tagName.toLowerCase());
+}
+/**
+ * Extract semantic classes (filter out utility classes)
+ */
+function extractSemanticClasses(className) {
+    const classes = className.split(/\s+/).filter(Boolean);
+    return classes.filter(cls => {
+        // Reject utility classes
+        if (isUtilityClass(cls))
+            return false;
+        // Keep names that are:
+        // - 3-30 characters long
+        // - Start with letter, contain only alphanumeric, hyphens, underscores
+        return cls.length >= 3 && cls.length <= 30 && /^[a-z][a-z0-9-_]*$/i.test(cls);
+    });
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// GLOBAL INSTANCE AND CONVENIENCE FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Global generator instance
+ */
+let globalGenerator = null;
+/**
+ * Initialize the global generator with site analysis
+ */
+export function initializeSelectorGenerator(analysis) {
+    globalGenerator = new IntelligentSelectorGenerator();
+    globalGenerator.initialize(analysis);
+}
+/**
+ * Generate optimal selector for an element (uses global instance)
+ */
+export function generateSelector(element) {
+    if (!globalGenerator) {
+        // Create default instance if not initialized
+        globalGenerator = new IntelligentSelectorGenerator();
+        // Use PROFIL_ACCESSIBLE as default strategy
+        globalGenerator.strategy = SELECTOR_STRATEGIES.PROFIL_ACCESSIBLE;
+    }
+    const result = globalGenerator.generateSelector(element);
+    return result.selector;
+}
+/**
+ * Generate selector with metadata (tier, type, weight)
+ */
+export function generateSelectorWithMetadata(element) {
+    if (!globalGenerator) {
+        globalGenerator = new IntelligentSelectorGenerator();
+        globalGenerator.strategy = SELECTOR_STRATEGIES.PROFIL_ACCESSIBLE;
+    }
+    return globalGenerator.generateSelector(element);
+}
+/**
+ * Get the current site profile
+ */
+export function getSiteProfile() {
+    return globalGenerator?.getProfile() || null;
+}
+/**
+ * Get the current strategy
+ */
+export function getSelectorStrategy() {
+    return globalGenerator?.getStrategy() || null;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORT UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+// Note: isGeneratedId, isSemanticId, isUtilityClass are already exported at definition
+// Export strategies for testing/customization
+export { SELECTOR_STRATEGIES };