@sun-asterisk/sungen 1.0.0

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -0,0 +1,480 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'yaml';
+
+// New structured selector format
+interface SelectorEntry {
+  selector?: string;  // CSS selector (optional, empty string means use type/value)
+  type?: 'placeholder' | 'role' | 'testid' | 'label' | 'text';  // Locator strategy
+  value?: string;     // Natural language value for the locator (e.g., 'button', 'link' for role)
+  name?: string;      // Accessible name for role-based selectors (e.g., 'Login', 'Submit')
+  nth?: number;       // Element index (0 = no index, 1+ = append .nth())
+}
+
+// New selector file structure: flat key-value pairs
+type SelectorFile = Record<string, SelectorEntry>;
+
+// Legacy format for backward compatibility
+interface LegacySelectorElement {
+  selector: string;
+  type?: 'selector' | 'data' | 'testid' | 'placeholder' | 'label' | 'text' | 'id' | 'button';
+  value?: string;
+  nth?: number;
+}
+
+interface LegacySelectorFile {
+  screen: string;
+  elements: Record<string, LegacySelectorElement>;
+}
+
+export interface ResolvedSelector {
+  strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role';
+  value: string;
+  role?: string;      // For role-based selectors (e.g., 'button', 'link')
+  name?: string;      // For accessible name in role selectors
+  selector?: string;  // CSS selector for fallback
+  nth?: number;       // Index for .nth() if multiple matches exist
+}
+
+/**
+ * SelectorResolver - Resolves selector references to direct Playwright locator code
+ * Supports natural language references with auto-generated keys
+ */
+export class SelectorResolver {
+  private selectorCache = new Map<string, SelectorFile | LegacySelectorFile>();
+  private selectorsDir: string;
+  private featureName?: string;
+  private screenName?: string;
+
+  constructor(selectorsDir?: string, screenName?: string) {
+    this.selectorsDir = selectorsDir || path.join(process.cwd(), 'qa', 'selectors', 'screens');
+    this.screenName = screenName;
+  }
+
+  /**
+   * Set screen context for base selector file lookup
+   */
+  setScreenContext(screenName: string): void {
+    this.screenName = screenName;
+  }
+
+  /**
+   * Set feature context for automatic file inference
+   */
+  setFeatureContext(featureName: string): void {
+    this.featureName = featureName;
+  }
+
+  /**
+   * Generate selector key from natural language label
+   * "Email Address" → "email.address"
+   * "Submit Button" → "submit.button"
+   * "User's Profile" → "users.profile"
+   */
+  static generateKey(label: string): string {
+    return label
+      .toLowerCase()
+      .replace(/['\u2019]s/g, 's')     // Apostrophe s to just s ("User's" → "users")
+      .replace(/['\u2019]/g, '')        // Remove remaining apostrophes
+      .replace(/[^a-z0-9\s]/g, '')     // Remove special chars except spaces
+      .trim()
+      .replace(/\s+/g, '.');            // Spaces to dots
+  }
+
+  /**
+   * Resolve selector reference to Playwright locator code
+   * Supports:
+   * - Natural language: "Email Address", "Password" (with feature context)
+   * - Legacy format: "login:email_field" or "login.email_field" (with screen prefix)
+   */
+  resolveSelector(selectorRef: string, featureName?: string): ResolvedSelector {
+    const contextName = featureName || this.featureName;
+
+    // Check if it's legacy format (contains : or has dot with screen prefix)
+    // Legacy: "login:email_field" or "login.email_field"
+    // Natural: "Email Address", "Password", "Submit Button"
+    const hasColonSeparator = selectorRef.includes(':');
+    const hasDotSeparator = selectorRef.includes('.');
+    
+    // If it has colon, it's definitely legacy
+    if (hasColonSeparator) {
+      return this.resolveLegacyFormat(selectorRef);
+    }
+    
+    // If it has dots and looks like a technical identifier (lowercase, no spaces), it's legacy
+    if (hasDotSeparator && /^[a-z0-9\-\_\.]+$/.test(selectorRef)) {
+      return this.resolveLegacyFormat(selectorRef);
+    }
+
+    // Otherwise, it's natural language with feature context
+    if (!contextName) {
+      throw new Error(
+        `Natural language selector "${selectorRef}" requires feature context. ` +
+        `Use setFeatureContext() or pass featureName parameter.`
+      );
+    }
+
+    return this.resolveNaturalLanguage(selectorRef, contextName);
+  }
+
+  /**
+   * Resolve natural language selector
+   */
+  private resolveNaturalLanguage(label: string, featureName: string): ResolvedSelector {
+    const key = SelectorResolver.generateKey(label);
+    const selectorFile = this.loadNewSelectorFile(featureName);
+
+    const entry = selectorFile[key];
+    if (!entry) {
+      throw new Error(
+        `Selector "${label}" (key: ${key}) not found in ${featureName}.yaml. ` +
+        `Available selectors: ${Object.keys(selectorFile).join(', ')}`
+      );
+    }
+
+    return this.resolveFromEntry(entry, label);
+  }
+
+  /**
+   * Resolve legacy format selector
+   * Now uses feature context instead of requiring screen prefix in selector
+   */
+  private resolveLegacyFormat(selectorRef: string): ResolvedSelector {
+    // Extract screen and element
+    const cleaned = selectorRef.replace(/[\[\]]/g, '');
+    
+    // Check if it has screen prefix (legacy format: "login:email_field" or "login.email_field")
+    if (cleaned.includes(':') || cleaned.includes('.')) {
+      const parts = cleaned.split(/[.:]/);
+      
+      if (parts.length < 2) {
+        throw new Error(
+          `Invalid legacy selector reference: ${selectorRef}. ` +
+          `Expected format with screen prefix: [screen:element] or [screen.element]`
+        );
+      }
+
+      const screenId = parts[0];
+      const elementId = parts.slice(1).join('_');
+
+      // Load selector metadata from legacy file
+      const element = this.loadLegacySelectorElement(screenId, elementId);
+
+      // Priority chain: testid → id → placeholder → label → text → css
+      return this.resolveByPriority(element);
+    }
+    
+    // Single word without separator - treat as natural language with feature context
+    if (!this.featureName) {
+      throw new Error(
+        `Selector "${selectorRef}" requires feature context. ` +
+        `Use setFeatureContext() or pass featureName parameter.`
+      );
+    }
+    
+    return this.resolveNaturalLanguage(selectorRef, this.featureName);
+  }
+
+  /**
+   * Resolve from new structured entry format
+   */
+  private resolveFromEntry(entry: SelectorEntry, originalLabel: string): ResolvedSelector {
+    // Default values
+    const selector = entry.selector || '';
+    const type = entry.type || 'placeholder';
+    const value = entry.value || originalLabel;
+    const name = entry.name || originalLabel;  // Use name field if provided, otherwise use label
+    const nth = entry.nth || 0;
+
+    // If custom selector is provided, use it
+    if (selector && selector.trim()) {
+      return {
+        strategy: 'css',
+        value: selector,
+        selector: selector,
+        nth,
+      };
+    }
+
+    // Use type-based strategy
+    switch (type) {
+      case 'placeholder':
+        return {
+          strategy: 'placeholder',
+          value,
+          nth,
+        };
+
+      case 'role':
+        return {
+          strategy: 'role',
+          role: value,
+          name: name,  // Use the name field for accessible name
+          value,
+          nth,
+        };
+
+      case 'testid':
+        return {
+          strategy: 'testid',
+          value,
+          nth,
+        };
+
+      case 'label':
+        return {
+          strategy: 'label',
+          value,
+          nth,
+        };
+
+      case 'text':
+        return {
+          strategy: 'text',
+          value,
+          nth,
+        };
+
+      default:
+        // Fallback to placeholder
+        return {
+          strategy: 'placeholder',
+          value,
+          nth,
+        };
+    }
+  }
+
+  /**
+   * Resolve selector by priority chain (legacy)
+   * Returns metadata only - no framework-specific code
+   */
+  private resolveByPriority(element: LegacySelectorElement): ResolvedSelector {
+    // Extract data-testid from selector if present
+    const testIdMatch = element.selector.match(/\[data-testid=["']([^"']+)["']\]/);
+    if (testIdMatch) {
+      return {
+        strategy: 'testid',
+        value: testIdMatch[1],
+        nth: element.nth,
+      };
+    }
+
+    // Check type-based strategies
+    if (element.type === 'button' && element.value) {
+      return {
+        strategy: 'role',
+        role: 'button',
+        name: element.value,
+        value: element.value,
+        nth: element.nth,
+      };
+    }
+
+    if (element.type === 'placeholder' && element.value) {
+      return {
+        strategy: 'placeholder',
+        value: element.value,
+        nth: element.nth,
+      };
+    }
+
+    if (element.type === 'label' && element.value) {
+      return {
+        strategy: 'label',
+        value: element.value,
+        nth: element.nth,
+      };
+    }
+
+    if (element.type === 'text' && element.value) {
+      return {
+        strategy: 'text',
+        value: element.value,
+        nth: element.nth,
+      };
+    }
+
+    // Extract #id from selector if present
+    const idMatch = element.selector.match(/#([\w-]+)/);
+    if (idMatch) {
+      return {
+        strategy: 'id',
+        value: idMatch[1],
+        selector: `#${idMatch[1]}`,
+        nth: element.nth,
+      };
+    }
+
+    // Fallback to CSS selector
+    return {
+      strategy: 'css',
+      value: element.selector,
+      selector: element.selector,
+      nth: element.nth,
+    };
+  }
+
+  /**
+   * Load new format selector file (flat key-value structure)
+   * Supports base + feature-specific merging:
+   * 1. Load base (screen-level) selectors - OPTIONAL
+   * 2. Load feature-specific selectors - REQUIRED
+   * 3. Merge (feature overrides base)
+   *
+   * Priority: override > normal, checks both old and new folder structures
+   * Old: qa/selectors/screens/<feature>.yaml
+   * New: qa/screens/<feature>/selectors/<feature>.yaml
+   */
+  private loadNewSelectorFile(featureName: string): SelectorFile {
+    const cacheKey = `new:${featureName}`;
+    if (this.selectorCache.has(cacheKey)) {
+      return this.selectorCache.get(cacheKey) as SelectorFile;
+    }
+
+    const selectors: SelectorFile = {};
+
+    // 1. Try load base file (screen-level shared selectors) - OPTIONAL
+    if (this.screenName) {
+      const basePath = this.findSelectorPath(this.screenName);
+      if (basePath && fs.existsSync(basePath)) {
+        const baseContent = fs.readFileSync(basePath, 'utf-8');
+        const baseSelectors = yaml.parse(baseContent) as SelectorFile;
+        Object.assign(selectors, baseSelectors);
+      }
+    }
+
+    // 2. Load feature-specific selectors - REQUIRED
+    const featurePath = this.findSelectorPath(featureName);
+    if (!featurePath) {
+      throw new Error(
+        `Selector file not found for feature "${featureName}". ` +
+        `Searched paths for ${featureName}.yaml`
+      );
+    }
+
+    const featureContent = fs.readFileSync(featurePath, 'utf-8');
+    const featureSelectors = yaml.parse(featureContent) as SelectorFile;
+
+    // 3. Merge: feature-specific overrides base
+    Object.assign(selectors, featureSelectors);
+
+    this.selectorCache.set(cacheKey, selectors);
+    return selectors;
+  }
+
+  /**
+   * Find selector file path (checks both old and new structures)
+   */
+  private findSelectorPath(name: string): string | null {
+    // Build list of possible paths (priority order)
+    const possiblePaths: string[] = [];
+
+    // Old structure: qa/selectors/screens/<name>.yaml
+    const oldOverridePath = path.join(this.selectorsDir, `${name}-override.yaml`);
+    const oldNormalPath = path.join(this.selectorsDir, `${name}.yaml`);
+    possiblePaths.push(oldOverridePath, oldNormalPath);
+
+    // New structure: qa/screens/<screenName>/selectors/<name>.yaml
+    const qaDir = path.dirname(path.dirname(this.selectorsDir)); // go up from qa/selectors/screens to qa/
+    
+    if (this.screenName) {
+      // Use screenName for directory, name for filename
+      const newOverridePath = path.join(qaDir, 'screens', this.screenName, 'selectors', `${name}-override.yaml`);
+      const newNormalPath = path.join(qaDir, 'screens', this.screenName, 'selectors', `${name}.yaml`);
+      possiblePaths.push(newOverridePath, newNormalPath);
+    } else {
+      // Fallback: assume name is both screen and feature
+      const newOverridePath = path.join(qaDir, 'screens', name, 'selectors', `${name}-override.yaml`);
+      const newNormalPath = path.join(qaDir, 'screens', name, 'selectors', `${name}.yaml`);
+      possiblePaths.push(newOverridePath, newNormalPath);
+    }
+
+    // Find first existing file
+    for (const p of possiblePaths) {
+      if (fs.existsSync(p)) {
+        return p;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Load selector element from legacy YAML file
+   */
+  private loadLegacySelectorElement(screenId: string, elementId: string): LegacySelectorElement {
+    const selectorFile = this.loadLegacySelectorFile(screenId);
+    
+    const element = selectorFile.elements[elementId];
+    if (!element) {
+      throw new Error(
+        `Element "${elementId}" not found in screen "${screenId}". ` +
+        `Available elements: ${Object.keys(selectorFile.elements).join(', ')}`
+      );
+    }
+
+    return element;
+  }
+
+  /**
+   * Load legacy selector file from disk (with caching)
+   * Checks both old and new folder structures
+   */
+  private loadLegacySelectorFile(screenId: string): LegacySelectorFile {
+    const cacheKey = `legacy:${screenId}`;
+    if (this.selectorCache.has(cacheKey)) {
+      return this.selectorCache.get(cacheKey) as LegacySelectorFile;
+    }
+
+    // Build list of possible paths (priority order)
+    const possiblePaths: string[] = [];
+
+    // Old structure: qa/selectors/screens/<screen>.yaml
+    const oldOverridePath = path.join(this.selectorsDir, `${screenId}-override.yaml`);
+    const oldNormalPath = path.join(this.selectorsDir, `${screenId}.yaml`);
+    possiblePaths.push(oldOverridePath, oldNormalPath);
+
+    // New structure: qa/screens/<screen>/selectors/<screen>.yaml
+    const qaDir = path.dirname(path.dirname(this.selectorsDir));
+    const newOverridePath = path.join(qaDir, 'screens', screenId, 'selectors', `${screenId}-override.yaml`);
+    const newNormalPath = path.join(qaDir, 'screens', screenId, 'selectors', `${screenId}.yaml`);
+    possiblePaths.push(newOverridePath, newNormalPath);
+
+    // Find first existing file
+    let filePath: string | undefined;
+    for (const p of possiblePaths) {
+      if (fs.existsSync(p)) {
+        filePath = p;
+        break;
+      }
+    }
+
+    if (!filePath) {
+      throw new Error(
+        `Selector file not found for screen "${screenId}". ` +
+        `Searched: ${possiblePaths.join(', ')}`
+      );
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const selectorFile = yaml.parse(content) as LegacySelectorFile;
+
+    this.selectorCache.set(cacheKey, selectorFile);
+    return selectorFile;
+  }
+
+  /**
+   * Escape single quotes in strings
+   */
+  private escapeQuotes(text: string): string {
+    return text.replace(/'/g, "\\'");
+  }
+
+  /**
+   * Clear cache (useful for testing)
+   */
+  clearCache(): void {
+    this.selectorCache.clear();
+  }
+}

package/src/generators/types.ts

@@ -0,0 +1,226 @@
+/**
+ * Core types for Selector DSL Framework
+ * Framework-agnostic types for multi-platform support
+ */
+
+// ============================================================================
+// UI Model Types
+// ============================================================================
+
+export interface UIElement {
+  key: string;                    // Unique key within screen (e1, e2, ...)
+  tag: string;                    // HTML/component tag (input, button, View, TextField, ...)
+  role?: string;                  // ARIA role or semantic role
+  name?: string;                  // name attribute
+  id?: string;                    // id/resource-id attribute
+  placeholder?: string;           // placeholder text
+  label?: string;                 // Associated label text
+  text?: string;                  // Text content
+  ariaLabel?: string;             // aria-label attribute
+  testId?: string;                // data-testid / test ID
+  source: string;                 // Source file path
+  framework?: string;             // Framework-specific type (TextField, EditText, etc.)
+  props?: Record<string, any>;    // Additional framework-specific props
+}
+
+export interface UIModel {
+  screenId: string;               // Screen identifier (login, dashboard, ...)
+  routeId: string;                // Route path or identifier
+  framework: FrameworkType;       // Framework type
+  sourceFiles: string[];          // All source files merged
+  elements: UIElement[];          // All UI elements on this screen
+  metadata?: {
+    scannedAt: string;            // ISO timestamp
+    version: string;              // Tool version
+    hash: string;                 // Content hash for cache
+  };
+}
+
+// ============================================================================
+// Selector DSL Types
+// ============================================================================
+
+export type DiscoveryMethod =
+  | 'ai-static-analysis'          // Generated by AI from static code analysis
+  | 'manual'                      // Manually written by QA
+  | 'runtime';                    // Discovered at runtime
+
+export type LocatorType =
+  | 'css'                         // CSS selector (web)
+  | 'xpath'                       // XPath selector
+  | 'resource-id'                 // Android resource-id
+  | 'accessibility-id'            // iOS accessibility identifier
+  | 'test-id'                     // Framework test ID (data-testid, etc.)
+  | 'key'                         // Flutter Key
+  | 'text'                        // Text-based locator
+  | 'role';                       // ARIA role locator
+
+export interface SelectorEntry {
+  selector: string;               // The actual selector string
+  type: string;                   // Element type (input, button, link, text, ...)
+  description: string;            // Human-readable description
+  discoveryMethod: DiscoveryMethod;
+  locatorType?: LocatorType;      // Type of locator (for multi-platform)
+  confidence?: 'high' | 'medium' | 'low'; // AI confidence level
+  alternatives?: string[];        // Alternative selectors (fallbacks)
+  metadata?: {
+    lastValidated?: string;       // ISO timestamp
+    validationStatus?: 'valid' | 'invalid' | 'unknown';
+  };
+}
+
+export interface SelectorDSL {
+  [elementId: string]: SelectorEntry;
+}
+
+// ============================================================================
+// Framework Types
+// ============================================================================
+
+export type FrameworkType =
+  | 'react'
+  | 'react-nextjs'
+  | 'vue'
+  | 'angular'
+  | 'html'
+  | 'flutter'
+  | 'jetpack-compose'
+  | 'swiftui';
+
+export type TargetPlatform =
+  | 'web'
+  | 'android'
+  | 'ios'
+  | 'desktop';
+
+// ============================================================================
+// Executor Types
+// ============================================================================
+
+export type ExecutorType =
+  | 'playwright'                  // Web - Playwright
+  | 'puppeteer'                   // Web - Puppeteer
+  | 'selenium'                    // Web - Selenium
+  | 'appium-android'              // Android - Appium
+  | 'appium-ios'                  // iOS - Appium
+  | 'flutter-driver'              // Flutter Driver
+  | 'espresso'                    // Android - Espresso
+  | 'xcuitest';                   // iOS - XCUITest
+
+export interface ExecutorConfig {
+  type: ExecutorType;
+  platform: TargetPlatform;
+  selectorPath: string;           // Path to selector DSL files
+  overridePath?: string;          // Path to override files
+}
+
+// ============================================================================
+// Cache Types
+// ============================================================================
+
+export interface CacheEntry {
+  screenId: string;
+  hash: string;                   // SHA-256 hash of UI Model + element IDs
+  selectors: SelectorDSL;
+  metadata: {
+    createdAt: string;            // ISO timestamp
+    aiModel?: string;             // AI model used (claude-3-5-sonnet, gemini-2.0-flash, ...)
+    tokenCost?: number;           // Token usage
+    framework: FrameworkType;
+  };
+}
+
+// ============================================================================
+// Generator Config Types
+// ============================================================================
+
+export interface GeneratorConfig {
+  // AI Provider
+  aiProvider: 'anthropic' | 'google' | 'openai';
+  aiModel?: string;               // Optional: specific model (defaults to best available)
+
+  // Paths
+  sourceRoot: string;             // Root directory to scan (e.g., 'app', 'src')
+  uiModelPath: string;            // Where to save UI models
+  selectorPath: string;           // Where to save selectors
+  cachePath: string;              // Cache directory
+
+  // Framework
+  framework: FrameworkType;
+
+  // Options
+  enableCache: boolean;
+  cacheExpiry?: number;           // Cache expiry in milliseconds
+  parallelScans?: number;         // Number of parallel scans
+  verbose?: boolean;
+}
+
+// ============================================================================
+// CLI Types
+// ============================================================================
+
+export interface DiscoverOptions {
+  screenId?: string;              // Specific screen to discover
+  all?: boolean;                  // Discover all screens
+  force?: boolean;                // Force re-scan even if cached
+}
+
+export interface GenerateOptions {
+  screenId?: string;              // Specific screen to generate
+  all?: boolean;                  // Generate all screens
+  force?: boolean;                // Force re-generation
+  skipCache?: boolean;            // Skip cache lookup
+}
+
+export interface ValidateOptions {
+  screenId?: string;              // Specific screen to validate
+  all?: boolean;                  // Validate all screens
+  executor?: ExecutorType;        // Executor to validate against
+}
+
+// ============================================================================
+// Gherkin Integration Types
+// ============================================================================
+
+export interface GherkinElementReference {
+  elementId: string;              // e.g., "[login.email]"
+  screenId: string;               // e.g., "login"
+  elementName: string;            // e.g., "email"
+}
+
+export function parseElementReference(ref: string): GherkinElementReference | null {
+  // Parse "[screen.element]" format
+  const match = ref.match(/^\[([^.]+)\.([^\]]+)\]$/);
+  if (!match) return null;
+
+  return {
+    elementId: ref,
+    screenId: match[1],
+    elementName: match[2]
+  };
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export class SelectorNotFoundError extends Error {
+  constructor(public elementId: string, public screenId: string) {
+    super(`Selector not found: ${elementId} on screen ${screenId}`);
+    this.name = 'SelectorNotFoundError';
+  }
+}
+
+export class UIModelNotFoundError extends Error {
+  constructor(public screenId: string) {
+    super(`UI Model not found for screen: ${screenId}`);
+    this.name = 'UIModelNotFoundError';
+  }
+}
+
+export class GeneratorError extends Error {
+  constructor(message: string, public cause?: Error) {
+    super(message);
+    this.name = 'GeneratorError';
+  }
+}