@sun-asterisk/sungen 3.2.28 → 3.2.30

package/src/generators/test-generator/diagnostics.ts

@@ -10,6 +10,13 @@
  *   SG-W002 — step parsed a {{dataRef}} value but the generated code never uses it
  *   SG-W003 — `name` filter defaulted from the Gherkin reference on a name-from-content
  *             role (status/alert/…) — such a filter can never match; opt out with `name: null`
+ *   SG-W004 — a selectors.yaml entry declares a field no consumer reads, so writing it has no
+ *             effect on the generated test. Reserved for this in the original diagnostics spec
+ *             (`exact: true` with no construct it applies to) and implemented for the wider class
+ *             by #712, where `pagination:` and `contenteditable:` were public, documented,
+ *             plumbed — and read by nothing. The field partition lives in
+ *             utils/selector-entry-fields.ts; a field added there without a named consumer is
+ *             the bug this code exists to catch.
  *   SG-W005 — qa/app.yaml problem (unknown key, unknown preset, unparseable)
  *   SG-W006 — qa/app.<env>.yaml found (per-environment profiles are unsupported by design)
  *   SG-W007 — browser-alert handler step written AFTER an action step: the listener
@@ -45,6 +52,12 @@
  *             "3 cards are shown" gets an assertion that can only pass if the card's text
  *             IS the digit. Count semantics exist on row/table ("see [T] table with {{n}}",
  *             "see [Ref] row with {{n}}") and lists ("should have count") only
+ *   SG-W016 — a table step on a table located by CSS/testid whose value does not mention `table`
+ *             and that declares no `rows:`. The table templates find rows by `getByRole('row')`;
+ *             on a <div> list that is 0 elements, so `is hidden` / `is empty` pass without checking
+ *             anything and counts/clicks time out (issue #688). A heuristic — the compiler cannot
+ *             see the DOM — so a warning that names both ways out: `rows: '<row shape>'` on the
+ *             table entry, or `role: table`. Once per table per feature
  *   SG-E024 — a mobile app-lifecycle step (restart / reinstall) in a feature that declares no
  *             `Path:` app id. The templates resolve the app through a helper the test-file only
  *             emits when the id is present, so the spec used to compile clean and then die at
@@ -53,6 +66,23 @@
  *             but the generated code is a BARE VISIBILITY check: the clause was swallowed by the
  *             catch-all and the test would pass whatever the element says. Four separate defects
  *             have arrived this way, so the step compiles to a runtime throw instead.
+ *   SG-W017 — a step needs a selector-entry field the entry does not declare, so there is nothing
+ *             honest to compile. Today: a table paginate step whose table declares no
+ *             `pagination.next`/`.prev` (#712). The mirror of SG-W004 — that one reports a field
+ *             written that nothing reads, this one a field a consumer needs that nobody wrote.
+ *             Compiles the step to a loud runtime throw rather than guessing a locator, which is
+ *             the #690 failure (a locator no page has, failing far from the cause).
+ *   SG-W018 — a selectors.yaml entry declares an `nth:` the compiler cannot use (#720). `nth:` was
+ *             the one entry field whose VALUE nothing checked: the key is known (SG-W004 quiet) and
+ *             the `type:` is valid (SG-E027 quiet), so `nth: -1`, `nth: 'last'`, `nth: 1.5` and
+ *             `nth: -2` all compiled clean — the web side dropped the filter entirely (identical to
+ *             deleting the line, then a strict-mode violation naming the DOM) while the mobile side
+ *             emitted `$$('~x')[-1]` / `[last]`, undefined-indexing and a bare identifier that even
+ *             the SG-E022 parse check reads as valid JavaScript. The contract is an integer `>= -1`
+ *             (`0..N` a zero-based index, `-1` the last match); anything else is normalised away
+ *             before it reaches a template, and reported here so "ignored" is stated rather than
+ *             discovered. A warning, on SG-W004's reasoning — the value is inert once dropped and
+ *             `--strict` already turns the channel non-zero
  *   SG-E020 — the step matched a pattern whose template the ACTIVE adapter does not ship. Before
  *             the platform SPI this was an unhandled `Template not found` that killed the WHOLE
  *             feature file and named neither the step nor the adapter. The step now compiles to a
@@ -74,7 +104,10 @@
  *             (11), the clause vanished, and the step compiled to `toHaveURL(...)` — asserting the
  *             page IS displayed, the exact opposite of what it reads as, and passing while doing so.
  *             The pattern layer declares what it accounts for via `StepPattern.states`; anything
- *             undeclared reports here and compiles to a loud `throw`
+ *             undeclared reports here and compiles to a loud `throw`. One shape is NOT the author's:
+ *             a pattern NAMED for the state (`is-hidden`) with no `states` at all is a
+ *             @sungen/driver-* older than core — the message then names `sungen update` as the
+ *             fix, and discovery prefers core's own copy of a bundled driver over a stale project one
  *   SG-W022 — a `page` assertion on the mobile adapter that emitted NO executable code. A native app
  *             has no URL, so `Then User see [X] page` compiles to a bare comment: the step reads as
  *             an assertion, checks nothing, and the scenario PASSES regardless. Worse than the
@@ -91,6 +124,40 @@
  *             mobile suite already carrying one of these steps. The remedy is a feature-level reset
  *             tier (`@reset:data`), which is what the message names — app state is reset between
  *             scenarios in the `beforeEach` hook, not mid-scenario by a step.
+ *   SG-E025 — a feature that declares `@platform:ios` uses a step the Appium adapter does NOT serve
+ *             on iOS. The template ships and the step compiles, so nothing about the feature file
+ *             looks wrong; on a simulator it either throws deep in the run (set-connectivity,
+ *             location-services, open-notifications) or — worse — silently does nothing
+ *             (hide-keyboard, guarded `if (!driver.isIOS …)`). Derived from the template body via
+ *             the per-OS axis of the step-support matrix, so it cannot disagree with the adapter.
+ *             SCOPE, stated plainly because the name oversells it: only `@platform:ios` is caught.
+ *             A feature tagged `@platform:mobile` runs on whichever OS `MOBILE_PLATFORM` selects at
+ *             RUN time, so the compiler cannot know — the matrix, not this code, is the net that
+ *             covers that case. Reported as an E-code and compiled to a loud throw, because the
+ *             feature has declared the one OS where the step is known not to work.
+ *   SG-E026 — a click step names a POSITION (`at position "top-left"`, `at offset x=…, y=…`) that
+ *             would not be honoured: the keyword is misspelt, a value is outside the grammar (not a
+ *             number, negative, above 100%, a missing axis, an unknown preset), or another click form
+ *             claimed the step first (`try to click`, a `with {{v}}` text filter, `… and accept [OK]
+ *             alert`). Each of those would compile to a click on the element's CENTRE and pass — for a
+ *             backdrop-dismiss overlay that is the one outcome that proves nothing — so the step
+ *             compiles to a loud throw instead
+ *   SG-W026 — a mobile ACTIVE-NAVIGATION step that emitted NO executable code, so a promised screen
+ *             change never happens. `When User open [Settings] page` compiles to the one-line
+ *             `navigation` template — a comment noting the app was already launched by the wdio
+ *             capabilities — so the step reads as "go to Settings" and goes nowhere. Pair it with a
+ *             `page` assertion (itself a no-op, reported as SG-W022) and the scenario passes without
+ *             ever touching the app. Completes a half-finished class: `route-assertion` already
+ *             throws and `page-assertion` already reports W022; only `navigation` was silent.
+ *             Scoped to the ACTIVE forms (`open [X] page`, `navigate to [X] page`). The `is on [X]
+ *             page|screen` anchor is EXCLUDED on purpose: that is mobile's app-launch directive and
+ *             its empty output is correct, so warning on it would cry wolf on valid features — and a
+ *             diagnostic that cries wolf gets filtered out, taking the real ones with it.
+ *             Like W021/W022/W023 this stays a WARNING by default. `generate --strict` already fails
+ *             on ANY diagnostic, so this code is blocking under it from the day it lands — which
+ *             means a project running --strict today with an `open [X] page` step starts failing.
+ *             That is the intended outcome (the step was never navigating), but it is a migration
+ *             step, not a silent one: the message names the tap/gesture rewrite.
  *   SG-W024 — two or more scenarios in one feature share a name and at least ONE carries a `@reset:`
  *             tag. The generated per-scenario lookup is keyed on the scenario NAME (a @cases title is
  *             built at runtime, so no compile-time key can match the rendered title), so every
@@ -101,6 +168,15 @@
  *             Reported rather than resolved by precedence — two tests genuinely sharing one title
  *             cannot be told apart by a name-keyed lookup, so the only honest fix is a rename. Silently
  *             picking a winner would be the same silent-discard shape as SG-W021
+ *   SG-E027 — a selectors.yaml entry declares a `type:` that is not a selector type at all. YAML is
+ *             untyped at run time, so `type: 'testId'` (capital I), `'xpth'`, `'rol'` or any other
+ *             misspelling used to compile clean and resolve through the strategy switch's
+ *             `default:` branch as `getByPlaceholder('<the value>')` — a locator that cannot
+ *             match, failing much later as a timeout naming placeholder text the author never
+ *             wrote. Checked where the selector FILE is loaded rather than in the switch: `page`
+ *             legitimately reaches that `default:` on every page assertion, and the load point can
+ *             name the entry key and the nearest valid spelling. Reported once per entry, and
+ *             every step naming that entry compiles to a `throw`
  *   SG-E022 — the generated spec is not parseable JS/TS, so NOTHING in the file runs — Playwright
  *             reports one SyntaxError and every scenario in the unit is lost. A compiler self-check
  *             (@babel/parser) on the emitted code, added after a field report where the runtime-data
@@ -109,16 +185,50 @@
  *             compiler, not the Gherkin: it should be impossible, and it is reported so a broken
  *             build names itself at generate time instead of one step further downstream
  *
+ *   SG-W028 — a step's trailing scope clause was DROPPED, so the step runs against more of the page
+ *             than its sentence names. Two causes, one code: the `<word>` after `in [X]` is not a
+ *             container type (a typo, or a leaf element used as a parent), or the by-content form
+ *             `in [X] <type> with {{v}}` was written for the mobile adapter, which chains a parent
+ *             element and has no content filter. Before this, both compiled clean and silently
+ *             widened the assertion to the whole screen — the failure mode that only a diff of the
+ *             generated spec against the Gherkin could reveal (#667)
+ *   SG-W029 — a mobile (appium) feature compiled with NO usable app-package `Path:` — either the line
+ *             is missing outright, or it holds a web-style route (`Path: /applied-jobs`) that the
+ *             package guard rejects. Both used to be silent, and both cost the same two things: the
+ *             per-scenario `beforeEach` was not emitted at all, so Background dropped to Mocha's
+ *             `before()` (once per FILE, every scenario sharing one continuous app session — a tab
+ *             switch or a scroll in one scenario stranding elements off-screen for every later one),
+ *             and the `@reset:` tier ladder went with it, leaving the tag inert. The spec now always
+ *             emits the reset machinery and resolves the app id from the session capability that
+ *             wdio.conf sets, throwing a named error when nothing supplies one — so this is a
+ *             warning about an under-declared feature file, not a broken build (#669)
+ *   SG-W030 — a selectors.yaml `expanded.class`/`expanded.attribute` carries a character outside the
+ *             accepted class/attribute-name set (whitespace, a quote, a backslash, `$`, `{`, `}`).
+ *             The value is pasted into the generated spec (string literal, regex, classList argument),
+ *             and selectors.yaml is often generated from the page under test, so it is refused and the
+ *             field dropped — the step falls back to driving/asserting `aria-expanded`. Reported once
+ *             per entry and field. A WARNING rather than a refusal because the fallback still tests
+ *             something; the checked/selected signal has no fallback and is refused outright instead
+ *
+ *   SG-E031 — a selectors.yaml `checked:`/`selected:` declaration the compiler refuses: the two
+ *             spellings disagree, a class token or attribute name carries whitespace/a quote/a
+ *             backslash, or one entry declares both a class and an attribute. Each is silent at run
+ *             time — the matcher would never match and the step would time out blaming the
+ *             component — so the declaration is refused rather than compiled. Unlike the expanded
+ *             signal (SG-W030) it is not dropped-and-warned: with no signal the step is back on the
+ *             failure the declaration exists to fix. Recorded here AND thrown, so a pattern that
+ *             resolves selectors inside a `catch` cannot swallow it silently
  * Diagnostics never change the EXIT CODE by themselves; `sungen generate --strict` turns any
  * collected diagnostic into a non-zero exit. They are not all inert, though: SG-W001, SG-W011,
- * SG-E020, SG-E021, SG-W020, SG-E023 and SG-E024 additionally compile the offending step to a runtime
- * `throw`, because a step that reads as a check and silently checks nothing is worse than one that
- * fails loudly. (SG-E022 is the one exception to the "blame the Gherkin" rule and throws nothing: the
- * file is still written so the user keeps the artifact to inspect.)
+ * SG-E020, SG-E021, SG-W020, SG-E023, SG-E024, SG-E025, SG-E026 and SG-E027 additionally compile
+ * the offending step to a runtime `throw` — a step that reads as a check and silently checks
+ * nothing is worse than one that fails loudly — and SG-E031 refuses the file outright. (SG-E022 is
+ * the one exception to the "blame the Gherkin" rule and throws nothing: the file is still written
+ * so the user keeps the artifact to inspect.)
  * Generation always COMPLETES — the rest of the scenario and the rest of the file still compile.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-E022' | 'SG-E023' | 'SG-E024';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W004' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-W016' | 'SG-W017' | 'SG-W018' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-W026' | 'SG-E025' | 'SG-E026' | 'SG-E022' | 'SG-E023' | 'SG-E024' | 'SG-E027' | 'SG-W028' | 'SG-W029' | 'SG-W030' | 'SG-E031';
 
 export interface Diagnostic {
   code: DiagnosticCode;
@@ -142,6 +252,7 @@ export class DiagnosticsCollector {
     return this.items.length;
   }
 
+
   /** One line per diagnostic, ready for CLI output. */
   formatLines(): string[] {
     return this.items.map((d) => {

package/src/generators/test-generator/patterns/index.ts

@@ -1,10 +1,13 @@
 import { ParsedStep } from '../../gherkin-parser';
 import { MappedStep } from '../step-mapper';
-import { StepPattern, PatternContext, Platform } from './types';
+import { StepPattern, PatternContext, Platform, StateClause } from './types';
 import { capabilityRegistry } from '../../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 import { maskRefsForMatching } from '../utils/mask-refs-for-matching';
 import { unsupportedStepCode } from './unsupported-step-code';
+import { osSupportOfTemplate } from '../adapters/appium/os-support';
+import { withParentScope } from './with-parent-scope';
+import { escapeSingleQuoted } from '../utils/escape-js-string';
 
 // Both helpers moved out of this file so the Gherkin parser (state-clause extraction) and the
 // step-mapper (SG-W001 no-pattern fallback) can use them without importing the pattern registry.
@@ -31,12 +34,18 @@ const TAP_GESTURE_FORMS = /\bdouble[-\s]?tap|\btap(?:s)?\b[^.]*\b(?:top of|at th
  * The rewrite is ADDITIVE — `tap` becomes `tap click`, it does not become `click`. Two reasons, and
  * the first one cost a full golden run to learn:
  *
- *   1. `@sungen/driver-mobile` is registered on WEB projects too (same non-opt-in bundling as
- *      driver-ui). Substituting the verb re-keys `mobile-tap` onto "click", where its priority 15
- *      outranks the generic `click-element` (10) — so it captured every plain click on every WEB
- *      feature and relabelled it a tap. 8 golden fixtures caught it. Adding a verb instead of
- *      swapping one means text with no "tap" in it is returned untouched, so web output cannot
- *      change here BY CONSTRUCTION rather than by our vigilance.
+ *   1. `@sungen/driver-mobile` can be registered on a WEB project. (It is NOT bundled — an earlier
+ *      version of this comment said it was, which was never true: it is not in `BUNDLED_DRIVERS`
+ *      and not a core dependency. Discovery simply loaded whatever it could resolve, which in this
+ *      monorepo is everything; discovery now gates an opt-in platform driver by the project
+ *      `platform:`, so this reaches web only when both drivers are present and no platform is
+ *      declared.) Substituting the verb re-keys `mobile-tap` onto "click", where its
+ *      priority 15 outranks the generic `click-element` (10) — so it captured every plain click on
+ *      every WEB feature and relabelled it a tap. 8 golden fixtures caught it. Adding a verb instead
+ *      of swapping one means text with no "tap" in it is returned untouched, so web output cannot
+ *      change here BY CONSTRUCTION rather than by our vigilance. `platforms:` does not remove the
+ *      need for that: `mobile-tap` resolves to `click-action`, which both adapters ship, so it is
+ *      one of the two mobile patterns that must stay UNDECLARED.
  *   2. Both vocabularies then see their own verb, and ordinary PRIORITY decides the winner —
  *      no matcher has to learn about the other. `tap … and accept alert` reaches
  *      `click-with-alert` (21); `tap … in [T] table row 2` reaches `table-action-in-row-nth` (19);
@@ -128,6 +137,10 @@ export class PatternRegistry {
     // Matching mirrors findPattern exactly: refs masked FIRST (so `[Tap Water]` is not a
     // verb), then `tap` → `click` normalisation for the mobile vocabulary.
     const matchStep: ParsedStep = { ...step, text: normalizeVerbs(maskRefsForMatching(step.text)) };
+    // The step's parent scope, resolved ONCE for the whole search. Not per candidate pattern: a
+    // resolver may decline and hand the step to the next one, and re-resolving here would report
+    // the mobile by-content refusal (SG-W028) once per attempt instead of once per step.
+    const parentScope = PatternRegistry.resolveParentLocator(step, context);
     for (const pattern of this.patterns) {
       if (!this.matchesPattern(matchStep, pattern.matcher)) continue;
 
@@ -137,12 +150,28 @@ export class PatternRegistry {
       const platformMiss = PatternRegistry.platformMiss(pattern, context, step);
       if (platformMiss) return platformMiss;
 
+      // Shared by BOTH code paths below. The injection used to live inside the resolver branch, so
+      // a `generator` pattern discarded a perfectly parsed scope: `see [Tag] header with {{label}}
+      // in [Job Card] section` routes to `see-with-variable` (a generator) and asserted against the
+      // whole page (#667). Scope that is parsed and then dropped widens the step just as silently
+      // as scope that never parsed at all.
+      // `table-*` patterns opt out by name — they resolve the container from the step text
+      // themselves and would otherwise scope it twice.
+      const parentLocator = pattern.name.startsWith('table-') ? undefined : parentScope;
+      const scoped = parentLocator ? withParentScope(context, parentLocator) : context;
+
       try {
         // Prefer resolver (framework-agnostic) over generator (legacy)
         if (pattern.resolver) {
-          const resolved = pattern.resolver(step, context);
+          const resolved = pattern.resolver(step, scoped);
           if (!resolved) continue; // resolver declined — fall through
 
+          // iOS gate — AFTER the resolver, because it needs the template the step actually reached.
+          // The sibling of platformMiss above: that one refuses a pattern off-platform, this one
+          // refuses a template the declared OS cannot serve.
+          const iosMiss = PatternRegistry.iosUnsupported(resolved.templateName, context, step);
+          if (iosMiss) return iosMiss;
+
           // State-clause gate. Deliberately AFTER the resolver, not before it: a resolver may return
           // null to say "not mine after all", and the search then continues to a lower-priority
           // pattern that may well be the one that asserts the state. Gating earlier judged a pattern
@@ -154,17 +183,16 @@ export class PatternRegistry {
           if (resolverStateMiss) return resolverStateMiss;
 
           // Auto-inject parent scoping if step has parentRef
-          // Skip for table-* patterns — they resolve the table name internally from step text
-          if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
-            resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
-              step.parentRef, step.parentType, context
-            );
-          }
+          if (parentLocator) resolved.data.parentLocator = parentLocator;
 
           const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
+          // The compiler's post-map guards need to know WHICH form won and what it resolved to (e.g.
+          // a refusal a resolver recorded in its data) — without re-matching.
           return {
             code,
             comment: resolved.comment,
+            pattern: pattern.name,
+            templateData: resolved.data,
           };
         }
 
@@ -172,7 +200,9 @@ export class PatternRegistry {
           // A legacy generator has no decline path, so this pattern owns the step already.
           const generatorStateMiss = PatternRegistry.stateMiss(pattern, context, step);
           if (generatorStateMiss) return generatorStateMiss;
-          return pattern.generator(step, context);
+          // A generator returning nothing still falls through to the no-pattern path.
+          const generated = pattern.generator(step, scoped);
+          return generated ? { ...generated, pattern: pattern.name } : null;
         }
 
         return null;
@@ -190,6 +220,45 @@ export class PatternRegistry {
   /**
    * SG-W020 — the matched pattern declares `platforms` and the active one is not among them.
    */
+  /**
+   * SG-E025 — the feature says `@platform:ios`, and the template it reached does not work there.
+   *
+   * Derived from the template body (`osSupportOfTemplate`), never from a list, so it cannot drift
+   * from the adapter the way a hand-kept table would. Two states are refused, for different
+   * reasons: `refuses` would throw deep inside a device run instead of at compile time, and `noop`
+   * would not fail at all — the step would run, do nothing, and the scenario would pass.
+   *
+   * Only an EXPLICIT `@platform:ios` is gated. `@platform:mobile` picks its OS from
+   * MOBILE_PLATFORM at run time, so gating it would mean guessing; the per-OS matrix columns are
+   * what cover that case, and they are the primary deliverable of this axis.
+   */
+  private static iosUnsupported(
+    templateName: string, context: PatternContext, step: ParsedStep
+  ): MappedStep | null {
+    if (context.featurePlatform !== 'ios') return null;
+    if ((context.platform ?? 'web') !== 'mobile') return null;
+
+    const pair = osSupportOfTemplate(templateName);
+    // No appium template of that name is a different failure, already reported by template
+    // resolution — a second message here would give one cause two names.
+    if (!pair || pair.ios === 'yes' || pair.ios === 'inherit') return null;
+
+    const why = pair.ios === 'noop'
+      ? 'does nothing on iOS — it is guarded out with no error, so the step would run and the scenario would PASS having done nothing'
+      : 'throws on iOS — the template refuses there, so the failure would surface deep inside a device run instead of here';
+    const reason =
+      `step "${step.text}" compiles to \`${templateName}\`, which ${why}. ` +
+      `This feature declares @platform:ios. Either drop to @platform:android (the OS that serves this step), ` +
+      `move the step out of the iOS feature, or tag the scenario @manual:M10 (device/OS capability). ` +
+      `See the Android/iOS columns in docs/spec/step-support-matrix.md.`;
+
+    context.diagnostics?.add('SG-E025', reason, { feature: context.featureName, step: step.text });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `iOS-unsupported step in an @platform:ios feature — see SG-E025`,
+    };
+  }
+
   private static platformMiss(
     pattern: StepPattern, context: PatternContext, step: ParsedStep
   ): MappedStep | null {
@@ -241,7 +310,8 @@ export class PatternRegistry {
       `("${pattern.name}") does not assert that state — the clause would be SILENTLY DROPPED and the ` +
       `step would check something other than what it reads as. Use a step form that owns the state ` +
       `(e.g. "User see [Ref] <type> is ${state}" on the element itself), or drop the clause if the ` +
-      `bare assertion is what you meant. If sungen cannot express the check, tag the scenario @manual.`;
+      `bare assertion is what you meant. If sungen cannot express the check, tag the scenario @manual.` +
+      PatternRegistry.stateMissSkewHint(pattern, state);
 
     context.diagnostics?.add('SG-E021', reason, {
       feature: context.featureName,
@@ -253,6 +323,23 @@ export class PatternRegistry {
     };
   }
 
+  /**
+   * The one SG-E021 that is NOT the author's to fix. A pattern NAMED for the state (`is-hidden`,
+   * `should-be-disabled`) that declares no `states` at all is not under-annotated — it is a driver
+   * built before the field existed, loaded against a core that requires it (a stale project copy of
+   * @sungen/driver-ui). The generic message then tells the author to use the exact form they wrote,
+   * which cost a QA team a day of Gherkin rewrites that could never work. Name the real cause.
+   */
+  private static stateMissSkewHint(pattern: StepPattern, state: StateClause): string {
+    const namesTheState = pattern.name.includes(state.replace(/\s+/g, '-'));
+    if (pattern.states !== undefined || !namesTheState) return '';
+    return (
+      ` NOTE: "${pattern.name}" is named for this very state yet declares no states at all — that is a ` +
+      `@sungen/driver-* package older than sungen itself, not a Gherkin problem. Run \`sungen update\` in the ` +
+      `project so the drivers match the sungen version, then generate again.`
+    );
+  }
+
   /**
    * SG-E020 — the pattern is in-platform but the active adapter ships no template for it. A gap in
    * the adapter, not in the authored Gherkin: name every coordinate a reader needs to act on it.
@@ -277,14 +364,23 @@ export class PatternRegistry {
   }
 
   /**
-   * Resolve parent scoping to a Playwright locator string.
-   * Tries YAML lookup first, falls back to auto-infer from parentType.
+   * Resolve a step's `in [Parent] <type> [with <value>]` scope to a locator string, or `undefined`
+   * when the step carries no scope.
    *
-   * Parent type → Playwright role:
-   *   table → 'table', list → 'list', section → 'region',
-   *   dialog → 'dialog', form → 'form'
+   * Tries YAML lookup first, falls back to auto-inferring a role from the container type with the
+   * reference as the accessible name. A reference written as `{{var}}` is resolved through
+   * test-data before it reaches that name — containers are routinely labelled with the text under
+   * test, and a literal `{{var}}` in the name matches nothing.
    */
-  private static resolveParentLocator(
+  private static resolveParentLocator(step: ParsedStep, context: PatternContext): string | undefined {
+    const { parentRef, parentType } = step;
+    if (!parentRef || !parentType) return undefined;
+
+    const base = PatternRegistry.parentContainerLocator(parentRef, parentType, context);
+    return PatternRegistry.filterParentByValue(base, step, context);
+  }
+
+  private static parentContainerLocator(
     parentRef: string, parentType: string, context: PatternContext
   ): string {
     // Try resolving from selectors YAML
@@ -300,13 +396,68 @@ export class PatternRegistry {
     const roleMap: Record<string, string> = {
       table: 'table',
       list: 'list',
+      'list-item': 'listitem',
+      listitem: 'listitem',
+      item: 'listitem',
+      row: 'row',
       section: 'region',
+      container: 'region',
+      panel: 'region',
+      card: 'region',
+      group: 'group',
       dialog: 'dialog',
+      modal: 'dialog',
+      drawer: 'dialog',
+      overlay: 'dialog',
       form: 'form',
+      tab: 'tabpanel',
+      menu: 'menu',
     };
     const role = roleMap[parentType] || parentType;
-    const escapedName = parentRef.replace(/'/g, "\\'");
-    return `page.getByRole('${role}', { name: '${escapedName}' })`;
+    const name = escapeSingleQuoted(PatternRegistry.resolveInlineData(parentRef, context));
+    return `page.getByRole('${role}', { name: '${name}' })`;
+  }
+
+  /**
+   * Narrow the container to the ONE whose content matches the step's parent value — the
+   * `with {{job_title}}` tail of `see [Tag] header with {{label}} in [Job Card] card with
+   * {{job_title}}`. Without it a list of identical cards leaves the assertion matching whichever
+   * one Playwright reaches first.
+   *
+   * Web-only, and refused rather than approximated elsewhere: the Appium partial chains a parent
+   * with `$()`, which has no content filter, so emitting one would be invalid code and pretending
+   * the scope applied would be the very silence this whole fix exists to end (SG-W028).
+   */
+  private static filterParentByValue(
+    base: string, step: ParsedStep, context: PatternContext
+  ): string {
+    const raw = step.parentValueRef
+      ? PatternRegistry.resolveInlineData(`{{${step.parentValueRef}}}`, context)
+      : step.parentValueText;
+    if (raw === undefined) return base;
+
+    if (context.platform === 'mobile') {
+      context.diagnostics?.add('SG-W028',
+        `scoping a container BY CONTENT ("in [${step.parentRef}] ${step.parentType} with …") is web-only — the mobile adapter chains a parent element, which has no content filter, so this step would search every ${step.parentType} on the screen. Give the container an accessibility id that identifies it and scope by that instead, or assert on the element the value belongs to`,
+        { feature: context.featureName, step: step.text });
+      return base;
+    }
+    return `${base}.filter({ hasText: '${escapeSingleQuoted(raw)}' })`;
+  }
+
+  /**
+   * Resolve a `{{var}}` written where literal text is expected, leaving anything else untouched.
+   * An unknown variable stays as written rather than throwing — the locator is then wrong in a way
+   * the author can read, which beats losing the whole step.
+   */
+  private static resolveInlineData(text: string, context: PatternContext): string {
+    const match = text.match(/^\{\{([a-z0-9\-._]+)\}\}$/i);
+    if (!match) return text;
+    try {
+      return context.dataResolver.resolveData(match[1], context.featureName);
+    } catch {
+      return text;
+    }
   }
 
   /**

package/src/generators/test-generator/patterns/types.ts

@@ -84,6 +84,14 @@ export interface PatternContext {
   effectiveKeyword?: string;
   /** The platform the ACTIVE adapter compiles for. Absent = 'web' (back-compat default). */
   platform?: Platform;
+  /**
+   * The OS the FEATURE declares via `@platform:<mobile|android|ios>` — distinct from `platform`
+   * above, which is the adapter. Only `ios` is actionable at compile time: it is the single case
+   * where the compiler knows which mobile OS will run, so it can refuse a step that does nothing
+   * (or throws) there. `mobile` means both OSes and is deliberately NOT gated — the real OS is
+   * chosen at run time by MOBILE_PLATFORM, so a compile-time verdict would be a guess.
+   */
+  featurePlatform?: 'mobile' | 'android' | 'ios';
   /** The adapter's own name ('playwright' | 'appium' | …) — quoted verbatim in SG-E020/SG-W020. */
   adapterName?: string;
   /** Compile-diagnostics channel, so the pattern layer can report instead of throwing. */

package/src/generators/test-generator/patterns/with-parent-scope.ts

@@ -0,0 +1,41 @@
+import { PatternContext } from './types';
+
+/**
+ * Return a `PatternContext` in which every selector the pattern resolves comes back already scoped
+ * to `parentLocator`.
+ *
+ * Why a wrapped context rather than one assignment. A `resolver` pattern hands its template data
+ * back to the registry, which can stamp `parentLocator` on it; a `generator` pattern renders its own
+ * code and never exposes that object, so the registry had no seam and the scope was simply lost
+ * (#667). The seam both kinds share is where they ASK for a selector — `selectorResolver` and
+ * `renderLocator` — so the scope is attached there instead, and every locator partial (Playwright
+ * and Appium alike) already knows what to do with a `parentLocator` field.
+ *
+ * Only the target's own scope is stamped; anything a pattern resolves that ALREADY carries a
+ * `parentLocator` is left alone, so a pattern that builds its own container chain (table rows) keeps
+ * winning over the generic one.
+ */
+export function withParentScope(context: PatternContext, parentLocator: string): PatternContext {
+  const scope = <T>(resolved: T): T =>
+    resolved && typeof resolved === 'object' && !(resolved as any).parentLocator
+      ? { ...(resolved as any), parentLocator }
+      : resolved;
+
+  // A Proxy rather than a copy: SelectorResolver carries more than the one method patterns call,
+  // and a hand-written stand-in would silently drop whatever it forgot.
+  const selectorResolver = new Proxy(context.selectorResolver, {
+    get(target, prop, receiver) {
+      if (prop === 'resolveSelector') {
+        return (...args: unknown[]) => scope((target as any).resolveSelector(...args));
+      }
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+
+  return {
+    ...context,
+    selectorResolver,
+    renderLocator: (resolved: any) => context.renderLocator(scope(resolved)),
+  };
+}