@sun-asterisk/sungen 1.0.24 → 2.0.1

package/src/generators/test-generator/types.ts

@@ -1,38 +1,17 @@
 /**
- * Test Generator Interface
- * Defines contract for test framework code generators
+ * Test Generator Types
+ * Core type definitions for the test generation compiler
  */
 
-import { RuntimeConfig } from '../../config/config-schema';
-import { ParsedFeature } from '../../core/selector-base/gherkin-parser';
-import * as path from 'path';
-
 /**
- * Main Test Generator Interface
- */
-export interface TestGenerator {
-  readonly framework: string;
-
-  generate(
-    feature: ParsedFeature,
-    selectors: Record<string, any>,
-    testData: Record<string, any>,
-    config: RuntimeConfig
-  ): Promise<GeneratedTest>;
-
-  getFileExtension(): string;
-
-  validate(): boolean;
-}
-
-/**
- * Generated Test Result (executor-level)
+ * Generated Test Result
  */
 export interface GeneratedTest {
-  feature: string;
-  outputPath: string;
+  featureName: string;
+  filePath: string;
   code: string;
-  stats: GenerationStats;
+  sourceFile?: string;
+  stepCount?: number;
 }
 
 /**
@@ -42,90 +21,6 @@ export interface GenerationStats {
   totalScenarios: number;
   totalSteps: number;
   dictionaryMatched: number;
-  aiGenerated: number;
   todoCount: number;
   generationTime: number;
 }
-
-/**
- * Test Generator Factory
- */
-export class TestGeneratorFactory {
-  static create(framework: string, config: RuntimeConfig): TestGenerator {
-    switch (framework) {
-      case 'playwright': {
-        const { CodeGenerator } = require('./code-generator');
-
-        return {
-          framework: 'playwright',
-
-          async generate(
-            feature: ParsedFeature,
-            selectors: Record<string, any>,
-            testData: Record<string, any>,
-            cfg: RuntimeConfig
-          ): Promise<GeneratedTest> {
-            const startTime = Date.now();
-
-            let screenName: string | undefined;
-            if (feature.sourceFile) {
-              const sourceDir = path.dirname(feature.sourceFile);
-              const parts = sourceDir.split(path.sep);
-              const screensIndex = parts.indexOf('screens');
-              if (screensIndex >= 0 && screensIndex < parts.length - 2) {
-                screenName = parts[screensIndex + 1];
-              }
-            }
-
-            const generator = new CodeGenerator({
-              useAI: cfg.testGenerator.enableAIFallback,
-              verbose: cfg.verbose,
-              screenName,
-            });
-
-            const outputDir = cfg.paths.specsDir;
-            const result = await generator.generateTest(feature, outputDir);
-            generator.writeTest(result);
-
-            const countSteps = (f: ParsedFeature) =>
-              f.scenarios.reduce((sum: number, s: any) => sum + (s.steps ? s.steps.length : 0), 0);
-            const countTodos = (code: string) => (code.match(/\/\/ TODO/g) || []).length;
-
-            const stats: GenerationStats = {
-              totalScenarios: feature.scenarios.length,
-              totalSteps: countSteps(feature),
-              dictionaryMatched: 0,
-              aiGenerated: 0,
-              todoCount: countTodos(result.code),
-              generationTime: Date.now() - startTime,
-            };
-
-            return {
-              feature: feature.name,
-              outputPath: result.filePath,
-              code: result.code,
-              stats,
-            };
-          },
-
-          getFileExtension() {
-            return '.spec.ts';
-          },
-
-          validate() {
-            return true;
-          },
-        };
-      }
-
-      case 'appium':
-        throw new Error('Appium generator not yet implemented');
-
-      case 'integration':
-        throw new Error('Integration test generator not yet implemented');
-
-      default:
-        throw new Error(`Unsupported test framework: ${framework}`);
-    }
-  }
-}

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

@@ -190,15 +190,33 @@ function convertJapaneseToRomaji(text: string): string {
 
 import { SelectorType } from '../../../utils/selector-types';
 
-// New structured selector format
+// Structured selector format v2
 interface SelectorEntry {
-  locator?: string;  // CSS locator (optional, empty string means use type/value)
-  type?: SelectorType;  // 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())
-  exact?: boolean;    // Whether to use exact matching (default: false)
-  inputMethod?: string; // 'pressSequentially' for contenteditable/rich-text elements
+  locator?: string;       // CSS locator (optional, empty string means use type/value)
+  type?: SelectorType;    // 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())
+  exact?: boolean;        // Whether to use exact matching (default: false)
+  inputMethod?: string;   // 'pressSequentially' for contenteditable/rich-text elements
+
+  // === v2: Disambiguation ===
+  scope?: string;         // Parent landmark aria-label to scope within (e.g., 'desktop navigation')
+  match?: 'exact' | 'partial';  // For getByText matching (default: partial)
+
+  // === v2: Complex Elements ===
+  variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload subtype
+  trigger?: string;       // Visible button that triggers hidden file input
+  frame?: string;         // iframe selector for cross-frame elements
+  contenteditable?: boolean;  // Rich text editor (contenteditable div)
+
+  // === v2: Table ===
+  columns?: Record<string, { index: number; header: string; elements?: Record<string, SelectorEntry> }>;
+  pagination?: Record<string, string>;
+
+  // === v2: Assertion Helpers ===
+  attribute?: string;     // Attribute to check (for "has" assertions)
+  pattern?: string;       // Regex for attribute value
 }
 
 // New selector file structure: flat key-value pairs
@@ -220,12 +238,24 @@ interface LegacySelectorFile {
 export interface ResolvedSelector {
   strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator';
   value: string;
-  role?: string;      // For role-based selectors (e.g., 'button', 'link')
-  name?: string;      // For accessible name in role selectors
-  locator?: string;  // CSS locator for fallback
-  nth?: number;       // Index for .nth() if multiple matches exist
-  exact?: boolean;    // Whether to use exact matching (default: false)
+  role?: string;        // For role-based selectors (e.g., 'button', 'link')
+  name?: string;        // For accessible name in role selectors
+  locator?: string;     // CSS locator for fallback
+  nth?: number;         // Index for .nth() if multiple matches exist
+  exact?: boolean;      // Whether to use exact matching (default: false)
   inputMethod?: string; // 'pressSequentially' for contenteditable/rich-text elements
+
+  // === v2 fields ===
+  scope?: string;       // Parent landmark to scope within
+  match?: 'exact' | 'partial';  // For getByText exact matching
+  variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload type
+  trigger?: string;     // Button that triggers hidden file input
+  frame?: string;       // iframe selector
+  contenteditable?: boolean;  // Rich text editor
+  columns?: Record<string, { index: number; header: string; elements?: Record<string, any> }>;
+  pagination?: Record<string, string>;
+  attribute?: string;   // Attribute to check
+  pattern?: string;     // Regex for attribute value
 }
 
 /**
@@ -520,17 +550,32 @@ export class SelectorResolver {
     // Check if name exists in entry (even if empty string), use it; otherwise use originalLabel
     const name = entry.name !== undefined && entry.name !== null ? entry.name : originalLabel;
     const nth = entry.nth || 0;
-    const exact = entry.exact === true;
+    const exact = entry.exact === true || entry.match === 'exact';
     const inputMethod = entry.inputMethod;
 
-    // Helper to attach inputMethod only when present
-    const withInputMethod = (resolved: ResolvedSelector): ResolvedSelector =>
-      inputMethod ? { ...resolved, inputMethod } : resolved;
+    // v2 fields
+    const v2Fields: Partial<ResolvedSelector> = {};
+    if (entry.scope) v2Fields.scope = entry.scope;
+    if (entry.match) v2Fields.match = entry.match;
+    if (entry.variant) v2Fields.variant = entry.variant;
+    if (entry.trigger) v2Fields.trigger = entry.trigger;
+    if (entry.frame) v2Fields.frame = entry.frame;
+    if (entry.contenteditable) v2Fields.contenteditable = true;
+    if (entry.columns) v2Fields.columns = entry.columns;
+    if (entry.pagination) v2Fields.pagination = entry.pagination;
+    if (entry.attribute) v2Fields.attribute = entry.attribute;
+    if (entry.pattern) v2Fields.pattern = entry.pattern;
+
+    // Helper to attach v2 fields and inputMethod
+    const withExtras = (resolved: ResolvedSelector): ResolvedSelector => {
+      if (inputMethod) resolved.inputMethod = inputMethod;
+      return { ...resolved, ...v2Fields };
+    };
 
     // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly
     if (type === 'locator') {
       const locatorValue = locator && locator.trim() ? locator : value;
-      return withInputMethod({
+      return withExtras({
         strategy: 'locator',
         value: locatorValue,
         locator: locatorValue,
@@ -540,7 +585,7 @@ export class SelectorResolver {
 
     // If custom locator is provided and type is not 'locator', use it as CSS selector
     if (locator && locator.trim()) {
-      return withInputMethod({
+      return withExtras({
         strategy: 'css',
         value: locator,
         locator: locator,
@@ -551,7 +596,7 @@ export class SelectorResolver {
     // Use type-based strategy
     switch (type) {
       case 'placeholder':
-        return withInputMethod({
+        return withExtras({
           strategy: 'placeholder',
           value,
           nth,
@@ -559,7 +604,7 @@ export class SelectorResolver {
         });
 
       case 'role':
-        return withInputMethod({
+        return withExtras({
           strategy: 'role',
           role: value,
           name: name,  // Use the name field for accessible name
@@ -569,14 +614,14 @@ export class SelectorResolver {
         });
 
       case 'testid':
-        return withInputMethod({
+        return withExtras({
           strategy: 'testid',
           value,
           nth,
         });
 
       case 'label':
-        return withInputMethod({
+        return withExtras({
           strategy: 'label',
           value,
           nth,
@@ -584,7 +629,7 @@ export class SelectorResolver {
         });
 
       case 'text':
-        return withInputMethod({
+        return withExtras({
           strategy: 'text',
           value,
           nth,
@@ -593,7 +638,7 @@ export class SelectorResolver {
 
       default:
         // Fallback to placeholder
-        return withInputMethod({
+        return withExtras({
           strategy: 'placeholder',
           value,
           nth,

package/src/orchestrator/project-initializer.ts

@@ -46,6 +46,9 @@ export class ProjectInitializer {
     // Create README
     this.createReadme();
 
+    // Create AI rules files
+    this.createAIRules();
+
     // Display summary
     this.displaySummary(normalizedProjectName);
   }
@@ -111,7 +114,8 @@ export class ProjectInitializer {
       'specs/generated/',
       'specs/.auth/',
       'test-results/',
-      'playwright-report/'
+      'playwright-report/',
+      '.playwright-mcp/'
     ];
 
     if (!fs.existsSync(gitignorePath)) {
@@ -178,10 +182,73 @@ export class ProjectInitializer {
     if (projectName) {
       console.log(`  ${stepIndex++}. cd ${projectName}`);
     }
-    console.log(`  ${stepIndex++}. Review README.md for workflow overview`);
-    console.log(`  ${stepIndex++}. Create your first screen with: sungen add --screen <name>`);
-    console.log(`  ${stepIndex++}. Generate mapped tests with: sungen map --screen <name> | sungen map --all`);
-    console.log(`  ${stepIndex++}. Generate tests with: sungen generate --screen <name> | sungen generate --all\n`);
+    console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name> --path <url-path>`);
+    console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live page`);
+    console.log(`  ${stepIndex++}. Compile tests: sungen generate --screen <name>`);
+    console.log(`  ${stepIndex++}. Run tests: npx playwright test\n`);
+  }
+
+  /**
+   * Create AI rules files for GitHub Copilot and Claude Code
+   */
+  private createAIRules(): void {
+    const rulesContent = this.getAIRulesContent();
+
+    // GitHub Copilot: .github/copilot-instructions.md
+    const githubDir = path.join(this.cwd, '.github');
+    const copilotPath = path.join(githubDir, 'copilot-instructions.md');
+    if (!fs.existsSync(copilotPath)) {
+      if (!fs.existsSync(githubDir)) {
+        fs.mkdirSync(githubDir, { recursive: true });
+      }
+      fs.writeFileSync(copilotPath, rulesContent, 'utf-8');
+      this.createdItems.push('.github/copilot-instructions.md');
+    } else {
+      this.skippedItems.push('.github/copilot-instructions.md');
+    }
+
+    // Claude Code: CLAUDE.md
+    const claudePath = path.join(this.cwd, 'CLAUDE.md');
+    if (!fs.existsSync(claudePath)) {
+      fs.writeFileSync(claudePath, rulesContent, 'utf-8');
+      this.createdItems.push('CLAUDE.md');
+    } else {
+      this.skippedItems.push('CLAUDE.md');
+    }
+
+    // Gherkin Dictionary: docs/gherkin-dictionary.md
+    const docsDir = path.join(this.cwd, 'docs');
+    const dictPath = path.join(docsDir, 'gherkin-dictionary.md');
+    if (!fs.existsSync(dictPath)) {
+      // Copy from sungen package if available, otherwise generate stub
+      const packageDictPath = path.join(__dirname, '..', '..', 'docs', 'gherkin-dictionary.md');
+      if (!fs.existsSync(docsDir)) {
+        fs.mkdirSync(docsDir, { recursive: true });
+      }
+      if (fs.existsSync(packageDictPath)) {
+        fs.copyFileSync(packageDictPath, dictPath);
+      } else {
+        fs.writeFileSync(dictPath, '# Sungen Gherkin Dictionary\n\nSee https://github.com/sun-asterisk/sungen for the full dictionary.\n', 'utf-8');
+      }
+      this.createdItems.push('docs/gherkin-dictionary.md');
+    } else {
+      this.skippedItems.push('docs/gherkin-dictionary.md');
+    }
+  }
+
+  /**
+   * Read a template file from the templates directory
+   */
+  private readTemplate(filename: string): string {
+    const templatePath = path.join(__dirname, 'templates', filename);
+    return fs.readFileSync(templatePath, 'utf-8');
+  }
+
+  /**
+   * Get AI rules content (shared between Copilot and Claude)
+   */
+  private getAIRulesContent(): string {
+    return this.readTemplate('ai-rules.md');
   }
 
   /**
@@ -207,172 +274,20 @@ export class ProjectInitializer {
    * Get Playwright configuration template
    */
   private getPlaywrightConfigTemplate(): string {
-    return `import { defineConfig, devices } from '@playwright/test';
-
-/**
- * Read environment variables from file.
- * https://github.com/motdotla/dotenv
- */
-// import dotenv from 'dotenv';
-// import path from 'path';
-// dotenv.config({ path: path.resolve(__dirname, '.env') });
-
-/**
- * See https://playwright.dev/docs/test-configuration.
- */
-export default defineConfig({
-  testDir: './specs/generated',
-  /* Run tests in files in parallel */
-  fullyParallel: true,
-  /* Fail the build on CI if you accidentally left test.only in the source code. */
-  forbidOnly: !!process.env.CI,
-  /* Retry on CI only */
-  retries: process.env.CI ? 2 : 0,
-  /* Opt out of parallel tests on CI. */
-  workers: process.env.CI ? 1 : undefined,
-  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
-  reporter: 'html',
-  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
-  use: {
-    /* Base URL to use in actions like \`await page.goto('')\`. */
-    baseURL: 'https://example.com',
-
-    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
-    trace: 'on-first-retry',
-  },
-
-  /* Configure projects for major browsers */
-  projects: [
-    {
-      name: 'chromium',
-      use: { ...devices['Desktop Chrome'] },
-    },
-
-    /*
-    // {
-    //   name: 'firefox',
-    //   use: { ...devices['Desktop Firefox'] },
-    // },
-
-    // {
-    //   name: 'webkit',
-    //   use: { ...devices['Desktop Safari'] },
-    // },
-
-    /* Test against mobile viewports.
-    // {
-    //   name: 'Mobile Chrome',
-    //   use: { ...devices['Pixel 5'] },
-    // },
-    // {
-    //   name: 'Mobile Safari',
-    //   use: { ...devices['iPhone 12'] },
-    // },
-
-    /* Test against branded browsers. */
-    // {
-    //   name: 'Microsoft Edge',
-    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
-    // },
-    // {
-    //   name: 'Google Chrome',
-    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
-    // },
-  ],
-
-  /* Run your local dev server before starting the tests */
-  // webServer: {
-  //   command: 'npm run start',
-  //   url: 'http://localhost:3000',
-  //   reuseExistingServer: !process.env.CI,
-  // },
-});
-`;
+    return this.readTemplate('playwright.config.ts');
   }
 
   /**
    * Get .gitignore template
    */
   private getGitignoreTemplate(): string {
-    return `# Dependencies
-node_modules/
-
-# Build output
-dist/
-build/
-
-# Environment variables
-.env
-.env.local
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-`;
+    return this.readTemplate('gitignore');
   }
 
   /**
    * Get README template
    */
   private getReadmeTemplate(): string {
-    return `# Sungen Test Automation
-
-This project uses [Sungen](https://github.com/sun-asterisk/sungen) for AI-native E2E test generation.
-
-## Directory Structure
-
-\`\`\`
-├── qa/
-│   └── screens/          # Screen definitions and selectors
-└── specs/
-    └── generated/        # Auto-generated Playwright tests
-\`\`\`
-
-## Workflow
-
-### 1. Add new Screens
-Define a new screen for your application:
-
-\`\`\`bash
-sungen add --screen login
-\`\`\`
-
-### 2. Generate mapped or full tests
-Generate mapper elements for a specific screen or all screens:
-
-\`\`\`bash
-sungen map --screen login
-# or
-sungen map --all
-\`\`\`
-
-### 4. Generate full Playwright tests
-Generate complete tests based on mapped elements:
-
-\`\`\`bash
-sungen generate --screen login
-# or for all screens
-sungen generate --all
-\`\`\`
-
-## Configuration
-
-Edit \`sungen.config.yaml\` to customize:
-- Source root directory
-- UI framework (react/vue/html)
-- AI provider settings
-- Test generation options
-
-## Documentation
-
-- [Sungen Documentation](https://github.com/sun-asterisk/sungen)
-- [Playwright Documentation](https://playwright.dev)
-
-## Learn More
-
-Visit the [Sungen GitHub repository](https://github.com/sun-asterisk/sungen) for detailed guides and examples.
-`;
+    return this.readTemplate('readme.md');
   }
 }