@sun-asterisk/sungen 1.0.0

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

@@ -0,0 +1,530 @@
+/**
+ * Intelligent Selector Mapper with Context-Aware Scoring
+ *
+ * Maps logical element names (from Gherkin) to actual UI elements using:
+ * 1. Semantic context understanding
+ * 2. Multi-criteria scoring algorithm
+ * 3. Ambiguity detection and resolution
+ * 4. Reasoning generation for transparency
+ */
+
+interface EnhancedUIElement {
+  key: string;
+  tag: string;
+  text: string | null;
+  testId?: string;
+  role?: string;
+  id?: string;
+  name?: string;
+  placeholder?: string;
+  semanticContext: {
+    purpose: string;
+    section: string;
+    interactionType: string;
+    formContext?: {
+      formName: string;
+      fieldName: string;
+      formPurpose: string;
+    };
+    spatialContext: {
+      precedingText?: string;
+      followingText?: string;
+      nearbyLabels?: string[];
+    };
+    accessibility: {
+      ariaRole?: string;
+      ariaLabel?: string;
+      implicitRole?: string;
+    };
+  };
+  selectorStrategies: Array<{
+    type: string;
+    selector: string;
+    confidence: string;
+    stability: string;
+    playwrightCode?: string;
+  }>;
+}
+
+interface SelectorMapping {
+  logicalName: string;
+  element: EnhancedUIElement;
+  primary: {
+    type: string;
+    selector: string;
+    playwright: string;
+    confidence: string;
+  };
+  fallbacks: Array<{
+    type: string;
+    selector: string;
+    playwright: string;
+  }>;
+  score: number;
+  reasoning: string[];
+  contextClues: string[];
+  ambiguityWarning?: string;
+}
+
+export class IntelligentSelectorMapper {
+  /**
+   * Map a logical name to best matching element using context
+   */
+  mapElement(
+    logicalName: string,
+    elements: EnhancedUIElement[],
+    gherkinContext?: string
+  ): SelectorMapping | null {
+    // 1. Find candidates
+    const candidates = this.findCandidates(logicalName, elements);
+
+    if (candidates.length === 0) {
+      console.warn(`⚠️  No candidates found for: ${logicalName}`);
+      return null;
+    }
+
+    // 2. Score each candidate
+    const scored = candidates.map(element => ({
+      element,
+      score: this.scoreElement(element, logicalName, gherkinContext),
+      reasoning: this.generateReasoning(element, logicalName, gherkinContext),
+      contextClues: this.extractContextClues(element, gherkinContext),
+    }));
+
+    // 3. Sort by score
+    scored.sort((a, b) => b.score - a.score);
+
+    // 4. Detect ambiguity
+    const best = scored[0];
+    const secondBest = scored[1];
+    const ambiguityWarning = this.detectAmbiguity(best, secondBest);
+
+    // 5. Build mapping
+    const primary = this.selectPrimaryStrategy(best.element);
+    const fallbacks = best.element.selectorStrategies
+      .filter(s => s !== primary)
+      .sort((a, b) => this.strategyPriority(b) - this.strategyPriority(a));
+
+    return {
+      logicalName,
+      element: best.element,
+      primary: {
+        type: primary.type,
+        selector: primary.selector,
+        playwright: primary.playwrightCode || primary.selector,
+        confidence: primary.confidence,
+      },
+      fallbacks: fallbacks.map(s => ({
+        type: s.type,
+        selector: s.selector,
+        playwright: s.playwrightCode || s.selector,
+      })),
+      score: best.score,
+      reasoning: best.reasoning,
+      contextClues: best.contextClues,
+      ambiguityWarning,
+    };
+  }
+
+  /**
+   * Find candidate elements that might match logical name
+   */
+  private findCandidates(logicalName: string, elements: EnhancedUIElement[]): EnhancedUIElement[] {
+    const normalized = this.normalizeLogicalName(logicalName);
+    const keywords = normalized.split(/[-_\s]+/);
+
+    return elements.filter(element => {
+      // Match by text content
+      if (element.text && this.textMatches(element.text, keywords)) {
+        return true;
+      }
+
+      // Match by ARIA label
+      if (element.semanticContext.accessibility.ariaLabel) {
+        if (this.textMatches(element.semanticContext.accessibility.ariaLabel, keywords)) {
+          return true;
+        }
+      }
+
+      // Match by form field name
+      if (element.semanticContext.formContext?.fieldName) {
+        if (this.textMatches(element.semanticContext.formContext.fieldName, keywords)) {
+          return true;
+        }
+      }
+
+      // Match by element name
+      if (element.name && this.textMatches(element.name, keywords)) {
+        return true;
+      }
+
+      // Match by placeholder
+      if (element.placeholder && this.textMatches(element.placeholder, keywords)) {
+        return true;
+      }
+
+      // Match by purpose + tag
+      const purposeMatch = keywords.some(k =>
+        element.semanticContext.purpose.toLowerCase().includes(k)
+      );
+      const tagMatch = keywords.some(k => element.tag.toLowerCase().includes(k));
+
+      if (purposeMatch || tagMatch) {
+        return true;
+      }
+
+      return false;
+    });
+  }
+
+  /**
+   * Score an element based on how well it matches logical name
+   */
+  private scoreElement(
+    element: EnhancedUIElement,
+    logicalName: string,
+    gherkinContext?: string
+  ): number {
+    let score = 0;
+    const normalized = this.normalizeLogicalName(logicalName);
+    const keywords = normalized.split(/[-_\s]+/);
+
+    // === TEXT CONTENT MATCHING (0-50 points) ===
+    if (element.text) {
+      const textNorm = element.text.toLowerCase();
+      if (textNorm === normalized) {
+        score += 50; // Exact match
+      } else if (keywords.every(k => textNorm.includes(k))) {
+        score += 35; // Contains all keywords
+      } else if (keywords.some(k => textNorm.includes(k))) {
+        score += 20; // Contains some keywords
+      }
+    }
+
+    // === ARIA LABEL MATCHING (0-45 points) ===
+    const ariaLabel = element.semanticContext.accessibility.ariaLabel;
+    if (ariaLabel) {
+      const ariaNorm = ariaLabel.toLowerCase();
+      if (ariaNorm === normalized) {
+        score += 45;
+      } else if (keywords.every(k => ariaNorm.includes(k))) {
+        score += 30;
+      } else if (keywords.some(k => ariaNorm.includes(k))) {
+        score += 15;
+      }
+    }
+
+    // === FORM FIELD NAME MATCHING (0-40 points) ===
+    if (element.semanticContext.formContext) {
+      const fieldName = element.semanticContext.formContext.fieldName.toLowerCase();
+      if (fieldName === normalized) {
+        score += 40;
+      } else if (keywords.every(k => fieldName.includes(k))) {
+        score += 25;
+      } else if (keywords.some(k => fieldName.includes(k))) {
+        score += 12;
+      }
+    }
+
+    // === NAME ATTRIBUTE MATCHING (0-35 points) ===
+    if (element.name) {
+      const nameNorm = element.name.toLowerCase();
+      if (nameNorm === normalized) {
+        score += 35;
+      } else if (keywords.every(k => nameNorm.includes(k))) {
+        score += 20;
+      } else if (keywords.some(k => nameNorm.includes(k))) {
+        score += 10;
+      }
+    }
+
+    // === PLACEHOLDER MATCHING (0-30 points) ===
+    if (element.placeholder) {
+      const placeholderNorm = element.placeholder.toLowerCase();
+      if (keywords.every(k => placeholderNorm.includes(k))) {
+        score += 30;
+      } else if (keywords.some(k => placeholderNorm.includes(k))) {
+        score += 15;
+      }
+    }
+
+    // === PURPOSE MATCHING (0-20 points) ===
+    const purposeKeywords = {
+      button: 'action',
+      input: 'input',
+      link: 'navigation',
+      select: 'input',
+      checkbox: 'input',
+    };
+
+    keywords.forEach(keyword => {
+      if (purposeKeywords[keyword] === element.semanticContext.purpose) {
+        score += 20;
+      }
+    });
+
+    // === TAG MATCHING (0-15 points) ===
+    keywords.forEach(keyword => {
+      if (element.tag.toLowerCase() === keyword) {
+        score += 15;
+      }
+    });
+
+    // === GHERKIN CONTEXT MATCHING (0-25 points) ===
+    if (gherkinContext) {
+      const contextNorm = gherkinContext.toLowerCase();
+
+      // Preceding text mentioned
+      if (element.semanticContext.spatialContext.precedingText) {
+        const preceding = element.semanticContext.spatialContext.precedingText.toLowerCase();
+        if (contextNorm.includes(preceding)) {
+          score += 15;
+        }
+      }
+
+      // Section mentioned
+      if (contextNorm.includes(element.semanticContext.section)) {
+        score += 10;
+      }
+
+      // Form context mentioned
+      if (element.semanticContext.formContext) {
+        const formPurpose = element.semanticContext.formContext.formPurpose;
+        if (contextNorm.includes(formPurpose)) {
+          score += 10;
+        }
+      }
+    }
+
+    // === SELECTOR QUALITY BONUS (0-20 points) ===
+    const hasHighConfARIA = element.selectorStrategies.some(
+      s => s.type === 'aria' && s.confidence === 'high'
+    );
+    if (hasHighConfARIA) {
+      score += 20;
+    }
+
+    // === UNIQUENESS PENALTY (0 to -30 points) ===
+    // This would require passing all elements to check for duplicates
+    // For now, skip this in basic implementation
+
+    return Math.max(0, score);
+  }
+
+  /**
+   * Generate human-readable reasoning for the mapping
+   */
+  private generateReasoning(
+    element: EnhancedUIElement,
+    logicalName: string,
+    gherkinContext?: string
+  ): string[] {
+    const reasons: string[] = [];
+
+    // Text match
+    if (element.text) {
+      reasons.push(`Text: "${element.text}"`);
+    }
+
+    // ARIA label
+    if (element.semanticContext.accessibility.ariaLabel) {
+      reasons.push(`ARIA label: "${element.semanticContext.accessibility.ariaLabel}"`);
+    }
+
+    // Form context
+    if (element.semanticContext.formContext) {
+      reasons.push(
+        `Form field: ${element.semanticContext.formContext.formName}/${element.semanticContext.formContext.fieldName}`
+      );
+    }
+
+    // Element type
+    reasons.push(`Element: <${element.tag}>`);
+
+    // Purpose
+    reasons.push(`Purpose: ${element.semanticContext.purpose}`);
+
+    // Section
+    if (element.semanticContext.section !== 'main') {
+      reasons.push(`Section: ${element.semanticContext.section}`);
+    }
+
+    // Preceding text
+    if (element.semanticContext.spatialContext.precedingText) {
+      reasons.push(`After: "${element.semanticContext.spatialContext.precedingText}"`);
+    }
+
+    return reasons;
+  }
+
+  /**
+   * Extract context clues that helped with matching
+   */
+  private extractContextClues(
+    element: EnhancedUIElement,
+    gherkinContext?: string
+  ): string[] {
+    const clues: string[] = [];
+
+    if (element.semanticContext.section !== 'main') {
+      clues.push(`section:${element.semanticContext.section}`);
+    }
+
+    if (element.semanticContext.formContext) {
+      clues.push(`form:${element.semanticContext.formContext.formName}`);
+    }
+
+    if (element.semanticContext.accessibility.ariaLabel) {
+      clues.push(`aria-label`);
+    }
+
+    if (element.semanticContext.spatialContext.precedingText) {
+      clues.push(`has-preceding-text`);
+    }
+
+    if (gherkinContext) {
+      clues.push(`gherkin-context-used`);
+    }
+
+    return clues;
+  }
+
+  /**
+   * Detect if there's ambiguity between top candidates
+   */
+  private detectAmbiguity(
+    best: { score: number; element: EnhancedUIElement },
+    secondBest?: { score: number; element: EnhancedUIElement }
+  ): string | undefined {
+    if (!secondBest) return undefined;
+
+    const scoreDiff = best.score - secondBest.score;
+
+    if (scoreDiff < 10) {
+      return `⚠️ Low confidence - score difference only ${scoreDiff} points. Consider adding more specific identifiers.`;
+    }
+
+    if (scoreDiff < 20) {
+      return `⚠️ Moderate confidence - multiple similar elements found.`;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Select the best selector strategy for an element
+   */
+  private selectPrimaryStrategy(element: EnhancedUIElement): any {
+    // Priority: high-conf ARIA > high-conf semantic > testid > medium-conf ARIA > CSS
+    const strategies = element.selectorStrategies;
+
+    // Try high-confidence ARIA first
+    const highAria = strategies.find(s => s.type === 'aria' && s.confidence === 'high');
+    if (highAria) return highAria;
+
+    // Try high-confidence semantic
+    const highSemantic = strategies.find(s => s.type === 'semantic' && s.confidence === 'high');
+    if (highSemantic) return highSemantic;
+
+    // Try testid
+    const testid = strategies.find(s => s.type === 'testid');
+    if (testid) return testid;
+
+    // Try medium-confidence ARIA
+    const medAria = strategies.find(s => s.type === 'aria' && s.confidence === 'medium');
+    if (medAria) return medAria;
+
+    // Try any semantic
+    const semantic = strategies.find(s => s.type === 'semantic');
+    if (semantic) return semantic;
+
+    // Fallback to first available
+    return strategies[0];
+  }
+
+  /**
+   * Get priority score for a strategy type
+   */
+  private strategyPriority(strategy: any): number {
+    const priorities = {
+      aria: { high: 100, medium: 80, low: 60 },
+      semantic: { high: 90, medium: 70, low: 50 },
+      testid: { high: 85, medium: 85, low: 85 },
+      css: { high: 40, medium: 30, low: 20 },
+    };
+
+    const typePriority = priorities[strategy.type] || { high: 10, medium: 5, low: 1 };
+    return typePriority[strategy.confidence] || 1;
+  }
+
+  /**
+   * Normalize logical name for comparison
+   */
+  private normalizeLogicalName(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[-_.]/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  /**
+   * Check if text matches keywords
+   */
+  private textMatches(text: string, keywords: string[]): boolean {
+    const textNorm = text.toLowerCase();
+    return keywords.some(keyword => textNorm.includes(keyword));
+  }
+
+  /**
+   * Map multiple logical names at once
+   */
+  mapElements(
+    logicalNames: string[],
+    elements: EnhancedUIElement[],
+    gherkinContexts?: Record<string, string>
+  ): Record<string, SelectorMapping | null> {
+    const mappings: Record<string, SelectorMapping | null> = {};
+
+    logicalNames.forEach(name => {
+      const context = gherkinContexts?.[name];
+      mappings[name] = this.mapElement(name, elements, context);
+    });
+
+    return mappings;
+  }
+
+  /**
+   * Generate statistics about mappings
+   */
+  generateStats(mappings: Record<string, SelectorMapping | null>) {
+    const total = Object.keys(mappings).length;
+    const successful = Object.values(mappings).filter(m => m !== null).length;
+    const failed = total - successful;
+
+    const selectorTypeBreakdown: Record<string, number> = {};
+    const confidenceBreakdown: Record<string, number> = {};
+    const ambiguityCount = Object.values(mappings).filter(
+      m => m && m.ambiguityWarning
+    ).length;
+
+    Object.values(mappings).forEach(mapping => {
+      if (mapping) {
+        selectorTypeBreakdown[mapping.primary.type] =
+          (selectorTypeBreakdown[mapping.primary.type] || 0) + 1;
+        confidenceBreakdown[mapping.primary.confidence] =
+          (confidenceBreakdown[mapping.primary.confidence] || 0) + 1;
+      }
+    });
+
+    return {
+      total,
+      successful,
+      failed,
+      successRate: ((successful / total) * 100).toFixed(1) + '%',
+      selectorTypeBreakdown,
+      confidenceBreakdown,
+      ambiguityCount,
+    };
+  }
+}

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -0,0 +1,49 @@
+/**
+ * Test Generator Adapter Interface
+ * Defines the contract for framework-specific test code generation
+ */
+
+export interface TestFileData {
+  imports: string;
+  featureName: string;
+  featureDescription?: string;
+  background?: string;
+  scenarios: string[];
+}
+
+export interface ScenarioData {
+  scenarioName: string;
+  steps: Array<{ comment?: string; code: string }>;
+}
+
+export interface StepTemplateData {
+  templateName: string;
+  data: Record<string, any>;
+}
+
+export interface LocatorExpression {
+  varName: string;
+  locatorCode: string;
+  type: string;
+  value: string;
+  nth?: number;
+}
+
+/**
+ * TestGeneratorAdapter
+ * Framework-specific code generation using template engine
+ */
+export interface TestGeneratorAdapter {
+  readonly frameworkName: string;
+  readonly fileExtension: string;
+  readonly templatesDir: string;
+
+  // Template rendering methods
+  renderTestFile(data: TestFileData): string;
+  renderScenario(data: ScenarioData): string;
+  renderImports(): string;
+  renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
+
+  // Step rendering
+  renderStep(templateName: string, data: any): string;
+}

package/src/generators/test-generator/adapters/adapter-registry.ts

@@ -0,0 +1,56 @@
+import { TestGeneratorAdapter } from './adapter-interface';
+
+/**
+ * Adapter Registry
+ * Manages available test framework adapters
+ */
+export class AdapterRegistry {
+  private adapters: Map<string, () => TestGeneratorAdapter> = new Map();
+  private static instance: AdapterRegistry;
+
+  private constructor() {}
+
+  static getInstance(): AdapterRegistry {
+    if (!AdapterRegistry.instance) {
+      AdapterRegistry.instance = new AdapterRegistry();
+    }
+    return AdapterRegistry.instance;
+  }
+
+  /**
+   * Register a new adapter
+   */
+  register(frameworkName: string, adapterFactory: () => TestGeneratorAdapter): void {
+    this.adapters.set(frameworkName.toLowerCase(), adapterFactory);
+  }
+
+  /**
+   * Get adapter by framework name
+   */
+  getAdapter(frameworkName: string): TestGeneratorAdapter {
+    const factory = this.adapters.get(frameworkName.toLowerCase());
+    if (!factory) {
+      throw new Error(
+        `Unknown test framework: ${frameworkName}. Available: ${Array.from(this.adapters.keys()).join(', ')}`
+      );
+    }
+    return factory();
+  }
+
+  /**
+   * Check if adapter is registered
+   */
+  hasAdapter(frameworkName: string): boolean {
+    return this.adapters.has(frameworkName.toLowerCase());
+  }
+
+  /**
+   * List all registered adapters
+   */
+  getAvailableAdapters(): string[] {
+    return Array.from(this.adapters.keys());
+  }
+}
+
+// Singleton instance
+export const adapterRegistry = AdapterRegistry.getInstance();

package/src/generators/test-generator/adapters/index.ts

@@ -0,0 +1,9 @@
+export { TestGeneratorAdapter, TestFileData, ScenarioData, StepTemplateData, LocatorExpression } from './adapter-interface';
+export { AdapterRegistry, adapterRegistry } from './adapter-registry';
+export { PlaywrightAdapter } from './playwright/playwright-adapter';
+
+// Auto-register built-in adapters
+import { adapterRegistry } from './adapter-registry';
+import { PlaywrightAdapter } from './playwright/playwright-adapter';
+
+adapterRegistry.register('playwright', () => new PlaywrightAdapter());

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -0,0 +1,40 @@
+import path from 'path';
+import { TestGeneratorAdapter, TestFileData, ScenarioData } from '../adapter-interface';
+import { TemplateEngine } from '../../template-engine';
+
+/**
+ * PlaywrightAdapter
+ * Generates Playwright TypeScript test code using Handlebars templates
+ */
+export class PlaywrightAdapter implements TestGeneratorAdapter {
+  readonly frameworkName = 'playwright';
+  readonly fileExtension = '.spec.ts';
+  readonly templatesDir: string;
+  private templateEngine: TemplateEngine;
+
+  constructor() {
+    // Use adapter-specific templates directory
+    this.templatesDir = path.join(__dirname, 'templates');
+    this.templateEngine = new TemplateEngine(this.templatesDir);
+  }
+
+  renderTestFile(data: TestFileData): string {
+    return this.templateEngine.renderTestFile(data);
+  }
+
+  renderScenario(data: ScenarioData): string {
+    return this.templateEngine.renderScenario(data);
+  }
+
+  renderImports(): string {
+    return this.templateEngine.renderImports();
+  }
+
+  renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string {
+    return this.templateEngine.renderBeforeEach(data);
+  }
+
+  renderStep(templateName: string, data: any): string {
+    return this.templateEngine.renderStep(templateName, data);
+  }
+}

package/src/generators/test-generator/adapters/playwright/templates/before-each.hbs

@@ -0,0 +1,8 @@
+  test.beforeEach(async ({ page }) => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -0,0 +1,5 @@
+import { test, expect } from '@playwright/test';
+
+// This file is auto-generated from Gherkin feature files
+// DO NOT EDIT MANUALLY - changes will be overwritten
+// To modify tests, edit the corresponding .feature file and regenerate

package/src/generators/test-generator/adapters/playwright/templates/scenario.hbs

@@ -0,0 +1,8 @@
+  test('{{scenarioName}}', async ({ page }) => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });