@sun-asterisk/sungen 1.0.23 → 2.0.0

package/src/core/live-scanner/role-fallback.ts

@@ -1,43 +0,0 @@
-/**
- * Role Fallback Groups
- * Maps Gherkin element type hints to ordered lists of ARIA roles to try.
- */
-
-const ROLE_FALLBACK_GROUPS: Record<string, string[]> = {
-  button:   ['button', 'link', 'menuitem', 'tab'],
-  link:     ['link', 'button', 'menuitem'],
-  field:    ['textbox', 'combobox', 'searchbox', 'spinbutton'],
-  dropdown: ['combobox', 'listbox', 'select', 'button'],
-  checkbox: ['checkbox', 'switch'],
-  text:     ['heading', 'paragraph'],
-  menuitem: ['menuitem', 'option', 'link'],
-  dialog:   ['dialog', 'alertdialog'],
-  modal:    ['dialog', 'alertdialog'],
-  tab:      ['tab', 'button', 'link'],
-  row:      ['row', 'listitem', 'option'],
-  tag:      ['button', 'link', 'option'],
-  uploader: ['textbox', 'button'],
-  textarea: ['textbox'],
-  radio:    ['radio'],
-  select:   ['combobox', 'listbox', 'select'],
-  page:     [],
-};
-
-/**
- * Get the ordered list of ARIA roles to try for a given Gherkin element type.
- * Returns empty array if the type is unknown (will fall through to text matching).
- */
-export function getRoleFallbacks(gherkinType: string): string[] {
-  const normalized = gherkinType.toLowerCase().trim();
-  return ROLE_FALLBACK_GROUPS[normalized] || [];
-}
-
-/**
- * Check if a Gherkin type should use getByText as its primary strategy
- * (types that don't map well to ARIA roles).
- */
-export function isTextOnlyType(gherkinType: string): boolean {
-  const normalized = gherkinType.toLowerCase().trim();
-  return normalized === 'text' || normalized === 'message' || normalized === 'error'
-    || normalized === 'warning' || normalized === 'success' || normalized === 'alert';
-}

package/src/core/live-scanner/scanner.ts

@@ -1,254 +0,0 @@
-/**
- * Live Scanner
- * Main orchestrator: parses features, sets up auth, replays steps, collects elements.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { glob } from 'glob';
-import { LiveScanResult, LiveScanScenario, LiveScanOptions } from './types';
-import { replaySteps } from './step-replayer';
-import { writeMatrix } from './matrix-writer';
-import { readMatrix, mergeMatrixElements } from './matrix-reader';
-import { readBaseUrlFromPlaywrightConfig } from './config-reader';
-
-export class LiveScanner {
-  private options: LiveScanOptions;
-
-  constructor(options: LiveScanOptions) {
-    this.options = options;
-  }
-
-  async scan(): Promise<LiveScanResult[]> {
-    const { screenName, screensDir } = this.options;
-    const screenDir = path.join(screensDir, screenName);
-    const featuresDir = path.join(screenDir, 'features');
-    const selectorsDir = path.join(screenDir, 'selectors');
-
-    if (!fs.existsSync(featuresDir)) {
-      throw new Error(`Features directory not found: ${featuresDir}`);
-    }
-
-    // Resolve baseUrl: explicit option > playwright.config.ts
-    const baseUrl = this.resolveBaseUrl();
-    console.log(`🌐 Base URL: ${baseUrl}`);
-
-    fs.mkdirSync(selectorsDir, { recursive: true });
-
-    const featureFiles = glob.sync('**/*.feature', {
-      cwd: featuresDir,
-      absolute: true,
-    });
-
-    if (featureFiles.length === 0) {
-      throw new Error(`No .feature files found in ${featuresDir}`);
-    }
-
-    // Lazy-load playwright to avoid errors when not installed
-    let playwright: any;
-    try {
-      playwright = require('playwright');
-    } catch {
-      throw new Error(
-        'Playwright is required for live-scan. Install it with: npm install playwright'
-      );
-    }
-
-    const browser = await playwright.chromium.launch({
-      headless: !this.options.headed,
-    });
-
-    const results: LiveScanResult[] = [];
-
-    try {
-      // Parse all features first
-      const { GherkinParser } = require('../../generators/gherkin-parser');
-      const parser = new GherkinParser();
-
-      for (const featureFile of featureFiles) {
-        const featureName = path.basename(featureFile, '.feature');
-        console.log(`\n📄 Scanning feature: ${featureName}`);
-
-        // Load existing matrix for incremental scan (non-force mode)
-        let existingResult: LiveScanResult | null = null;
-        if (!this.options.force) {
-          const matrixPath = path.join(selectorsDir, `${featureName}.live-scan.yaml`);
-          existingResult = readMatrix(matrixPath);
-          if (existingResult) {
-            console.log(`   📦 Found existing scan — resolved elements will be skipped`);
-          }
-        }
-
-        try {
-          const parsed = parser.parseFeatureFile(featureFile);
-          const result = await this.scanFeature(browser, playwright, parsed, baseUrl, existingResult);
-          results.push(result);
-
-          // Write matrix file
-          const matrixPath = path.join(selectorsDir, `${featureName}.live-scan.yaml`);
-          writeMatrix(result, matrixPath);
-          console.log(`   ✅ Matrix written: ${matrixPath}`);
-        } catch (error: any) {
-          console.error(`   ❌ Failed to scan ${featureName}: ${error.message}`);
-        }
-      }
-    } finally {
-      await browser.close();
-    }
-
-    return results;
-  }
-
-  private resolveBaseUrl(): string {
-    // 1. Explicit option (from --url flag)
-    if (this.options.baseUrl) {
-      return this.options.baseUrl;
-    }
-
-    // 2. Auto-detect from playwright.config.ts
-    const detected = readBaseUrlFromPlaywrightConfig(process.cwd());
-    if (detected) {
-      console.log(`📋 Auto-detected baseURL from playwright.config.ts`);
-      return detected;
-    }
-
-    throw new Error(
-      'Base URL not found. Either:\n' +
-      '  • Add baseURL to your playwright.config.ts\n' +
-      '  • Use --url <baseUrl> flag'
-    );
-  }
-
-  private async scanFeature(
-    browser: any,
-    playwright: any,
-    feature: any,
-    baseUrl: string,
-    existingResult?: LiveScanResult | null
-  ): Promise<LiveScanResult> {
-    const featurePath = feature.path || '/';
-    const scenarios: Record<string, LiveScanScenario> = {};
-
-    // Build merged existing elements map for skip logic
-    const existingElements = existingResult ? mergeMatrixElements(existingResult) : undefined;
-
-    // Build a map of @steps scenarios for resolution
-    const stepsMap = new Map<string, any>();
-    for (const scenario of feature.scenarios) {
-      if (scenario.stepsName) {
-        stepsMap.set(scenario.stepsName, scenario);
-      }
-    }
-
-    for (const scenario of feature.scenarios) {
-      // Skip @steps-only scenarios (they're reusable blocks, not standalone)
-      if (scenario.stepsName && !scenario.extendsName) {
-        console.log(`   ⏭️  Skipping @steps block: ${scenario.name}`);
-        continue;
-      }
-
-      const scenarioKey = slugify(scenario.name);
-      console.log(`   🎬 Scenario: ${scenario.name}`);
-
-      // Extract auth tag
-      const authTag = scenario.tags.find((t: string) => t.startsWith('@auth:'));
-      const authRole = authTag ? authTag.replace('@auth:', '') : null;
-
-      // Resolve @extend: inline base steps
-      let steps = [...scenario.steps];
-      if (scenario.extendsName) {
-        const baseScenario = stepsMap.get(scenario.extendsName);
-        if (baseScenario) {
-          steps = [...baseScenario.steps, ...steps];
-          console.log(`   🔗 Extended with @steps:${scenario.extendsName} (${baseScenario.steps.length} steps)`);
-        } else {
-          console.warn(`   ⚠️  @extend:${scenario.extendsName} not found`);
-        }
-      }
-
-      // Set up browser context with auth
-      const contextOptions: any = {};
-      if (authRole) {
-        const authPath = path.join(this.options.authDir || 'specs/.auth', `${authRole}.json`);
-        if (fs.existsSync(authPath)) {
-          contextOptions.storageState = authPath;
-          console.log(`   🔐 Auth: ${authRole}`);
-        } else {
-          console.warn(`   ⚠️  Auth file not found for role '${authRole}', scanning without authentication`);
-        }
-      }
-
-      const context = await browser.newContext(contextOptions);
-      const page = await context.newPage();
-
-      try {
-        const result = await replaySteps(page, steps, featurePath, baseUrl, existingElements);
-
-        scenarios[scenarioKey] = {
-          auth: authRole,
-          extends: scenario.extendsName || null,
-          path: featurePath,
-          elements: result.elements,
-        };
-
-        // Print element summary
-        const elementCount = Object.keys(result.elements).length;
-        const skipped = Object.values(result.elements).filter(
-          (e: any) => e.skipped
-        ).length;
-        const resolved = Object.values(result.elements).filter(
-          (e: any) => e.matchMethod !== 'unresolved'
-        ).length;
-        const warnings = Object.values(result.elements).filter(
-          (e: any) => e.warning
-        ).length;
-
-        const skippedInfo = skipped > 0 ? `, ${skipped} cached` : '';
-        console.log(`   📊 Elements: ${resolved}/${elementCount} resolved${skippedInfo}${warnings > 0 ? `, ${warnings} warnings` : ''}`);
-
-        for (const error of result.errors) {
-          console.log(`   ⚠️  ${error}`);
-        }
-
-        // Print per-element status
-        for (const [key, el] of Object.entries(result.elements) as any) {
-          if (el.skipped) {
-            // Already printed in replaySteps
-            continue;
-          }
-          if (el.matchMethod === 'unresolved') {
-            console.log(`      ✗ [${el.gherkinRef}] ${el.gherkinType} → NOT FOUND`);
-          } else if (el.warning) {
-            console.log(`      ⚠ [${el.gherkinRef}] ${el.gherkinType} → ${el.selectorType}(${el.selectorValue || el.name}) (${el.warning})`);
-          } else {
-            const locatorDesc = el.selectorType
-              ? `${el.selectorType}${el.role ? `('${el.role}', {name: '${el.name}'})` : `('${el.selectorValue || el.name}')`}`
-              : el.gherkinType;
-            console.log(`      ✓ [${el.gherkinRef}] → getBy${capitalize(el.selectorType || 'text')}${el.role ? `('${el.role}', {name: '${el.name}'})` : `('${el.selectorValue || el.name}')`}`);
-          }
-        }
-      } finally {
-        await context.close();
-      }
-    }
-
-    return {
-      screen: this.options.screenName,
-      baseUrl,
-      scannedAt: new Date().toISOString(),
-      scenarios,
-    };
-  }
-}
-
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, '')
-    .trim()
-    .replace(/\s+/g, '-');
-}
-
-function capitalize(str: string): string {
-  return str.charAt(0).toUpperCase() + str.slice(1);
-}

package/src/core/live-scanner/step-replayer.ts

@@ -1,306 +0,0 @@
-/**
- * Step Replayer
- * Replays Gherkin steps on a live Playwright page to reveal dynamic elements.
- * Takes a snapshot and finds elements after each action.
- */
-
-import type { Page } from 'playwright';
-import { findElement } from './element-finder';
-import { LiveElement, ElementContext } from './types';
-import { SelectorResolver } from '../../generators/test-generator/utils/selector-resolver';
-
-interface ParsedStepInfo {
-  keyword: string;
-  text: string;
-  selectorRef?: string;
-  dataRef?: string;
-  elementType?: string;
-  nth?: number;
-}
-
-interface ReplayResult {
-  elements: Record<string, LiveElement>;
-  errors: string[];
-}
-
-/**
- * Replay a sequence of Gherkin steps on a Playwright page,
- * finding and interacting with elements along the way.
- */
-export async function replaySteps(
-  page: Page,
-  steps: ParsedStepInfo[],
-  featurePath: string,
-  baseUrl: string,
-  existingElements?: Record<string, LiveElement>
-): Promise<ReplayResult> {
-  const elements: Record<string, LiveElement> = {};
-  const errors: string[] = [];
-  let currentContext: ElementContext = 'page';
-
-  // Pre-scan: detect which base keys have multiple normalized element types
-  // so we can append --type suffix (matching scaffold generator behavior)
-  // Uses normalizeElementType to match scaffold generator's extractTargetType mapping
-  // e.g. modal/dialog both normalize to 'dialog', so they won't create a false conflict
-  const typesPerKey = new Map<string, Set<string>>();
-  for (const step of steps) {
-    if (!step.selectorRef) continue;
-    const baseKey = generateElementKey(step.selectorRef, step.elementType, step.nth);
-    const action = detectAction(step.text);
-    const normalizedType = normalizeElementType(step.elementType || 'button', action);
-    if (!typesPerKey.has(baseKey)) {
-      typesPerKey.set(baseKey, new Set());
-    }
-    typesPerKey.get(baseKey)!.add(normalizedType);
-  }
-  const conflictKeys = new Set<string>();
-  for (const [key, types] of typesPerKey) {
-    if (types.size > 1) conflictKeys.add(key);
-  }
-
-  for (const step of steps) {
-    try {
-      const action = detectAction(step.text);
-
-      // Handle navigation (Given User is on [x] page)
-      if (action === 'navigate') {
-        await page.goto(baseUrl + featurePath, { waitUntil: 'networkidle', timeout: 15000 });
-        await settle(page);
-        if (step.selectorRef) {
-          const baseKey = generateElementKey(step.selectorRef, step.elementType, step.nth);
-          const normalizedType = normalizeElementType(step.elementType || 'page', action);
-          const key = conflictKeys.has(baseKey) ? `${baseKey}--${normalizedType}` : baseKey;
-          // Record the page element but don't search for it on the DOM
-          elements[key] = {
-            gherkinRef: step.selectorRef,
-            gherkinType: step.elementType || 'page',
-            selectorType: '',
-            selectorValue: featurePath,
-            role: '',
-            name: step.selectorRef,
-            testid: null,
-            tag: '',
-            contenteditable: false,
-            placeholder: null,
-            label: null,
-            context: 'page',
-            matchMethod: 'exact_role',
-            exact: false,
-            warning: null,
-          };
-        }
-        continue;
-      }
-
-      // Skip steps without element references
-      if (!step.selectorRef) continue;
-
-      const baseKey = generateElementKey(step.selectorRef, step.elementType, step.nth);
-      const elementType = step.elementType || 'button';
-      const normalizedType = normalizeElementType(elementType, action);
-      const key = conflictKeys.has(baseKey) ? `${baseKey}--${normalizedType}` : baseKey;
-      const nth = step.nth || 0;
-
-      // Skip column-type elements — they use header text matching, no DOM lookup needed
-      if (normalizedType === 'column') {
-        console.log(`      ⏭️  [${step.selectorRef}] column → skipped (table header match)`);
-        continue;
-      }
-
-      // Skip if element already resolved in existing scan (non-force mode)
-      if (existingElements && existingElements[key] && existingElements[key].matchMethod !== 'unresolved') {
-        elements[key] = existingElements[key];
-        (elements[key] as any).skipped = true;
-        console.log(`      ⏩ [${step.selectorRef}] ${elementType} → cached (${existingElements[key].selectorType})`);
-
-        // Still execute clicks for cached elements to maintain page state
-        if (action === 'click') {
-          try {
-            await executeClick(page, step.selectorRef, elementType, nth);
-            await settle(page);
-            currentContext = await detectCurrentContext(page, currentContext, step.text);
-          } catch {
-            // Click failed for cached element, continue anyway
-          }
-        }
-        continue;
-      }
-
-      // Find the element on the page, scoped to current context (dialog/page)
-      const element = await findElement(page, step.selectorRef, elementType, nth, currentContext);
-      element.context = currentContext;
-
-      // Record in matrix (first match wins for duplicate keys)
-      if (!elements[key]) {
-        elements[key] = element;
-      }
-
-      // Execute the action if element was found
-      if (element.matchMethod !== 'unresolved') {
-        if (action === 'click') {
-          await executeClick(page, step.selectorRef, elementType, nth);
-          await settle(page);
-          currentContext = await detectCurrentContext(page, currentContext, step.text);
-        } else if (action === 'fill') {
-          // For fill actions during scanning, use a placeholder value
-          // We just need to verify the element exists
-        }
-        // 'see' and 'wait' actions: just record, don't interact
-      } else {
-        errors.push(`Step "${step.text}": element [${step.selectorRef}] not found`);
-        // Continue scanning remaining steps — record what we can even if some elements are missing
-      }
-    } catch (error: any) {
-      errors.push(`Step "${step.text}": ${error.message}`);
-      // On navigation or critical errors, stop replaying this scenario
-      if (error.message.includes('Navigation') || error.message.includes('net::')) {
-        break;
-      }
-    }
-  }
-
-  return { elements, errors };
-}
-
-async function executeClick(
-  page: Page,
-  ref: string,
-  elementType: string,
-  nth: number
-): Promise<void> {
-  const namePattern = new RegExp(escapeRegex(ref), 'i');
-
-  // Try role-based click first
-  const { getRoleFallbacks } = require('./role-fallback');
-  const roles = getRoleFallbacks(elementType);
-
-  for (const role of roles) {
-    try {
-      const locator = page.getByRole(role as any, { name: namePattern });
-      const target = nth > 0 ? locator.nth(nth) : locator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        await target.click({ timeout: 5000 });
-        return;
-      }
-    } catch {
-      continue;
-    }
-  }
-
-  // Fallback to text click
-  try {
-    const locator = page.getByText(namePattern);
-    const target = nth > 0 ? locator.nth(nth) : locator.first();
-    await target.click({ timeout: 5000 });
-  } catch {
-    // Try testid as last resort
-    const normalized = ref.toLowerCase().replace(/[\s_-]+/g, '-');
-    await page.locator(`[data-testid*="${normalized}" i]`).first().click({ timeout: 5000 });
-  }
-}
-
-function detectAction(text: string): string {
-  const lower = text.toLowerCase();
-  if (/\b(is on|navigate|go to|visit|open)\b/.test(lower) && /\bpage\b/.test(lower)) return 'navigate';
-  if (/\b(click|press|tap|submit)\b/.test(lower)) return 'click';
-  if (/\b(fill|enter|type|input)\b/.test(lower)) return 'fill';
-  if (/\b(see|verify|check|expect|visible|displayed)\b/.test(lower)) return 'see';
-  if (/\b(select|choose|pick)\b/.test(lower)) return 'select';
-  if (/\b(wait)\b/.test(lower)) return 'wait';
-  return 'see';
-}
-
-async function detectCurrentContext(
-  page: Page,
-  previous: ElementContext,
-  stepText: string
-): Promise<ElementContext> {
-  const lower = stepText.toLowerCase();
-
-  // Check if we opened a dialog/modal
-  if (/\b(dialog|modal|panel)\b/.test(lower)) {
-    return 'dialog';
-  }
-
-  // Check if a dialog is now visible on the page
-  try {
-    const dialogLocator = page.getByRole('dialog');
-    if (await dialogLocator.count() > 0) {
-      return 'dialog';
-    }
-  } catch {
-    // ignore
-  }
-
-  // Check for menu
-  if (/\b(menu|dropdown)\b/.test(lower)) {
-    return 'menu';
-  }
-
-  try {
-    const menuLocator = page.getByRole('menu');
-    if (await menuLocator.count() > 0) {
-      return 'menu';
-    }
-  } catch {
-    // ignore
-  }
-
-  return previous;
-}
-
-async function settle(page: Page): Promise<void> {
-  try {
-    await page.waitForLoadState('networkidle', { timeout: 5000 });
-  } catch {
-    // Timeout is acceptable — page may have long-polling connections
-  }
-  // Small extra wait for animations/transitions
-  await page.waitForTimeout(300);
-}
-
-function generateElementKey(ref: string, elementType?: string, nth?: number): string {
-  // Use the same key generation as the scaffold generator
-  // so live-scan keys match scaffold keys in the map command.
-  // Append --N suffix for nth > 0, consistent with scaffold generator format.
-  const baseKey = SelectorResolver.generateKey(ref);
-  return nth && nth > 0 ? `${baseKey}--${nth}` : baseKey;
-}
-
-/**
- * Normalize element type to match scaffold generator's extractTargetType() mapping.
- * e.g. modal→dialog, img/icon/logo→img, input→field, select→dropdown, etc.
- */
-function normalizeElementType(elementType: string, action: string): string {
-  const t = elementType.toLowerCase();
-  if (t === 'page') return 'page';
-  if (t === 'link') return 'link';
-  if (t === 'button') return 'button';
-  if (t === 'radio') return 'radio';
-  if (t === 'dropdown' || t === 'select') return 'dropdown';
-  if (t === 'checkbox') return 'checkbox';
-  if (t === 'field' || t === 'input') return 'field';
-  if (t === 'textbox') return 'textbox';
-  if (t === 'textarea') return 'textarea';
-  if (t === 'text') return 'text';
-  if (t === 'label') return 'label';
-  if (t === 'uploader') return 'uploader';
-  if (t === 'element') return 'element';
-  if (t === 'column' || t === 'columnheader') return 'column';
-  if (t === 'logo' || t === 'image' || t === 'img' || t === 'icon') return 'img';
-  if (t === 'dialog' || t === 'modal') return 'dialog';
-  if (t === 'heading' || t === 'header') return 'heading';
-  if (t === 'title' || t === 'caption' || t === 'message') return 'text';
-  // Default based on action (matches scaffold generator)
-  switch (action) {
-    case 'click': return 'text';
-    case 'fill': return 'field';
-    case 'see': return 'text';
-    case 'select': return 'dropdown';
-    default: return 'element';
-  }
-}
-
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/src/core/live-scanner/types.ts

@@ -1,58 +0,0 @@
-/**
- * Live Scanner Types
- * Defines the data structures for live DOM scanning and matrix file output.
- *
- * Selector types map directly to Playwright locator strategies:
- *   testid      → page.getByTestId(value)
- *   role        → page.getByRole(value, { name })
- *   label       → page.getByLabel(value)
- *   placeholder → page.getByPlaceholder(value)
- *   text        → page.getByText(value)
- */
-
-export type MatchMethod = 'testid' | 'exact_role' | 'role_fallback' | 'label' | 'placeholder' | 'text_only' | 'contenteditable' | 'unresolved';
-
-export type SelectorType = 'testid' | 'role' | 'label' | 'placeholder' | 'text' | 'locator';
-
-export type ElementContext = 'page' | 'dialog' | 'menu' | 'modal' | 'popup';
-
-export interface LiveElement {
-  gherkinRef: string;
-  gherkinType: string;
-  selectorType: SelectorType | '';
-  selectorValue: string;
-  role: string;
-  name: string;
-  testid: string | null;
-  tag: string;
-  contenteditable: boolean;
-  placeholder: string | null;
-  label: string | null;
-  context: ElementContext;
-  matchMethod: MatchMethod;
-  exact: boolean;
-  warning: string | null;
-}
-
-export interface LiveScanScenario {
-  auth: string | null;
-  extends: string | null;
-  path: string;
-  elements: Record<string, LiveElement>;
-}
-
-export interface LiveScanResult {
-  screen: string;
-  baseUrl: string;
-  scannedAt: string;
-  scenarios: Record<string, LiveScanScenario>;
-}
-
-export interface LiveScanOptions {
-  baseUrl?: string;
-  screenName: string;
-  screensDir: string;
-  headed?: boolean;
-  authDir?: string;
-  force?: boolean;
-}