@sun-asterisk/sungen 3.2.29 → 3.2.31

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 });
+  }
+}