@sun-asterisk/sungen 1.0.0

package/src/generators/dsl-writer/index.ts

@@ -0,0 +1,253 @@
+/**
+ * DSL Writer and Override Loader
+ * Writes selector DSL to YAML files and loads with override support
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { SelectorDSL, SelectorEntry } from '../types';
+
+// ============================================================================
+// DSL Writer
+// ============================================================================
+
+export interface WriteOptions {
+  outputPath: string;
+  screenId: string;
+  platform?: string; // web, android, ios, etc.
+}
+
+export async function writeDSL(
+  selectors: SelectorDSL,
+  options: WriteOptions
+): Promise<string> {
+  const { outputPath, screenId, platform } = options;
+
+  // Determine file path
+  let filePath: string;
+  if (platform) {
+    // Multi-platform: qa/selectors/web/screens/login.yaml
+    const platformDir = path.join(outputPath, platform, 'screens');
+    fs.mkdirSync(platformDir, { recursive: true });
+    filePath = path.join(platformDir, `${screenId}.yaml`);
+  } else {
+    // Single platform: qa/selectors/screens/login.yaml
+    const screensDir = path.join(outputPath, 'screens');
+    fs.mkdirSync(screensDir, { recursive: true });
+    filePath = path.join(screensDir, `${screenId}.yaml`);
+  }
+
+  // Convert to YAML with comments
+  const yamlContent = generateYAML(selectors, screenId);
+
+  // Write file
+  fs.writeFileSync(filePath, yamlContent, 'utf-8');
+
+  return filePath;
+}
+
+/**
+ * Generate YAML content with nice formatting
+ */
+function generateYAML(selectors: SelectorDSL, screenId: string): string {
+  const header = `# Selector DSL for screen: ${screenId}
+# Auto-generated by AI-assisted selector mapper
+# To override selectors, create ${screenId}.override.yaml in the same directory
+
+`;
+
+  const yamlDoc = yaml.stringify(selectors, {
+    indent: 2,
+    lineWidth: 100,
+    defaultKeyType: 'PLAIN',
+    defaultStringType: 'QUOTE_DOUBLE'
+  });
+
+  return header + yamlDoc;
+}
+
+// ============================================================================
+// DSL Loader with Override Support
+// ============================================================================
+
+export interface LoadOptions {
+  selectorPath: string;
+  screenId: string;
+  platform?: string;
+}
+
+export async function loadDSL(options: LoadOptions): Promise<SelectorDSL> {
+  const { selectorPath, screenId, platform } = options;
+
+  // Determine base file path
+  let basePath: string;
+  if (platform) {
+    basePath = path.join(selectorPath, platform, 'screens', `${screenId}.yaml`);
+  } else {
+    basePath = path.join(selectorPath, 'screens', `${screenId}.yaml`);
+  }
+
+  // Check if base file exists
+  if (!fs.existsSync(basePath)) {
+    throw new Error(`Selector DSL not found: ${basePath}`);
+  }
+
+  // Load base selectors
+  const baseContent = fs.readFileSync(basePath, 'utf-8');
+  const baseSelectors: SelectorDSL = yaml.parse(baseContent) || {};
+
+  // Load override file if exists
+  const overridePath = basePath.replace('.yaml', '.override.yaml');
+  if (fs.existsSync(overridePath)) {
+    const overrideContent = fs.readFileSync(overridePath, 'utf-8');
+    const overrideSelectors: SelectorDSL = yaml.parse(overrideContent) || {};
+
+    // Merge: override wins
+    return mergeSelectors(baseSelectors, overrideSelectors);
+  }
+
+  return baseSelectors;
+}
+
+/**
+ * Merge base and override selectors
+ * Override selectors take precedence
+ */
+export function mergeSelectors(
+  base: SelectorDSL,
+  override: SelectorDSL
+): SelectorDSL {
+  const merged: SelectorDSL = { ...base };
+
+  for (const [elementId, entry] of Object.entries(override)) {
+    // Override completely replaces base
+    merged[elementId] = {
+      ...entry,
+      discoveryMethod: 'manual' // Mark as manually overridden
+    };
+  }
+
+  return merged;
+}
+
+// ============================================================================
+// Helper: Get Selector
+// ============================================================================
+
+export async function getSelector(
+  elementId: string,
+  options: LoadOptions
+): Promise<SelectorEntry | null> {
+  const selectors = await loadDSL(options);
+  return selectors[elementId] || null;
+}
+
+// ============================================================================
+// Helper: List All Selectors for Screen
+// ============================================================================
+
+export async function listSelectors(
+  options: LoadOptions
+): Promise<{ elementId: string; entry: SelectorEntry }[]> {
+  const selectors = await loadDSL(options);
+
+  return Object.entries(selectors).map(([elementId, entry]) => ({
+    elementId,
+    entry
+  }));
+}
+
+// ============================================================================
+// Helper: Validate Selector DSL File
+// ============================================================================
+
+export async function validateDSL(options: LoadOptions): Promise<{
+  valid: boolean;
+  errors: string[];
+}> {
+  const errors: string[] = [];
+
+  try {
+    const selectors = await loadDSL(options);
+
+    // Validate each selector entry
+    for (const [elementId, entry] of Object.entries(selectors)) {
+      // Check required fields
+      if (!entry.selector) {
+        errors.push(`${elementId}: Missing 'selector' field`);
+      }
+      if (!entry.type) {
+        errors.push(`${elementId}: Missing 'type' field`);
+      }
+      if (!entry.description) {
+        errors.push(`${elementId}: Missing 'description' field`);
+      }
+      if (!entry.discoveryMethod) {
+        errors.push(`${elementId}: Missing 'discoveryMethod' field`);
+      }
+
+      // Validate selector syntax (basic check)
+      if (entry.selector && entry.locatorType === 'css') {
+        try {
+          // Very basic CSS selector validation
+          if (entry.selector.includes('>>') || entry.selector.includes('//')) {
+            errors.push(`${elementId}: Invalid CSS selector syntax`);
+          }
+        } catch {
+          errors.push(`${elementId}: Invalid selector format`);
+        }
+      }
+    }
+  } catch (error) {
+    errors.push(`Failed to load DSL: ${(error as Error).message}`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+// ============================================================================
+// Helper: Create Override Template
+// ============================================================================
+
+export async function createOverrideTemplate(
+  options: LoadOptions
+): Promise<string> {
+  const { selectorPath, screenId, platform } = options;
+
+  // Load base selectors
+  const baseSelectors = await loadDSL(options);
+
+  // Generate override template with all elements commented out
+  let content = `# Override selectors for screen: ${screenId}
+# Uncomment and modify the selectors you want to override
+# Only include selectors that need to be changed
+
+`;
+
+  for (const [elementId, entry] of Object.entries(baseSelectors)) {
+    content += `# ${elementId}:\n`;
+    content += `#   selector: "${entry.selector}"\n`;
+    content += `#   type: "${entry.type}"\n`;
+    content += `#   description: "${entry.description}"\n`;
+    content += `#   discoveryMethod: manual\n\n`;
+  }
+
+  // Determine override file path
+  let overridePath: string;
+  if (platform) {
+    overridePath = path.join(selectorPath, platform, 'screens', `${screenId}.override.yaml`);
+  } else {
+    overridePath = path.join(selectorPath, 'screens', `${screenId}.override.yaml`);
+  }
+
+  // Write template if it doesn't exist
+  if (!fs.existsSync(overridePath)) {
+    fs.writeFileSync(overridePath, content, 'utf-8');
+  }
+
+  return overridePath;
+}

package/src/generators/gherkin-parser/index.ts

@@ -0,0 +1,155 @@
+// @ts-nocheck
+import * as Gherkin from '@cucumber/gherkin';
+import * as Messages from '@cucumber/messages';
+import fs from 'fs';
+import path from 'path';
+
+export interface ParsedStep {
+  keyword: string; // Given, When, Then, And, But
+  text: string; // Original step text
+  selectorRef?: string; // Extracted selector reference like [auth-login.email]
+  dataRef?: string; // Extracted data reference like <valid_user.email>
+  value?: string; // Static value if any
+}
+
+export interface ParsedScenario {
+  name: string;
+  tags: string[];
+  steps: ParsedStep[];
+}
+
+export interface ParsedFeature {
+  name: string;
+  description: string;
+  path?: string; // Path metadata extracted from description (e.g., "Path: /login")
+  background?: ParsedScenario;
+  scenarios: ParsedScenario[];
+  sourceFile?: string; // Optional: source .feature file path for data resolution
+}
+
+export class GherkinParser {
+  private builder: Gherkin.AstBuilder;
+  private matcher: Gherkin.GherkinClassicTokenMatcher;
+  private parser: Gherkin.Parser;
+
+  constructor() {
+    const uuidFn = Messages.IdGenerator.uuid();
+    this.builder = new Gherkin.AstBuilder(uuidFn);
+    this.matcher = new Gherkin.GherkinClassicTokenMatcher();
+    this.parser = new Gherkin.Parser(this.builder, this.matcher);
+  }
+
+  /**
+   * Parse a .feature file
+   */
+  parseFeatureFile(filePath: string): ParsedFeature {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const gherkinDocument = this.parser.parse(content);
+
+    if (!gherkinDocument.feature) {
+      throw new Error(`No feature found in ${filePath}`);
+    }
+
+    const feature = gherkinDocument.feature;
+    
+    // Extract Path metadata from description (e.g., "Path: /login")
+    const description = feature.description || '';
+    const pathMatch = description.match(/^Path:\s*(.+)$/m);
+    const path = pathMatch ? pathMatch[1].trim() : undefined;
+
+    return {
+      name: feature.name,
+      description,
+      path,
+      background: this.parseBackground(feature),
+      scenarios: this.parseScenarios(feature),
+      sourceFile: filePath,
+    };
+  }
+
+  /**
+   * Parse background steps
+   */
+  private parseBackground(feature: Messages.Feature): ParsedScenario | undefined {
+    const background = feature.children.find(
+      (child) => child.background
+    )?.background;
+
+    if (!background) {
+      return undefined;
+    }
+
+    return {
+      name: 'Background',
+      tags: [],
+      steps: background.steps.map((step) => this.parseStep(step)),
+    };
+  }
+
+  /**
+   * Parse all scenarios
+   */
+  private parseScenarios(feature: Messages.Feature): ParsedScenario[] {
+    return feature.children
+      .filter((child) => child.scenario)
+      .map((child) => {
+        const scenario = child.scenario!;
+        return {
+          name: scenario.name,
+          tags: scenario.tags.map((tag) => tag.name),
+          steps: scenario.steps.map((step) => this.parseStep(step)),
+        };
+      });
+  }
+
+  /**
+   * Parse a single step and extract selector/data references
+   */
+  private parseStep(step: Messages.Step): ParsedStep {
+    const text = step.text;
+
+    // Extract selector reference: [Email Address] or [login:email_field] (legacy)
+    // Support natural language and legacy formats
+    const selectorMatch = text.match(/\[([^\]]+)\]/i);
+    const selectorRef = selectorMatch ? selectorMatch[1] : undefined;
+
+    // Extract data reference: {{login.email.valid}} or <valid_user.email> (legacy)
+    const dataMatch = text.match(/\{\{([a-z0-9\-\.\_]+)\}\}|<([^>]+)>/i);
+    const dataRef = dataMatch ? (dataMatch[1] || dataMatch[2]) : undefined;
+
+    // Extract quoted value: "Hello, how are you?"
+    const valueMatch = text.match(/"([^"]+)"/);
+    const value = valueMatch ? valueMatch[1] : undefined;
+
+    return {
+      keyword: step.keyword.trim(),
+      text,
+      selectorRef,
+      dataRef,
+      value,
+    };
+  }
+
+  /**
+   * Discover all .feature files in a directory
+   */
+  static discoverFeatureFiles(featuresDir: string): string[] {
+    const files: string[] = [];
+
+    function walk(dir: string) {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath);
+        } else if (entry.isFile() && entry.name.endsWith('.feature')) {
+          files.push(fullPath);
+        }
+      }
+    }
+
+    walk(featuresDir);
+    return files;
+  }
+}

package/src/generators/gherkin-parser/selector-extractor.ts

@@ -0,0 +1,142 @@
+/**
+ * Gherkin Selector Extractor
+ * Scans Gherkin feature files and extracts all [screen.element] references
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+
+export interface ExtractedSelector {
+  screenId: string;
+  elementId: string;
+  fullRef: string; // e.g., "[auth-login.email]"
+  occurrences: number;
+}
+
+export interface SelectorsByScreen {
+  [screenId: string]: {
+    [elementId: string]: {
+      fullRef: string;
+      occurrences: number;
+    };
+  };
+}
+
+export class GherkinSelectorExtractor {
+  /**
+   * Extract all selector references from Gherkin feature files
+   */
+  extractSelectors(featuresDir: string): SelectorsByScreen {
+    const featureFiles = glob.sync('**/*.feature', {
+      cwd: featuresDir,
+      absolute: true,
+    });
+
+    const selectorsByScreen: SelectorsByScreen = {};
+
+    for (const filePath of featureFiles) {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const selectors = this.extractSelectorsFromContent(content);
+
+      // Merge into selectorsByScreen
+      for (const selector of selectors) {
+        if (!selectorsByScreen[selector.screenId]) {
+          selectorsByScreen[selector.screenId] = {};
+        }
+
+        if (!selectorsByScreen[selector.screenId][selector.elementId]) {
+          selectorsByScreen[selector.screenId][selector.elementId] = {
+            fullRef: selector.fullRef,
+            occurrences: 0,
+          };
+        }
+
+        selectorsByScreen[selector.screenId][selector.elementId].occurrences++;
+      }
+    }
+
+    return selectorsByScreen;
+  }
+
+  /**
+   * Extract selectors from feature file content
+   */
+  private extractSelectorsFromContent(content: string): ExtractedSelector[] {
+    const selectors: ExtractedSelector[] = [];
+
+    // Regex to match [screen.element] or [screen]
+    const selectorRegex = /\[([a-zA-Z0-9_-]+)(?:\.([a-zA-Z0-9_-]+))?\]/g;
+
+    let match;
+    while ((match = selectorRegex.exec(content)) !== null) {
+      const fullRef = match[0]; // e.g., "[auth-login.email]"
+      const screenId = match[1]; // e.g., "auth-login"
+      const elementId = match[2]; // e.g., "email" (undefined for route-only refs)
+
+      // Only include selectors with both screen and element (skip route-only refs)
+      if (elementId) {
+        selectors.push({
+          screenId,
+          elementId,
+          fullRef,
+          occurrences: 1,
+        });
+      }
+    }
+
+    return selectors;
+  }
+
+  /**
+   * Generate base skeleton YAML structure
+   */
+  generateSkeletonYaml(screenId: string, selectors: SelectorsByScreen): string {
+    const screenSelectors = selectors[screenId];
+
+    if (!screenSelectors) {
+      return `# No selectors found for screen: ${screenId}\n`;
+    }
+
+    const lines: string[] = [
+      `# Selector skeleton for screen: ${screenId}`,
+      `# AI will fill in the selector values based on UI model`,
+      `# This file is generated by scanning Gherkin feature files`,
+      '',
+    ];
+
+    // Sort by element ID for consistency
+    const sortedElementIds = Object.keys(screenSelectors).sort();
+
+    for (const elementId of sortedElementIds) {
+      const { fullRef, occurrences } = screenSelectors[elementId];
+
+      lines.push(`"${fullRef}":`);
+      lines.push(`  selector: ""`);
+      lines.push(`  type: ""`);
+      lines.push(`  description: ""`);
+      lines.push(`  # Referenced ${occurrences} time(s) in Gherkin`);
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Write skeleton files for all screens
+   */
+  writeSkeletonFiles(
+    selectors: SelectorsByScreen,
+    outputDir: string
+  ): void {
+    // Ensure output directory exists
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    for (const screenId of Object.keys(selectors)) {
+      const skeletonContent = this.generateSkeletonYaml(screenId, selectors);
+      const outputPath = path.join(outputDir, `${screenId}.skeleton.yaml`);
+
+      fs.writeFileSync(outputPath, skeletonContent, 'utf-8');
+    }
+  }
+}