@sun-asterisk/sungen 1.0.0

package/src/core/selector-mapper/priority-mapper.ts

@@ -0,0 +1,607 @@
+/**
+ * Priority-based Selector Mapper - v3.1
+ *
+ * Maps Gherkin element references to actual selectors using priority waterfall:
+ *
+ * Priority 1: Direct ID Match (data-testid) - INSTANT, FREE, DETERMINISTIC
+ * Priority 2: Accessibility Match (role + aria-label) - SEMANTIC, STABLE, FREE
+ * Priority 3: Heuristic/AI Fallback - LAST RESORT
+ *
+ * Philosophy: AI is a safety net, not the primary solution
+ */
+
+import { StrictUIElement, StrictScanResult } from '../ui-scanner/strict-scanner';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface SelectorMappingConfig {
+  strategy: 'priority-waterfall';
+  priorities: ('direct-id' | 'accessibility' | 'heuristic-ai')[];
+  aiProvider?: string;
+  model?: string;
+  confidenceThreshold?: number; // Minimum confidence to accept (0.0 - 1.0)
+}
+
+export interface MappingRequest {
+  elementId: string;          // From Gherkin: [login.email-input]
+  screenName: string;          // e.g., "login"
+  uiModel: StrictScanResult;   // Scanned UI elements
+}
+
+export interface MappingResult {
+  elementId: string;           // Original Gherkin reference
+  selector: string;            // Final selector (Playwright-compatible)
+  fallbackSelector?: string;   // Fallback if primary fails
+
+  // Discovery metadata
+  discoveryMethod: 'direct-id' | 'accessibility' | 'heuristic' | 'ai';
+  confidence: number;          // 0.0 - 1.0
+  matchedElement?: StrictUIElement;
+
+  // Stats
+  attemptedPriorities: string[];
+  mappingTime: number;         // ms
+
+  // Warnings
+  warnings?: string[];
+}
+
+export interface MappingStats {
+  totalMappings: number;
+  successfulMappings: number;
+  failedMappings: number;
+
+  // By priority
+  directIdMatches: number;
+  accessibilityMatches: number;
+  heuristicMatches: number;
+  aiMatches: number;
+
+  // Performance
+  averageMappingTime: number;
+  totalMappingTime: number;
+
+  // Cost (AI calls)
+  aiCallsCount: number;
+  estimatedCost: number; // USD
+}
+
+// ============================================================================
+// PRIORITY LEVEL 1: DIRECT ID MATCHER
+// ============================================================================
+
+class DirectIDMatcher {
+  /**
+   * Priority 1: Exact or fuzzy data-testid matching
+   *
+   * Confidence levels:
+   * - 1.0: Exact match
+   * - 0.95: Partial match (testid contains element name)
+   * - 0.0: No match
+   */
+  match(elementName: string, uiElements: StrictUIElement[]): MappingResult | null {
+    const startTime = Date.now();
+
+    // Normalize element name
+    const normalized = this.normalize(elementName);
+
+    // Try exact match first
+    for (const element of uiElements) {
+      if (element.discoveryMethod !== 'direct-id') continue;
+
+      const testId = this.extractTestId(element.primaryLocator);
+      if (!testId) continue;
+
+      const testIdNorm = this.normalize(testId);
+
+      // Exact match
+      if (testIdNorm === normalized) {
+        return {
+          elementId: elementName,
+          selector: element.primaryLocator,
+          fallbackSelector: element.fallbackStrategy,
+          discoveryMethod: 'direct-id',
+          confidence: 1.0,
+          matchedElement: element,
+          attemptedPriorities: ['direct-id'],
+          mappingTime: Date.now() - startTime,
+        };
+      }
+    }
+
+    // Try partial match (fuzzy)
+    for (const element of uiElements) {
+      if (element.discoveryMethod !== 'direct-id') continue;
+
+      const testId = this.extractTestId(element.primaryLocator);
+      if (!testId) continue;
+
+      const testIdNorm = this.normalize(testId);
+
+      // Partial match (contains)
+      if (testIdNorm.includes(normalized) || normalized.includes(testIdNorm)) {
+        return {
+          elementId: elementName,
+          selector: element.primaryLocator,
+          fallbackSelector: element.fallbackStrategy,
+          discoveryMethod: 'direct-id',
+          confidence: 0.95,
+          matchedElement: element,
+          attemptedPriorities: ['direct-id'],
+          mappingTime: Date.now() - startTime,
+          warnings: [`Partial match: ${elementName} ≈ ${testId}`],
+        };
+      }
+    }
+
+    return null;
+  }
+
+  private normalize(str: string): string {
+    let normalized = str.toLowerCase().replace(/[\[\]]/g, '');  // Remove brackets
+
+    // Remove screen prefix: "auth-login.email-input" → "email-input" OR "auth-login-email-input" → "email-input"
+    normalized = normalized.replace(/^[^.]*\./, '');  // Remove prefix before dot
+
+    // Also try to remove prefix before third hyphen (screen-name-element pattern)
+    // e.g., "auth-login-email-input" → "email-input"
+    const parts = normalized.split('-');
+    if (parts.length >= 3) {
+      // Assume screen name is first two parts: "auth-login"
+      normalized = parts.slice(2).join('-');
+    }
+
+    // Finally remove all separators for comparison
+    return normalized.replace(/[-_\s]/g, '');
+  }
+
+  private extractTestId(locator: string): string | null {
+    // Extract from [data-testid="..."]
+    const match = locator.match(/data-testid="([^"]+)"/);
+    return match ? match[1] : null;
+  }
+}
+
+// ============================================================================
+// PRIORITY LEVEL 2: ACCESSIBILITY MATCHER
+// ============================================================================
+
+class AccessibilityMatcher {
+  /**
+   * Priority 2: Semantic matching via role + aria-label
+   *
+   * Confidence levels:
+   * - 0.9: role + aria-label match
+   * - 0.8: role match with similar text
+   * - 0.0: No match
+   */
+  match(elementName: string, uiElements: StrictUIElement[]): MappingResult | null {
+    const startTime = Date.now();
+
+    // Infer expected role and label from element name
+    const expected = this.inferExpectedAttributes(elementName);
+
+    // Try matching by role + aria-label
+    for (const element of uiElements) {
+      if (element.discoveryMethod !== 'accessibility') continue;
+
+      const role = element.role;
+      const ariaLabel = element.ariaLabel;
+
+      if (!role) continue;
+
+      // Match role + aria-label
+      if (expected.role === role && ariaLabel) {
+        const labelNorm = this.normalize(ariaLabel);
+        const expectedLabelNorm = this.normalize(expected.label || elementName);
+
+        if (labelNorm.includes(expectedLabelNorm) || expectedLabelNorm.includes(labelNorm)) {
+          return {
+            elementId: elementName,
+            selector: element.primaryLocator,
+            fallbackSelector: element.fallbackStrategy,
+            discoveryMethod: 'accessibility',
+            confidence: 0.9,
+            matchedElement: element,
+            attemptedPriorities: ['direct-id', 'accessibility'],
+            mappingTime: Date.now() - startTime,
+          };
+        }
+      }
+
+      // Match role with text/placeholder
+      if (expected.role === role) {
+        const text = element.text || element.placeholder || element.label;
+        if (text) {
+          const textNorm = this.normalize(text);
+          const expectedNorm = this.normalize(elementName);
+
+          if (textNorm.includes(expectedNorm) || expectedNorm.includes(textNorm)) {
+            return {
+              elementId: elementName,
+              selector: element.primaryLocator,
+              fallbackSelector: element.fallbackStrategy,
+              discoveryMethod: 'accessibility',
+              confidence: 0.8,
+              matchedElement: element,
+              attemptedPriorities: ['direct-id', 'accessibility'],
+              mappingTime: Date.now() - startTime,
+              warnings: [`Matched by role + text: ${role}`],
+            };
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private inferExpectedAttributes(elementName: string): { role?: string; label?: string } {
+    const normalized = elementName.toLowerCase();
+
+    // Infer role from common patterns
+    if (normalized.includes('button') || normalized.includes('btn')) {
+      return { role: 'button', label: elementName };
+    }
+
+    if (normalized.includes('link')) {
+      return { role: 'link', label: elementName };
+    }
+
+    if (normalized.includes('input') || normalized.includes('field')) {
+      return { role: 'textbox', label: elementName };
+    }
+
+    if (normalized.includes('select') || normalized.includes('dropdown')) {
+      return { role: 'combobox', label: elementName };
+    }
+
+    return { label: elementName };
+  }
+
+  private normalize(str: string): string {
+    return str
+      .toLowerCase()
+      .replace(/[\[\]]/g, '')
+      .replace(/[-_\s]/g, '');
+  }
+}
+
+// ============================================================================
+// PRIORITY LEVEL 3: HEURISTIC MATCHER
+// ============================================================================
+
+class HeuristicMatcher {
+  /**
+   * Priority 3: Heuristic matching using various strategies
+   *
+   * Strategies:
+   * - Pattern matching (email, password, submit...)
+   * - Tag + type matching
+   * - Text content matching
+   * - Position-based matching
+   *
+   * Confidence: 0.5 - 0.75
+   */
+  match(elementName: string, uiElements: StrictUIElement[]): MappingResult | null {
+    const startTime = Date.now();
+
+    // Strategy 1: Pattern matching
+    const patternMatch = this.matchByPattern(elementName, uiElements);
+    if (patternMatch) {
+      return {
+        ...patternMatch,
+        attemptedPriorities: ['direct-id', 'accessibility', 'heuristic'],
+        mappingTime: Date.now() - startTime,
+      } as MappingResult;
+    }
+
+    // Strategy 2: Tag + attribute matching
+    const tagMatch = this.matchByTagAndAttributes(elementName, uiElements);
+    if (tagMatch) {
+      return {
+        ...tagMatch,
+        attemptedPriorities: ['direct-id', 'accessibility', 'heuristic'],
+        mappingTime: Date.now() - startTime,
+      } as MappingResult;
+    }
+
+    // Strategy 3: Text content matching
+    const textMatch = this.matchByTextContent(elementName, uiElements);
+    if (textMatch) {
+      return {
+        ...textMatch,
+        attemptedPriorities: ['direct-id', 'accessibility', 'heuristic'],
+        mappingTime: Date.now() - startTime,
+      } as MappingResult;
+    }
+
+    return null;
+  }
+
+  private matchByPattern(elementName: string, elements: StrictUIElement[]): Partial<MappingResult> | null {
+    const normalized = elementName.toLowerCase();
+
+    // Email pattern
+    if (normalized.includes('email') || normalized.includes('mail')) {
+      const match = elements.find(el =>
+        el.tag === 'input' &&
+        (el.elementType === 'email' ||
+         el.props.type === 'email' ||
+         el.props.name?.includes('email'))
+      );
+
+      if (match) {
+        return {
+          elementId: elementName,
+          selector: match.primaryLocator,
+          fallbackSelector: match.fallbackStrategy,
+          discoveryMethod: 'heuristic',
+          confidence: 0.75,
+          matchedElement: match,
+          warnings: ['Pattern match: email input'],
+        };
+      }
+    }
+
+    // Password pattern
+    if (normalized.includes('password') || normalized.includes('pass')) {
+      const match = elements.find(el =>
+        el.tag === 'input' &&
+        (el.elementType === 'password' || el.props.type === 'password')
+      );
+
+      if (match) {
+        return {
+          elementId: elementName,
+          selector: match.primaryLocator,
+          fallbackSelector: match.fallbackStrategy,
+          discoveryMethod: 'heuristic',
+          confidence: 0.75,
+          matchedElement: match,
+          warnings: ['Pattern match: password input'],
+        };
+      }
+    }
+
+    // Submit button pattern
+    if (normalized.includes('submit') || normalized.includes('login') || normalized.includes('signin')) {
+      const match = elements.find(el =>
+        el.tag === 'button' &&
+        (el.elementType === 'submit' || el.props.type === 'submit')
+      );
+
+      if (match) {
+        return {
+          elementId: elementName,
+          selector: match.primaryLocator,
+          fallbackSelector: match.fallbackStrategy,
+          discoveryMethod: 'heuristic',
+          confidence: 0.7,
+          matchedElement: match,
+          warnings: ['Pattern match: submit button'],
+        };
+      }
+    }
+
+    return null;
+  }
+
+  private matchByTagAndAttributes(elementName: string, elements: StrictUIElement[]): Partial<MappingResult> | null {
+    const normalized = elementName.toLowerCase();
+
+    // Infer tag type
+    let expectedTag: string | null = null;
+    if (normalized.includes('input')) expectedTag = 'input';
+    if (normalized.includes('button') || normalized.includes('btn')) expectedTag = 'button';
+    if (normalized.includes('link')) expectedTag = 'a';
+    if (normalized.includes('select')) expectedTag = 'select';
+
+    if (!expectedTag) return null;
+
+    // Find elements matching tag
+    const candidates = elements.filter(el => el.tag === expectedTag);
+
+    if (candidates.length === 1) {
+      // Only one candidate - likely match
+      return {
+        elementId: elementName,
+        selector: candidates[0].primaryLocator,
+        fallbackSelector: candidates[0].fallbackStrategy,
+        discoveryMethod: 'heuristic',
+        confidence: 0.65,
+        matchedElement: candidates[0],
+        warnings: [`Only ${expectedTag} element found`],
+      };
+    }
+
+    return null;
+  }
+
+  private matchByTextContent(elementName: string, elements: StrictUIElement[]): Partial<MappingResult> | null {
+    const normalized = this.normalize(elementName);
+
+    for (const element of elements) {
+      const text = element.text || element.label || element.placeholder;
+      if (!text) continue;
+
+      const textNorm = this.normalize(text);
+
+      if (textNorm.includes(normalized) || normalized.includes(textNorm)) {
+        return {
+          elementId: elementName,
+          selector: element.primaryLocator,
+          fallbackSelector: element.fallbackStrategy,
+          discoveryMethod: 'heuristic',
+          confidence: 0.6,
+          matchedElement: element,
+          warnings: [`Text match: "${text}"`],
+        };
+      }
+    }
+
+    return null;
+  }
+
+  private normalize(str: string): string {
+    return str
+      .toLowerCase()
+      .replace(/[\[\]]/g, '')
+      .replace(/[-_\s]/g, '');
+  }
+}
+
+// ============================================================================
+// PRIORITY MAPPER (Main Class)
+// ============================================================================
+
+export class PriorityMapper {
+  private config: SelectorMappingConfig;
+  private directIdMatcher = new DirectIDMatcher();
+  private accessibilityMatcher = new AccessibilityMatcher();
+  private heuristicMatcher = new HeuristicMatcher();
+
+  private stats: MappingStats = {
+    totalMappings: 0,
+    successfulMappings: 0,
+    failedMappings: 0,
+    directIdMatches: 0,
+    accessibilityMatches: 0,
+    heuristicMatches: 0,
+    aiMatches: 0,
+    averageMappingTime: 0,
+    totalMappingTime: 0,
+    aiCallsCount: 0,
+    estimatedCost: 0,
+  };
+
+  constructor(config: SelectorMappingConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Map a single element using priority waterfall
+   */
+  async mapElement(request: MappingRequest): Promise<MappingResult> {
+    this.stats.totalMappings++;
+
+    const elementName = this.extractElementName(request.elementId);
+    const uiElements = request.uiModel.elements;
+
+    const confidenceThreshold = this.config.confidenceThreshold || 0.5;
+
+    // Priority 1: Direct ID Match
+    if (this.config.priorities.includes('direct-id')) {
+      const result = this.directIdMatcher.match(elementName, uiElements);
+      if (result && result.confidence >= confidenceThreshold) {
+        this.stats.successfulMappings++;
+        this.stats.directIdMatches++;
+        this.stats.totalMappingTime += result.mappingTime;
+        return result;
+      }
+    }
+
+    // Priority 2: Accessibility Match
+    if (this.config.priorities.includes('accessibility')) {
+      const result = this.accessibilityMatcher.match(elementName, uiElements);
+      if (result && result.confidence >= confidenceThreshold) {
+        this.stats.successfulMappings++;
+        this.stats.accessibilityMatches++;
+        this.stats.totalMappingTime += result.mappingTime;
+        return result;
+      }
+    }
+
+    // Priority 3: Heuristic Match
+    if (this.config.priorities.includes('heuristic-ai')) {
+      const result = this.heuristicMatcher.match(elementName, uiElements);
+      if (result && result.confidence >= confidenceThreshold) {
+        this.stats.successfulMappings++;
+        this.stats.heuristicMatches++;
+        this.stats.totalMappingTime += result.mappingTime;
+        return result;
+      }
+    }
+
+    // Priority 4: AI Fallback (TODO: implement)
+    // if (this.config.priorities.includes('heuristic-ai')) {
+    //   const aiResult = await this.aiMapper.map(request);
+    //   if (aiResult) {
+    //     this.stats.successfulMappings++;
+    //     this.stats.aiMatches++;
+    //     this.stats.aiCallsCount++;
+    //     this.stats.estimatedCost += 0.002; // Estimate
+    //     return aiResult;
+    //   }
+    // }
+
+    // No match found
+    this.stats.failedMappings++;
+
+    return {
+      elementId: request.elementId,
+      selector: `/* TODO: Map ${request.elementId} */`,
+      discoveryMethod: 'heuristic',
+      confidence: 0,
+      attemptedPriorities: this.config.priorities,
+      mappingTime: 0,
+      warnings: ['No match found - manual mapping required'],
+    };
+  }
+
+  /**
+   * Map multiple elements in batch
+   */
+  async mapElements(requests: MappingRequest[]): Promise<MappingResult[]> {
+    const results: MappingResult[] = [];
+
+    for (const request of requests) {
+      const result = await this.mapElement(request);
+      results.push(result);
+    }
+
+    // Calculate average mapping time
+    if (this.stats.totalMappings > 0) {
+      this.stats.averageMappingTime = this.stats.totalMappingTime / this.stats.totalMappings;
+    }
+
+    return results;
+  }
+
+  /**
+   * Get mapping statistics
+   */
+  getStats(): MappingStats {
+    return { ...this.stats };
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void {
+    this.stats = {
+      totalMappings: 0,
+      successfulMappings: 0,
+      failedMappings: 0,
+      directIdMatches: 0,
+      accessibilityMatches: 0,
+      heuristicMatches: 0,
+      aiMatches: 0,
+      averageMappingTime: 0,
+      totalMappingTime: 0,
+      aiCallsCount: 0,
+      estimatedCost: 0,
+    };
+  }
+
+  private extractElementName(elementId: string): string {
+    // Remove brackets: [login.email] → login.email
+    let cleaned = elementId.replace(/[\[\]]/g, '');
+
+    // Extract element name: login.email → email (keep last part)
+    const parts = cleaned.split('.');
+    return parts[parts.length - 1];
+  }
+}