@sun-asterisk/sungen 1.0.0

package/src/generators/README.md

@@ -0,0 +1,410 @@
+# Selector DSL Generator Framework
+
+> **AI-Native QA Framework** for multi-platform E2E testing with automated selector discovery
+
+## 🎯 Overview
+
+This framework enables:
+- **AI-powered selector generation** from source code (no manual mapping!)
+- **Multi-platform support** (Web, Android, iOS, Flutter, Compose, SwiftUI)
+- **Gherkin-compatible** element references `[screen.element]`
+- **Framework-agnostic** architecture (Playwright, Appium, Flutter Driver, etc.)
+- **Cache-first** approach to minimize AI API costs
+- **Override mechanism** for manual fine-tuning
+
+## 🏗️ Architecture
+
+```
+Gherkin Test Scenarios
+        ↓
+   [screen.element] References
+        ↓
+  Selector DSL (YAML)  ← AI-generated + Manual overrides
+        ↓
+  Executor Adapter (Playwright/Appium/etc.)
+        ↓
+    Actual UI Tests
+```
+
+## 📁 Directory Structure
+
+```
+qa/
+├── generators/           # Core framework code
+│   ├── types.ts          # TypeScript types
+│   ├── ui-model-builder/ # Source code scanners
+│   │   └── react-scanner.ts
+│   ├── selector-mapper/  # AI mapping engine
+│   │   └── ai-mapper.ts
+│   ├── dsl-writer/       # YAML writer/loader
+│   ├── cache/            # Cache management
+│   └── cli.ts            # Command-line interface
+├── helpers/
+│   └── selector-loader.ts # Executor adapters
+├── selectors/
+│   ├── screens/          # Generated selector DSL files
+│   │   ├── auth-login.yaml
+│   │   ├── auth-login.override.yaml  # Manual overrides
+│   │   └── ...
+│   └── .cache/           # AI response cache
+├── ui-models/            # Extracted UI models
+└── specs/                # Test files
+    └── login-dsl.spec.ts # Example tests
+```
+
+## 🚀 Quick Start
+
+### 1. Discover Screens
+
+Scan your application and extract UI models:
+
+```bash
+# Discover all screens
+npm run qa:dsl:discover -- --all --verbose
+
+# Discover specific screen
+npm run qa:dsl:discover -- --screen auth-login
+```
+
+**Output:** `qa/ui-models/auth-login.json`
+
+### 2. Generate Selectors
+
+Use AI to map element IDs to CSS selectors:
+
+```bash
+# Generate for all screens
+npm run qa:dsl:generate -- --all --provider anthropic
+
+# Generate for specific screen
+npm run qa:dsl:generate -- --screen auth-login --provider google
+
+# Force re-generation (skip cache)
+npm run qa:dsl:generate -- --all --force
+```
+
+**Output:** `qa/selectors/screens/auth-login.yaml`
+
+### 3. Validate Selectors
+
+Check if generated selectors are valid:
+
+```bash
+npm run qa:dsl:validate -- --all
+```
+
+### 4. View Statistics
+
+```bash
+npm run qa:dsl:info
+```
+
+Output:
+```
+📊 Cache Statistics:
+  Screens cached: 4
+  Cache entries: 4
+  Total size: 5.02 KB
+
+📁 Selector Files:
+  Total screens: 7
+  - auth-login: 5 selectors
+  - auth-register: 7 selectors
+  - chat: 2 selectors
+```
+
+### 5. Clear Cache
+
+```bash
+# Clear specific screen
+npm run qa:dsl:cache-clear -- --screen auth-login
+
+# Clear all cache
+npm run qa:dsl:cache-clear -- --all
+```
+
+## 📝 Writing Tests
+
+### Using Selector Loader (Recommended)
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { createPlaywrightSelectors } from '../helpers/selector-loader';
+
+test('login test', async ({ page }) => {
+  await page.goto('http://localhost:3000/auth/login');
+
+  // Create Playwright helper
+  const pw = createPlaywrightSelectors(page);
+
+  // Use DSL selectors
+  await pw.fill('[auth-login.email]', 'test@example.com', 'auth-login');
+  await pw.fill('[auth-login.password]', 'password123', 'auth-login');
+  await pw.click('[auth-login.submit]', 'auth-login');
+
+  // Verify
+  expect(page.url()).toContain('/chat');
+});
+```
+
+### Using Raw Selector Strings
+
+```typescript
+import { getSelector } from '../helpers/selector-loader';
+
+test('login test', async ({ page }) => {
+  await page.goto('http://localhost:3000/auth/login');
+
+  // Get raw selector string
+  const emailSelector = await getSelector('[auth-login.email]', 'auth-login');
+
+  // Use with Playwright directly
+  await page.fill(emailSelector, 'test@example.com');
+});
+```
+
+## 🔧 Manual Override
+
+If AI-generated selectors are incorrect, create an override file:
+
+```bash
+# This will be done automatically by the framework when needed
+# Or create manually:
+touch qa/selectors/screens/auth-login.override.yaml
+```
+
+**Override file format:**
+
+```yaml
+# qa/selectors/screens/auth-login.override.yaml
+
+"[auth-login.submit]":
+  selector: "button[type='submit']"
+  type: "button"
+  description: "Login submit button (manually fixed)"
+  discoveryMethod: manual
+  locatorType: css
+```
+
+The override will automatically merge with the base file, taking precedence.
+
+## 🌍 Multi-Platform Support
+
+### Folder Structure for Multi-Platform
+
+```
+qa/selectors/
+├── web/
+│   └── screens/
+│       └── login.yaml
+├── android/
+│   └── screens/
+│       └── login.yaml
+└── ios/
+    └── screens/
+        └── login.yaml
+```
+
+### Platform-Specific Selectors
+
+**Web (Playwright):**
+```yaml
+"[login.email]":
+  selector: "input[name='email']"
+  locatorType: css
+```
+
+**Android (Appium):**
+```yaml
+"[login.email]":
+  selector: "com.example:id/email_input"
+  locatorType: resource-id
+```
+
+**iOS (Appium):**
+```yaml
+"[login.email]":
+  selector: "emailTextField"
+  locatorType: accessibility-id
+```
+
+**Flutter:**
+```yaml
+"[login.email]":
+  selector: "emailInput"
+  locatorType: key
+```
+
+## 🤖 AI Providers
+
+The framework supports multiple AI providers:
+
+### Anthropic (Claude)
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+npm run qa:dsl:generate -- --provider anthropic --model claude-3-5-haiku-20241022
+```
+
+### Google (Gemini)
+
+```bash
+export GEMINI_API_KEY=AIza...
+npm run qa:dsl:generate -- --provider google --model gemini-2.0-flash-exp
+```
+
+### OpenAI (Future)
+
+```bash
+export OPENAI_API_KEY=sk-...
+npm run qa:dsl:generate -- --provider openai --model gpt-4o-mini
+```
+
+## 💰 Cost Optimization
+
+### Cache Strategy
+
+The framework automatically caches AI responses based on:
+- UI Model content hash
+- Element IDs list
+- Screen ID
+
+**Cache hit = $0 cost!**
+
+### Token Usage
+
+Typical usage per screen:
+- Small screen (2-5 elements): ~600-800 tokens
+- Medium screen (5-10 elements): ~800-1200 tokens
+- Large screen (10+ elements): ~1200-2000 tokens
+
+**Cost example (Claude Haiku):**
+- 1000 tokens ≈ $0.0005
+- 100 screens ≈ $0.05 - $0.10 (one-time generation)
+- Subsequent runs = $0 (cached)
+
+## 🔍 Troubleshooting
+
+### Selectors not found
+
+```bash
+# Re-discover screens
+npm run qa:dsl:discover -- --all --force
+
+# Re-generate selectors
+npm run qa:dsl:generate -- --all --force
+
+# Check generated selectors
+cat qa/selectors/screens/auth-login.yaml
+```
+
+### AI-generated selectors are incorrect
+
+Create an override file:
+
+```yaml
+# qa/selectors/screens/auth-login.override.yaml
+"[auth-login.email]":
+  selector: "#email-address"  # Fixed selector
+  type: "input"
+  description: "Email input (manually corrected)"
+  discoveryMethod: manual
+```
+
+### Cache issues
+
+```bash
+# Clear cache for specific screen
+npm run qa:dsl:cache-clear -- --screen auth-login
+
+# Clear all cache
+npm run qa:dsl:cache-clear -- --all
+```
+
+## 🎓 Best Practices
+
+### 1. Use Meaningful Element IDs
+
+**Good:**
+```
+[login.email-input]
+[login.password-input]
+[login.submit-button]
+```
+
+**Bad:**
+```
+[login.e1]
+[login.e2]
+[login.e3]
+```
+
+### 2. Add `data-testid` Attributes
+
+```tsx
+<input
+  name="email"
+  data-testid="login-email-input"  // Helps AI generate better selectors
+  placeholder="Email"
+/>
+```
+
+### 3. Use Override Files for Flaky Selectors
+
+If a selector is unstable, override it with a more robust one.
+
+### 4. Commit Generated Files to Git
+
+```bash
+git add qa/selectors/screens/*.yaml
+git add qa/ui-models/*.json
+git commit -m "chore: update selector DSL"
+```
+
+**Do NOT commit:**
+- `qa/selectors/.cache/` (gitignored)
+
+## 📊 Workflow
+
+```mermaid
+graph LR
+    A[Write Code] --> B[Discover Screens]
+    B --> C[Generate Selectors]
+    C --> D[Review Generated Selectors]
+    D --> E{Need Override?}
+    E -->|Yes| F[Create Override File]
+    E -->|No| G[Write Tests]
+    F --> G
+    G --> H[Run Tests]
+    H --> I{Tests Pass?}
+    I -->|No| J[Fix Selectors]
+    J --> F
+    I -->|Yes| K[Commit & Deploy]
+```
+
+## 🚧 Roadmap
+
+- [x] React/Next.js scanner
+- [x] Playwright executor adapter
+- [x] Cache layer
+- [x] Override mechanism
+- [x] CLI tools
+- [ ] Vue.js scanner
+- [ ] Angular scanner
+- [ ] Appium executor adapter
+- [ ] Flutter Driver executor
+- [ ] Runtime discovery (Vision AI)
+- [ ] Selector health monitoring
+- [ ] Auto-healing selectors
+
+## 📚 API Reference
+
+See [types.ts](./types.ts) for complete API documentation.
+
+## 🤝 Contributing
+
+This is an internal framework. For questions or feature requests, contact the QA team.
+
+## 📄 License
+
+Proprietary - Internal Use Only

package/src/generators/cache/cache-manager.ts

@@ -0,0 +1,322 @@
+// @ts-nocheck
+/**
+ * Cache Manager
+ * Manages caching of UI models and selector mappings to reduce AI API calls
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { UIModel, SelectorDSL, CacheEntry } from '../types';
+
+// ============================================================================
+// Cache Configuration
+// ============================================================================
+
+export interface CacheConfig {
+  cachePath: string;
+  enabled: boolean;
+  expiryMs?: number; // Cache expiry in milliseconds (default: no expiry)
+}
+
+// ============================================================================
+// Cache Manager Class
+// ============================================================================
+
+export class CacheManager {
+  private config: CacheConfig;
+
+  constructor(config: CacheConfig) {
+    this.config = config;
+
+    // Ensure cache directory exists
+    if (config.enabled) {
+      fs.mkdirSync(config.cachePath, { recursive: true });
+    }
+  }
+
+  /**
+   * Generate cache key from UI model and element IDs
+   */
+  generateCacheKey(
+    screenId: string,
+    uiModel: UIModel,
+    elementIds: string[]
+  ): string {
+    // Create content for hash
+    const content = JSON.stringify({
+      screenId,
+      elements: uiModel.elements,
+      elementIds: elementIds.sort() // Sort for consistent hash
+    });
+
+    // Generate SHA-256 hash
+    const hash = crypto.createHash('sha256').update(content).digest('hex');
+
+    return hash;
+  }
+
+  /**
+   * Get cache file path
+   */
+  private getCachePath(screenId: string, hash: string): string {
+    const screenDir = path.join(this.config.cachePath, screenId);
+    return path.join(screenDir, `${hash}.json`);
+  }
+
+  /**
+   * Check if cache exists and is valid
+   */
+  has(screenId: string, hash: string): boolean {
+    if (!this.config.enabled) return false;
+
+    const cachePath = this.getCachePath(screenId, hash);
+
+    if (!fs.existsSync(cachePath)) return false;
+
+    // Check expiry if configured
+    if (this.config.expiryMs) {
+      const stats = fs.statSync(cachePath);
+      const age = Date.now() - stats.mtimeMs;
+
+      if (age > this.config.expiryMs) {
+        // Cache expired, delete it
+        fs.unlinkSync(cachePath);
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get cached selectors
+   */
+  get(screenId: string, hash: string): CacheEntry | null {
+    if (!this.config.enabled) return null;
+
+    const cachePath = this.getCachePath(screenId, hash);
+
+    if (!this.has(screenId, hash)) return null;
+
+    try {
+      const content = fs.readFileSync(cachePath, 'utf-8');
+      return JSON.parse(content) as CacheEntry;
+    } catch (error) {
+      console.error(`Failed to read cache: ${cachePath}`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Save selectors to cache
+   */
+  set(
+    screenId: string,
+    hash: string,
+    selectors: SelectorDSL,
+    metadata: {
+      aiModel?: string;
+      tokenCost?: number;
+      framework: string;
+    }
+  ): void {
+    if (!this.config.enabled) return;
+
+    const cachePath = this.getCachePath(screenId, hash);
+    const screenDir = path.dirname(cachePath);
+
+    // Ensure screen directory exists
+    fs.mkdirSync(screenDir, { recursive: true });
+
+    // Create cache entry
+    const cacheEntry: CacheEntry = {
+      screenId,
+      hash,
+      selectors,
+      metadata: {
+        createdAt: new Date().toISOString(),
+        aiModel: metadata.aiModel,
+        tokenCost: metadata.tokenCost,
+        framework: metadata.framework
+      }
+    };
+
+    // Write to cache
+    fs.writeFileSync(cachePath, JSON.stringify(cacheEntry, null, 2), 'utf-8');
+  }
+
+  /**
+   * Invalidate cache for a screen
+   */
+  invalidate(screenId: string): number {
+    if (!this.config.enabled) return 0;
+
+    const screenDir = path.join(this.config.cachePath, screenId);
+
+    if (!fs.existsSync(screenDir)) return 0;
+
+    // Delete all cache files in screen directory
+    const files = fs.readdirSync(screenDir);
+    let deletedCount = 0;
+
+    for (const file of files) {
+      if (file.endsWith('.json')) {
+        fs.unlinkSync(path.join(screenDir, file));
+        deletedCount++;
+      }
+    }
+
+    // Remove directory if empty
+    if (deletedCount > 0) {
+      try {
+        fs.rmdirSync(screenDir);
+      } catch {
+        // Directory might not be empty, ignore
+      }
+    }
+
+    return deletedCount;
+  }
+
+  /**
+   * Clear all cache
+   */
+  clearAll(): number {
+    if (!this.config.enabled) return 0;
+
+    if (!fs.existsSync(this.config.cachePath)) return 0;
+
+    let deletedCount = 0;
+
+    // Get all screen directories
+    const screenDirs = fs.readdirSync(this.config.cachePath);
+
+    for (const screenDir of screenDirs) {
+      const screenPath = path.join(this.config.cachePath, screenDir);
+      const stat = fs.statSync(screenPath);
+
+      if (stat.isDirectory()) {
+        const count = this.invalidate(screenDir);
+        deletedCount += count;
+      }
+    }
+
+    return deletedCount;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    totalScreens: number;
+    totalEntries: number;
+    totalSize: number;
+    oldestEntry?: string;
+    newestEntry?: string;
+  } {
+    if (!this.config.enabled || !fs.existsSync(this.config.cachePath)) {
+      return {
+        totalScreens: 0,
+        totalEntries: 0,
+        totalSize: 0
+      };
+    }
+
+    let totalEntries = 0;
+    let totalSize = 0;
+    let oldestTime = Infinity;
+    let newestTime = 0;
+
+    const screenDirs = fs.readdirSync(this.config.cachePath);
+    const totalScreens = screenDirs.filter(dir => {
+      const stat = fs.statSync(path.join(this.config.cachePath, dir));
+      return stat.isDirectory();
+    }).length;
+
+    for (const screenDir of screenDirs) {
+      const screenPath = path.join(this.config.cachePath, screenDir);
+      const stat = fs.statSync(screenPath);
+
+      if (!stat.isDirectory()) continue;
+
+      const files = fs.readdirSync(screenPath);
+
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue;
+
+        const filePath = path.join(screenPath, file);
+        const fileStat = fs.statSync(filePath);
+
+        totalEntries++;
+        totalSize += fileStat.size;
+
+        if (fileStat.mtimeMs < oldestTime) {
+          oldestTime = fileStat.mtimeMs;
+        }
+        if (fileStat.mtimeMs > newestTime) {
+          newestTime = fileStat.mtimeMs;
+        }
+      }
+    }
+
+    return {
+      totalScreens,
+      totalEntries,
+      totalSize,
+      oldestEntry: oldestTime !== Infinity ? new Date(oldestTime).toISOString() : undefined,
+      newestEntry: newestTime !== 0 ? new Date(newestTime).toISOString() : undefined
+    };
+  }
+
+  /**
+   * List all cached screens
+   */
+  listScreens(): string[] {
+    if (!this.config.enabled || !fs.existsSync(this.config.cachePath)) {
+      return [];
+    }
+
+    const screenDirs = fs.readdirSync(this.config.cachePath);
+
+    return screenDirs.filter(dir => {
+      const stat = fs.statSync(path.join(this.config.cachePath, dir));
+      return stat.isDirectory();
+    });
+  }
+
+  /**
+   * Get all cache entries for a screen
+   */
+  getScreenEntries(screenId: string): CacheEntry[] {
+    if (!this.config.enabled) return [];
+
+    const screenDir = path.join(this.config.cachePath, screenId);
+
+    if (!fs.existsSync(screenDir)) return [];
+
+    const files = fs.readdirSync(screenDir);
+    const entries: CacheEntry[] = [];
+
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+
+      try {
+        const content = fs.readFileSync(path.join(screenDir, file), 'utf-8');
+        entries.push(JSON.parse(content));
+      } catch (error) {
+        console.error(`Failed to read cache entry: ${file}`, error);
+      }
+    }
+
+    return entries;
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function createCacheManager(config: CacheConfig): CacheManager {
+  return new CacheManager(config);
+}