@sun-asterisk/sungen 3.2.28 → 3.2.30

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

@@ -1,18 +1,49 @@
 import { ParsedStep } from '../gherkin-parser';
+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 { locatorIdentityKey } from './utils/dialog-scope-identity';
 import { DiagnosticsCollector } from './diagnostics';
 import { unsupportedStepCode } from './patterns/unsupported-step-code';
+import { maskRefsForMatching } from './utils/mask-refs-for-matching';
+import { isKnownSelectorType } from './utils/selector-type-validation';
 import { loadAppProfile, ResolvedAppProfile } from './app-profile';
 import { capabilityRegistry } from '../../capabilities/registry';
 
+/**
+ * The correction SG-W001 owes a project that gated a platform driver away.
+ *
+ * Gating (plan `260903-1654` phase 11) keeps a mobile-only pattern out of a web project's registry.
+ * Right isolation — but `platformMiss` then has nothing to catch, so a mobile-only step falls
+ * through to SG-W001, whose sentence "sungen has no step form for it" is FALSE: the form exists in
+ * a vocabulary this project declined. Ungated, the author would have seen SG-W020 naming the
+ * alternative.
+ *
+ * It states only what discovery knows. Which STEP the skipped driver owned is unknowable here — the
+ * patterns were never loaded — and a static list of off-platform step texts would rot on the next
+ * pattern anyone adds, putting a second wrong sentence where the first one was.
+ *
+ * Returns '' when nothing was gated, so every project that predates the platform profile keeps the
+ * message it has today, word for word.
+ */
+function offPlatformHint(): string {
+  const gated = capabilityRegistry.gatedDrivers();
+  if (!gated.length) return '';
+  const platform = capabilityRegistry.gatedForPlatform();
+  const names = gated.map(([pkg, serves]) => `${pkg} (${serves})`).join(', ');
+  return `this project declares platform: ${platform}, so ${names} was not loaded; a ${gated[0][1]}-only step form exists but is out of scope here. Per-platform vocabulary: docs/spec/step-support-matrix.md.`;
+}
+
+
 export interface MappedStep {
   code: string; // Generated Playwright code
   comment?: string; // Optional comment
   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)
 }
 
 /**
@@ -28,6 +59,8 @@ export class StepMapper {
   private dataResolver: DataResolver;
   private baseURL: string;
   private featureName?: string;
+  /** The feature's declared `@platform:` OS, for the compile-time iOS gate (SG-E025). */
+  private featurePlatform?: 'mobile' | 'android' | 'ios';
   private screenName?: string;
   private featurePath?: string;
   private currentScenarioSteps?: ParsedStep[];
@@ -74,7 +107,9 @@ export class StepMapper {
     this.platform = adapter.frameworkName === 'appium' ? 'mobile' : 'web';
     this.templateEngine = new TemplateEngine(templatesDir);
     this.patternRegistry = new PatternRegistry();
-    this.selectorResolver = new SelectorResolver(undefined, options.screenName);
+    // `platform` is set just above from the ADAPTER — the resolver needs it to decline the
+    // list-member auto-infer that has no mobile equivalent (#665).
+    this.selectorResolver = new SelectorResolver(undefined, options.screenName, this.platform);
     this.dataResolver = new DataResolver(undefined, options.screenName, options.runtimeData);
 
     // App profile (qa/app.yaml) — loaded after PatternRegistry so capability discovery has
@@ -100,8 +135,9 @@ export class StepMapper {
   /**
    * Set feature context for data and selector resolution
    */
-  setFeatureContext(featureName: string, featurePath?: string): void {
+  setFeatureContext(featureName: string, featurePath?: string, featurePlatform?: 'mobile' | 'android' | 'ios'): void {
     this.featureName = featureName;
+    this.featurePlatform = featurePlatform;
     this.featurePath = featurePath;
     this.selectorResolver.setFeatureContext(featureName);
     // One StepMapper serves every feature in a run, so the step counter that names the
@@ -173,6 +209,19 @@ export class StepMapper {
     this.dataResolver.registerCaptured(name);
   }
 
+  /**
+   * Register the head of a variable bound by the feature's `@beforeAll` hook. Feature-scoped: it
+   * survives setScenarioContext() so every scenario can read `{{head.*}}` as a runtime get().
+   */
+  registerFeatureCaptured(head: string): void {
+    this.dataResolver.registerFeatureCaptured(head);
+  }
+
+  /** Drop feature-scoped captured vars — call once per feature, before its hooks and scenarios map. */
+  clearFeatureCaptured(): void {
+    this.dataResolver.clearFeatureCaptured();
+  }
+
   /**
    * Map a Gherkin step to Playwright code
    * Uses pattern registry first, falls back to AI if enabled
@@ -186,6 +235,8 @@ export class StepMapper {
       this.lastPrimaryKeyword = keyword;
     }
 
+    this.warnScopeClauseDiscarded(step);
+
     // SG-W015 — `see [X] card with {{n}}` where n is a bare number compiles to a TEXT
     // assertion (toHaveText('3')), not a count. An author reaching for "3 cards are shown"
     // gets an assertion that can only pass if the card's TEXT is the digit — a wrong test
@@ -265,20 +316,25 @@ export class StepMapper {
       this.templateEngine.setBaseContext({ inFrame: true, frameSelector });
       // C1 — routed through the adapter instead of building `page.frameLocator(...)` inline:
       // the Appium adapter's own template performs its webview-context switch instead.
-      const code = this.templateEngine.renderStep('frame-enter-action', { frameSelector });
+      // `frameRef` carries the name as WRITTEN in the Gherkin: the Appium twin can fail (#705),
+      // and its error has to quote the step the author would go and look at, not the resolved
+      // xpath they never typed.
+      const code = this.templateEngine.renderStep('frame-enter-action', { frameSelector, frameRef: selectorRef });
       return { code, comment: `Switch to ${selectorRef} frame` };
     }
 
     // Dialog scope directives — intercept before pattern matching
     if (/\buse dialog\b/i.test(step.text)) {
       this.inDialogScope = true;
-      this.templateEngine.setBaseContext({ inDialog: true });
+      // setBaseContext MERGES — an earlier scope's root keys in the same scenario would
+      // otherwise leak into this unnamed one.
+      this.templateEngine.setBaseContext({ inDialog: true, dialogScopeKey: undefined });
       this.warnDialogScopeIgnoredOnMobile(step);
       return { code: '', comment: 'Enter dialog scope' };
     }
     if (/\b(?:close|dismiss|exit)\s+dialog\b/i.test(step.text)) {
       this.inDialogScope = false;
-      this.templateEngine.setBaseContext({ inDialog: false });
+      this.templateEngine.setBaseContext({ inDialog: false, dialogScopeKey: undefined });
       return { code: '', comment: 'Exit dialog scope' };
     }
     // `is on [X] <type>` supports exactly two shapes: `page` (URL from the page-type selector
@@ -314,6 +370,7 @@ export class StepMapper {
         dialogRootExpr: undefined,
         dialogRoleName: undefined,
         dialogFilterText: undefined,
+        dialogScopeKey: undefined,
       };
 
       if (step.selectorRef && step.dataRef) {
@@ -342,6 +399,16 @@ export class StepMapper {
       }
       // Case 1: no selectorRef → plain page.getByRole('dialog')
 
+      // Record what this root IS, so a later step naming the same element is recognized as the
+      // root rather than nested inside it (issue #692). The declared entry when there is one;
+      // otherwise the named-dialog fallback the element itself will resolve to.
+      if (step.selectorRef) {
+        const entry = this.resolveDialogEntry(step.selectorRef);
+        contextVars.dialogScopeKey = entry
+          ? locatorIdentityKey(entry)
+          : locatorIdentityKey({ strategy: 'role', role: 'dialog', name: step.selectorRef });
+      }
+
       this.templateEngine.setBaseContext(contextVars);
       return { code: '', comment: `Enter dialog scope${step.selectorRef ? ': ' + step.selectorRef : ''}` };
     }
@@ -396,10 +463,15 @@ export class StepMapper {
       this.checkDataRefConsumed(step, mappedStep);
       this.checkPageAssertionNoOpOnMobile(step, mappedStep);
       this.checkSetupNoOpOnMobile(step, mappedStep);
-      this.checkPageAssertionFallback(step, mappedStep);
+      this.checkNavigationNoOpOnMobile(step, mappedStep);
+      this.checkPageStepFallback(step, mappedStep);
       this.checkDeclaredUrlHasNoQuery(step, mappedStep);
+      const positionDropped = this.checkClickPositionDropped(step, mappedStep);
+      if (positionDropped) return positionDropped;
       const swallowed = this.checkAssertionClauseSwallowed(step, mappedStep);
       if (swallowed) return swallowed;
+      const badType = this.checkUnknownSelectorType(step, mappedStep);
+      if (badType) return badType;
       return mappedStep;
     }
 
@@ -422,7 +494,13 @@ export class StepMapper {
         step: step.text,
       });
     } else {
-      reason = `step "${step.text}" matched no pattern — sungen has no step form for it. Rephrase using a supported step form (see the sungen-gherkin-syntax reference), or tag the scenario @manual if the check cannot be automated.`;
+      // Two shapes, because the ORIGINAL CLAUSE is what was wrong. Appending a correction to
+      // "sungen has no step form for it" leaves the reader a sentence that contradicts itself one
+      // clause later. When the gate dropped a vocabulary, that clause is simply not written.
+      const hint = offPlatformHint();
+      reason = hint
+        ? `step "${step.text}" matched no pattern here — ${hint} If that is not what you meant, rephrase using a supported step form (see the sungen-gherkin-syntax reference), or tag the scenario @manual if the check cannot be automated.`
+        : `step "${step.text}" matched no pattern — sungen has no step form for it. Rephrase using a supported step form (see the sungen-gherkin-syntax reference), or tag the scenario @manual if the check cannot be automated.`;
       this.diagnostics?.add('SG-W001', reason, {
         feature: this.featureName,
         step: step.text,
@@ -450,6 +528,27 @@ export class StepMapper {
    * falls back to the legacy named-dialog root, so behavior is unchanged for those entries.
    */
   private renderDialogRoot(selectorRef: string, opts: { nonRoleOnly?: boolean } = {}): string | undefined {
+    const resolved = this.resolveDialogEntry(selectorRef);
+    if (!resolved) return undefined;
+    if (!StepMapper.DIALOG_ROOT_STRATEGIES.includes(resolved.strategy)) return undefined;
+    if (opts.nonRoleOnly && resolved.strategy === 'role') return undefined;
+
+    // Render the root PAGE-rooted: leaving inDialog set (or `scope: dialog` on the entry
+    // itself) would send the partial back through dialog-root and nest the dialog in itself.
+    const expr = this.templateEngine.renderStep('locator', {
+      ...resolved,
+      scope: resolved.scope === 'dialog' ? undefined : resolved.scope,
+      inDialog: false,
+    }).trim();
+    return expr || undefined;
+  }
+
+  /**
+   * The selectors.yaml entry behind a dialog reference, normalized the way the `locator` partial
+   * needs it. Shared by `renderDialogRoot` (which turns it into the root expression) and the
+   * scope-entry path (which keys off it to recognize the root again later — issue #692).
+   */
+  private resolveDialogEntry(selectorRef: string): any | undefined {
     let resolved: any;
     try {
       resolved = this.selectorResolver.resolveSelector(selectorRef, this.featureName, 'dialog', 0);
@@ -463,34 +562,27 @@ export class StepMapper {
     if (resolved.strategy === 'css' && resolved.locator) {
       resolved = { ...resolved, strategy: 'locator', value: resolved.locator };
     }
-    if (!StepMapper.DIALOG_ROOT_STRATEGIES.includes(resolved.strategy)) return undefined;
-    if (opts.nonRoleOnly && resolved.strategy === 'role') return undefined;
-
-    // Render the root PAGE-rooted: leaving inDialog set (or `scope: dialog` on the entry
-    // itself) would send the partial back through dialog-root and nest the dialog in itself.
-    const expr = this.templateEngine.renderStep('locator', {
-      ...resolved,
-      scope: resolved.scope === 'dialog' ? undefined : resolved.scope,
-      inDialog: false,
-    }).trim();
-    return expr || undefined;
+    return resolved;
   }
 
   /**
-   * SG-W013 — a page assertion whose path came from a fallback rather than from a `type: page`
-   * selector entry. Both resolvers degrade quietly when `[Ref]` does not resolve: `see [X] page`
-   * falls back to the feature's own path, `is on [X] page` to `/<ref>/`. Before the assertion was
-   * anchored that produced a test which always PASSED; anchored, it produces one that can never
-   * pass. Neither is the assertion the author wrote, and nothing said so.
+   * SG-W013 — a page STEP whose path came from a fallback rather than from a `type: page`
+   * selector entry. Every resolver degrades quietly when `[Ref]` does not resolve: `see [X] page`
+   * and `wait for [X] page` fall back to the feature's own path, `is on [X] page` to `/<ref>/`.
+   * Before the match was anchored that produced a test which always PASSED; anchored, it produces
+   * one that can never pass — an assertion that always fails, or, since #677 anchored the wait
+   * too, a wait that can only time out. None is the step the author wrote, and nothing said so.
    *
-   * Detected here rather than in the resolver on purpose: `MappedStep` carries only
-   * `{code, comment, imports}`, and the resolvers live in the driver packages while the collector
-   * lives in core. Re-asking the SAME resolver the step-mapper already owns costs three lines and
+   * Detected here rather than in the resolver on purpose: the resolvers live in the driver packages
+   * while the collector lives in core (the mapped step now also names its pattern and carries the
+   * resolver's data, but the fallback itself is only visible by re-resolving the selector). Re-asking the SAME resolver the step-mapper already owns costs three lines and
    * duplicates no logic — the alternative is widening the adapter contract for every driver.
    */
-  private checkPageAssertionFallback(step: ParsedStep, mapped: MappedStep): void {
+  private checkPageStepFallback(step: ParsedStep, mapped: MappedStep): void {
     if (!this.diagnostics || !step.selectorRef || step.elementType !== 'page') return;
-    if (!/\b(?:urlMatches|expectPage)\(/.test(mapped.code || '')) return;   // both URL-assertion shapes (#662)
+    // every shape that compiles a page path into an ANCHORED match: the two assertions (#662)
+    // and the wait (#677). A step that emitted none of them has no path to get wrong.
+    if (!/\b(?:urlMatches|expectPage|waitForPage)\(/.test(mapped.code || '')) return;
     let resolvedAsPage = false;
     try {
       const resolved = this.selectorResolver.resolveSelector(
@@ -502,7 +594,7 @@ export class StepMapper {
     }
     if (resolvedAsPage) return;
     this.diagnostics.add('SG-W013',
-      `page assertion for "[${step.selectorRef}]" has no "type: page" selector entry, so it asserts a FALLBACK path — the anchored assertion cannot match the real URL. Declare the page, e.g. "${step.selectorRef.toLowerCase()}:\\n  type: page\\n  value: '/your/path'"`,
+      `page step "[${step.selectorRef}]" has no "type: page" selector entry, so it targets a FALLBACK path — the anchored match can never reach the real URL (an assertion always fails; a wait can only time out). Declare the page, e.g. "${step.selectorRef.toLowerCase()}:\\n  type: page\\n  value: '/your/path'"`,
       { feature: this.featureName, step: step.text });
   }
 
@@ -551,6 +643,43 @@ export class StepMapper {
    * Deliberately narrow — it fires only on the bare-visibility shape, so a pattern that genuinely
    * consumed the clause (`is-hidden`, `contains`, `matches-format`, the state family) is untouched.
    */
+  /**
+   * SG-E027 (#711) — the step names an entry whose `type:` is not a selector type, so the resolver
+   * fell to its placeholder default and this step compiled to `getByPlaceholder('<the value>')`:
+   * a locator that cannot match, which would fail much later as a timeout naming placeholder text
+   * the author never wrote. Compile it to a `throw` instead — the same reasoning as SG-E023 above,
+   * that a step which reads as a check and can only ever fail obscurely is worse than one that
+   * fails loudly and says why.
+   *
+   * The DIAGNOSTIC is not added here. `SelectorResolver.loadNewSelectorFile` already reported this
+   * entry once for the whole file; re-reporting per step would print the same line twenty times for
+   * one typo. This method only replaces the code, so the compile-time message and the runtime
+   * failure stay one fact reported once.
+   *
+   * A resolve throw means the key is missing entirely — a different defect that the resolver's own
+   * error already owns — and an auto-inferred selector stamps no `selectorType`, so both skip.
+   */
+  private checkUnknownSelectorType(step: ParsedStep, mapped: MappedStep): MappedStep | null {
+    if (!step.selectorRef) return null;
+    let selectorType: unknown;
+    try {
+      selectorType = this.selectorResolver.resolveSelector(
+        step.selectorRef, this.featureName, step.elementType, step.nth,
+      ).selectorType;
+    } catch {
+      return null;   // missing key — the resolver's own error owns that
+    }
+    if (selectorType === undefined || isKnownSelectorType(selectorType)) return null;
+    const reason = `step "${step.text}" names selector "${step.selectorRef}", whose selectors.yaml `
+      + `entry declares type: "${String(selectorType)}" — not a selector type, so the entry `
+      + `resolved to a placeholder locator that cannot match. See SG-E027 for the valid types and `
+      + `the nearest spelling to what was written.`;
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `Unknown selector type "${String(selectorType)}" — see SG-E027: ${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.
@@ -593,6 +722,42 @@ export class StepMapper {
     };
   }
 
+  /**
+   * A click step that names a POSITION (`at position "top-left"`, `at offset x=…, y=…`) must compile
+   * through the positioned-click form with a position it understood. Anything else — a typo in the
+   * keyword, a value the grammar rejects, or a combination another click form claims first (`try to
+   * click … at position`, `… at offset … and accept [OK] alert`, `… with {{v}} … at position`) —
+   * would otherwise click the element's CENTRE and pass, which for a backdrop-dismiss test is the
+   * one outcome that proves nothing. Owned by the compiler rather than the driver so it holds no
+   * matter which pattern wins.
+   */
+  private static readonly CLICK_POSITION_HINT =
+    /\bat\s+(?:position|offset)\b|\bat\s+\w+\s+(?:"(?:top|bottom)-(?:left|right)"|x\s*=)|\b(?:top|bottom)[- ](?:left|right)\b|\bat\s+x\s*=/i;
+
+  private checkClickPositionDropped(step: ParsedStep, mapped: MappedStep): MappedStep | null {
+    // Refs are masked; so is every quoted VALUE except a preset name — `with "Engineer at position 3"`
+    // is a text filter, not a position, while a mistyped `at postion "top-left"` must stay visible.
+    const masked = maskRefsForMatching(step.text)
+      .replace(/"([^"]*)"/g, (quoted, inner: string) => (/^(?:top|bottom)-(?:left|right)$/i.test(inner.trim()) ? quoted : '"~"'));
+    if (!/\bclick/i.test(masked) || !StepMapper.CLICK_POSITION_HINT.test(masked)) return null;
+    // Already refused upstream (off-platform SG-W020, a dropped state clause, a missing template…):
+    // that refusal names the real cause; this guard only exists to stop a SILENT centre click.
+    if (/^throw new Error\("\[sungen\]/.test(mapped.code.trim())) return null;
+    const refused = mapped.templateData?.positionError as string | undefined;
+    if (mapped.pattern === 'click-element-at-position' && !refused) return null;
+    const reason = refused
+      ? `step "${step.text}": ${refused}`
+      : `step "${step.text}" asks for a click position but compiled through the "${mapped.pattern ?? 'unknown'}" `
+        + 'step form, which clicks the element\'s centre — the position would be silently dropped. Write '
+        + 'it as `click [X] <type> at position "<preset>"` or `… at offset x=<n>px|%, y=<n>px|%` on its own: '
+        + '`try to click`, a `with {{v}}` text filter and `… and accept [OK] alert` do not take a position.';
+    this.diagnostics?.add('SG-E026', reason, { feature: this.featureName, step: step.text });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `Click position dropped — see SG-E026: ${step.text}`,
+    };
+  }
+
   private checkDataRefConsumed(step: ParsedStep, mapped: MappedStep): void {
     if (!step.dataRef || !this.diagnostics) return;
     const code = mapped.code || '';
@@ -665,6 +830,70 @@ export class StepMapper {
   /**
    * Create pattern context for generators
    */
+  /**
+   * Whether a mapped step emits anything that actually RUNS.
+   *
+   * Comments are stripped — block comments as well as line ones, because a template written with
+   * `/* … *\/` would otherwise read as executable code and silence the no-op diagnostics exactly
+   * when they were needed. Keyed on the emitted CODE rather than on a template name (MappedStep
+   * does not carry one), so any future template that degrades to a comment is caught without being
+   * enumerated anywhere.
+   *
+   * Shared by the SG-W022 / SG-W023 / SG-W026 checks — the three of them ask the same question, and
+   * three copies of this would drift.
+   */
+  private emitsExecutableCode(mapped: MappedStep): boolean {
+    return Boolean(
+      (mapped.code || '')
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .split('\n')
+        .map((l) => l.replace(/\/\/.*$/, '').trim())
+        .filter(Boolean)
+        .join(''),
+    );
+  }
+
+  /**
+   * 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. The step reads as "go to Settings"
+   * and goes nowhere. Pair it with `Then User see [X] page` — itself a no-op, reported as SG-W022 —
+   * and the whole scenario passes without ever touching the app.
+   *
+   * This completes a class that was handled in halves: `route-assertion` already throws loudly and
+   * `page-assertion` already reports W022; `navigation` alone was silent.
+   *
+   * Scoped to the ACTIVE forms. `is on [X] page` and its mobile `screen` twin are mobile's
+   * app-LAUNCH anchor, whose empty output is correct and documented as such where IS_ON_TYPES is
+   * defined — warning there would cry wolf on every valid mobile feature, and a diagnostic that
+   * cries wolf gets filtered out, taking the real ones with it. The exclusion is matched on
+   * `is on` FIRST, before the open/navigate test, because "the user is on the page they opened"
+   * phrasings contain both.
+   *
+   * Deliberately NOT a `throw`, for the same reason as SG-W023: an unfulfilled navigation weakens
+   * the scenario rather than inverting an assertion, and throwing would break every mobile suite
+   * already carrying one of these steps. `generate --strict` is the opt-in that makes it fail.
+   */
+  private checkNavigationNoOpOnMobile(step: ParsedStep, mapped: MappedStep): void {
+    if (this.platform !== 'mobile' || !this.diagnostics) return;
+
+    const text = step.text.toLowerCase();
+    // The anchor is checked first and wins: it is legitimately empty on mobile.
+    if (/\bis\s+on\b/.test(text)) return;
+    if (!/\bopens?\b|\bnavigates?\s+to\b|\bgo(es)?\s+to\b/.test(text)) return;
+    // Only the navigation TARGET forms — `open [X] page|screen`. `open [X] dialog`/`menu` is a tap
+    // on a control, which compiles to real code and never reaches here anyway.
+    if (step.elementType && !['page', 'screen'].includes(step.elementType)) return;
+
+    if (this.emitsExecutableCode(mapped)) return;
+
+    this.diagnostics.add('SG-W026',
+      'this navigation step compiled to a COMMENT — a native app is already launched by the wdio capabilities, so nothing navigates and the following steps run against whatever screen the app happens to be on. Change screens the way a user does, with a tap/gesture on the control that opens it (`When User tap [Settings] button`), and assert a marker on the new screen; keep `is on [X] screen` only as the feature\'s opening anchor',
+      { feature: this.featureName, step: step.text });
+  }
+
   /**
    * SG-W023 — a mobile SETUP step that emitted no executable code, so a declared precondition is
    * never actually established.
@@ -699,13 +928,7 @@ export class StepMapper {
     // Strip comments; whatever remains is what actually runs. Block comments too — a template written
     // with `/* … */` would otherwise read as executable code and silence this check exactly when it
     // was needed.
-    const executable = (mapped.code || '')
-      .replace(/\/\*[\s\S]*?\*\//g, '')
-      .split('\n')
-      .map((l) => l.replace(/\/\/.*$/, '').trim())
-      .filter(Boolean)
-      .join('');
-    if (executable) return;
+    if (this.emitsExecutableCode(mapped)) return;
 
     const remedy = isBackendState
       ? 'backend state is not app state — reset it through a test API/script, or bind a `@query:` precondition, the same way the web adapter has to'
@@ -738,18 +961,28 @@ export class StepMapper {
     // Strip comments; whatever remains is what actually runs. Block comments are handled as well as
     // line ones: a template written with `/* … */` would otherwise read as executable code and
     // silently defeat this check — the diagnostic would go quiet exactly when it was needed.
-    const executable = (mapped.code || '')
-      .replace(/\/\*[\s\S]*?\*\//g, '')
-      .split('\n')
-      .map((l) => l.replace(/\/\/.*$/, '').trim())
-      .filter(Boolean)
-      .join('');
-    if (executable) return;
+    if (this.emitsExecutableCode(mapped)) return;
     this.diagnostics.add('SG-W022',
       'a native app has no URL, so this page assertion compiled to a COMMENT — it asserts nothing and the scenario passes regardless. Assert a marker that is actually on the screen instead (`Then User see [Some Element] ...`), or tag the scenario @manual',
       { feature: this.featureName, step: step.text });
   }
 
+  /**
+   * SG-W028 — a trailing `in [X] <word>` scope clause whose `<word>` is not a container type.
+   *
+   * The clause is dropped, and everything downstream takes the FIRST `[ref]` and the FIRST
+   * `{{data}}` it finds, so the sentence compiles clean while the assertion silently widens to the
+   * whole screen (#667). Unlike an unrecognized STEP, which at least raises SG-W001, a partially
+   * understood step used to say nothing at all — and a check that runs against more than it names
+   * passes for the wrong reason in exactly the list-of-identical-cards case it was written for.
+   */
+  private warnScopeClauseDiscarded(step: ParsedStep): void {
+    if (!step.unsupportedScopeType) return;
+    this.diagnostics?.add('SG-W028',
+      `\`${step.unsupportedScopeType}\` is not a container type, so the scope clause was DROPPED and this step runs against the whole page, not the named container. Supported: ${PARENT_CONTAINER_TYPES.join(', ')}`,
+      { feature: this.featureName, step: step.text });
+  }
+
   /**
    * SG-W021 — dialog scope is a no-op on the Appium adapter.
    *
@@ -779,6 +1012,7 @@ export class StepMapper {
       renderLocator: (resolved) => this.templateEngine.renderStep('locator', resolved),
       appProfile: this.appProfile,
       platform: this.platform,
+      featurePlatform: this.featurePlatform,
       adapterName: this.adapterName,
       diagnostics: this.diagnostics,
       baseURL: this.baseURL,

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

@@ -1,7 +1,9 @@
 import Handlebars from 'handlebars';
+import { escapeSingleQuoted } from './utils/escape-js-string';
 import fs from 'fs';
 import path from 'path';
-import type { RenderImportsOptions } from './adapters/adapter-interface';
+import type { RenderImportsOptions, HookRenderData } from './adapters/adapter-interface';
+import { locatorIdentityKey } from './utils/dialog-scope-identity';
 
 export class TemplateEngine {
   private templates: Map<string, HandlebarsTemplateDelegate> = new Map();
@@ -28,16 +30,9 @@ export class TemplateEngine {
     // the result in '…' (selector values, attribute values, scope), so a value containing a newline,
     // backslash, or quote must be escaped or the generated spec is a syntax error (e.g. a Flutter
     // composite content-desc like "Quick Convert\nSelect File\n…" used as an accessibility-id).
-    // Order matters: backslash first, then the rest.
-    Handlebars.registerHelper('escapeQuotes', function(text: string) {
-      if (text == null) return '';
-      return String(text)
-        .replace(/\\/g, '\\\\')
-        .replace(/'/g, "\\'")
-        .replace(/\n/g, '\\n')
-        .replace(/\r/g, '\\r')
-        .replace(/\t/g, '\\t');
-    });
+    // The rule itself lives in utils/escape-js-string so the pattern layer, which builds some
+    // locator strings by hand, cannot drift from what the templates do.
+    Handlebars.registerHelper('escapeQuotes', (text: string) => escapeSingleQuoted(text));
 
     // Escape a raw string for embedding inside a REGEX LITERAL (/…/). Metacharacters first —
     // that class doubles a backslash, so the control-char passes below cannot be mis-read as
@@ -152,6 +147,17 @@ export class TemplateEngine {
       // element is dialog-rooted even if its role is portal-exempt (issue #465).
       const explicitDialog = this.scope === 'dialog';
       if (!this.inDialog && !explicitDialog) return 'page';
+      // The element being resolved IS the active scope's own dialog root (issue #692). Prefixing
+      // it with that root asks for a dialog nested inside itself —
+      // getByRole('dialog',{name:X}).getByRole('dialog',{name:X}) — which can never resolve, yet
+      // compiles clean and fails as a plain timeout reading "the dialog never opened". So the
+      // root is idempotent: re-asserting the dialog you are scoped inside means what it reads as.
+      // Skipped for a `with {{v}}` root, whose .filter({ hasText }) form is not expressible as
+      // the element's own locator — identity says nothing about it there.
+      if (this.inDialog && !this.dialogFilterText && this.dialogScopeKey &&
+          locatorIdentityKey(this) === this.dialogScopeKey) {
+        return 'page';
+      }
       // Portal-rendered roles (Radix/MUI/Headless UI/antd render option/menu/tooltip
       // layers onto document.body) live OUTSIDE the dialog's DOM subtree — wrapping
       // them in the dialog root guarantees a timeout. List comes from the app profile
@@ -297,7 +303,7 @@ export class TemplateEngine {
   }
 
   renderImports(options?: RenderImportsOptions): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock, urlAssertImports: options?.urlAssertImports, regexEscapeImport: options?.regexEscapeImport });
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock, urlAssertImports: options?.urlAssertImports, regexEscapeImport: options?.regexEscapeImport, checkedStateImports: options?.checkedStateImports });
   }
 
   renderTestFile(data: {
@@ -332,21 +338,15 @@ export class TemplateEngine {
     return this.render('before-each', data);
   }
 
-  renderBeforeAll(data: {
-    steps: Array<{ comment?: string; code: string }>;
-  }): string {
+  renderBeforeAll(data: HookRenderData): string {
     return this.render('before-all', data);
   }
 
-  renderAfterEach(data: {
-    steps: Array<{ comment?: string; code: string }>;
-  }): string {
+  renderAfterEach(data: HookRenderData): string {
     return this.render('after-each', data);
   }
 
-  renderAfterAll(data: {
-    steps: Array<{ comment?: string; code: string }>;
-  }): string {
+  renderAfterAll(data: HookRenderData): string {
     return this.render('after-all', data);
   }
 

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

@@ -29,6 +29,27 @@ export class DataResolver {
     this.capturedVars.clear();
   }
 
+  // Vars bound by a `@beforeAll` hook's `@api:`/`@query:` preconditions. The hook runs before every
+  // test of the feature, so its bindings are readable from EVERY scenario — they survive the
+  // per-scenario clearCaptured(). Stored by head (`login`) and matched against the ref's head
+  // (`login.body.token` → `login`), since a scenario may read any sub-path of the bound response.
+  private featureCaptured = new Set<string>();
+
+  /** Register the head of a variable bound by the feature's `@beforeAll` hook (feature-scoped). */
+  registerFeatureCaptured(head: string): void {
+    this.featureCaptured.add(head);
+  }
+
+  /** Clear feature-scoped captured vars — call at the start of each feature. */
+  clearFeatureCaptured(): void {
+    this.featureCaptured.clear();
+  }
+
+  /** Runtime-only ref (scenario-captured, or bound by the feature's `@beforeAll` hook)? */
+  private isCaptured(dataRef: string): boolean {
+    return this.capturedVars.has(dataRef) || this.featureCaptured.has(dataRef.split(/[.[]/)[0]);
+  }
+
   constructor(testDataDir?: string, screenName?: string, runtimeMode: boolean = false) {
     this.testDataDir = testDataDir || path.join(process.cwd(), 'qa', 'test-data');
     this.screenName = screenName;
@@ -52,7 +73,7 @@ export class DataResolver {
   resolveData(dataRef: string, featureName?: string): string {
     // Captured vars exist only at runtime → emit a marker (→ testData.get) and
     // skip YAML validation. Requires runtime mode (capture writes testData.set).
-    if (this.capturedVars.has(dataRef)) {
+    if (this.isCaptured(dataRef)) {
       return DataResolver.encodeMarker(dataRef);
     }
 
@@ -75,7 +96,7 @@ export class DataResolver {
    * anything said about it belongs in a warning, never a gate.
    */
   peekBaseValue(dataRef: string, featureName?: string): string | undefined {
-    if (this.capturedVars.has(dataRef)) return undefined;
+    if (this.isCaptured(dataRef)) return undefined;
     try {
       return this.resolveValue(dataRef, featureName);
     } catch {