@sun-asterisk/sungen 3.2.31 → 3.2.33

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

@@ -186,12 +186,29 @@
  *             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
+ *             than its sentence names. Three 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)
+ *             generated spec against the Gherkin could reveal (#667).
+ *             The third is the RENDER-time half #667 could not reach: the clause parsed and the
+ *             container resolved, but the step form that won the sentence emits a locator built
+ *             inline and never applies it. Judged on the emitted code — every path that honours a
+ *             scope emits the resolved container locator verbatim, so its absence IS the drop —
+ *             which makes the check total rather than a list of templates to keep in sync. Found
+ *             via `see [学科] label with {{v}} in [Education Card 6] card` compiling to a page-wide
+ *             `getByText` on a screen repeating ten identical cards (#747)
+ *   SG-W037 — a `type: page` entry says something about the QUERY that the compiler cannot use.
+ *             Two causes, one code, and the same root confusion behind both: a bare `see [X] page`
+ *             asserts the URL carries NO query (#464), which is unsatisfiable for a page keyed by
+ *             one (`/admins/detail?id=5`, where the id comes from the row just clicked). Either the
+ *             entry's `value` carries a `?`/`#` — dropped, because a page value is the path only and
+ *             the pattern is matched against `u.pathname`, which never holds a query — or `query:`
+ *             declares something other than `any`, which is ignored rather than read as permissive,
+ *             since a typo must never quietly switch off the #464 assertion. Both used to be silent,
+ *             and the first is how #748 was misdiagnosed in the field as a regex-escaping bug: the
+ *             obvious workaround produced byte-identical output and no hint why
  *   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
@@ -218,9 +235,58 @@
  *             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
+ *   SG-W032 — a step carries the row filter `in [T] table with {{v}}` but the pattern that won it
+ *             dropped the clause, so the generated code runs against the WHOLE table. Reproduced
+ *             live: `Then User see [Status] text in [Job Table] table with {{v}}` asserts on every
+ *             `.status` in the table and passes on a row the sentence never named. Judged on the
+ *             emitted code — row scoping compiles to `.filter(` on every path that honours it — so
+ *             the `table-*` family (which resolves the container itself, positioned rows included)
+ *             and steps already refused elsewhere are excluded, as is the two-`with` form, which
+ *             binds its tail to the parent and is the rewrite this message points at. A step that
+ *             WRITES is excluded too: a write needs a value, so its `with {{v}}` IS that value and
+ *             cannot also be a row filter — `fill [Search] field in [T] table with {{v}}` is an
+ *             ordinary container-scoped write
+ *   SG-W034 — a `see [X] column with {{v}}` step runs inside a table whose rows are declared with a
+ *             `rows:` SHAPE, so the row is not an ARIA row and holds no ARIA cells — yet the
+ *             assertion's only other way to reach a cell is `getByRole('cell')`, which matches
+ *             nothing there. `columns.<col>.index` cannot rescue it either: it indexes that same
+ *             empty set. Silent before this, and silent in the worst way — `toBeVisible()` on an
+ *             empty locator fails as a timeout blaming the app. The message names the
+ *             `columns.<col>.elements.cell` declaration that resolves the cell directly. Scoped to
+ *             the `rows:` case on purpose: on a real <table> the role fallback is correct, and a
+ *             diagnostic that fires on the correct spelling gets muted along with the real ones
+ *   SG-E035 — `table match data:` on a table whose rows are declared with a `rows:` SHAPE and whose
+ *             columns are not declared (or do not cover every column of the DataTable). The
+ *             assertion reads the header row from `thead tr` and addresses cells as `td, th`;
+ *             a list built from <div>s has neither, forever — not a render race — so the step can
+ *             only wait out every timeout and fail on an empty header row. Refused at compile time
+ *             instead, naming the `columns:` entries it needs. Declaring them replaces the runtime
+ *             header read entirely: the index is known at compile time, and a column that names
+ *             its own `elements.cell` addresses the cell without any table role at all
+ *   SG-W036 — a `remember [X] … as {{v}}` capture whose entry selects by SHAPE (`locator`/`css`)
+ *             and pins no `nth:`. A capture reads ONE element and the template takes the first
+ *             match — the right default, and exactly what the documented `nth: 0` workaround asked
+ *             for after Playwright's strict mode turned a list-shaped selector into a hard failure
+ *             naming the count instead of the step. But "the first of many" is a decision: if the
+ *             selector describes every item in a list, the captured value is the first row's rather
+ *             than the one the scenario means, and nothing else would ever say so. Not reported for
+ *             testid/label/placeholder/role+name/text entries, which name a particular thing —
+ *             warning there would fire on nearly every capture in a suite
+ *   SG-E038 — a `{{var}}` the compiler cannot resolve: no test-data file for the feature, no such
+ *             key, or a key holding a list/map where a value was needed. Twenty-four step patterns
+ *             used to catch this and emit the PLACEHOLDER TEXT as the value — `fill [ID] with
+ *             {{valid_partner_id}}` compiled to `fill('${valid_partner_id}')`, generate exited 0,
+ *             and the literal 20 characters were typed into the app. The field under test applied
+ *             no format validation, so the string was accepted, the server saw an unknown user, and
+ *             the scenario failed at the assertion it was written to fail at, for the reason it was
+ *             written to fail: a suite that looked exactly right while feeding the system garbage.
+ *             Worse than one wrong value — every run shared the SAME literal id, so a scenario
+ *             needing a fresh user silently reused one and its state leaked between runs (#781).
+ *             Note a feature resolves `{{var}}` against a data file named after ITSELF, so the
+ *             second `.feature` in a screen directory starts life with no data file at all
  * 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, SG-E024, SG-E025, SG-E026 and SG-E027 additionally compile
+ * SG-E020, SG-E021, SG-W020, SG-E023, SG-E024, SG-E025, SG-E026, SG-E027, SG-E035 and SG-E038 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
@@ -228,7 +294,7 @@
  * 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-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 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' | 'SG-W032' | 'SG-W034' | 'SG-E035' | 'SG-W036' | 'SG-W037' | 'SG-E038';
 
 export interface Diagnostic {
   code: DiagnosticCode;

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

@@ -48,7 +48,7 @@ const TAP_GESTURE_FORMS = /\bdouble[-\s]?tap|\btap(?:s)?\b[^.]*\b(?:top of|at th
  *      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);
+ *      `click-with-alert` (21); `tap … in [T] table row 2` reaches `table-action-in-row-nth` (18);
  *      a plain `tap` still lands on `mobile-tap` (15) ahead of `click-element` (10).
  *
  * Safe because every click-keyed matcher in the vocabulary is a word-boundary test (`\bclick(s)?\b`
@@ -193,6 +193,7 @@ export class PatternRegistry {
             comment: resolved.comment,
             pattern: pattern.name,
             templateData: resolved.data,
+            parentLocator,
           };
         }
 
@@ -202,7 +203,7 @@ export class PatternRegistry {
           if (generatorStateMiss) return generatorStateMiss;
           // 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 generated ? { ...generated, pattern: pattern.name, parentLocator } : null;
         }
 
         return null;
@@ -447,17 +448,23 @@ export class PatternRegistry {
 
   /**
    * 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.
+   *
+   * An unresolvable ref is NOT kept as written. That was the last of the #781 swallows, and the
+   * hardest to see, because the old rationale — "the locator is then wrong in a way the author can
+   * read, which beats losing the whole step" — is true of a locator NAME and false here. The second
+   * `with` in `see [Tag] header with {{label}} in [Job Card] card with {{job_title}}` binds to the
+   * PARENT scope, so the value lands in `.filter({ hasText: '{{job_title}}' })`: a scope that can
+   * never match, compiled with ZERO diagnostics and `generate` exiting 0. The author then reads a
+   * "element not found" timeout that says nothing about the missing test-data key.
+   *
+   * Letting it throw routes it to StepMapper.mapStep like every other ref, so the step names the
+   * ref and the file it wanted. Only a string that IS exactly `{{ref}}` is ever resolved here;
+   * anything else is returned untouched, so ordinary literal text is unaffected.
    */
   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;
-    }
+    return context.dataResolver.resolveData(match[1], context.featureName);
   }
 
   /**

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

@@ -96,6 +96,21 @@ export interface PatternContext {
   adapterName?: string;
   /** Compile-diagnostics channel, so the pattern layer can report instead of throwing. */
   diagnostics?: DiagnosticsSink;
+  /**
+   * The container locator the step's `in [Parent] <type>` clause resolved to, already rendered —
+   * set by `withParentScope`, absent when the step carries no scope clause.
+   *
+   * `withParentScope` also stamps this onto everything the pattern RESOLVES, which is the seam that
+   * serves the ordinary case. It is not enough on its own: a pattern whose locator is not built from
+   * a selectors.yaml entry never has a `resolved` object to carry it. `see [学科] label with {{v}}`
+   * is exactly that — the ref names on-screen CAPTION text, so the common case has no entry at all,
+   * `resolveSelector` throws, and the branch renders from `{}`. The scope was then dropped with no
+   * diagnostic (#747), which is the silence #667 set out to end.
+   *
+   * Read it ONLY where the template's locator is built inline rather than from `resolved`; every
+   * other pattern gets the scope through `resolved` and must not apply it twice.
+   */
+  parentLocator?: string;
   /** App profile (qa/app.yaml merged over presets/defaults) — widget variants, recipes,
    *  loading indicator, table row conventions. Typed loosely to keep the SPI decoupled;
    *  the concrete shape is ResolvedAppProfile. */

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

@@ -14,6 +14,11 @@ import { PatternContext } from './types';
  * 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.
+ *
+ * The scope also rides on the CONTEXT itself, not only on what the pattern resolves. A pattern whose
+ * locator is built inline — `see [X] label with {{v}}` matches on-screen caption text and usually
+ * has no selectors.yaml entry at all, so `resolveSelector` throws and the branch renders from `{}` —
+ * has no `resolved` object for the stamp to land on, and lost the scope silently (#747).
  */
 export function withParentScope(context: PatternContext, parentLocator: string): PatternContext {
   const scope = <T>(resolved: T): T =>
@@ -35,6 +40,7 @@ export function withParentScope(context: PatternContext, parentLocator: string):
 
   return {
     ...context,
+    parentLocator,
     selectorResolver,
     renderLocator: (resolved: any) => context.renderLocator(scope(resolved)),
   };

package/src/generators/test-generator/step-mapper.ts

@@ -3,8 +3,8 @@ import { PARENT_CONTAINER_TYPES } from '../gherkin-parser/parent-scope-clause';
 import { TemplateEngine } from './template-engine';
 import { adapterRegistry } from './adapters';
 import { PatternRegistry, PatternContext, Platform } from './patterns';
-import { SelectorResolver } from './utils/selector-resolver';
-import { DataResolver } from './utils/data-resolver';
+import { SelectorResolver, type ResolvedSelector } from './utils/selector-resolver';
+import { DataResolver, DataRefError } from './utils/data-resolver';
 import { locatorIdentityKey } from './utils/dialog-scope-identity';
 import { DiagnosticsCollector } from './diagnostics';
 import { unsupportedStepCode } from './patterns/unsupported-step-code';
@@ -44,6 +44,9 @@ export interface MappedStep {
   imports?: string[]; // Required imports
   pattern?: string; // Name of the step form that produced the code (post-map guards read it)
   templateData?: Record<string, any>; // What the resolver handed the template (e.g. a recorded refusal)
+  /** The container locator the step's `in [Parent] <type>` clause resolved to, when it carried one.
+   *  Recorded so a post-map guard can check the scope actually reached the code (SG-W028, #747). */
+  parentLocator?: string;
 }
 
 /**
@@ -226,7 +229,45 @@ export class StepMapper {
    * Map a Gherkin step to Playwright code
    * Uses pattern registry first, falls back to AI if enabled
    */
+  /**
+   * SG-E038 — the ONE place an unresolvable `{{var}}` is answered.
+   *
+   * Twenty-four step patterns used to catch the resolver's failure each in their own way and
+   * substitute the placeholder TEXT as the value, so `fill [ID] with {{valid_partner_id}}` shipped
+   * `fill('${valid_partner_id}')` — 20 literal characters typed into the app, `generate` exiting 0,
+   * and a scenario that failed exactly where it was written to fail, for the reason it was written
+   * to fail. Nothing told the run apart from a correct one (#781).
+   *
+   * The step now compiles to a throw naming the ref and the file, which is the house answer to
+   * "the compiler would otherwise invent something" (SG-E023/E024/E026 all work this way). A throw
+   * is preferred over letting the error kill the feature file, because one run then reports EVERY
+   * unresolved ref instead of the first; `--strict` turns the diagnostic into exit 1.
+   */
   mapStep(step: ParsedStep): MappedStep | Promise<MappedStep> {
+    try {
+      return this.mapStepResolving(step);
+    } catch (err) {
+      if (err instanceof DataRefError) return this.unresolvedDataRef(step, err);
+      throw err;
+    }
+  }
+
+  private unresolvedDataRef(step: ParsedStep, err: DataRefError): MappedStep {
+    const fix = err.file
+      ? `add a "${err.dataRef}" key to ${err.file}`
+      : `define "${err.dataRef}" in the feature's test-data file`;
+    const reason =
+      `step "${step.text}": {{${err.dataRef}}} does not resolve — ${err.message}. `
+      + `${fix}, or reference a key that exists. The step compiles to this throw rather than `
+      + `typing the literal text "\${${err.dataRef}}" into the app as if it were data.`;
+    this.diagnostics?.add('SG-E038', reason, { feature: this.featureName, step: step.text });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `Unresolved {{${err.dataRef}}} — see SG-E038: ${step.text}`,
+    };
+  }
+
+  private mapStepResolving(step: ParsedStep): MappedStep | Promise<MappedStep> {
     this.stepCounter++;
 
     // Track effective keyword: And/But inherit from previous Given/When/Then
@@ -377,12 +418,7 @@ export class StepMapper {
         // Case 3: [panel] dialog with {{value}}
         // Use dataRef as filter text — the dialog name is dynamic (from test-data),
         // so use .filter({ hasText }) instead of { name } for reliable matching
-        let filterText = '';
-        try {
-          filterText = this.dataResolver.resolveData(step.dataRef, this.featureName);
-        } catch {
-          filterText = `\${${step.dataRef}}`;
-        }
+        const filterText = this.dataResolver.resolveData(step.dataRef, this.featureName);
         contextVars.dialogFilterText = filterText;
         // The declared entry still owns the ROOT the filter applies to — but only when it
         // is a non-role strategy (locator/testid/css). A role entry keeps the bare
@@ -470,8 +506,14 @@ export class StepMapper {
       if (positionDropped) return positionDropped;
       const swallowed = this.checkAssertionClauseSwallowed(step, mappedStep);
       if (swallowed) return swallowed;
+      const rowFilterDropped = this.checkRowFilterClauseDropped(step, mappedStep);
+      if (rowFilterDropped) return rowFilterDropped;
       const badType = this.checkUnknownSelectorType(step, mappedStep);
       if (badType) return badType;
+      // LAST of the guards, and deliberately so: every check above can REPLACE the step with a
+      // refusal, and reporting a dropped scope against code that is about to be discarded is the
+      // "two contradictory messages about one step" this guard's own doc rules out.
+      this.checkParentScopeDropped(step, mappedStep);
       return mappedStep;
     }
 
@@ -680,6 +722,112 @@ export class StepMapper {
     };
   }
 
+  /**
+   * The `in [T] table with {{v}}` row filter is the sentence's narrowest claim — it names ONE row.
+   * A pattern that does not consume it leaves the step running against the WHOLE table, and the
+   * author cannot see that from the Gherkin.
+   *
+   * Judged on the emitted code, not on which pattern won: `.filter(` is what row scoping compiles
+   * to on every path that honours the clause, so its absence is the fact. Three exclusions, each
+   * measured rather than assumed:
+   *   - the `table-*` family resolves the container from the step text itself; its positioned-row
+   *     form emits `toHaveCount(1)` + `toContainText` with no filter at all and is CORRECT;
+   *   - a step already refused elsewhere compiles to a `throw`, and a second opinion on top of the
+   *     refusal (an off-platform table step already gets SG-W020) is two contradictory messages
+   *     about one step;
+   *   - the two-`with` form binds its tail to the PARENT, which does compile to a filter — it is
+   *     the shape this diagnostic points people at, so it must never be flagged.
+   *
+   * A step that WRITES is exempt rather than escalated — see ROW_FILTER_WRITE_CALL. It stays a
+   * WARNING for the rest, in line with the repo's rule that a diagnostic which cries wolf gets muted
+   * wholesale: the single-`with` sentence is genuinely ambiguous, and reading the value as the
+   * expected text is a legitimate compilation of it, just not the one most authors mean.
+   */
+  private static readonly ROW_FILTER_CLAUSE = /\bin\s+\[[^\]]+\]\s+table\s+with\b/i;
+
+  /**
+   * Calls that WRITE through the scoped locator, as opposed to reading it. Both adapters are listed:
+   * the mobile spelling of a fill is `setValue`/`addValue`.
+   *
+   * A write is EXEMPT, not escalated. A step that writes needs a value, so its `with {{v}}` is that
+   * value and cannot also be a row filter — `fill [Search] field in [Job Table] table with {{v}}` is
+   * an ordinary container-scoped write, and a toolbar search box inside a table is exactly that. The
+   * danger an earlier reading claimed for it does not exist either: on a multi-row table a
+   * mis-scoped write is a loud strict-mode failure, and on a single-row table there is only one
+   * field to write to.
+   */
+  private static readonly ROW_FILTER_WRITE_CALL =
+    /\.(?:fill|type|setInputFiles|selectOption|clear|check|uncheck|press|setValue|addValue|clearValue)\(/;
+
+  private checkRowFilterClauseDropped(step: ParsedStep, mapped: MappedStep): MappedStep | null {
+    const code = mapped.code || '';
+    if (!StepMapper.ROW_FILTER_CLAUSE.test(step.text)) return null;
+    // Bound to the parent instead of the target — that IS the scoped form.
+    if (step.parentValueRef || step.parentValueText) return null;
+    if (mapped.pattern?.startsWith('table-')) return null;
+    if (code.startsWith('throw new Error(')) return null;
+    if (/\.filter\(/.test(code)) return null;
+
+    if (StepMapper.ROW_FILTER_WRITE_CALL.test(code)) return null;
+
+    const table = step.parentRef ?? 'Table';
+    const target = step.selectorRef ?? 'X';
+    const type = step.elementType ?? 'text';
+    const filter = step.dataRef ? `{{${step.dataRef}}}` : 'the row value';
+    const rewrite = `User see [${target}] ${type} with <expected> in [<Row Entry>] row with ${filter}`;
+    this.diagnostics?.add('SG-W032',
+      `step "${step.text}" reads "with ${filter}" as the EXPECTED VALUE, not as a row filter — the `
+      + `sentence names a row but the assertion runs against the whole [${table}] table, so it can `
+      + `pass on a row the sentence never named. To scope the row, use the two-"with" form: `
+      + `"${rewrite}". Point that second \`[…]\` at a ROW entry, not at the table entry — a filter `
+      + `applied to the table narrows nothing and the assertion stays as weak as it is now.`,
+      { feature: this.featureName, step: step.text });
+    return null;
+  }
+
+  /**
+   * The container scope parsed, resolved — and then never reached the emitted code.
+   *
+   * #667 closed the parse-time half of this: an `in [X] <word>` whose `<word>` is not a container
+   * type is reported (SG-W028) rather than truncated. It could not close the render-time half,
+   * because honouring the scope is per-template work: the registry stamps `parentLocator` on what a
+   * RESOLVER hands back and `withParentScope` stamps it on what any pattern RESOLVES, but a branch
+   * that builds its locator inline and renders from hand-picked fields receives neither. Three did,
+   * and `see [学科] label with {{v}} in [Education Card 6] card` compiled to a page-wide
+   * `getByText` with no diagnostic at all (#747) — a green test reading a card the sentence never
+   * names, findable only by diffing the generated spec against the Gherkin.
+   *
+   * So the fact is taken from the OUTPUT, exactly as SG-W032 takes the row filter from `.filter(`:
+   * every path that honours a container scope emits the resolved container locator verbatim, so its
+   * absence from the code IS the drop. That makes the guard total — it covers every template that
+   * exists now and every one added later, without a list to keep in sync.
+   *
+   * A step already refused elsewhere is excluded: it compiles to a `throw`, and a second opinion on
+   * top of a refusal is two contradictory messages about one step (SG-W032's reasoning, unchanged).
+   * The `throw` test covers a refusal the PATTERN layer recorded; a refusal one of the guards above
+   * substitutes is covered by call order instead — this one runs last.
+   *
+   * Returns `void`, not `MappedStep | null` like its siblings: it only ever REPORTS. Typed that way
+   * on purpose, so a future edit copying the sibling shape cannot assume a replacement step is being
+   * consumed when nothing is looking at one.
+   */
+  private checkParentScopeDropped(step: ParsedStep, mapped: MappedStep): void {
+    const parent = mapped.parentLocator;
+    if (!parent) return;
+    const code = mapped.code || '';
+    if (code.startsWith('throw new Error(')) return;
+    if (code.includes(parent)) return;
+
+    this.diagnostics?.add('SG-W028',
+      `step "${step.text}" names the container [${step.parentRef}] but the generated code does not `
+      + `scope to it — the step runs against the WHOLE page, so it fails where the target repeats and `
+      + `passes on a DIFFERENT [${step.parentRef}] where it does not. The "${mapped.pattern}" step `
+      + `form does not carry a container scope. Assert on an element the container owns (give it a `
+      + `selectors.yaml entry and use "has text"/"contains"), or drop the clause so the sentence `
+      + `matches what is actually checked.`,
+      { feature: this.featureName, step: step.text });
+  }
+
   private checkAssertionClauseSwallowed(step: ParsedStep, mapped: MappedStep): MappedStep | null {
     const code = mapped.code || '';
     // Bare visibility: nothing but a visible/displayed assertion on one locator.
@@ -766,7 +914,6 @@ export class StepMapper {
     // delimiters, so the code may carry `__SUNGEN_TD\$key\$__` instead of the plain form.
     const marker = DataResolver.encodeMarker(step.dataRef);
     if (code.includes(marker) || code.includes(marker.replace(/\$/g, '\\$'))) return;
-    if (code.includes(`\${${step.dataRef}}`)) return;                    // unresolved fallback
     if (code.includes(step.dataRef)) return;                             // testData.set('ref'), comments
     try {
       const value = this.dataResolver.resolveData(step.dataRef, this.featureName);
@@ -804,21 +951,57 @@ export class StepMapper {
 
     // Try to find column index from table's columns config
     let columnIndex: number | undefined;
+    // The CELL, when the table declares one. `getByRole('cell')` below is the only other way this
+    // template can reach a cell, and a row shape built from <div>s has no cell role anywhere in it
+    // — the assertion then matches zero elements on a list that renders perfectly well. A
+    // `columns.<col>.elements.cell` entry names the cell directly and sidesteps the role entirely.
+    // `columns.<col>.index` cannot help there: it indexes the very getByRole('cell') set that is
+    // empty.
+    let cellLocator: string | undefined;
     if (this.rowScopeTable) {
+      // Only the table LOOKUP is guarded. Widening the catch to cover the cell resolution below
+      // would swallow a broken `elements.cell` declaration under a comment about a missing table,
+      // and silently serve the ARIA fallback with no diagnostic at all.
+      let tableResolved: ResolvedSelector | undefined;
       try {
-        const tableResolved = this.selectorResolver.resolveSelector(
+        tableResolved = this.selectorResolver.resolveSelector(
           this.rowScopeTable, this.featureName, 'table', 0
         );
-        const columnKey = columnRef.toLowerCase().normalize('NFC');
-        columnIndex = tableResolved.columns?.[columnKey]?.index;
       } catch {
         // Table not found — fallback to filter
       }
+      if (tableResolved) {
+        const columnKey = columnRef.toLowerCase().normalize('NFC');
+        const column = tableResolved.columns?.[columnKey];
+        columnIndex = column?.index;
+        const cellEntry = column?.elements?.cell;
+        // A shape that still selects <tr> keeps its ARIA rows and cells, so the role fallback below
+        // serves it exactly as before. Only a shape built from something else loses them.
+        const shapeHidesTableRoles = !!tableResolved.rows
+          && !/(^|[\s>+~,(])tr\b/i.test(tableResolved.rows);
+        if (cellEntry) {
+          cellLocator = this.templateEngine.renderStep('locator', {
+            ...this.selectorResolver.resolveNestedEntry(cellEntry, columnRef),
+            parentLocator: 'tableRow',
+          });
+        } else if (shapeHidesTableRoles) {
+          // The rows are not ARIA rows, so their children are not ARIA cells either. Warned only in
+          // that case: on a real <table> — including one that pins its row universe with
+          // `rows: 'tbody tr'` — the role fallback is correct, and a diagnostic that fires on the
+          // correct spelling gets muted along with the real ones.
+          this.diagnostics?.add('SG-W034',
+            `column "[${columnRef}]" is asserted inside a table whose rows are declared with a "rows:" `
+            + `shape, so the row is not an ARIA row and holds no ARIA cells — this step falls back to `
+            + `getByRole('cell'), which matches nothing there. Name the cell on the column, e.g. `
+            + `"${this.rowScopeTable.toLowerCase()}:\\n  columns:\\n    ${columnKey}:\\n      index: 0\\n      header: '${columnRef}'\\n      elements:\\n        cell:\\n          type: locator\\n          value: '.your-cell-class'"`,
+            { feature: this.featureName, step: step.text });
+        }
+      }
     }
 
     const isGiven = this.lastPrimaryKeyword === 'Given';
     const code = this.templateEngine.renderStep('row-scoped-column-assertion', {
-      columnIndex, cellValue, isGiven,
+      columnIndex, cellValue, isGiven, cellLocator,
     });
 
     return {

package/src/generators/test-generator/template-engine.ts

@@ -53,6 +53,24 @@ export class TemplateEngine {
         .replace(/\u2029/g, '\\u2029');
     });
 
+    // The CSS selector behind an `id` strategy, from whichever field carries it.
+    //
+    // Two shapes reach this with two different conventions. A new-format entry (`type: id`) keeps
+    // whatever the author wrote in `value`; the legacy `resolveByPriority` path STRIPS the hash,
+    // returning `value: 'submit-btn'` with the full `#submit-btn` in `locator`. Reading `value`
+    // alone would therefore compile `#submit-btn` down to `page.locator('submit-btn')` — a type
+    // selector that matches nothing, which an `is hidden` assertion then passes forever.
+    //
+    // A bare word gets its `#` back for the same reason: `id` is also a mobile strategy, where the
+    // convention IS bare ("bottom_bar"), so an entry copied across platforms would otherwise be a
+    // silent no-match on web. Anything already carrying selector syntax is passed through untouched.
+    Handlebars.registerHelper('cssIdSelector', function(locator: any, value: any) {
+      const raw = (typeof locator === 'string' && locator) ? locator : (value ?? '');
+      const text = String(raw);
+      if (!text) return '';
+      return /[#.\[\]:>~+ ]/.test(text) ? text : `#${text}`;
+    });
+
     Handlebars.registerHelper('includes', function(text: string, search: string) {
       return typeof text === 'string' && text.includes(search);
     });

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

@@ -1,6 +1,33 @@
 import * as path from 'path';
 import { readYamlIfExists } from '../../../utils/yaml-io';
 
+/**
+ * A `{{var}}` the compiler could not resolve: missing data file, missing key, or a key holding
+ * something that is not a primitive.
+ *
+ * A TYPE rather than a message convention, because the one thing callers must never do with this
+ * failure is guess. Twenty-four step patterns used to catch it and substitute the placeholder text
+ * as the VALUE — `fill('${valid_partner_id}')` typed 20 literal characters into the app, `generate`
+ * exited 0, and the scenario failed at the assertion it was written to fail at, for the reason it
+ * was written to fail. Nothing distinguished that run from a correct one (#781).
+ *
+ * So the failure is now carried, not converted, and it is answered in exactly one place —
+ * `StepMapper.mapStep`, which turns it into SG-E038 plus a step that throws by name. Catching this
+ * anywhere else to produce a value is the defect, and the type is what makes that visible in review.
+ */
+export class DataRefError extends Error {
+  constructor(
+    message: string,
+    /** The `{{ref}}` as written in the feature, e.g. `valid_partner_id` or `user.email`. */
+    readonly dataRef: string,
+    /** The test-data file consulted, relative to the project root. Absent when no file was reached. */
+    readonly file?: string,
+  ) {
+    super(message);
+    this.name = 'DataRefError';
+  }
+}
+
 /**
  * DataResolver - Resolves data references to actual values
  *
@@ -106,16 +133,17 @@ export class DataResolver {
 
   private resolveValue(dataRef: string, featureName?: string): string {
     const { fileName, valuePath } = this.parseDataRef(dataRef, featureName);
-    const data = this.loadDataFile(fileName);
+    const data = this.loadDataFile(fileName, dataRef);
+    const rel = this.screenName
+      ? `qa/${this.flowMode ? 'flows' : 'screens'}/${this.screenName}/test-data/${fileName}.yaml`
+      : undefined;
 
     let current = data;
     for (const key of valuePath) {
       if (current && typeof current === 'object' && key in current) {
         current = current[key];
       } else {
-        throw new Error(
-          `Data path not found: ${dataRef}. Failed at key: ${key}`
-        );
+        throw new DataRefError(`Data path not found: ${dataRef}. Failed at key: ${key}`, dataRef, rel);
       }
     }
 
@@ -124,8 +152,10 @@ export class DataResolver {
     } else if (typeof current === 'number' || typeof current === 'boolean') {
       return String(current);
     } else {
-      throw new Error(
-        `Data reference ${dataRef} must resolve to a primitive value, got: ${typeof current}`
+      throw new DataRefError(
+        `Data reference ${dataRef} must resolve to a primitive value, got: ${typeof current}`,
+        dataRef,
+        rel,
       );
     }
   }
@@ -147,7 +177,7 @@ export class DataResolver {
     }
 
     if (parts.length < 2) {
-      throw new Error(`Invalid data reference: ${dataRef}. Expected format: file.path.to.value or provide featureName`);
+      throw new DataRefError(`Invalid data reference: ${dataRef}. Expected format: file.path.to.value or provide featureName`, dataRef);
     }
     return { fileName: parts[0], valuePath: parts.slice(1) };
   }
@@ -168,24 +198,23 @@ export class DataResolver {
    * Load data file from disk (with caching)
    * Merges base + env-specific: {name}.yaml + {name}.{SUNGEN_ENV}.yaml
    */
-  private loadDataFile(fileName: string): any {
+  private loadDataFile(fileName: string, dataRef: string): any {
     if (this.dataCache.has(fileName)) {
       return this.dataCache.get(fileName)!;
     }
 
     if (!this.screenName) {
-      throw new Error(`Data resolution requires screen/flow context for "${fileName}"`);
+      throw new DataRefError(`Data resolution requires screen/flow context for "${fileName}"`, dataRef);
     }
 
     const subDir = this.flowMode ? 'flows' : 'screens';
     const baseDir = path.join(process.cwd(), 'qa', subDir, this.screenName, 'test-data');
     const basePath = path.join(baseDir, `${fileName}.yaml`);
+    const rel = `qa/${subDir}/${this.screenName}/test-data/${fileName}.yaml`;
     const data = readYamlIfExists(basePath);
 
     if (!data || typeof data !== 'object' || Object.keys(data).length === 0) {
-      throw new Error(
-        `Data file not found or empty: qa/${subDir}/${this.screenName}/test-data/${fileName}.yaml`
-      );
+      throw new DataRefError(`Data file not found or empty: ${rel}`, dataRef, rel);
     }
 
     let merged = { ...data };

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

@@ -36,6 +36,7 @@ export const CONSUMED_ENTRY_FIELDS: ReadonlySet<string> = new Set([
   'scope',            // dialog/landmark scoping in the locator partial
   'match',            // collapses into `exact` for getByText
   'anchor',           // page assertions — the rendered-content proof (#662)
+  'query',            // page assertions — `any` drops the bare-page no-query rule (#748)
   'android',          // appium adapter → androidSelector (#392)
   'ios',              // appium adapter → iosSelector (#392)
   'variant',          // widget recipes / native select / upload subtype