@sun-asterisk/sungen 3.2.21 → 3.2.22-beta.2

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

@@ -1,6 +1,6 @@
 import { ParsedStep } from '../../gherkin-parser';
 import { MappedStep } from '../step-mapper';
-import { StepPattern, PatternContext } from './types';
+import { StepPattern, PatternContext, Platform } from './types';
 import { capabilityRegistry } from '../../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 
@@ -21,6 +21,78 @@ export function maskRefsForMatching(text: string): string {
     .replace(/\[[^\]]*\]/g, '[~]');
 }
 
+/**
+ * Gesture forms that OWN the word "tap" — each has its own pattern keyed on it (`mobile-double-tap`
+ * at priority 17, `tap-top-of-element` at 18) and means MORE than a click. They are the one
+ * carve-out from the synonym rule below: leave their text exactly as written.
+ */
+const TAP_GESTURE_FORMS = /\bdouble[-\s]?tap|\btap(?:s)?\b[^.]*\b(?:top of|at the top|at top)\b/i;
+
+/**
+ * `tap` is a synonym of `click` — for MATCHING only.
+ *
+ * The vocabulary was split: exactly three patterns in `@sungen/driver-mobile` key on "tap", while
+ * every other pattern in the shared vocabulary keys on "click". So a mobile-phrased step SILENTLY
+ * LOST meaning instead of failing — `User tap [Sign In] button and accept [OK] alert` matched the
+ * plain-tap pattern and the alert clause simply vanished, leaving a test that passed having checked
+ * less than it claimed. Green tests that assert nothing are the worst outcome in this whole class,
+ * which is why this is a synonym rather than 40 duplicated matchers.
+ *
+ * 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.
+ *   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);
+ *      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`
+ * / `includes('click')`) — none depends on the verb's neighbours, and none tests for the ABSENCE of
+ * "click". Verified across driver-ui, driver-db, driver-mock and driver-mobile before relying on it.
+ *
+ * Resolvers and generators always receive the ORIGINAL `step.text`, so comments and value
+ * extraction never see this string.
+ *
+ * ORDER IS LOAD-BEARING: this runs AFTER `maskRefsForMatching`, so a selector or variable NAME
+ * containing "tap" (a `[Tap Water]` field) has already been blanked and cannot be rewritten into a
+ * verb. Reversing the two would reclassify that step as a click. The unit test asserts the order.
+ */
+export function normalizeVerbs(text: string): string {
+  if (TAP_GESTURE_FORMS.test(text)) return text;
+  return text.replace(/\btap(s|ped)?\b/gi, (m) => `${m} click`);
+}
+
+/**
+ * `TemplateEngine.loadStepTemplate` signals an absent `.hbs` with this exact message
+ * (`template-engine.ts`). Matching on it is what separates "this adapter cannot express the step"
+ * — a reviewable compile diagnostic — from a genuine bug inside a template, which must keep
+ * propagating untouched.
+ */
+const TEMPLATE_NOT_FOUND = /^Template not found: (.+)\.hbs in any subfolder$/;
+
+/**
+ * The step body emitted in place of code the active adapter cannot produce. A comment alone would
+ * let the test go GREEN having asserted nothing — the silent-loss class this SPI exists to close —
+ * so the step throws at run time as well as reporting at compile time.
+ *
+ * `JSON.stringify` does the quoting, NOT a hand-rolled `replace(/'/g, …)`. The reason string embeds
+ * arbitrary author text (the step sentence), and hand-escaping only the quote character is wrong for
+ * any input containing a backslash or a raw newline: a step ending `…\` would emit `'…\\'`, whose
+ * trailing escaped-backslash-then-quote breaks the literal and takes the WHOLE generated spec down
+ * with a syntax error — reopening, one level deeper, the exact "one bad step kills the file" failure
+ * this function exists to prevent. Step text here is routinely non-ASCII (Vietnamese, Japanese),
+ * which JSON.stringify also handles correctly.
+ */
+function unsupportedStepCode(reason: string): string {
+  return `throw new Error(${JSON.stringify(`[sungen] ${reason}`)});`;
+}
+
 /**
  * Pattern Registry - manages all step patterns
  */
@@ -59,7 +131,10 @@ export class PatternRegistry {
   findPattern(step: ParsedStep): StepPattern | null {
     // Match against text with ref CONTENTS masked, so a verb substring inside a selector/data name
     // (e.g. "click" in `{{double_click_guard_account.email}}`) can't hijack the verb classification.
-    const matchStep: ParsedStep = { ...step, text: maskRefsForMatching(step.text) };
+    // THEN normalise `tap` → `click`, so the mobile phrasing reaches the whole shared vocabulary
+    // instead of only the three patterns that happen to key on "tap". Masking first is what keeps a
+    // `[Tap Water]` ref from being read as a verb.
+    const matchStep: ParsedStep = { ...step, text: normalizeVerbs(maskRefsForMatching(step.text)) };
     for (const pattern of this.patterns) {
       if (this.matchesPattern(matchStep, pattern.matcher)) {
         return pattern;
@@ -73,37 +148,109 @@ export class PatternRegistry {
    * Prefers resolver (returns template data) over generator (renders directly).
    */
   generateStep(step: ParsedStep, context: PatternContext): MappedStep | null {
-    const pattern = this.findPattern(step);
-    if (!pattern) {
-      return null;
-    }
+    // Matchers see only the STEP; some decisions need context (a resolver reading the
+    // test-data value, e.g. row-count's numeric check). A resolver may therefore return
+    // null to say "not mine after all" — the search continues with the next matching
+    // pattern in priority order instead of crashing or silently dropping the step.
+    // 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)) };
+    for (const pattern of this.patterns) {
+      if (!this.matchesPattern(matchStep, pattern.matcher)) continue;
 
-    // Prefer resolver (framework-agnostic) over generator (legacy)
-    if (pattern.resolver) {
-      const resolved = pattern.resolver(step, context);
+      // Platform gate — BEFORE any template lookup. A pattern that declares its platforms and is
+      // matched on another one is a vocabulary mismatch, not a missing file: report it in its own
+      // terms (SG-W020) rather than letting it fail later as a confusing absent template.
+      const platformMiss = PatternRegistry.platformMiss(pattern, context, step);
+      if (platformMiss) return platformMiss;
 
-      // 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
-        );
-      }
+      try {
+        // Prefer resolver (framework-agnostic) over generator (legacy)
+        if (pattern.resolver) {
+          const resolved = pattern.resolver(step, context);
+          if (!resolved) continue; // resolver declined — fall through
 
-      const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
-      return {
-        code,
-        comment: resolved.comment,
-      };
-    }
+          // 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 (pattern.generator) {
-      return pattern.generator(step, context);
-    }
+          const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
+          return {
+            code,
+            comment: resolved.comment,
+          };
+        }
+
+        if (pattern.generator) {
+          return pattern.generator(step, context);
+        }
 
+        return null;
+      } catch (err: any) {
+        // The step matched a pattern the ACTIVE adapter has no template for. Before this guard the
+        // unhandled throw killed the ENTIRE feature file and named neither the step nor the adapter.
+        const missing = TEMPLATE_NOT_FOUND.exec(String(err?.message ?? ''));
+        if (!missing) throw err;
+        return PatternRegistry.unsupportedTemplate(missing[1], pattern, context, step);
+      }
+    }
     return null;
   }
 
+  /**
+   * SG-W020 — the matched pattern declares `platforms` and the active one is not among them.
+   */
+  private static platformMiss(
+    pattern: StepPattern, context: PatternContext, step: ParsedStep
+  ): MappedStep | null {
+    const platform: Platform = context.platform ?? 'web';
+    if (!pattern.platforms || pattern.platforms.includes(platform)) return null;
+
+    const adapter = context.adapterName ?? platform;
+    const supported = pattern.platforms.join('/');
+    const alternative = pattern.platformAlternative
+      ?? 'use a supported step form, or tag the scenario @manual';
+    const reason =
+      `step "${step.text}" uses pattern "${pattern.name}", which is ${supported}-only — ` +
+      `the ${adapter} adapter cannot express it. Instead: ${alternative}.`;
+
+    context.diagnostics?.add('SG-W020', reason, {
+      feature: context.featureName,
+      step: step.text,
+    });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `${supported}-only step on the ${adapter} adapter — see SG-W020`,
+    };
+  }
+
+  /**
+   * 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.
+   */
+  private static unsupportedTemplate(
+    templateName: string, pattern: StepPattern, context: PatternContext, step: ParsedStep
+  ): MappedStep {
+    const adapter = context.adapterName ?? context.platform ?? 'web';
+    const reason =
+      `step "${step.text}" needs template "${templateName}.hbs", which the ${adapter} adapter ` +
+      `does not ship (pattern "${pattern.name}"). Rephrase with a supported step form, or tag ` +
+      `the scenario @manual.`;
+
+    context.diagnostics?.add('SG-E020', reason, {
+      feature: context.featureName,
+      step: step.text,
+    });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `no ${adapter} template for "${templateName}" — see SG-E020`,
+    };
+  }
+
   /**
    * Resolve parent scoping to a Playwright locator string.
    * Tries YAML lookup first, falls back to auto-infer from parentType.

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

@@ -3,6 +3,22 @@ import { MappedStep } from '../step-mapper';
 import { SelectorResolver } from '../utils/selector-resolver';
 import { DataResolver } from '../utils/data-resolver';
 
+/**
+ * The subset of DiagnosticsCollector the pattern layer needs. Structural, not a class import,
+ * so the framework-agnostic pattern SPI keeps depending on nothing concrete.
+ */
+export interface DiagnosticsSink {
+  add(code: any, message: string, context?: { feature?: string; step?: string }): void;
+}
+
+/**
+ * The platform a pattern (and its templates) can compile for. Drawn from the ACTIVE adapter:
+ * `appium` → 'mobile', everything else → 'web'. A pattern that omits `platforms` is assumed to
+ * work on BOTH — the historical assumption, kept as the default so no existing pattern changes
+ * behaviour.
+ */
+export type Platform = 'web' | 'mobile';
+
 /**
  * Pattern matcher function or regex
  */
@@ -44,6 +60,12 @@ export interface PatternContext {
   scenarioSteps?: ParsedStep[];
   /** Effective Gherkin keyword (Given/When/Then), resolved from And/But */
   effectiveKeyword?: string;
+  /** The platform the ACTIVE adapter compiles for. Absent = 'web' (back-compat default). */
+  platform?: Platform;
+  /** 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. */
+  diagnostics?: DiagnosticsSink;
   /** 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. */
@@ -69,4 +91,17 @@ export interface StepPattern {
   resolver?: PatternResolver;
   generator?: PatternGenerator;
   priority?: number;
+  /**
+   * Platforms this pattern can compile for. ABSENT = both (the default — every pattern that
+   * predates the platform SPI). Declaring it narrows the pattern: matching it on any other
+   * platform emits SG-W020 and compiles to a loud runtime `throw` instead of silently
+   * producing code that references a driver the platform does not have.
+   */
+  platforms?: ReadonlyArray<Platform>;
+  /**
+   * Free-text alternative named in the SG-W020 message when this pattern is used off-platform
+   * (e.g. "`@api` / `@query`, or tag the scenario @manual"). Optional — a generic pointer is
+   * emitted when absent.
+   */
+  platformAlternative?: string;
 }

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

@@ -1,7 +1,7 @@
 import { ParsedStep } from '../gherkin-parser';
 import { TemplateEngine } from './template-engine';
 import { adapterRegistry } from './adapters';
-import { PatternRegistry, PatternContext } from './patterns';
+import { PatternRegistry, PatternContext, Platform } from './patterns';
 import { SelectorResolver } from './utils/selector-resolver';
 import { DataResolver } from './utils/data-resolver';
 import { DiagnosticsCollector } from './diagnostics';
@@ -49,6 +49,10 @@ export class StepMapper {
   private diagnostics?: DiagnosticsCollector;
   /** App profile (qa/app.yaml merged over presets/defaults) — the per-project BEHAVIOR layer */
   private appProfile: ResolvedAppProfile;
+  /** The platform the ACTIVE adapter compiles for — drives the pattern-layer platform gate */
+  private platform: Platform;
+  /** The active adapter's own name ('playwright' | 'appium') — quoted in SG-E020/SG-W020 */
+  private adapterName: string;
 
   constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean; framework?: string } = {}) {
     this.verbose = options.verbose ?? false;
@@ -60,7 +64,13 @@ export class StepMapper {
     // mobile→Appium). The adapter owns its templatesDir; resolving it here keeps step
     // rendering and the file skeleton (code-generator) on the same framework.
     const framework = options.framework || 'web';
-    const templatesDir = adapterRegistry.getAdapter(framework).templatesDir;
+    const adapter = adapterRegistry.getAdapter(framework);
+    const templatesDir = adapter.templatesDir;
+    // The platform gate keys on the ADAPTER, not on the requested framework name: 'mobile' and
+    // 'appium' are aliases of the same adapter, so asking the adapter itself keeps one source of
+    // truth as more aliases appear.
+    this.adapterName = adapter.frameworkName;
+    this.platform = adapter.frameworkName === 'appium' ? 'mobile' : 'web';
     this.templateEngine = new TemplateEngine(templatesDir);
     this.patternRegistry = new PatternRegistry();
     this.selectorResolver = new SelectorResolver(undefined, options.screenName);
@@ -175,6 +185,28 @@ export class StepMapper {
       this.lastPrimaryKeyword = keyword;
     }
 
+    // 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
+    // with no error. Count semantics live on row/table ("see [T] table with {{n}}",
+    // "see [Ref] row with {{n}}") and lists ("should have count"); on the container types
+    // below, a bare-number text expectation is almost never what the author meant. A text
+    // element asserting a numeric readout ("[Row Quantity] text with 4") stays silent.
+    const COUNT_MISREAD_TYPES = new Set(['card', 'item', 'items', 'cards', 'option', 'options']);
+    if (this.diagnostics && step.dataRef && step.selectorRef &&
+        COUNT_MISREAD_TYPES.has((step.elementType || '').toLowerCase()) &&
+        /\bsees?\s+\[/.test(step.text) && /\bwith\b/.test(step.text)) {
+      // peekBaseValue reads the literal from test-data even in runtime-data mode,
+      // where resolveData returns an opaque marker (never numeric-looking).
+      let resolvedValue: string | undefined;
+      try { resolvedValue = this.dataResolver.peekBaseValue(step.dataRef, this.featureName); } catch { /* unresolved at compile time → cannot judge */ }
+      if (resolvedValue !== undefined && /^\d+$/.test(resolvedValue.trim())) {
+        this.diagnostics.add('SG-W015',
+          `\`see [${step.selectorRef}] ${step.elementType} with {{${step.dataRef}}}\` compiles to a TEXT assertion toHaveText('${resolvedValue.trim()}'), NOT a count of ${step.elementType}s. For a count use \`see [Ref] row with {{n}}\` / \`see [T] table with {{n}}\` (or a list "should have count"); if '${resolvedValue.trim()}' really is the ${step.elementType}'s text, assert it on a text/label element instead`,
+          { feature: this.featureName, step: step.text });
+      }
+    }
+
     // SG-W007 — a two-step-form browser-alert handler (`click [OK] alert`) written AFTER
     // an action step registers its page.once('dialog') listener too late: a dialog
     // triggered by the earlier action auto-dismisses with no error (issue #472).
@@ -212,10 +244,12 @@ export class StepMapper {
       const selectorRef = step.selectorRef || '';
 
       if (selectorRef.toLowerCase() === 'main') {
-        // Exit frame scope
+        // Exit frame scope — routed through the adapter (C1): the Appium twin performs the
+        // real webview→native context switch; a bare comment here would silently no-op on mobile.
         this.inFrameScope = false;
         this.templateEngine.setBaseContext({ inFrame: false });
-        return { code: '// Back to main page context', comment: 'Exit frame scope' };
+        const code = this.templateEngine.renderStep('frame-exit-action', {});
+        return { code, comment: 'Exit frame scope' };
       }
 
       // Enter frame scope
@@ -228,7 +262,9 @@ export class StepMapper {
         // Use selectorRef as-is
       }
       this.templateEngine.setBaseContext({ inFrame: true, frameSelector });
-      const code = `const frame = page.frameLocator('${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 });
       return { code, comment: `Switch to ${selectorRef} frame` };
     }
 
@@ -236,6 +272,7 @@ export class StepMapper {
     if (/\buse dialog\b/i.test(step.text)) {
       this.inDialogScope = true;
       this.templateEngine.setBaseContext({ inDialog: true });
+      this.warnDialogScopeIgnoredOnMobile(step);
       return { code: '', comment: 'Enter dialog scope' };
     }
     if (/\b(?:close|dismiss|exit)\s+dialog\b/i.test(step.text)) {
@@ -246,6 +283,7 @@ export class StepMapper {
     // Given User is on [...] dialog — set dialog scope (3 cases)
     if (step.text.includes('is on') && step.elementType === 'dialog') {
       this.inDialogScope = true;
+      this.warnDialogScopeIgnoredOnMobile(step);
       // setBaseContext MERGES — clear every root key so a previous dialog scope in the
       // same scenario cannot leak its root into this one.
       const contextVars: Record<string, any> = {
@@ -333,6 +371,7 @@ export class StepMapper {
         console.log(`  ✓ Pattern matched: ${step.text.substring(0, 50)}...`);
       }
       this.checkDataRefConsumed(step, mappedStep);
+      this.checkPageAssertionNoOpOnMobile(step, mappedStep);
       this.checkPageAssertionFallback(step, mappedStep);
       this.checkDeclaredUrlHasNoQuery(step, mappedStep);
       return mappedStep;
@@ -493,6 +532,11 @@ export class StepMapper {
    * includeHidden + visible filter: when a modal (e.g. Radix Dialog) is open the
    * background gets aria-hidden="true", which empties plain getByRole() even though
    * the cells are still rendered — measure what the user SEES, not the a11y tree.
+   *
+   * C2 — this method used to build the Playwright code string itself (referencing `tableRow`,
+   * a binding that only exists in the Playwright output). It now only gathers data and routes
+   * through the adapter template; the Appium twin throws (HTML table roles), matching the
+   * `table-*` house style.
    */
   private generateRowScopedColumnAssertion(step: ParsedStep): MappedStep {
     const columnRef = step.selectorRef || '';
@@ -515,24 +559,9 @@ export class StepMapper {
     }
 
     const isGiven = this.lastPrimaryKeyword === 'Given';
-    const escapedValue = cellValue.replace(/'/g, "\\'");
-
-    let code: string;
-    if (columnIndex !== undefined) {
-      // Exact cell: nth(index) + toHaveText
-      if (isGiven) {
-        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth(${columnIndex})).toHaveText('${escapedValue}');`;
-      } else {
-        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth(${columnIndex})).toHaveText('${escapedValue}');`;
-      }
-    } else {
-      // Fallback: filter by text
-      if (isGiven) {
-        code = `await tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '${escapedValue}' }).filter({ visible: true }).waitFor();`;
-      } else {
-        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '${escapedValue}' }).filter({ visible: true })).toBeVisible();`;
-      }
-    }
+    const code = this.templateEngine.renderStep('row-scoped-column-assertion', {
+      columnIndex, cellValue, isGiven,
+    });
 
     return {
       code,
@@ -543,6 +572,57 @@ export class StepMapper {
   /**
    * Create pattern context for generators
    */
+  /**
+   * SG-W022 — a `page` assertion that emitted no executable code on mobile.
+   *
+   * A native app has no URL, so the Appium `page-assertion` template is a bare comment. The step
+   * therefore READS as an assertion and checks nothing: the scenario passes whatever the app is
+   * showing. That is strictly worse than the missing-template crashes this pass closed — a crash is
+   * visible on the first run, a false pass hides until someone trusts it. (Its `is on [X] page` twin
+   * routes to `route-assertion`, which throws loudly; only this half was silent.)
+   *
+   * Keyed on the EMITTED CODE rather than on a template name, so any future page-assertion path
+   * that degrades to a comment is caught by the same check without being enumerated here. Scoped to
+   * the `see` form: the `is on` twin is mobile's app-launch directive, whose empty output is right.
+   */
+  private checkPageAssertionNoOpOnMobile(step: ParsedStep, mapped: MappedStep): void {
+    if (this.platform !== 'mobile' || !this.diagnostics) return;
+    if (step.elementType !== 'page') return;
+    // Only the ASSERTION form. `Given User is on [X] page` is the app-LAUNCH directive on mobile —
+    // it emits a comment because wdio capabilities already launched the app, which is correct and
+    // must not be warned about. `Then User see [X] page` is the one that claims to check something.
+    if (!/\bsees?\b/i.test(step.text)) return;
+    // 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;
+    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-W021 — dialog scope is a no-op on the Appium adapter.
+   *
+   * `setBaseContext({ inDialog: true })` records the scope faithfully, and every Playwright locator
+   * partial consults it. No Appium template does. So on mobile the step reads as "narrow everything
+   * that follows to this dialog" and in fact narrows nothing — the following steps search the whole
+   * screen. Scope that is silently discarded is what produced this entire defect class, so it is
+   * reported rather than left to be discovered from a passing test.
+   */
+  private warnDialogScopeIgnoredOnMobile(step: ParsedStep): void {
+    if (this.platform !== 'mobile') return;
+    this.diagnostics?.add('SG-W021',
+      'dialog scope has no effect on the mobile adapter — no Appium template reads `inDialog`, so the following steps resolve against the whole screen, not the dialog. Scope the elements themselves instead (a `scope: dialog` entry, or accessibility-ids unique to the dialog)',
+      { feature: this.featureName, step: step.text });
+  }
+
   private createPatternContext(): PatternContext {
     return {
       stepCounter: this.stepCounter,
@@ -555,6 +635,9 @@ export class StepMapper {
       dataResolver: this.dataResolver,
       renderLocator: (resolved) => this.templateEngine.renderStep('locator', resolved),
       appProfile: this.appProfile,
+      platform: this.platform,
+      adapterName: this.adapterName,
+      diagnostics: this.diagnostics,
       baseURL: this.baseURL,
       featureName: this.featureName,
       screenName: this.screenName,