@sun-asterisk/sungen 3.2.28 → 3.2.30

package/src/generators/test-generator/utils/dialog-scope-identity.ts

@@ -0,0 +1,71 @@
+/**
+ * Identity of a locator as the `locator` partial actually renders it — issue #692.
+ *
+ * `Given User is on [X] dialog` records a scope root, and the `pageRoot` helper prefixes every
+ * locator rendered afterwards with it. That is the whole point of the scope — except when a later
+ * step names the SAME element as the scope root, where the prefix nests the dialog inside itself:
+ *
+ *     page.getByRole('dialog', { name: 'Confirm' }).getByRole('dialog', { name: 'Confirm' })
+ *
+ * A dialog cannot contain itself, so that query can never resolve. It compiles clean, emits no
+ * diagnostic, and fails as a plain timeout — which reads as "the dialog never opened" rather than
+ * "the query is impossible". Re-asserting the dialog you are scoped inside is the natural thing to
+ * write straight after the `Given`, so the scope root is made idempotent instead.
+ *
+ * The guard needs exactly one question answered: does this element render to the same locator as
+ * the active scope root? So the key carries the fields the partial reads FOR THAT STRATEGY and
+ * nothing else — two entries share a key iff they render the same expression. Comparing role+name
+ * alone (the shape the issue first suggested) would miss `type: locator` and `type: testid`
+ * dialogs, which self-nest just the same.
+ *
+ * Deliberately says nothing about a `with {{v}}` filtered root: that root is
+ * `getByRole('dialog').filter({ hasText })`, which is not expressible as the element's own
+ * locator, so an identity match there would be meaningless. The caller skips the guard in that
+ * case — see the `dialogFilterText` check in `pageRoot`.
+ */
+
+/** The subset of a resolved selector that the `locator` partial reads. */
+export interface LocatorIdentityFields {
+  strategy?: string;
+  value?: string;
+  role?: string;
+  name?: string;
+  exact?: boolean;
+  nth?: number;
+  scope?: string;
+}
+
+/**
+ * A stable key for the locator `fields` renders to, or undefined when there is no strategy to
+ * render (nothing to compare, so no guard).
+ */
+export function locatorIdentityKey(fields: LocatorIdentityFields | undefined): string | undefined {
+  if (!fields || !fields.strategy) return undefined;
+
+  // `scope: dialog` is the dialog-rooting sentinel rather than part of the element's own
+  // identity — renderDialogRoot strips it before rendering the root for the same reason.
+  const scope = fields.scope && fields.scope !== 'dialog' ? fields.scope : '';
+  const nth = typeof fields.nth === 'number' && fields.nth >= 0 ? String(fields.nth) : '';
+  const exact = fields.exact ? '1' : '';
+
+  const parts: string[] = [];
+  switch (fields.strategy) {
+    case 'role':
+      // getByRole reads role/name/exact — never `value`.
+      parts.push('role', fields.role || '', fields.name || '', exact);
+      break;
+    case 'testid':
+      parts.push('testid', fields.value || '');
+      break;
+    case 'placeholder':
+    case 'label':
+    case 'text':
+      parts.push(fields.strategy, fields.value || '', exact);
+      break;
+    default:
+      // 'locator', 'id', 'css' and the partial's own default all render locator('<value>').
+      parts.push('locator', fields.value || '');
+  }
+
+  return [...parts, `nth=${nth}`, `scope=${scope}`].join('|');
+}

package/src/generators/test-generator/utils/escape-js-string.ts

@@ -0,0 +1,24 @@
+/**
+ * Escape a raw string for embedding inside a SINGLE-QUOTED JS string literal.
+ *
+ * Order matters: backslash first, or the escapes added afterwards get re-escaped. Getting this
+ * half-right is worse than not doing it — a value ending in `\` turns `'…\'` into an escaped
+ * closing quote, and the string literal runs on into the rest of the file, so the generated
+ * `.spec.ts` stops parsing and EVERY scenario in it is lost rather than the one step.
+ *
+ * The line terminators are not cosmetic either: a card's accessible text is routinely a composite
+ * of several lines (a Flutter content-desc, a multi-line heading), and a literal newline inside
+ * `'…'` is a syntax error.
+ *
+ * Lives here rather than inside the Handlebars helper because the pattern layer also builds locator
+ * strings by hand — the parent-scope chain among them — and two copies of this rule drift.
+ */
+export function escapeSingleQuoted(text: unknown): string {
+  if (text == null) return '';
+  return String(text)
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+}

package/src/generators/test-generator/utils/nearest-match.ts

@@ -0,0 +1,55 @@
+/**
+ * Nearest-known-spelling suggestion, shared by the selector-surface checks.
+ *
+ * Two checks need the same judgement about the same class of author mistake — SG-W004 on an entry
+ * FIELD nobody reads (#712) and SG-E027 on an entry `type:` VALUE nothing dispatches (#711) — so
+ * the rule lives in one place rather than being re-tuned independently in each. The tuning is the
+ * substance here, not the edit distance:
+ *
+ *   - A case-only difference is returned first and always. `testId` for `testid` and
+ *     `contentEditable` for `contenteditable` are the single likeliest way to write either
+ *     wrongly, and both surfaces are lowercase throughout, so this is a near-certainty rather
+ *     than a guess.
+ *   - Otherwise a distance of 1-2 is a typo worth naming.
+ *   - Anything further is a DIFFERENT word, and guessing at it sends the author somewhere wrong.
+ *     `selector` is not a misspelling of `locator` — it is someone reasonably assuming a field
+ *     that does not exist, and "did you mean locator?" would be a worse answer than silence.
+ *     The caller supplies its own hint for that case.
+ */
+
+/** Levenshtein distance. Bounded use only — these are short identifiers. */
+function distance(a: string, b: string): number {
+  const m = a.length, n = b.length;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const curr = [i];
+    for (let j = 1; j <= n; j++) {
+      curr[j] = Math.min(
+        prev[j] + 1,
+        curr[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = curr;
+  }
+  return prev[n];
+}
+
+/**
+ * The nearest candidate to `value`, when one is close enough to be a likely typo rather than a
+ * different word. Returns undefined when nothing is close enough to name honestly.
+ */
+export function nearestMatch(
+  value: string, candidates: Iterable<string>, maxDistance = 2,
+): string | undefined {
+  const lower = value.toLowerCase();
+  const all = [...candidates];
+  for (const c of all) if (c.toLowerCase() === lower) return c;
+  let best: string | undefined;
+  let bestDist = Infinity;
+  for (const c of all) {
+    const d = distance(lower, c.toLowerCase());
+    if (d < bestDist) { bestDist = d; best = c; }
+  }
+  return bestDist <= maxDistance ? best : undefined;
+}

package/src/generators/test-generator/utils/selector-entry-fields.ts

@@ -0,0 +1,131 @@
+/**
+ * The selector-entry field partition, and the SG-W004 check built on it (issue #712).
+ *
+ * The root cause behind #690, #711 and #712 is one shape: `selectors.yaml` has a DOCUMENTED
+ * surface wider than the compiler's IMPLEMENTED surface, and nothing compared the two. A field
+ * could be declared on `SelectorEntry`, assigned onto `ResolvedSelector`, and printed in the
+ * public reference while no consumer ever read it back — discovered only by grepping.
+ *
+ * This module states the contract as a partition, the same way #690 answered the equivalent
+ * question for `type:` values (STRATEGY_SELECTOR_TYPES vs NON_STRATEGY_SELECTOR_TYPES). Every
+ * field an author may write belongs to exactly one set, each entry naming who reads it — so the
+ * next unconsumed field is a failing check with a name attached, not an archaeology exercise.
+ *
+ * The check is deliberately a WARNING, not an error. An unknown key is inert (the compiler simply
+ * never reads it), so refusing to compile would break projects over a stray comment-turned-key
+ * while teaching nothing extra. `--strict` already turns the whole channel non-zero for CI.
+ */
+
+import type { DiagnosticsCollector } from '../diagnostics';
+import { nearestMatch } from './nearest-match';
+import { walkSelectorEntries } from './selector-entry-walk';
+
+/**
+ * Fields a consumer actually reads. The comment on each names WHO — that is the part that rots,
+ * so it is recorded next to the claim rather than in prose elsewhere. Adding a field here without
+ * a named consumer re-opens exactly the hole #712 was filed for.
+ */
+export const CONSUMED_ENTRY_FIELDS: ReadonlySet<string> = new Set([
+  'locator',          // resolveFromEntry → strategy 'css'/'locator'
+  'type',             // the strategy switch; also ResolvedSelector.selectorType (#690)
+  'value',            // every strategy template
+  'name',             // role templates; `name: null` disables the filter
+  'nth',              // locator-nth partial
+  'exact',            // has-text-value partial / anchored-regex assertions
+  'inputMethod',      // driver-ui fill pattern → fill-editor-action
+  'scope',            // dialog/landmark scoping in the locator partial
+  'match',            // collapses into `exact` for getByText
+  'anchor',           // page assertions — the rendered-content proof (#662)
+  'android',          // appium adapter → androidSelector (#392)
+  'ios',              // appium adapter → iosSelector (#392)
+  'variant',          // widget recipes / native select / upload subtype
+  'trigger',          // upload step — the visible button over a hidden input
+  'frame',            // frame-enter/exit steps → page.frameLocator
+  'contenteditable',  // resolveFromEntry → inputMethod 'pressSequentially' (#712)
+  'columns',          // table column-index lookup in StepMapper
+  'pagination',       // driver-ui table-paginate pattern (#712)
+  'rows',             // table row templates, the row-shape universe (#688, SG-W016)
+  'attribute',        // "has attribute" assertions → toHaveAttribute
+  'pattern',          // regex for the attribute value
+  'expanded',         // expand/collapse state signal
+  // Two spellings of ONE signal — how a control that publishes no ARIA marks its ON state, as a
+  // class or as a boolean attribute (issue #730). Normalised to `checkedClass`/`checkedAttribute`
+  // in selector-resolver, then read by setCheckedState/expectCheckedState via the checked-opts
+  // partial.
+  'checked',          // checked state signal → setCheckedState/expectCheckedState
+  'selected',         // alias of `checked` for card/tab pickers
+]);
+
+/**
+ * Fields that are metadata by design — written for humans or for a non-codegen consumer, with no
+ * template behind them. Empty today: every field the schema accepts is now read by something.
+ *
+ * It is kept (rather than folded away) as the declared home for the NEXT such field, so that
+ * "nothing reads this" is an explicit, reviewable choice recorded here instead of an accident
+ * nobody notices for a release — which is precisely how `pagination:` and `contenteditable:`
+ * survived as documented no-ops.
+ */
+export const DECLARATIVE_ENTRY_FIELDS: ReadonlySet<string> = new Set([]);
+
+/** Everything an author may legitimately write on an entry. */
+export const KNOWN_ENTRY_FIELDS: ReadonlySet<string> = new Set([
+  ...CONSUMED_ENTRY_FIELDS,
+  ...DECLARATIVE_ENTRY_FIELDS,
+]);
+
+/** Keys of a `columns.<name>` definition — a column def is not a SelectorEntry. */
+export const COLUMN_DEF_FIELDS: ReadonlySet<string> = new Set(['index', 'header', 'elements']);
+
+export interface UnknownField {
+  /** Dotted path to the offending key, e.g. `orders.pagination` or `login.anchor`. */
+  path: string;
+  field: string;
+  /** A near-miss known field, when one is close enough to be worth naming. */
+  suggestion?: string;
+}
+
+/** Every key in `file` that no consumer will ever read. */
+export function collectUnknownEntryFields(file: Record<string, unknown>): UnknownField[] {
+  const out: UnknownField[] = [];
+  walkSelectorEntries(file, {
+    entry(entry, path) {
+      for (const field of Object.keys(entry)) {
+        if (KNOWN_ENTRY_FIELDS.has(field)) continue;
+        out.push({ path, field, suggestion: nearestMatch(field, KNOWN_ENTRY_FIELDS) });
+      }
+    },
+    // A column DEFINITION has its own small key set — this is the one check that judges it, and
+    // the reason the walk offers the visit at all.
+    columnDef(def, path) {
+      for (const field of Object.keys(def)) {
+        if (COLUMN_DEF_FIELDS.has(field)) continue;
+        out.push({ path, field, suggestion: nearestMatch(field, COLUMN_DEF_FIELDS) });
+      }
+    },
+  });
+  return out;
+}
+
+/**
+ * SG-W004 — report every entry field nothing reads.
+ *
+ * Runs once per selector FILE (the resolver's load is cached), not once per step, so a table named
+ * by twenty row steps is reported once. Silent when there is no diagnostics channel attached.
+ */
+export function reportUnknownEntryFields(
+  file: Record<string, unknown>,
+  opts: { feature?: string; diagnostics?: DiagnosticsCollector },
+): void {
+  const sink = opts.diagnostics;
+  if (!sink) return;
+  for (const { path, field, suggestion } of collectUnknownEntryFields(file)) {
+    const hint = suggestion
+      ? ` Did you mean "${suggestion}"?`
+      : ' A locator goes in "value:" (with a "type:") or "locator:" (raw CSS).';
+    sink.add('SG-W004',
+      `selectors.yaml entry "${path}" declares "${field}", which no consumer reads — `
+      + `writing it has no effect on the generated test and never will.${hint} `
+      + `See the selector reference for the fields an entry supports.`,
+      { feature: opts.feature });
+  }
+}

package/src/generators/test-generator/utils/selector-entry-walk.ts

@@ -0,0 +1,58 @@
+/**
+ * One walk over the entries of a `selectors.yaml` file, shared by every per-entry check.
+ *
+ * SG-W004 (#712), SG-E027 (#711) and SG-W018 (#720) ask three different questions about the same
+ * shape — an unknown KEY, an unknown VALUE for `type:`, an out-of-contract VALUE for `nth:` — and
+ * each shipped its own copy of the same recursion. Three copies of "where do entries live" is how
+ * a check silently stops covering a nesting level: #711's gate has an explicit case for
+ * `columns.*.elements.*` precisely because that level was easy to miss. The recursion lives here
+ * once, so a new nesting level is added in one place and every check gains it at the same moment.
+ */
+
+/** Sub-entries that are themselves full SelectorEntry values, so they recurse. */
+export const NESTED_ENTRY_FIELDS = ['anchor', 'android', 'ios'] as const;
+
+export function isEntryObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+
+export interface WalkVisitors {
+  /** Every SelectorEntry in the file, with its dotted path (`save`, `greeting.ios`, …). */
+  entry(entry: Record<string, unknown>, path: string): void;
+  /**
+   * Each `columns.<name>` DEFINITION, which is not a SelectorEntry (it holds index/header/
+   * elements). Only SG-W004 has business with these; the other checks omit it.
+   */
+  columnDef?(def: Record<string, unknown>, path: string): void;
+}
+
+function walkEntry(entry: Record<string, unknown>, entryPath: string, visit: WalkVisitors): void {
+  visit.entry(entry, entryPath);
+
+  for (const sub of NESTED_ENTRY_FIELDS) {
+    const v = entry[sub];
+    if (isEntryObject(v)) walkEntry(v, `${entryPath}.${sub}`, visit);
+  }
+
+  // A column DEFINITION is not a SelectorEntry, but the entries under its `elements:` map are,
+  // and each carries its own `type:` / `nth:`.
+  const columns = entry.columns;
+  if (!isEntryObject(columns)) return;
+  for (const [colName, colDef] of Object.entries(columns)) {
+    if (!isEntryObject(colDef)) continue;
+    const colPath = `${entryPath}.columns.${colName}`;
+    visit.columnDef?.(colDef, colPath);
+    const elements = colDef.elements;
+    if (!isEntryObject(elements)) continue;
+    for (const [elName, elEntry] of Object.entries(elements)) {
+      if (isEntryObject(elEntry)) walkEntry(elEntry, `${colPath}.elements.${elName}`, visit);
+    }
+  }
+}
+
+/** Visit every entry (and, on request, every column definition) in a parsed selector file. */
+export function walkSelectorEntries(file: Record<string, unknown>, visit: WalkVisitors): void {
+  for (const [label, entry] of Object.entries(file)) {
+    if (isEntryObject(entry)) walkEntry(entry, label, visit);
+  }
+}

package/src/generators/test-generator/utils/selector-nth-validation.ts

@@ -0,0 +1,99 @@
+/**
+ * SG-W018 — an `nth:` value outside the contract (issue #720).
+ *
+ * `nth:` was the one SelectorEntry field whose VALUE nothing validated. The key is recognised
+ * (it is in CONSUMED_ENTRY_FIELDS, so SG-W004 stays quiet) and the entry's `type:` is valid (so
+ * SG-E027 stays quiet) — every check we own stopped at the key. What landed in the value went
+ * straight to two adapters that disagreed about what a valid `nth` even is:
+ *
+ *   nth: -1     web → the filter vanished (`.getByRole('combobox')`, byte-identical to deleting
+ *                     the line), mobile → `$$('~x')[-1]`, which is `undefined` in JavaScript
+ *   nth: 'last' web → dropped, mobile → `$$('~x')[last]` — a bare identifier, valid syntax and a
+ *                     ReferenceError at run time, so even the SG-E022 parse self-check passed it
+ *   nth: 1.5    emitted verbatim into `.nth(1.5)` / `[1.5]`
+ *
+ * Zero diagnostics in every case. `SelectorEntry.nth` is typed `number?`, but YAML is parsed, not
+ * type-checked — the declared type buys nothing at the boundary. Same family as #712 (an
+ * unrecognised KEY) and #711 (an unrecognised VALUE for `type:`), one level deeper again.
+ *
+ * THE CONTRACT: an integer `>= -1`. `0..N` is the zero-based index; `-1` means the last match
+ * (Playwright's `.last()` IS `.nth(-1)`, and the appium side now renders `.at(-1)`). Anything
+ * else is ignored by the resolver — normalised to `undefined` before it can reach a template —
+ * and reported here, so "ignored" is something the author is told rather than something they
+ * discover from a strict-mode violation.
+ *
+ * A WARNING, not an error, on SG-W004's reasoning: the value is inert once dropped, the selector
+ * still resolves (it just does not filter by position), and `--strict` already turns the channel
+ * non-zero for CI.
+ */
+
+import type { DiagnosticsCollector } from '../diagnostics';
+import { walkSelectorEntries } from './selector-entry-walk';
+
+/** True for the values `nth:` accepts: an integer index `>= 0`, or `-1` for the last match. */
+export function isValidNth(v: unknown): v is number {
+  return typeof v === 'number' && Number.isInteger(v) && v >= -1;
+}
+
+/**
+ * The one normalisation every resolve path runs `nth` through: a valid index, or `undefined`.
+ *
+ * Returning `undefined` rather than the raw value is what makes the SG-W018 message true — and
+ * it is the half that keeps broken JavaScript out of the emitted spec even on paths this check
+ * does not walk (the legacy selector format), because a template only ever sees a real index.
+ */
+export function normalizeNth(v: unknown): number | undefined {
+  return isValidNth(v) ? v : undefined;
+}
+
+export interface InvalidNth {
+  /** Dotted path to the offending entry, e.g. `danh muc` or `greeting.android`. */
+  path: string;
+  /** The `nth:` value exactly as written, for quoting back at the author. */
+  nth: unknown;
+}
+
+/** Every entry in `file` whose `nth:` is present but outside the contract. */
+export function collectInvalidNth(file: Record<string, unknown>): InvalidNth[] {
+  const out: InvalidNth[] = [];
+  walkSelectorEntries(file, {
+    entry(entry, path) {
+      // An ABSENT `nth:` is the common case and means "no positional filter". An explicit
+      // `nth: null` is read the same way — the resolver has always treated null as unset, and
+      // reporting it would fire on a legitimate "no index here" written out loud.
+      if (entry.nth === undefined || entry.nth === null) return;
+      if (isValidNth(entry.nth)) return;
+      out.push({ path, nth: entry.nth });
+    },
+  });
+  return out;
+}
+
+/**
+ * SG-W018 — report every entry whose `nth:` the compiler cannot use.
+ *
+ * Runs once per selector FILE (the resolver's load is cached), so an entry named by twenty steps
+ * is reported once — the same load point and the same reason as SG-W004 and SG-E027. Silent when
+ * no diagnostics channel is attached: `generate` must not depend on diagnostics being wired.
+ */
+export function reportInvalidNth(
+  file: Record<string, unknown>,
+  opts: { feature?: string; diagnostics?: DiagnosticsCollector },
+): void {
+  const sink = opts.diagnostics;
+  if (!sink) return;
+  for (const { path, nth } of collectInvalidNth(file)) {
+    // Quoted for a string so `nth: 'last'` reads back as the string it is; `String()` for a number
+    // so -2, 1.5 and .nan survive as written (JSON.stringify renders NaN as `null`, which would
+    // quote a value the author never typed).
+    const written = typeof nth === 'string' ? `"${nth}"`
+      : typeof nth === 'number' ? String(nth)
+      : JSON.stringify(nth) ?? String(nth);
+    sink.add('SG-W018',
+      `selectors.yaml entry "${path}" declares nth: ${written}, which is not a valid index — `
+      + `it is IGNORED, so the selector does not filter by position and a step naming it resolves `
+      + `to every match (strict mode then fails at run time naming the DOM, never this line). `
+      + `Use an integer >= 0 for a zero-based index, or -1 for the last match.`,
+      { feature: opts.feature });
+  }
+}