@sun-asterisk/sungen 1.0.24 → 2.0.1

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

@@ -1,534 +0,0 @@
-/**
- * Element Finder
- *
- * Searches for elements using Playwright's own locator strategies in priority order:
- *   ① getByTestId    — data-testid attribute
- *   ② getByRole      — ARIA role + accessible name (exact match, then fallback roles)
- *   ③ getByLabel     — associated <label> text
- *   ④ getByPlaceholder — placeholder attribute
- *   ⑤ getByText      — visible text content
- *
- * The result records WHICH Playwright strategy found the element,
- * so `map` can generate the correct locator code.
- */
-
-import type { Page, Locator } from 'playwright';
-import { getRoleFallbacks, isTextOnlyType } from './role-fallback';
-import { LiveElement, MatchMethod, SelectorType, ElementContext } from './types';
-
-interface FindResult {
-  locator: Locator;
-  selectorType: SelectorType;
-  selectorValue: string;
-  role: string;
-  matchMethod: MatchMethod;
-  warning: string | null;
-}
-
-/**
- * Find an element on the page using cascading Playwright locator strategies.
- */
-export async function findElement(
-  page: Page,
-  gherkinRef: string,
-  gherkinType: string,
-  nth: number = 0,
-  context: ElementContext = 'page'
-): Promise<LiveElement> {
-  const namePattern = new RegExp(escapeRegex(gherkinRef), 'i');
-
-  const result = await cascadingSearch(page, gherkinRef, gherkinType, namePattern, nth, context);
-
-  if (!result) {
-    return buildUnresolvedElement(gherkinRef, gherkinType);
-  }
-
-  const attrs = await extractElementAttributes(result.locator);
-
-  // Use Playwright's computed accessible name (includes alt text, aria-label, etc.)
-  // This matches what getByRole/getByText actually see, unlike textContent
-  let playwrightName = '';
-  try {
-    playwrightName = await result.locator.evaluate((el) => {
-      // computedRole/computedLabel not available in all browsers, fallback to aria
-      const raw = (el as any).computedName
-        || el.getAttribute('aria-label')
-        || el.textContent?.trim()?.substring(0, 100)
-        || '';
-      return raw.replace(/[\n\r\t]/g, ' ').replace(/\s+/g, ' ').trim();
-    });
-    // Better approach: use Playwright's accessibility snapshot
-    const ariaSnapshot = await result.locator.ariaSnapshot();
-    // Parse accessible name from snapshot (format: "- role \"name\"" or "- role \"name\": ...")
-    // Regex handles escaped quotes (\") inside the name string
-    const nameMatch = ariaSnapshot?.match(/"((?:[^"\\]|\\.)*)"/);
-    if (nameMatch) {
-      playwrightName = unescapeAriaSnapshot(nameMatch[1]);
-    }
-  } catch {
-    playwrightName = attrs.accessibleName || gherkinRef;
-  }
-
-  const actualName = playwrightName || attrs.accessibleName || gherkinRef;
-  const isExactMatch = actualName.toLowerCase().trim() === gherkinRef.toLowerCase().trim();
-
-  return {
-    gherkinRef,
-    gherkinType,
-    selectorType: result.selectorType,
-    selectorValue: result.selectorValue,
-    role: result.role,
-    name: actualName,
-    testid: attrs.testid,
-    tag: attrs.tag,
-    contenteditable: attrs.contenteditable,
-    placeholder: attrs.placeholder,
-    label: attrs.label,
-    context: 'page',
-    matchMethod: result.matchMethod,
-    exact: isExactMatch,
-    warning: result.warning,
-  };
-}
-
-async function cascadingSearch(
-  page: Page,
-  gherkinRef: string,
-  gherkinType: string,
-  namePattern: RegExp,
-  nth: number,
-  context: ElementContext = 'page'
-): Promise<FindResult | null> {
-  // ① getByTestId
-  const testidResult = await tryTestId(page, gherkinRef, nth);
-  if (testidResult) return testidResult;
-
-  // For text-only types (text, message, error), skip role and go to text
-  if (!isTextOnlyType(gherkinType)) {
-    // ② getByRole — exact role match
-    const roles = getRoleFallbacks(gherkinType);
-    if (roles.length > 0) {
-      const exactResult = await tryRole(page, roles[0], gherkinRef, namePattern, nth);
-      if (exactResult) {
-        return {
-          ...exactResult,
-          matchMethod: 'exact_role',
-          warning: null,
-        };
-      }
-
-      // ③ getByRole — fallback roles
-      for (let i = 1; i < roles.length; i++) {
-        const fallbackResult = await tryRole(page, roles[i], gherkinRef, namePattern, nth);
-        if (fallbackResult) {
-          return {
-            ...fallbackResult,
-            matchMethod: 'role_fallback',
-            warning: `Gherkin says '${gherkinType}' but found role '${roles[i]}'`,
-          };
-        }
-      }
-    }
-
-    // ④ getByLabel — for form elements
-    const labelResult = await tryLabel(page, gherkinRef, namePattern, nth);
-    if (labelResult) return labelResult;
-
-    // ⑤ getByPlaceholder — for input fields
-    const placeholderResult = await tryPlaceholder(page, gherkinRef, namePattern, nth);
-    if (placeholderResult) return placeholderResult;
-
-    // ⑤.5 contenteditable — for rich text editors (textarea/textbox/field types)
-    // When role match fails (editor has role="textbox" but no accessible name),
-    // try to find a [contenteditable="true"] element scoped to the current context
-    if (isEditableType(gherkinType)) {
-      const ceResult = await tryContentEditable(page, nth, context);
-      if (ceResult) return ceResult;
-    }
-  }
-
-  // ⑥ getByText — final fallback
-  const textResult = await tryText(page, gherkinRef, namePattern, nth);
-  if (textResult) return textResult;
-
-  return null;
-}
-
-// ① getByTestId
-async function tryTestId(page: Page, ref: string, nth: number): Promise<FindResult | null> {
-  const normalized = ref.toLowerCase().replace(/[\s_-]+/g, '-');
-  const patterns = [normalized, ref.toLowerCase().replace(/\s+/g, '')];
-
-  for (const pattern of patterns) {
-    try {
-      const locator = page.locator(`[data-testid*="${pattern}" i]`);
-      const count = await locator.count();
-      if (count > 0) {
-        const target = nth > 0 ? locator.nth(nth) : locator.first();
-        if (await target.isVisible({ timeout: 3000 })) {
-          const testid = await target.getAttribute('data-testid');
-          return {
-            locator: target,
-            selectorType: 'testid',
-            selectorValue: testid || pattern,
-            role: '',
-            matchMethod: 'testid',
-            warning: null,
-          };
-        }
-      }
-    } catch {
-      // Continue
-    }
-  }
-  return null;
-}
-
-// ② ③ getByRole — regex first, exact disambiguation when ambiguous
-async function tryRole(
-  page: Page,
-  role: string,
-  gherkinRef: string,
-  namePattern: RegExp,
-  nth: number
-): Promise<FindResult | null> {
-  try {
-    const locator = page.getByRole(role as any, { name: namePattern });
-    const count = await locator.count();
-    if (count === 0) return null;
-
-    if (count === 1) {
-      const target = nth > 0 ? locator.nth(nth) : locator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        return {
-          locator: target,
-          selectorType: 'role',
-          selectorValue: role,
-          role: role,
-          matchMethod: 'exact_role',
-          warning: null,
-        };
-      }
-    } else {
-      // Multiple matches — try exact to disambiguate
-      try {
-        const exactLocator = page.getByRole(role as any, { name: gherkinRef, exact: true });
-        const exactCount = await exactLocator.count();
-        if (exactCount > 0) {
-          const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
-          if (await target.isVisible({ timeout: 3000 })) {
-            return {
-              locator: target,
-              selectorType: 'role',
-              selectorValue: role,
-              role: role,
-              matchMethod: 'exact_role',
-              warning: null,
-            };
-          }
-        }
-      } catch {
-        // Exact disambiguation failed
-      }
-
-      // Fall back to first regex match
-      const target = nth > 0 ? locator.nth(nth) : locator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        return {
-          locator: target,
-          selectorType: 'role',
-          selectorValue: role,
-          role: role,
-          matchMethod: 'exact_role',
-          warning: null,
-        };
-      }
-    }
-  } catch {
-    // Role not found
-  }
-  return null;
-}
-
-// ④ getByLabel — regex first, exact disambiguation when ambiguous
-async function tryLabel(page: Page, gherkinRef: string, namePattern: RegExp, nth: number): Promise<FindResult | null> {
-  try {
-    const locator = page.getByLabel(namePattern);
-    const count = await locator.count();
-    if (count === 0) return null;
-
-    if (count > 1) {
-      // Multiple matches — try exact to disambiguate
-      try {
-        const exactLocator = page.getByLabel(gherkinRef, { exact: true });
-        const exactCount = await exactLocator.count();
-        if (exactCount > 0) {
-          const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
-          if (await target.isVisible({ timeout: 3000 })) {
-            return {
-              locator: target,
-              selectorType: 'label',
-              selectorValue: '',
-              role: '',
-              matchMethod: 'label',
-              warning: null,
-            };
-          }
-        }
-      } catch {
-        // Exact disambiguation failed
-      }
-    }
-
-    // Single match or exact failed — use first regex match
-    const target = nth > 0 ? locator.nth(nth) : locator.first();
-    if (await target.isVisible({ timeout: 3000 })) {
-      return {
-        locator: target,
-        selectorType: 'label',
-        selectorValue: '',
-        role: '',
-        matchMethod: 'label',
-        warning: null,
-      };
-    }
-  } catch {
-    // Label not found
-  }
-  return null;
-}
-
-// ⑤ getByPlaceholder — regex first, exact disambiguation when ambiguous
-async function tryPlaceholder(page: Page, gherkinRef: string, namePattern: RegExp, nth: number): Promise<FindResult | null> {
-  try {
-    const locator = page.getByPlaceholder(namePattern);
-    const count = await locator.count();
-    if (count === 0) return null;
-
-    if (count > 1) {
-      // Multiple matches — try exact to disambiguate
-      try {
-        const exactLocator = page.getByPlaceholder(gherkinRef, { exact: true });
-        const exactCount = await exactLocator.count();
-        if (exactCount > 0) {
-          const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
-          if (await target.isVisible({ timeout: 3000 })) {
-            const rawPlaceholder = await target.getAttribute('placeholder');
-            return {
-              locator: target,
-              selectorType: 'placeholder',
-              selectorValue: sanitizeText(rawPlaceholder || ''),
-              role: '',
-              matchMethod: 'placeholder',
-              warning: null,
-            };
-          }
-        }
-      } catch {
-        // Exact disambiguation failed
-      }
-    }
-
-    // Single match or exact failed — use first regex match
-    const target = nth > 0 ? locator.nth(nth) : locator.first();
-    if (await target.isVisible({ timeout: 3000 })) {
-      const rawPlaceholder = await target.getAttribute('placeholder');
-      return {
-        locator: target,
-        selectorType: 'placeholder',
-        selectorValue: sanitizeText(rawPlaceholder || ''),
-        role: '',
-        matchMethod: 'placeholder',
-        warning: null,
-      };
-    }
-  } catch {
-    // Placeholder not found
-  }
-  return null;
-}
-
-/**
- * Check if gherkinType is an editable/input type that could be a contenteditable div
- */
-function isEditableType(gherkinType: string): boolean {
-  const normalized = gherkinType.toLowerCase().trim();
-  return normalized === 'textarea' || normalized === 'textbox' || normalized === 'field' || normalized === 'editor';
-}
-
-
-
-// ⑤.5 contenteditable — for rich text editors
-// Scoped to current context (dialog/page) to avoid matching wrong editor.
-// The nth from Gherkin refers to text matches, not contenteditable count,
-// so we try the requested nth first, then fall back to first match.
-async function tryContentEditable(page: Page, nth: number, context: ElementContext): Promise<FindResult | null> {
-  try {
-    // Scope the search to the current context
-    const root = context === 'dialog' ? page.getByRole('dialog') : page;
-    const locator = root.locator('[contenteditable="true"]');
-    const count = await locator.count();
-    if (count === 0) return null;
-
-    // Try requested nth first, then fall back to first visible
-    const candidates = nth > 0 && count > nth ? [nth, 0] : [0];
-    for (const idx of candidates) {
-      const target = idx > 0 ? locator.nth(idx) : locator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        return {
-          locator: target,
-          selectorType: 'locator',
-          selectorValue: '[contenteditable="true"]',
-          role: 'textbox',
-          matchMethod: 'contenteditable',
-          warning: count > 1
-            ? `${count} contenteditable elements in ${context}, using index ${idx}. Use nth in Gherkin to disambiguate.`
-            : null,
-        };
-      }
-    }
-  } catch {
-    // Not found
-  }
-  return null;
-}
-
-// ⑥ getByText — regex first, exact disambiguation when ambiguous
-async function tryText(page: Page, gherkinRef: string, namePattern: RegExp, nth: number): Promise<FindResult | null> {
-  try {
-    const locator = page.getByText(namePattern);
-    const count = await locator.count();
-    if (count === 0) return null;
-
-    if (count > 1) {
-      // Multiple matches — try exact to disambiguate
-      try {
-        const exactLocator = page.getByText(gherkinRef, { exact: true });
-        const exactCount = await exactLocator.count();
-        if (exactCount > 0) {
-          const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
-          if (await target.isVisible({ timeout: 3000 })) {
-            return {
-              locator: target,
-              selectorType: 'text',
-              selectorValue: '',
-              role: '',
-              matchMethod: 'text_only',
-              warning: null,
-            };
-          }
-        }
-      } catch {
-        // Exact disambiguation failed
-      }
-    }
-
-    // Single match or exact failed — use first regex match
-    const target = nth > 0 ? locator.nth(nth) : locator.first();
-    if (await target.isVisible({ timeout: 3000 })) {
-      return {
-        locator: target,
-        selectorType: 'text',
-        selectorValue: '',
-        role: '',
-        matchMethod: 'text_only',
-        warning: null,
-      };
-    }
-  } catch {
-    // Text not found
-  }
-  return null;
-}
-
-async function extractElementAttributes(locator: Locator): Promise<{
-  testid: string | null;
-  tag: string;
-  contenteditable: boolean;
-  accessibleName: string;
-  placeholder: string | null;
-  label: string | null;
-}> {
-  try {
-    return await locator.evaluate((el) => {
-      // Inline sanitizer — browser context can't access Node functions
-      const clean = (s: string | null | undefined): string =>
-        (s || '').replace(/[\n\r\t]/g, ' ').replace(/\s+/g, ' ').trim();
-
-      // Find associated label
-      let label: string | null = null;
-      if (el.id) {
-        const labelEl = el.ownerDocument.querySelector(`label[for="${el.id}"]`);
-        if (labelEl) label = clean(labelEl.textContent) || null;
-      }
-      if (!label && el.closest('label')) {
-        label = clean(el.closest('label')?.textContent) || null;
-      }
-
-      // Detect contenteditable: check element itself and ancestors (rich text editors
-      // often have contenteditable on a parent div wrapping the editable area)
-      const isContentEditable = el.getAttribute('contenteditable') === 'true'
-        || el.isContentEditable;
-
-      return {
-        testid: el.getAttribute('data-testid'),
-        tag: el.tagName.toLowerCase(),
-        contenteditable: isContentEditable,
-        accessibleName: clean(el.getAttribute('aria-label') || el.textContent?.trim()?.substring(0, 100)),
-        placeholder: clean(el.getAttribute('placeholder')) || null,
-        label,
-      };
-    });
-  } catch {
-    return { testid: null, tag: 'unknown', contenteditable: false, accessibleName: '', placeholder: null, label: null };
-  }
-}
-
-function buildUnresolvedElement(gherkinRef: string, gherkinType: string): LiveElement {
-  return {
-    gherkinRef,
-    gherkinType,
-    selectorType: '',
-    selectorValue: '',
-    role: '',
-    name: gherkinRef,
-    testid: null,
-    tag: '',
-    contenteditable: false,
-    placeholder: null,
-    label: null,
-    context: 'page',
-    matchMethod: 'unresolved',
-    exact: false,
-    warning: 'Element not found on page',
-  };
-}
-
-/**
- * Normalize a DOM text value for YAML output:
- * collapse real newlines/tabs/carriage-returns into spaces, then deduplicate whitespace.
- * Runs in both browser evaluate() and Node context.
- */
-function sanitizeText(str: string): string {
-  return str.replace(/[\n\r\t]/g, ' ').replace(/\s+/g, ' ').trim();
-}
-
-/**
- * Unescape a string extracted from Playwright's ariaSnapshot() output.
- * ariaSnapshot encodes special chars as literal escape sequences:
- *   \n → newline, \t → tab, \\ → backslash, \" → quote
- * We unescape them then normalize whitespace.
- */
-function unescapeAriaSnapshot(str: string): string {
-  return str
-    .replace(/\\n/g, ' ')
-    .replace(/\\t/g, ' ')
-    .replace(/\\"/g, '"')
-    .replace(/\\\\/g, '\\')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

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

@@ -1,7 +0,0 @@
-export { LiveScanner } from './scanner';
-export { findElement } from './element-finder';
-export { getRoleFallbacks, isTextOnlyType } from './role-fallback';
-export { writeMatrix } from './matrix-writer';
-export { readMatrix, mergeMatrixElements } from './matrix-reader';
-export { readBaseUrlFromPlaywrightConfig } from './config-reader';
-export * from './types';

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

@@ -1,65 +0,0 @@
-/**
- * Matrix Reader
- * Loads and parses a .live-scan.yaml file for consumption by the map command.
- * Merges elements across scenarios (first match wins).
- */
-
-import { readYamlIfExists } from '../../utils/yaml-io';
-import { LiveElement, LiveScanResult } from './types';
-
-/**
- * Read a .live-scan.yaml file and return the parsed result.
- * Returns null if file doesn't exist.
- */
-export function readMatrix(filePath: string): LiveScanResult | null {
-  const parsed = readYamlIfExists<any>(filePath);
-
-  if (!parsed || !parsed.scenarios) {
-    return null;
-  }
-
-  return parsed as LiveScanResult;
-}
-
-/**
- * Merge all elements across scenarios into a flat map.
- * First successful (non-unresolved) match wins for duplicate keys.
- */
-export function mergeMatrixElements(result: LiveScanResult): Record<string, LiveElement> {
-  const merged: Record<string, LiveElement> = {};
-
-  for (const scenario of Object.values(result.scenarios)) {
-    const elements = (scenario as any).elements;
-    if (!elements) continue;
-
-    for (const [key, raw] of Object.entries(elements)) {
-      const el = raw as any;
-
-      // Convert from YAML snake_case to interface camelCase
-      const element: LiveElement = {
-        gherkinRef: el.name || key,
-        gherkinType: el.gherkin_type || '',
-        selectorType: el.selector_type || '',
-        selectorValue: el.selector_value || '',
-        role: el.role || '',
-        name: el.name || '',
-        testid: el.testid || null,
-        tag: el.tag || '',
-        contenteditable: el.contenteditable === true,
-        placeholder: el.placeholder || null,
-        label: el.label || null,
-        context: (el.context as any) || 'page',
-        matchMethod: (el.match_method as any) || 'unresolved',
-        exact: el.exact === true,
-        warning: el.warning || null,
-      };
-
-      // First non-unresolved match wins
-      if (!merged[key] || (merged[key].matchMethod === 'unresolved' && element.matchMethod !== 'unresolved')) {
-        merged[key] = element;
-      }
-    }
-  }
-
-  return merged;
-}

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

@@ -1,77 +0,0 @@
-/**
- * Matrix Writer
- * Writes LiveScanResult to a .live-scan.yaml file.
- */
-
-import * as fs from 'fs';
-import * as yaml from 'yaml';
-import { LiveScanResult } from './types';
-
-/**
- * Sanitize a string value before YAML serialization:
- * collapse newlines/tabs/carriage-returns into spaces to prevent
- * broken escape sequences (e.g. \\n) in QUOTE_DOUBLE output.
- */
-function sanitizeForYaml(value: string | null): string | null {
-  if (!value) return value;
-  return value.replace(/[\n\r\t]/g, ' ').replace(/\s+/g, ' ').trim() || null;
-}
-
-export function writeMatrix(result: LiveScanResult, outputPath: string): void {
-  const output: any = {
-    screen: result.screen,
-    baseUrl: result.baseUrl,
-    scannedAt: result.scannedAt,
-    scenarios: {},
-  };
-
-  for (const [scenarioKey, scenario] of Object.entries(result.scenarios)) {
-    const scenarioData: any = {
-      auth: scenario.auth,
-      path: scenario.path,
-    };
-
-    if (scenario.extends) {
-      scenarioData.extends = scenario.extends;
-    }
-
-    scenarioData.elements = {};
-
-    for (const [elementKey, element] of Object.entries(scenario.elements)) {
-      scenarioData.elements[elementKey] = {
-        gherkin_type: element.gherkinType,
-        selector_type: element.selectorType,
-        selector_value: sanitizeForYaml(element.selectorValue),
-        role: element.role,
-        name: sanitizeForYaml(element.name),
-        testid: element.testid,
-        tag: element.tag,
-        contenteditable: element.contenteditable,
-        placeholder: sanitizeForYaml(element.placeholder),
-        label: sanitizeForYaml(element.label),
-        context: element.context,
-        match_method: element.matchMethod,
-        exact: element.exact,
-        warning: element.warning,
-      };
-    }
-
-    output.scenarios[scenarioKey] = scenarioData;
-  }
-
-  const header = [
-    `# Auto-generated by sungen live-scan`,
-    `# Screen: ${result.screen} | Base URL: ${result.baseUrl}`,
-    `# Scanned: ${result.scannedAt}`,
-    `# Do not edit manually — re-run 'sungen live-scan' to regenerate`,
-    '',
-  ].join('\n');
-
-  const yamlStr = yaml.stringify(output, {
-    lineWidth: 120,
-    defaultStringType: 'QUOTE_DOUBLE',
-    nullStr: 'null',
-  });
-
-  fs.writeFileSync(outputPath, header + yamlStr, 'utf-8');
-}