@sun-asterisk/sungen 1.0.0

package/src/generators/selector-mapper/ai-mapper.ts

@@ -0,0 +1,528 @@
+// @ts-nocheck
+/**
+ * AI-Assisted Selector Mapper
+ * Uses AI (Claude/Gemini) to map Gherkin element IDs to CSS selectors
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { UIModel, UIElement, SelectorDSL, SelectorEntry } from '../types';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface AIMapperConfig {
+  provider: 'anthropic' | 'google';
+  model?: string;
+  apiKey?: string;
+  verbose?: boolean;
+}
+
+interface MappingRequest {
+  uiModel: UIModel;
+  elementIds: string[];  // e.g., ["[login.email]", "[login.password]", "[login.submit]"]
+}
+
+interface MappingResult {
+  selectors: SelectorDSL;
+  metadata: {
+    aiModel: string;
+    tokenCost?: number;
+    provider: string;
+  };
+}
+
+// ============================================================================
+// AI Mapper Class
+// ============================================================================
+
+export class AIMapper {
+  private config: AIMapperConfig;
+  private anthropic?: Anthropic;
+  private googleAI?: GoogleGenerativeAI;
+
+  constructor(config: AIMapperConfig) {
+    this.config = config;
+
+    // Initialize AI clients
+    if (config.provider === 'anthropic') {
+      const apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY;
+      if (!apiKey) {
+        throw new Error('ANTHROPIC_API_KEY not found');
+      }
+      this.anthropic = new Anthropic({ apiKey });
+    } else if (config.provider === 'google') {
+      const apiKey = config.apiKey || process.env.GEMINI_API_KEY;
+      if (!apiKey) {
+        throw new Error('GEMINI_API_KEY not found');
+      }
+      this.googleAI = new GoogleGenerativeAI(apiKey);
+    }
+  }
+
+  /**
+   * Map element IDs to selectors using AI
+   */
+  async mapSelectors(request: MappingRequest): Promise<MappingResult> {
+    const prompt = this.buildPrompt(request);
+
+    if (this.config.verbose) {
+      console.log('\n📤 Sending request to AI...');
+    }
+
+    let response: string;
+    let aiModel: string;
+    let tokenCost: number | undefined;
+
+    if (this.config.provider === 'anthropic') {
+      const result = await this.callAnthropic(prompt);
+      response = result.response;
+      aiModel = result.model;
+      tokenCost = result.tokenCost;
+    } else {
+      const result = await this.callGoogle(prompt);
+      response = result.response;
+      aiModel = result.model;
+    }
+
+    // Parse AI response
+    const selectors = this.parseResponse(response, request.elementIds);
+
+    // UPDATED: Phase 1 - Task 3 - Don't create fake fallback placeholders
+    // Return null selectors with confidence "none" for missing elements
+    for (const elementId of request.elementIds) {
+      // CRITICAL FIX: Use clean ID to match heuristic format
+      const cleanId = elementId.replace(/[\[\]]/g, '').split('.').pop() || elementId;
+
+      if (!selectors[cleanId]) {
+        selectors[cleanId] = {
+          selector: null,
+          type: 'unknown',
+          description: 'Element not found in UI Model - re-scan or add manually',
+          discoveryMethod: 'ai-static-analysis',
+          locatorType: 'css',
+          confidence: 'none',
+          reason: 'not-in-ui-model',
+          suggestedAction: 'Run discovery again or add data-testid to source code'
+        };
+      }
+    }
+
+    return {
+      selectors,
+      metadata: {
+        aiModel,
+        tokenCost,
+        provider: this.config.provider
+      }
+    };
+  }
+
+  /**
+   * Build prompt for AI
+   */
+  private buildPrompt(request: MappingRequest): string {
+    const { uiModel, elementIds } = request;
+
+    // Extract ALL relevant attributes from UI model (DON'T simplify!)
+    const enrichedElements = uiModel.elements.map(el => {
+      // Extract critical props from the props object
+      const props = el.props || {};
+
+      return {
+        key: el.key,
+        tag: el.tag,
+        // Top-level attributes
+        id: el.id,
+        name: el.name,
+        placeholder: el.placeholder,
+        ariaLabel: el.ariaLabel,
+        testId: el.testId,
+        text: el.text,
+        role: el.role,
+        // CRITICAL: Extract props that AI needs for selector generation
+        type: props.type,           // button type="submit", input type="password"
+        href: props.href,           // link href="/auth/register"
+        value: props.value,         // input value
+        disabled: props.disabled,   // button disabled
+        required: props.required,   // input required
+        autoComplete: props.autoComplete, // input autocomplete
+        // Keep full props for AI to reference if needed
+        allProps: props
+      };
+    });
+
+    const prompt = `You are a test automation expert. Given a UI Model and a list of element IDs from Gherkin test scenarios, generate CSS selectors for each element.
+
+**CRITICAL: Use Semantic Understanding**
+The element IDs come from QA-written Gherkin scenarios and use human-readable names. You MUST understand the semantic meaning of each ID and match it to the appropriate UI element.
+
+**PHASE 2 ENHANCEMENT: Semantic Aliases & Context Awareness**
+
+Gherkin names often use INTENT-based naming while UI uses IMPLEMENTATION-based text. You must bridge this semantic gap:
+
+**Common Semantic Aliases:**
+
+**Action Buttons:**
+- "clear" / "clear-button" ≈ "New Chat" button (clears chat history)
+- "send" / "send-button" ≈ "Send", "Submit", "→", "➤" button
+- "submit" / "submit-button" ≈ "Submit", "Continue", "Sign In", "Register" button
+- "cancel" / "cancel-button" ≈ "Cancel", "Back", "Close" button
+- "delete" / "delete-button" ≈ "Delete", "Remove", "×" button
+- "edit" / "edit-button" ≈ "Edit", "Modify", "✎" button
+- "save" / "save-button" ≈ "Save", "Update", "Confirm" button
+
+**Brand/Identity Elements:**
+- "logo" ≈ heading with brand name OR image with alt="logo"
+- "title" ≈ main heading (h1) with brand/app name
+- "tagline" ≈ subtitle or description text
+
+**Navigation:**
+- "login-link" / "signin-link" ≈ link with text "Login", "Sign In", "Log In"
+- "register-link" / "signup-link" ≈ link with text "Register", "Sign Up", "Create Account"
+- "logout-link" / "signout-link" ≈ link/button with text "Logout", "Sign Out", "Log Out"
+- "back-link" ≈ link with text "Back", "←", "Return"
+
+**Input Fields (aliases for same field):**
+- "email" / "email-input" / "email-field" → input[type='email'] OR input[name='email']
+- "password" / "pass" / "password-input" / "pw" → input[type='password']
+- "message" / "message-input" / "input" / "textarea" → textarea for messages
+- "search" / "search-input" → input[type='search'] OR placeholder containing "search"
+
+**Container Elements:**
+- "messages" / "messages-container" / "messages-list" → div with overflow-y-auto OR flex-1 (scrollable area)
+- "empty-state" → text/paragraph shown when no content (e.g., "No messages yet", "Start a conversation")
+- "error" / "error-message" → text with red color (text-red-*) OR bg-red-*
+
+**Conditional Elements (may have isConditional marker):**
+- "timestamp" / "message-timestamp" → small text with time format (text-xs, text-gray-500)
+- "error" / "field-error" → conditionally rendered error message
+- "copy-button" → button that appears on hover (opacity-0 group-hover:opacity-100)
+- "tooltip" → conditionally shown helper text
+
+**Context Clues:**
+- If Gherkin says "clear-button" but UI has "New Chat" button → Match if button clears/resets state
+- If Gherkin says "logo" but UI has h1 text → Match heading with brand name
+- If Gherkin says "send" but UI has "Submit" → Match if button submits form
+- If multiple buttons exist, use context: submit buttons usually have type='submit', cancel buttons may have type='button'
+
+**Examples of semantic matching:**
+- \`[auth-login.email]\` OR \`[auth-login.email-input]\` → input with name="email" or id="email-address"
+- \`[auth-login.password]\` OR \`[auth-login.pass]\` → input with type="password" or name="password"
+- \`[auth-login.submit]\` OR \`[auth-login.login-button]\` → button with type="submit" OR button:has-text("Sign In")
+- \`[auth-login.signup-link]\` OR \`[auth-login.register-link]\` → link (a tag) pointing to signup/register
+- \`[chat.input]\` OR \`[chat.message-input]\` → textarea or input for chat messages
+- \`[chat.send-button]\` OR \`[chat.send]\` → button to send messages OR button:has-text("Send")
+- \`[chat.clear-button]\` → button:has-text("New Chat") (semantic alias: clear ≈ new chat)
+- \`[home.logo]\` → h1:has-text("PEU AI-Native Workflow") (logo as text heading)
+
+**Screen:** ${uiModel.screenId}
+**Framework:** ${uiModel.framework}
+
+**UI Elements Available:**
+${JSON.stringify(enrichedElements, null, 2)}
+
+**Element IDs to Resolve (from Gherkin):**
+${elementIds.map(id => `- ${id}`).join('\n')}
+
+**CRITICAL INSTRUCTIONS - MUST FOLLOW:**
+
+1. **Use EXACT attributes from UI Model** - Each element has \`type\`, \`href\`, \`id\`, \`name\`, etc. Use these EXACT values!
+
+2. **MANDATORY Selector Priority:**
+
+   **FOR BUTTONS (tag="button"):**
+   - If element has \`type\` attribute → **MUST use** \`button[type="..."]\`
+   - Example: \`type: "submit"\` → \`button[type='submit']\` (NOT \`button[role='button']\`!)
+   - Only use text if no type: \`button:has-text("...")\`
+
+   **FOR LINKS (tag="a", tag="link"):**
+   - If element has \`href\` → **MUST use** \`a[href="..."]\`
+   - Use EXACT href from UI Model
+   - Example: \`href: "/auth/register"\` → \`a[href='/auth/register']\`
+
+   **FOR INPUTS (tag="input"):**
+   - Priority: \`id\` > \`name\` > \`type\` + \`placeholder\`
+   - Example: \`id: "email-address"\` → \`#email-address\`
+   - Example: \`name: "password"\` → \`input[name='password']\`
+
+   **FOR TEXTAREA:**
+   - Priority: \`id\` > \`name\` > \`placeholder\`
+   - Example: \`placeholder: "Type your message"\` → \`textarea[placeholder*='Type your message']\`
+
+3. **NEVER use these (BANNED):**
+   - Generic \`role\` attribute for buttons/inputs
+   - Class names NOT in UI Model
+   - Invented/guessed selectors
+   - Just tag name without attributes (e.g., \`button\`, \`textarea\`)
+
+4. **Semantic matching:** "email", "email-input", "email-field" all = same element
+
+5. **Confidence levels:**
+   - \`high\`: Used id/name/type/href from UI Model - exact match
+   - \`medium\`: Used placeholder/text from UI Model OR semantic alias match (e.g., "clear" → "New Chat")
+   - \`low\`: Ambiguous match - multiple elements could match
+   - \`none\`: Element not found in UI Model (needs manual review)
+
+6. **PHASE 2: Ambiguity Detection & Helpful Messages**
+
+   If you find MULTIPLE elements that could match a Gherkin ID:
+   - Set confidence to \`low\`
+   - In description, list ALL potential matches
+   - Example:
+     \`\`\`json
+     {
+       "[chat.messages]": {
+         "selector": "div.flex-1.overflow-y-auto",
+         "type": "container",
+         "description": "AMBIGUOUS: Could be (1) messages container (div.flex-1), (2) messages list (div.max-w-4xl), or (3) message items. Recommend using [chat.messages-container] for container, [chat.messages-list] for list, or [chat.messages-item] for items.",
+         "confidence": "low"
+       }
+     }
+     \`\`\`
+
+   If element uses semantic alias:
+   - Set confidence to \`medium\`
+   - Explain the alias in description
+   - Example:
+     \`\`\`json
+     {
+       "[chat.clear-button]": {
+         "selector": "button:has-text('New Chat')",
+         "type": "button",
+         "description": "Semantic match: 'clear-button' maps to 'New Chat' button (clears chat history)",
+         "confidence": "medium"
+       }
+     }
+     \`\`\`
+
+7. **IF ELEMENT NOT FOUND IN UI MODEL:**
+   - DO NOT guess selectors or invent className patterns like \`div[className*='...']\`
+   - DO NOT create fake data-testid attributes like \`[data-testid="messages"]\`
+   - RETURN exactly:
+     \`\`\`json
+     {
+       "[element-id]": {
+         "selector": null,
+         "type": "unknown",
+         "description": "Element not found in UI Model",
+         "confidence": "none"
+       }
+     }
+     \`\`\`
+
+**Return ONLY valid JSON with this structure:**
+\`\`\`json
+{
+  "[element-id]": {
+    "selector": "css-selector-string",
+    "type": "input|button|link|textarea|text|container",
+    "description": "Human readable description",
+    "confidence": "high|medium|low"
+  }
+}
+\`\`\`
+
+**Example Response (showing CORRECT usage):**
+\`\`\`json
+{
+  "[auth-login.email]": {
+    "selector": "#email-address",
+    "type": "input",
+    "description": "Email input field",
+    "confidence": "high"
+  },
+  "[auth-login.submit]": {
+    "selector": "button[type='submit']",
+    "type": "button",
+    "description": "Login submit button",
+    "confidence": "high"
+  },
+  "[auth-login.signup-link]": {
+    "selector": "a[href='/auth/register']",
+    "type": "link",
+    "description": "Sign up link",
+    "confidence": "high"
+  }
+}
+\`\`\`
+
+**WRONG Examples (NEVER do this):**
+❌ \`"selector": "button[role='button']"\` - DON'T use role when type exists!
+❌ \`"selector": "button"\` - DON'T use tag only!
+❌ \`"selector": ".submit-btn"\` - DON'T invent class names!
+❌ \`"selector": "div[className*='chat-messages']"\` - DON'T guess className patterns!
+❌ \`"selector": "[data-testid='messages']"\` - DON'T create fake testids!
+✅ \`"selector": "button[type='submit']"\` - CORRECT! Uses type from UI Model!
+✅ \`"selector": null, "confidence": "none"\` - CORRECT! If not found in UI Model!
+
+**IMPORTANT:** Return ONLY the JSON object, no markdown, no additional text.`;
+
+    return prompt;
+  }
+
+  /**
+   * Call Anthropic API
+   */
+  private async callAnthropic(prompt: string): Promise<{
+    response: string;
+    model: string;
+    tokenCost: number;
+  }> {
+    if (!this.anthropic) {
+      throw new Error('Anthropic client not initialized');
+    }
+
+    const model = this.config.model || 'claude-3-5-haiku-20241022';
+
+    const message = await this.anthropic.messages.create({
+      model,
+      max_tokens: 4096,
+      messages: [{
+        role: 'user',
+        content: prompt
+      }]
+    });
+
+    const response = message.content[0].type === 'text' ? message.content[0].text : '';
+    const tokenCost = message.usage.input_tokens + message.usage.output_tokens;
+
+    if (this.config.verbose) {
+      console.log(`✅ Response received (${tokenCost} tokens)`);
+    }
+
+    return { response, model, tokenCost };
+  }
+
+  /**
+   * Call Google Gemini API
+   */
+  private async callGoogle(prompt: string): Promise<{
+    response: string;
+    model: string;
+  }> {
+    if (!this.googleAI) {
+      throw new Error('Google AI client not initialized');
+    }
+
+    const model = this.config.model || 'gemini-2.0-flash-exp';
+    const genModel = this.googleAI.getGenerativeModel({ model });
+
+    const result = await genModel.generateContent(prompt);
+    const response = result.response.text();
+
+    if (this.config.verbose) {
+      console.log(`✅ Response received from ${model}`);
+    }
+
+    return { response, model };
+  }
+
+  /**
+   * Parse AI response into SelectorDSL
+   */
+  private parseResponse(response: string, elementIds: string[]): SelectorDSL {
+    // Extract JSON from response (handle markdown code blocks)
+    let jsonStr = response.trim();
+
+    // Remove markdown code blocks if present
+    const codeBlockMatch = jsonStr.match(/```(?:json)?\s*(\{[\s\S]*\})\s*```/);
+    if (codeBlockMatch) {
+      jsonStr = codeBlockMatch[1];
+    }
+
+    try {
+      const parsed = JSON.parse(jsonStr);
+      const selectors: SelectorDSL = {};
+
+      // Convert to SelectorDSL format
+      for (const elementId of elementIds) {
+        if (parsed[elementId]) {
+          const entry = parsed[elementId];
+
+          // CRITICAL FIX: Clean element ID to match heuristic format
+          // [auth-login.email] → email
+          // [chat.message-input] → message-input
+          const cleanId = elementId.replace(/[\[\]]/g, '').split('.').pop() || elementId;
+
+          selectors[cleanId] = {
+            selector: entry.selector,
+            type: entry.type,
+            description: entry.description,
+            discoveryMethod: 'ai-static-analysis',
+            locatorType: 'css',
+            confidence: entry.confidence || 'medium'
+          };
+        }
+      }
+
+      return selectors;
+    } catch (error) {
+      console.error('Failed to parse AI response:', error);
+      console.error('Response:', response);
+      throw new Error('AI response is not valid JSON');
+    }
+  }
+
+  /**
+   * Create fallback selector using heuristic rules
+   */
+  private createFallbackSelector(elementId: string, uiModel: UIModel): SelectorEntry {
+    // Extract element name from ID
+    // e.g., "[login.email]" -> "email"
+    const match = elementId.match(/\[([^.]+)\.([^\]]+)\]/);
+    const elementName = match ? match[2] : 'unknown';
+
+    // Try to find matching element by name
+    const matchingElement = uiModel.elements.find(el =>
+      el.name === elementName ||
+      el.id === elementName ||
+      el.testId?.includes(elementName)
+    );
+
+    if (matchingElement) {
+      // Build selector
+      let selector = matchingElement.tag;
+      if (matchingElement.testId) {
+        selector = `[data-testid="${matchingElement.testId}"]`;
+      } else if (matchingElement.id) {
+        selector = `#${matchingElement.id}`;
+      } else if (matchingElement.name) {
+        selector = `${matchingElement.tag}[name="${matchingElement.name}"]`;
+      }
+
+      return {
+        selector,
+        type: matchingElement.tag,
+        description: `Fallback selector for ${elementName}`,
+        discoveryMethod: 'ai-static-analysis',
+        locatorType: 'css',
+        confidence: 'low'
+      };
+    }
+
+    // Ultimate fallback
+    return {
+      selector: `[data-testid="${elementName}"]`,
+      type: 'unknown',
+      description: `Placeholder selector for ${elementName} - needs manual review`,
+      discoveryMethod: 'ai-static-analysis',
+      locatorType: 'css',
+      confidence: 'low'
+    };
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export async function mapSelectors(
+  uiModel: UIModel,
+  elementIds: string[],
+  config: AIMapperConfig
+): Promise<MappingResult> {
+  const mapper = new AIMapper(config);
+  return mapper.mapSelectors({ uiModel, elementIds });
+}