@sun-asterisk/sungen 3.2.28 → 3.2.30

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

@@ -8,6 +8,9 @@ import { SelectorType } from '../../../utils/selector-types';
 import { DataResolver } from './data-resolver';
 import { DiagnosticsCollector } from '../diagnostics';
 import { DEFAULT_CONTENT_NAMED_ROLES } from '../app-profile';
+import { reportUnknownEntryFields } from './selector-entry-fields';
+import { reportUnknownSelectorTypes } from './selector-type-validation';
+import { normalizeNth, reportInvalidNth } from './selector-nth-validation';
 
 // Structured selector format v2
 interface SelectorEntry {
@@ -15,7 +18,8 @@ interface SelectorEntry {
   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 (undefined = no .nth(), 0+ = .nth(N))
+  nth?: number;           // Element index: undefined = no positional filter, 0+ = that index,
+                          // -1 = the last match. Anything else is dropped + SG-W018 (#720)
   exact?: boolean;        // Whether to use exact matching (default: false)
   inputMethod?: string;   // 'pressSequentially' for contenteditable/rich-text elements
 
@@ -46,6 +50,28 @@ interface SelectorEntry {
   // === v2: Table ===
   columns?: Record<string, { index: number; header: string; elements?: Record<string, SelectorEntry> }>;
   pagination?: Record<string, string>;
+  // What EVERY row of this table matches, relative to the table locator (issue #688). The table
+  // templates assume an ARIA table — `getByRole('row')`, `tbody` — and on a list built from plain
+  // <div>s that universe is 0 elements, so `is hidden` / `is empty` pass without checking anything.
+  // `rows: 'div.job-row'` replaces the whole row chain. Distinct from a ROW LABEL's own `type: locator`
+  // entry, which positions ONE row (`tbody tr:first-child`) — a shape is a property of the table.
+  rows?: string;
+
+  // === Checked/selected state signal (issue #730) ===
+  // How a control publishes its on/off state when it publishes NO ARIA. A Tailwind checkbox or
+  // card picker — a <div> with a class swap and no <input>, no role, no aria-checked/aria-pressed —
+  // has no state for `check`/`uncheck` to drive or for `is checked`/`is selected` to read, so every
+  // such step failed with "it has no on/off state to set" no matter how right the selector was.
+  // `checked: { class: 'is-checked' }` names the class that marks the ON state.
+  //
+  // `selected:` is an ALIAS for the same signal, not a second one: a card picker declaring
+  // `checked:` reads wrong, and `is selected` on a non-ARIA element already falls through to the
+  // checked family (selected-assertion.hbs). Declaring both is a conflict — see resolveFromEntry.
+  // `checked.attribute` is the same signal published as a boolean attribute ('true'/'false')
+  // instead of a class, for a control that swaps `data-checked` rather than a class token.
+  // Declare ONE of the two per entry: class and attribute are two ways to read one state.
+  checked?: { class?: string; attribute?: string };
+  selected?: { class?: string; attribute?: string };
 
   // === v2: Assertion Helpers ===
   attribute?: string;     // Attribute to check (for "has" assertions)
@@ -117,7 +143,7 @@ export interface ResolvedSelector {
   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
+  nth?: number;         // Index for .nth() if multiple matches exist (0+, or -1 = last match)
   exact?: boolean;      // Whether to use exact matching (default: false)
   inputMethod?: string; // 'pressSequentially' for contenteditable/rich-text elements
 
@@ -130,9 +156,15 @@ export interface ResolvedSelector {
   contenteditable?: boolean;  // Rich text editor
   columns?: Record<string, { index: number; header: string; elements?: Record<string, any> }>;
   pagination?: Record<string, string>;
+  rows?: string;        // Row shape, relative to the table (issue #688) — see SelectorEntry.rows
   attribute?: string;   // Attribute to check
   pattern?: string;     // Regex for attribute value
   expanded?: { class?: string; attribute?: string; state?: 'none' };  // Expand/collapse state signal
+  // Class / boolean attribute marking the ON state, normalised from `checked:`/`selected:`
+  // (issue #730). Flat rather than an object because ONE resolved signal is what every consumer
+  // needs — the two YAML spellings are an authoring convenience, not two different things.
+  checkedClass?: string;
+  checkedAttribute?: string;
   anchor?: ResolvedSelector;  // page entries only — the rendered-content proof behind `see [X] page` (#662)
 }
 
@@ -150,13 +182,38 @@ export class SelectorResolver {
   private diagnostics?: DiagnosticsCollector;
   private contentNamedRoles: string[] = DEFAULT_CONTENT_NAMED_ROLES;
   private warnedContentNamed = new Set<string>();
+  /** The adapter's target platform — gates the list-member auto-infer (#665). Defaults to web. */
+  private platform: 'web' | 'mobile' = 'web';
 
-  constructor(selectorsDir?: string, screenName?: string) {
+  constructor(selectorsDir?: string, screenName?: string, platform: 'web' | 'mobile' = 'web') {
     this.selectorsDir = selectorsDir || path.join(process.cwd(), 'qa', 'selectors', 'screens');
     this.screenName = screenName;
+    this.platform = platform;
   }
 
-  /** Attach the compile-diagnostics collector (SG-W003) */
+  /**
+   * A role that resolved with NO accessible name, on the mobile adapter — a dead selector (#665).
+   *
+   * `appium-selector.hbs` renders a role as `~{{name || value}}`, so with no name it emits the role
+   * TOKEN itself: `~listitem`, `~status`. A native a11y tree has no role concept and contains no
+   * such string, so the locator can never match — yet it compiled clean and only failed at run time
+   * with `element with selector "~listitem" wasn't found`.
+   *
+   * The invariant is "role with no name", NOT "role in LIST_MEMBER_ROLES". Both are reachable and
+   * both are dead:
+   *   · auto-infer  — only the three LIST_MEMBER_ROLES are nameless (the other 22 default the label)
+   *   · an entry    — a list-member role withholds the name by design, and `name: null` is the
+   *                   documented opt-out for a content-named role, so `type: role` reaches it too
+   * One predicate covers every door; the CALLERS choose the remedy, because it differs: with no
+   * entry the fix is "add one", with an entry the fix is "change its type".
+   *
+   * Web is unaffected — there the role IS the locator (see LIST_MEMBER_ROLES).
+   */
+  private isUnusableMobileRole(r: ResolvedSelector | null | undefined): boolean {
+    return this.platform === 'mobile' && !!r && r.strategy === 'role' && !r.name;
+  }
+
+  /** Attach the compile-diagnostics collector (SG-W003, SG-W016, SG-W030) */
   setDiagnostics(collector: DiagnosticsCollector): void {
     this.diagnostics = collector;
   }
@@ -452,11 +509,28 @@ export class SelectorResolver {
     // Auto-infer locator from elementType when no exact YAML entry exists
     if (elementType) {
       const inferred = SelectorResolver.inferFromElementType(elementType, displayLabel);
-      if (inferred) {
+
+      // #665 — auto-infer is an ARIA concept. It survives on mobile only because a label-named
+      // role hands the appium template a `name` to render as an accessibility-id (`[Submit]
+      // button` → `~Submit`, a plausible guess). A nameless role has nothing to hand it, and the
+      // template's `~{{name || value}}` fell through to the role TOKEN — `[Job List] item` →
+      // `~listitem`, a string no Android/iOS a11y tree contains. Clean compile, guaranteed miss.
+      //
+      // Declining rather than warning is what repairs the workflow. `sungen-selector-fix` Phase 0
+      // decides whether to scan the live page by asking whether the ref "can't be auto-inferred";
+      // while auto-infer answered yes, Phase 0 skipped the scan, so no real selector was ever
+      // written and a warning would have reported the breakage with the repair path still switched
+      // off. Declining makes Phase 0 scan, and if it was skipped the not-found throw below names
+      // the exact key to add — the remedy here is "add an entry", which is what that error says.
+      //
+      // Web is untouched: `getByRole('listitem')` with no name is a real, working locator there.
+      if (inferred && !this.isUnusableMobileRole(inferred)) {
         // Same SG-W003 class as the explicit-entry path: an auto-inferred name on a
         // name-from-content role ([Loading] spinner → getByRole('status', { name: 'Loading' }))
         // can never match. Add a YAML entry with name: null to opt out.
-        if (inferred.strategy === 'role' && inferred.name && inferred.role && this.contentNamedRoles.includes(inferred.role)) {
+        // WEB ONLY — see the note at the entry-path emission (#665).
+        if (this.platform !== 'mobile'
+          && inferred.strategy === 'role' && inferred.name && inferred.role && this.contentNamedRoles.includes(inferred.role)) {
           const warnKey = `${inferred.role}:${displayLabel}`;
           if (!this.warnedContentNamed.has(warnKey)) {
             this.warnedContentNamed.add(warnKey);
@@ -546,9 +620,137 @@ export class SelectorResolver {
     });
   }
 
+  /** Encode `{{var}}` references inside a table's `columns: { <col>: { header } }` map. */
+  private static resolveColumnHeaders(
+    columns: NonNullable<SelectorEntry['columns']>,
+  ): NonNullable<SelectorEntry['columns']> {
+    const out: NonNullable<SelectorEntry['columns']> = {};
+    for (const [key, col] of Object.entries(columns)) {
+      out[key] = col && typeof col.header === 'string'
+        ? { ...col, header: SelectorResolver.resolveTemplateVars(col.header) }
+        : col;
+    }
+    return out;
+  }
+
+  /**
+   * Normalise `checked:` / `selected:` into the one signal consumers read (issue #730). The two
+   * spellings are an authoring convenience for the same thing — `checked:` on a toggle, `selected:`
+   * on a card/tab picker — so they collapse here rather than at every call site. Each spelling can
+   * publish the state as a class token or as a boolean attribute; one entry declares one of them.
+   *
+   * Validated at CODEGEN because every failure mode here is silent at run time: the class token
+   * lands inside `[class~="..."]`, where a quote breaks the selector and whitespace can never match
+   * (the `~=` operator matches ONE whitespace-separated token, so 'a b' matches nothing at all and
+   * the step would just time out claiming the control never changed state); an attribute name has
+   * the same exposure inside `[name="true"]`. Refused rather than warned-and-dropped, unlike
+   * `expanded:`: dropping this signal leaves the step with nothing to read, so it would fail again
+   * with the original "no on/off state" error and hide the real cause.
+   */
+  private resolveCheckedSignal(
+    entry: SelectorEntry,
+    label: string,
+  ): { class?: string; attribute?: string } | undefined {
+    const signal: { class?: string; attribute?: string } = {};
+    // Recorded BEFORE it is thrown, every time. A pattern that resolves its selector inside a
+    // `catch {}` — several do, to fall back when a `[Ref]` simply is not in the file — would
+    // otherwise swallow the refusal whole and emit a step against an unresolved locator, with
+    // nothing anywhere naming the entry. The throw is what stops the file; the diagnostic is what
+    // survives a caller that decided not to be stopped, and what `--strict` counts.
+    const refuse = (message: string): never => {
+      this.diagnostics?.add('SG-E031', message, { feature: this.featureName });
+      throw new Error(message);
+    };
+
+    for (const key of ['class', 'attribute'] as const) {
+      const fromChecked = entry.checked?.[key]?.trim();
+      const fromSelected = entry.selected?.[key]?.trim();
+
+      if (fromChecked && fromSelected && fromChecked !== fromSelected) {
+        refuse(
+          `Selector "[${label}]" declares both \`checked.${key}\` ("${fromChecked}") and ` +
+          `\`selected.${key}\` ("${fromSelected}") with different values. They are two spellings of ONE ` +
+          `signal — how the control marks its ON state — so only one can be right. Keep \`checked:\` for ` +
+          `a toggle/checkbox or \`selected:\` for a card/tab picker, and delete the other.`
+        );
+      }
+
+      const value = fromChecked || fromSelected;
+      if (!value) continue;
+
+      if (/\s/.test(value)) {
+        refuse(
+          `Selector "[${label}]" declares checked/selected ${key} "${value}", which contains whitespace. ` +
+          `This must be ONE ${key === 'class' ? 'class token, not a class list' : 'attribute name'}: the ` +
+          `generated matcher tests a single token, so a multi-token value can never match and the step ` +
+          `would time out rather than fail clearly. Pick the one ${key} that marks the ON state ` +
+          `(e.g. '${key === 'class' ? 'border-link' : 'data-checked'}', not ` +
+          `'${key === 'class' ? 'card border-link' : 'data-checked aria-checked'}').`
+        );
+      }
+      if (value.includes('"') || value.includes('\\')) {
+        refuse(
+          `Selector "[${label}]" declares checked/selected ${key} "${value}", which contains a quote or ` +
+          `backslash. The value is embedded in a [${key === 'class' ? 'class~="..."' : 'name="true"'}] CSS ` +
+          `selector, which those characters would break. A ${key} carrying them is almost certainly a typo.`
+        );
+      }
+      signal[key] = value;
+    }
+
+    if (signal.class && signal.attribute) {
+      refuse(
+        `Selector "[${label}]" declares both a checked/selected \`class\` ("${signal.class}") and ` +
+        `\`attribute\` ("${signal.attribute}"). One control publishes its ON state one way — declaring ` +
+        `two lets an action drive one signal while the assertion after it reads the other. Keep the one ` +
+        `the component actually swaps.`
+      );
+    }
+
+    return signal.class || signal.attribute ? signal : undefined;
+  }
+
   /**
    * Resolve from new structured entry format
    */
+  /**
+   * An `expanded:` signal's `class` / `attribute` value is pasted into the generated spec — into a
+   * string literal, a regex, a `classList.contains()` argument. selectors.yaml is often generated
+   * from the page under test, so a value carrying a quote, a `${`, whitespace or any other character
+   * a class or attribute name cannot legitimately contain is refused (diagnostic + the field is
+   * dropped) rather than compiled into code. Dropping it leaves a working step — codegen falls back
+   * to driving/asserting `aria-expanded` — which is why this warns where the checked/selected signal,
+   * whose fallback is the failure it exists to fix, refuses outright.
+   */
+  private validatedStateSignal(
+    signal: { class?: string; attribute?: string },
+    field: string,
+    label: string,
+  ): { class?: string; attribute?: string } | undefined {
+    // Letters, digits and the punctuation real class/attribute names use — including Tailwind
+    // arbitrary values (`bg-[#eff6ff]`, `!mt-0`, `@md:flex`, `w-[calc(100%-2rem)]`). Excluded on
+    // purpose: whitespace, quotes, backticks, backslash, `$`/`{`/`}` — the characters that could
+    // close a literal or open an interpolation in the generated code.
+    const SAFE = /^[A-Za-z0-9_\-:./[\]%#!@(),&+=*~|?]+$/;
+    const out: { class?: string; attribute?: string } = {};
+    for (const key of ['class', 'attribute'] as const) {
+      const value = signal[key];
+      if (value === undefined || value === null) continue;
+      const text = String(value);
+      if (SAFE.test(text)) { out[key] = text; continue; }
+      const warnKey = `w030:${label}:${field}.${key}`;
+      if (!this.warnedContentNamed.has(warnKey)) { // once per entry+field, not once per step that uses it
+        this.warnedContentNamed.add(warnKey);
+        this.diagnostics?.add(
+          'SG-W030',
+          `selector "${label}": ${field}.${key} ${JSON.stringify(text)} is not accepted as a ${key} name (no whitespace, quotes, backslash, \`$\`, \`{\` or \`}\`) — the value is ignored and the step compiles to its default form`,
+          { feature: this.featureName },
+        );
+      }
+    }
+    return out.class || out.attribute ? out : undefined;
+  }
+
   private resolveFromEntry(entry: SelectorEntry, originalLabel: string): ResolvedSelector {
     // Default values
     const locator = entry.locator || '';
@@ -570,9 +772,22 @@ export class SelectorResolver {
       : (entry.name ?? '');
     const value = SelectorResolver.resolveTemplateVars(rawValue);
     const name = SelectorResolver.resolveTemplateVars(rawName);
-    const nth = entry.nth !== undefined && entry.nth !== null ? entry.nth : undefined;
+    // `nth:` is the one field whose VALUE nothing used to check (#720): anything non-null was
+    // handed to the adapters, which disagreed about it — web dropped `-1` silently, mobile emitted
+    // `$$(...)[-1]`. Normalised to a real index (integer >= -1) or `undefined` HERE, so no template
+    // ever renders a value it cannot express; the out-of-contract write is reported as SG-W018 at
+    // the file load point below.
+    const nth = normalizeNth(entry.nth);
     const exact = entry.exact === true || entry.match === 'exact';
-    const inputMethod = entry.inputMethod;
+    // `contenteditable: true` is the MANUAL override for a rich-text editor (#712). It was a
+    // documented, plumbed field that nothing read: the rich-text decision lives in driver-ui's
+    // fill pattern, which gates on `inputMethod` to pick `fill-editor-action`, so an author who
+    // followed the selector reference and wrote `contenteditable: true` got a plain `.fill()` and
+    // no diagnostic. Forcing the input method HERE rather than adding a second condition in the
+    // pattern keeps ONE rich-text signal on ResolvedSelector, so every consumer — current and
+    // future — reads the intent off a single field. An explicit `inputMethod` is more specific and
+    // still wins, so the two may be mixed without surprise.
+    const inputMethod = entry.inputMethod ?? (entry.contenteditable ? 'pressSequentially' : undefined);
 
     // v2 fields
     const v2Fields: Partial<ResolvedSelector> = {};
@@ -582,11 +797,21 @@ export class SelectorResolver {
     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;
+    // A column's `header` is DOM text like any other selector field, so a `{{var}}` in it is a
+    // runtime reference — the same i18n escape hatch `name:`/`value:` have. Encoded here rather
+    // than at the read site so every consumer of the map gets it (issue #674).
+    if (entry.columns) v2Fields.columns = SelectorResolver.resolveColumnHeaders(entry.columns);
     if (entry.pagination) v2Fields.pagination = entry.pagination;
+    if (typeof entry.rows === 'string' && entry.rows.trim()) v2Fields.rows = entry.rows.trim();
     if (entry.attribute) v2Fields.attribute = entry.attribute;
     if (entry.pattern) v2Fields.pattern = entry.pattern;
-    if (entry.expanded) v2Fields.expanded = entry.expanded;
+    if (entry.expanded) {
+      const expanded = this.validatedStateSignal(entry.expanded, 'expanded', originalLabel);
+      if (expanded || entry.expanded.state) v2Fields.expanded = { ...expanded, ...(entry.expanded.state ? { state: entry.expanded.state } : {}) };
+    }
+    const checked = this.resolveCheckedSignal(entry, originalLabel);
+    if (checked?.class) v2Fields.checkedClass = checked.class;
+    if (checked?.attribute) v2Fields.checkedAttribute = checked.attribute;
     // The anchor is a selector in its own right; it must not inherit the PAGE's label as its
     // accessible name, so it resolves against its own name (or nothing).
     if (entry.anchor) v2Fields.anchor = this.resolveFromEntry(entry.anchor, entry.anchor.name ?? '');
@@ -622,7 +847,26 @@ export class SelectorResolver {
     // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly.
     // `exact` travels along: a locator LIST filtered by a test-data value (hasText) matches by
     // substring by default, and `exact: true` in the YAML opts into the anchored full-text match.
-    if (type === 'locator') {
+    //
+    // `upload` rides the SAME branch rather than getting a case of its own. A file input is
+    // addressed by CSS in practice (`input[type=file]`, an id, a testid wrapper), and the selector
+    // reference has always documented `upload` as `page.locator(value).setInputFiles()` — so the
+    // two spellings must resolve identically or teams migrating off the workaround get a silent
+    // behaviour change. It had no case at all before, so it fell through to `default:` and
+    // compiled to `getByPlaceholder('<the CSS string>')` — a locator hunting an input whose
+    // placeholder ATTRIBUTE is the literal text `input[type=file]`, which no page has. It failed
+    // at run time with no diagnostic, and the only way out was to work out for oneself that
+    // `type: locator` had to be used instead, which no page of the reference says (issue #690).
+    //
+    // Handled HERE, above the generic `locator:`-field branch below, because that branch returns
+    // strategy 'css' and drops `exact` — putting `upload` in the switch left the two spellings
+    // diverging for any entry that sets `locator:`. `withExtras` still stamps the declared
+    // `selectorType`, so a consumer that needs to tell an upload from a plain locator still can.
+    //
+    // `exact` is inert for the upload action itself (`setInputFiles` takes no text filter), but it
+    // is NOT dead: the same key reused by a filtered step (`… with {{v}}`) reaches has-text-value,
+    // which reads `exact` regardless of strategy.
+    if (type === 'locator' || type === 'upload') {
       const locatorValue = locator && locator.trim() ? locator : value;
       return withExtras({
         strategy: 'locator',
@@ -658,7 +902,16 @@ export class SelectorResolver {
         // reference text. For name-from-content roles (status/alert/…) that filter can
         // never match the live element (its accessible name is computed from its content,
         // e.g. a toast's message text) — issue #467. Opt out with `name: null`.
-        if (entry.name === undefined && name && this.contentNamedRoles.includes(value)) {
+        //
+        // WEB ONLY. "The accessible name is computed from content" is an ARIA rule with no mobile
+        // counterpart: the appium template turns a role into an accessibility-id lookup, so
+        // `[Loading] spinner` → `~Loading` is exactly as legitimate a guess as `[Submit] button`
+        // → `~Submit`, which this compiler emits happily. On mobile the warning was therefore a
+        // false positive — and worse, its remedy made things strictly worse: `name: null` leaves
+        // the role nameless, which now renders as the role TOKEN and is refused outright (#665).
+        // A wrong selector fails loudly at run time; advice that manufactures a dead one does not.
+        if (this.platform !== 'mobile'
+          && entry.name === undefined && name && this.contentNamedRoles.includes(value)) {
           const warnKey = `${value}:${originalLabel}`;
           if (!this.warnedContentNamed.has(warnKey)) {
             this.warnedContentNamed.add(warnKey);
@@ -669,14 +922,31 @@ export class SelectorResolver {
             );
           }
         }
-        return withExtras({
-          strategy: 'role',
-          role: value,
-          name: name,  // Use the name field for accessible name
-          value,
-          nth,
-          exact,
-        });
+        {
+          const resolvedRole = withExtras({
+            strategy: 'role',
+            role: value,
+            name: name,  // Use the name field for accessible name
+            value,
+            nth,
+            exact,
+          });
+          // #665 — the same dead selector as the auto-infer path, reached through an ENTRY: a
+          // list-member role withholds its name by design, and `name: null` is the documented
+          // opt-out for a content-named role. Either way a mobile role with no name renders as
+          // the role token. Different remedy from the auto-infer case, so a different message:
+          // the entry exists, it is the TYPE that cannot work here.
+          if (this.isUnusableMobileRole(resolvedRole)) {
+            throw new Error(
+              `Selector "${originalLabel}" is \`type: role, value: ${value}\`${name === null ? ' with `name: null`' : ''}, ` +
+              `which resolves to a role with no accessible name. A native app has no role concept, so this compiles to ` +
+              `the accessibility-id "~${value}" — a string no Android/iOS a11y tree contains, and the step can never match. ` +
+              `Give this entry a locator the device actually exposes: \`type: accessibility-id\` (a content-desc / ` +
+              `accessibilityIdentifier), \`type: xpath\`, or \`type: id\`.`
+            );
+          }
+          return resolvedRole;
+        }
 
       case 'testid':
         return withExtras({
@@ -722,7 +992,14 @@ export class SelectorResolver {
         });
 
       default:
-        // Fallback to placeholder
+        // Reached by the NON_STRATEGY_SELECTOR_TYPES (`page`/`table`/`column`/`frame`, whose
+        // consumers read the entry or `selectorType` rather than `strategy`) and by a type this
+        // compiler does not know at all — YAML is untyped at run time, so a misspelling lands
+        // here too. The placeholder result is inert for the first group and wrong for the second,
+        // but it MUST NOT throw: `page` alone reaches this branch on every page assertion.
+        // What must never arrive here is a STRATEGY type — that is the #690 defect, and
+        // tests/codegen/selector-type-dispatch.run.ts fails the build if one does (it checks the
+        // resolved strategy, so an early return above satisfies it as well as a `case` here).
         return withExtras({
           strategy: 'placeholder',
           value,
@@ -737,13 +1014,18 @@ export class SelectorResolver {
    * Returns metadata only - no framework-specific code
    */
   private resolveByPriority(element: LegacySelectorElement): ResolvedSelector {
+    // The legacy format never passes through the SG-W018 file check (that walks new-format
+    // entries), so it is normalised here instead — a template must never see an index it cannot
+    // express, whichever door the entry came through.
+    const nth = normalizeNth(element.nth);
+
     // Extract data-testid from locator if present
     const testIdMatch = element.locator.match(/\[data-testid=["']([^"']+)["']\]/);
     if (testIdMatch) {
       return {
         strategy: 'testid',
         value: testIdMatch[1],
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -754,7 +1036,7 @@ export class SelectorResolver {
         role: 'button',
         name: element.value,
         value: element.value,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -762,7 +1044,7 @@ export class SelectorResolver {
       return {
         strategy: 'placeholder',
         value: element.value,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -770,7 +1052,7 @@ export class SelectorResolver {
       return {
         strategy: 'label',
         value: element.value,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -778,7 +1060,7 @@ export class SelectorResolver {
       return {
         strategy: 'text',
         value: element.value,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -789,7 +1071,7 @@ export class SelectorResolver {
         strategy: 'id',
         value: idMatch[1],
         locator: `#${idMatch[1]}`,
-        nth: element.nth,
+        nth,
       };
     }
 
@@ -798,7 +1080,7 @@ export class SelectorResolver {
       strategy: 'css',
       value: element.locator,
       locator: element.locator,
-      nth: element.nth,
+      nth,
     };
   }
 
@@ -848,6 +1130,29 @@ export class SelectorResolver {
       }
     }
 
+    // SG-W004 — a field nothing reads (#712). Reported HERE, at the one cached load point, so a
+    // table named by twenty row steps warns once rather than twenty times.
+    reportUnknownEntryFields(selectors as Record<string, unknown>, {
+      feature: featureName,
+      diagnostics: this.diagnostics,
+    });
+
+    // SG-E027 — a `type:` nothing dispatches (#711). Same load point and same once-per-file
+    // reason as SG-W004 above: the two checks are the same question one level apart (an unknown
+    // KEY vs an unknown VALUE for a known key), and both want the file in hand to name the entry.
+    reportUnknownSelectorTypes(selectors as Record<string, unknown>, {
+      feature: featureName,
+      diagnostics: this.diagnostics,
+    });
+
+    // SG-W018 — an `nth:` value outside the contract (#720). Third of the same family at the same
+    // load point: SG-W004 asks whether anything READS the key, SG-E027 whether the `type:` VALUE
+    // dispatches, this one whether the `nth:` VALUE is an index the adapters can express.
+    reportInvalidNth(selectors as Record<string, unknown>, {
+      feature: featureName,
+      diagnostics: this.diagnostics,
+    });
+
     this.selectorCache.set(cacheKey, selectors);
     return selectors;
   }

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

@@ -0,0 +1,87 @@
+/**
+ * SG-E027 — an entry `type:` the compiler does not know (issue #711).
+ *
+ * `selectors.yaml` is YAML, so `type:` is an arbitrary string at run time. `VALID_SELECTOR_TYPES`
+ * constrained it only through the `SelectorType` TypeScript union, and nothing imported that list
+ * for a runtime check — so any value the resolver did not recognise fell to the strategy switch's
+ * `default:` branch, which returns `{ strategy: 'placeholder' }`, and the entry's `value:` was
+ * emitted as literal placeholder text:
+ *
+ *   save:
+ *     type: 'testId'        # note the capital I
+ *     value: 'btn-save'
+ *                           → await page.getByPlaceholder('btn-save').click();
+ *
+ * Same family as #690 (a valid type with no dispatch) and #712 (a documented field with no
+ * consumer): the DECLARED surface was wider than the IMPLEMENTED one and nothing compared the two.
+ * Here the gap was the widest of the three, because an unknown type is not a fixed list of
+ * oversights — it is every possible misspelling.
+ *
+ * Checked HERE, at the selector-file load, rather than in the strategy switch. The switch CANNOT
+ * throw: `type: page` reaches its `default:` on every page assertion (its `value` is a URL, not a
+ * locator) and `StepMapper.checkPageStepFallback` resolves inside a try/catch that would read
+ * a throw as "not a page" and emit a false SG-W013. Validating at the load point also buys a
+ * better message — the file, the entry key and the nearest valid spelling — and reports once per
+ * entry rather than once per step that names it.
+ */
+
+import type { DiagnosticsCollector } from '../diagnostics';
+import { VALID_SELECTOR_TYPES } from '../../../utils/selector-types';
+import { nearestMatch } from './nearest-match';
+import { walkSelectorEntries } from './selector-entry-walk';
+
+export interface UnknownSelectorType {
+  /** Dotted path to the offending entry, e.g. `save` or `greeting.ios`. */
+  path: string;
+  /** The unrecognised `type:` value exactly as written. */
+  type: string;
+  /** A near-miss valid type, when one is close enough to be worth naming. */
+  suggestion?: string;
+}
+
+/** Every entry in `file` whose `type:` is not a member of `VALID_SELECTOR_TYPES`. */
+export function collectUnknownSelectorTypes(file: Record<string, unknown>): UnknownSelectorType[] {
+  const out: UnknownSelectorType[] = [];
+  walkSelectorEntries(file, {
+    entry(entry, path) {
+      const type = entry.type;
+      // Only a STRING type is judged here. A non-string `type:` (a YAML nesting slip) is a
+      // different defect with a different fix, and SG-W004's field walk is not the owner of it
+      // either — naming it as an unknown type would print `[object Object]` at the author.
+      if (typeof type !== 'string') return;
+      if ((VALID_SELECTOR_TYPES as readonly string[]).includes(type)) return;
+      out.push({ path, type, suggestion: nearestMatch(type, VALID_SELECTOR_TYPES) });
+    },
+  });
+  return out;
+}
+
+/** True when this entry kind is one the compiler knows how to resolve. */
+export function isKnownSelectorType(type: unknown): boolean {
+  return typeof type === 'string' && (VALID_SELECTOR_TYPES as readonly string[]).includes(type);
+}
+
+/**
+ * SG-E027 — report every entry whose `type:` nothing dispatches.
+ *
+ * Runs once per selector FILE (the resolver's load is cached), so an entry named by twenty steps
+ * is reported once. Silent when there is no diagnostics channel attached — `generate` must not
+ * depend on diagnostics being wired.
+ */
+export function reportUnknownSelectorTypes(
+  file: Record<string, unknown>,
+  opts: { feature?: string; diagnostics?: DiagnosticsCollector },
+): void {
+  const sink = opts.diagnostics;
+  if (!sink) return;
+  for (const { path, type, suggestion } of collectUnknownSelectorTypes(file)) {
+    const hint = suggestion
+      ? ` Did you mean "${suggestion}"?`
+      : ` Valid types: ${VALID_SELECTOR_TYPES.join(', ')}.`;
+    sink.add('SG-E027',
+      `selectors.yaml entry "${path}" declares type: "${type}", which is not a selector type — `
+      + `the entry resolves to getByPlaceholder("<its value>"), a locator that cannot match, so `
+      + `every step naming it now throws instead of failing later as a mystery timeout.${hint}`,
+      { feature: opts.feature });
+  }
+}