@sun-asterisk/sungen 3.2.24 → 3.2.25

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

@@ -5,10 +5,12 @@ import { StepMapper } from './step-mapper';
 import { TestGeneratorAdapter, adapterRegistry } from './adapters';
 import { transformToRuntimeData } from './utils/runtime-data-transformer';
 import { DiagnosticsCollector } from './diagnostics';
+import { parseResetTier, DEFAULT_RESET_TIER } from './reset-tier';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities } from '../../harness/capability';
 import { parseManualComments } from '../../exporters/scenario-merger';
+import { findSyntaxError } from './utils/spec-syntax-check';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -80,7 +82,7 @@ function extractCleanupFlags(tags: string[]): { overlay?: boolean; forms?: boole
 const FUNCTIONAL_TAG_PREFIXES = [
   '@parallel', '@serial', '@cleanup:', '@auth:', '@manual', '@no-auth',
   '@steps:', '@extend:', '@screenshot:', '@beforeAll', '@afterEach', '@afterAll',
-  '@flow', '@cases:', '@deferred:', '@owned-by:', '@platform:',
+  '@flow', '@cases:', '@deferred:', '@owned-by:', '@platform:', '@reset:',
 ];
 
 function extractPassThroughTags(scenarioTags: string[], featureTags: string[]): string[] {
@@ -328,7 +330,16 @@ export class CodeGenerator {
     }
 
     // Generate test code (async now to support AI mapping)
-    const testCode = await this.generateTestCode(feature);
+    let testCode = await this.generateTestCode(feature);
+
+    // Runtime data: replace __SUNGEN_TD$…$__ markers with testData.get() calls.
+    // Runs BEFORE the imports are rendered so they can reflect what the transformed
+    // body actually references (a marker inside a regex literal becomes an
+    // escapeRegExp(...) call that needs its helper imported). Imports carry no
+    // markers, so transforming only the body loses nothing.
+    if (this.options.runtimeData) {
+      testCode = transformToRuntimeData(testCode);
+    }
 
     // `url-assert` is imported from what the body actually emitted, not from an active capability:
     // page assertions belong to the DEFAULT ui capability, so a capability flag would import the
@@ -338,16 +349,25 @@ export class CodeGenerator {
     const urlAssertImports = ['urlMatches', 'joinPath'].filter((n) => testCode.includes(`${n}(`)).join(', ');
     if (urlAssertImports) this.syncGeneratedHelper(outputDir, 'url-assert.ts', 'specs-url-assert.ts');
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock, urlAssertImports });
+    // Same body-first rule for the runtime regex-escape helper: only a spec whose
+    // transformed body wraps a value in escapeRegExp() imports (and syncs) it.
+    const regexEscapeImport = /\bescapeRegExp\(/.test(testCode);
+    if (regexEscapeImport) this.syncGeneratedHelper(outputDir, 'regex-escape.ts', 'specs-regex-escape.ts');
+
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock, urlAssertImports, regexEscapeImport });
 
     // Combine and collapse any runs of 3+ newlines down to 2 (one blank line max)
     const raw = `${imports}\n\n${testCode}`;
     let code = raw.replace(/\n{3,}/g, '\n\n');
 
-    // Runtime data: replace __SUNGEN_TD$…$__ markers with testData.get() calls
-    if (this.options.runtimeData) {
-      code = transformToRuntimeData(code);
-    }
+    // SG-E022 — compiler self-check. Every template and post-processor above assembles
+    // TEXT, so a delimiter bug in any of them yields a file Playwright cannot parse at all:
+    // one SyntaxError, zero scenarios run. That is exactly how the runtime-data quote-pairing
+    // defect reached a user — `sungen generate` reported success and the breakage only
+    // surfaced at `npx playwright test`, a step further from the cause. Parsing what we are
+    // about to write makes the compiler name its own bad output, at the moment it makes it.
+    // (The runtime-data transform itself ran on the body above, before the imports.)
+    this.assertParseable(code, feature.name, filePath);
 
     return {
       featureName: feature.name,
@@ -358,6 +378,24 @@ export class CodeGenerator {
     };
   }
 
+  /**
+   * Report SG-E022 when the emitted spec is not parseable. Reported, never thrown: the
+   * caller still writes the file, so the user keeps the artifact to inspect (and `--strict`
+   * turns it into a non-zero exit like every other diagnostic).
+   */
+  private assertParseable(code: string, featureName: string, filePath: string): void {
+    const detail = findSyntaxError(code);
+    if (!detail) return;
+    this.diagnostics.add(
+      'SG-E022',
+      `generated spec "${filePath}" is not parseable TypeScript (${detail}) — Playwright will `
+        + 'fail the whole file with one SyntaxError and run NONE of its scenarios. This is a sungen '
+        + 'compiler bug, not a problem with the .feature: please report it with the step this file '
+        + 'was generated from.',
+      { feature: featureName }
+    );
+  }
+
   /**
    * Count total steps in feature (excluding background).
    * For @extend scenarios, counts base steps + own steps (merged total).
@@ -767,6 +805,45 @@ export class CodeGenerator {
     // package (activity stripped, it isn't needed for terminateApp/activateApp); iosBundleId is the part
     // after `|` when present. Without these the test-file template's `{{#if appPackage}}` stays false and
     // the beforeEach (terminate+activate) reset is never emitted → nav scenarios cascade-fail.
+    // Mobile: how much state each scenario starts from — `@reset:none|soft|data|full`, default 'soft'
+    // (the terminate+activate relaunch this adapter always did, so an untagged feature is unchanged).
+    // Appium-only: web features get a clean slate from navigation and carry no tier.
+    const resetTier = this.adapter.frameworkName === 'appium'
+      ? (parseResetTier(feature.tags || []) ?? DEFAULT_RESET_TIER)
+      : undefined;
+
+    // Per-scenario `@reset:` overrides. Keyed on the scenario's BASE name — NOT the rendered it()
+    // title, because a @cases scenario concatenates its title at runtime from the row label, so no
+    // compile-time key could match it. The generated spec normalizes a title back to a base name and
+    // membership-tests each step, so a miss just inherits the feature tier rather than guessing wrong.
+    // `cases` marks a scenario whose it() title is BUILT AT RUNTIME (`name + ' — ' + row.__label`).
+    // Only those titles may have a row suffix stripped when looking a tier up; applying that strip to
+    // every scenario let a name that merely LOOKED like `<base> — <suffix>` resolve to a different
+    // scenario's tier.
+    const scenarioResetTiers = this.adapter.frameworkName === 'appium'
+      ? (feature.scenarios || []).reduce<Array<{ name: string; tier: string; cases: boolean }>>((acc, sc) => {
+          const tier = parseResetTier(sc.tags || []);
+          if (tier) acc.push({ name: sc.name, tier, cases: (sc.tags || []).some(t => t.startsWith('@cases:')) });
+          return acc;
+        }, [])
+      : undefined;
+    // SG-W024 — the runtime lookup is keyed on the scenario NAME, so two scenarios sharing a name
+    // cannot be told apart. Counted over EVERY scenario, not just the tagged ones: an UNTAGGED
+    // scenario sharing a name with a tagged one silently inherits that tier (weakening a
+    // `@reset:none` chain, or paying a reinstall it never asked for), and scanning only the tagged
+    // subset missed exactly that case.
+    if (scenarioResetTiers && scenarioResetTiers.length) {
+      const tiered = new Set(scenarioResetTiers.map(t => t.name));
+      const counts = new Map<string, number>();
+      for (const sc of feature.scenarios || []) counts.set(sc.name, (counts.get(sc.name) || 0) + 1);
+      for (const [name, n] of counts) {
+        if (n < 2 || !tiered.has(name)) continue;
+        this.diagnostics.add('SG-W024',
+          `${n} scenarios in this feature are named "${name}" and at least one carries a @reset: tag — the generated lookup is keyed on the scenario NAME, so every one of them resolves to the SAME tier, including any that declared none. Rename them so each is unique.`,
+          { feature: feature.name, step: name });
+      }
+    }
+
     let appPackage: string | undefined;
     let iosBundleId: string | undefined;
     if (this.adapter.frameworkName === 'appium' && feature.path) {
@@ -802,6 +879,8 @@ export class CodeGenerator {
       singleAuthRole,
       appPackage,
       iosBundleId,
+      resetTier,
+      scenarioResetTiers: scenarioResetTiers && scenarioResetTiers.length ? scenarioResetTiers : undefined,
     });
   }
 

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

@@ -3,7 +3,10 @@
  * and would otherwise silently discard or invent it" (spec: sungen_app_profile_spec.md §4).
  *
  * Codes:
- *   SG-W001 — step matched no pattern (compiles to a no-op `// TODO` comment)
+ *   SG-W001 — step matched no pattern: sungen has no step form for the sentence. Compiles to a loud
+ *             `throw` (it emitted a no-op `// TODO` comment until the unsupported-step gate, which
+ *             let the scenario pass having asserted nothing). `@manual` is the way to park a check
+ *             sungen cannot express — such scenarios are skipped before mapping and never reach here
  *   SG-W002 — step parsed a {{dataRef}} value but the generated code never uses it
  *   SG-W003 — `name` filter defaulted from the Gherkin reference on a name-from-content
  *             role (status/alert/…) — such a filter can never match; opt out with `name: null`
@@ -21,8 +24,10 @@
  *             entry: the label is display-only, so the step checks existence anywhere in the
  *             table — an ordering rule would pass even when the row moved
  *   SG-W011 — a storage assertion written in `expect … in local/session storage` form:
- *             `expect` steps only read `{{response}}` refs, so this compiles to a silent
- *             no-op — the supported grammar is `User see [KEY] in local storage exists/…`
+ *             `expect` steps only read `{{response}}` refs, so this matches no pattern — the
+ *             supported grammar is `User see [KEY] in local storage exists/…`. Compiles to a
+ *             `throw` (it was a silent no-op until the unsupported-step gate); the reason string
+ *             keeps naming the real grammar rather than falling back to SG-W001's generic text
  *   SG-W012 — a mock-install step AFTER a navigation step in the same block: page.route()
  *             registered after goto() misses every request fired during page load — move
  *             the install before the navigation (or into Background)
@@ -40,6 +45,14 @@
  *             "3 cards are shown" gets an assertion that can only pass if the card's text
  *             IS the digit. Count semantics exist on row/table ("see [T] table with {{n}}",
  *             "see [Ref] row with {{n}}") and lists ("should have count") only
+ *   SG-E024 — a mobile app-lifecycle step (restart / reinstall) in a feature that declares no
+ *             `Path:` app id. The templates resolve the app through a helper the test-file only
+ *             emits when the id is present, so the spec used to compile clean and then die at
+ *             runtime with a ReferenceError — taking the whole spec, not the step.
+ *   SG-E023 — the step carries an assertion clause (`matches "…"`, `contains`, `has text`, a state)
+ *             but the generated code is a BARE VISIBILITY check: the clause was swallowed by the
+ *             catch-all and the test would pass whatever the element says. Four separate defects
+ *             have arrived this way, so the step compiles to a runtime throw instead.
  *   SG-E020 — the step matched a pattern whose template the ACTIVE adapter does not ship. Before
  *             the platform SPI this was an unhandled `Template not found` that killed the WHOLE
  *             feature file and named neither the step nor the adapter. The step now compiles to a
@@ -54,17 +67,58 @@
  *             every following step resolves page-wide as if the scope had never been written.
  *             Silently-ignored scope is the exact defect class this channel exists for — the step
  *             LOOKS like it narrows the search and does not
+ *   SG-E021 — the step carried a trailing state clause (`… is hidden`) that the pattern which matched
+ *             it does not account for, so the clause would be SILENTLY DROPPED. This is the worst
+ *             shape in this catalogue: the others weaken an assertion, this one can INVERT it.
+ *             `see [X] page is hidden` matched `page-assertion` (priority 13) ahead of `is-hidden`
+ *             (11), the clause vanished, and the step compiled to `toHaveURL(...)` — asserting the
+ *             page IS displayed, the exact opposite of what it reads as, and passing while doing so.
+ *             The pattern layer declares what it accounts for via `StepPattern.states`; anything
+ *             undeclared reports here and compiles to a loud `throw`
  *   SG-W022 — a `page` assertion on the mobile adapter that emitted NO executable code. A native app
  *             has no URL, so `Then User see [X] page` compiles to a bare comment: the step reads as
  *             an assertion, checks nothing, and the scenario PASSES regardless. Worse than the
  *             crash class this plan closed — a crash is visible, a false pass is not. Its `is on`
  *             twin routes to `route-assertion`, which throws; this half was silent
+ *   SG-W023 — a mobile SETUP step that emitted NO executable code, so a declared PRECONDITION is never
+ *             established. `Given the user is logged out` matches `user-not-logged-in` → `clear-auth`,
+ *             whose Appium template is a bare comment: mobile auth lives in the keychain and prefs,
+ *             not in cookies, so there is nothing for a per-step action to clear. The scenario then
+ *             runs against whatever the PREVIOUS scenario left signed in — the same false-pass class
+ *             as SG-W022, arriving through setup rather than assertion.
+ *             Unlike SG-W020/SG-E021 this does NOT compile to a `throw`: an unestablished precondition
+ *             weakens the setup, it does not INVERT an assertion, and throwing would break every
+ *             mobile suite already carrying one of these steps. The remedy is a feature-level reset
+ *             tier (`@reset:data`), which is what the message names — app state is reset between
+ *             scenarios in the `beforeEach` hook, not mid-scenario by a step.
+ *   SG-W024 — two or more scenarios in one feature share a name and at least ONE carries a `@reset:`
+ *             tag. The generated per-scenario lookup is keyed on the scenario NAME (a @cases title is
+ *             built at runtime, so no compile-time key can match the rendered title), so every
+ *             same-named scenario resolves to the SAME tier — including one that declared none, which
+ *             then silently runs at its namesake's tier: a `@reset:none` chain broken, or a reinstall
+ *             nobody asked for. Counted over EVERY scenario rather than the tagged subset, because the
+ *             untagged twin is the one that gets the wrong tier and has no tag to be counted by.
+ *             Reported rather than resolved by precedence — two tests genuinely sharing one title
+ *             cannot be told apart by a name-keyed lookup, so the only honest fix is a rename. Silently
+ *             picking a winner would be the same silent-discard shape as SG-W021
+ *   SG-E022 — the generated spec is not parseable JS/TS, so NOTHING in the file runs — Playwright
+ *             reports one SyntaxError and every scenario in the unit is lost. A compiler self-check
+ *             (@babel/parser) on the emitted code, added after a field report where the runtime-data
+ *             marker post-processor mis-paired quote delimiters across two literals and the user only
+ *             found out at `npx playwright test`. Unlike every other code here this one blames the
+ *             compiler, not the Gherkin: it should be impossible, and it is reported so a broken
+ *             build names itself at generate time instead of one step further downstream
  *
- * Diagnostics never block generation by themselves; `sungen generate --strict`
- * turns any collected diagnostic into a non-zero exit.
+ * Diagnostics never change the EXIT CODE by themselves; `sungen generate --strict` turns any
+ * collected diagnostic into a non-zero exit. They are not all inert, though: SG-W001, SG-W011,
+ * SG-E020, SG-E021, SG-W020, SG-E023 and SG-E024 additionally compile the offending step to a runtime
+ * `throw`, because a step that reads as a check and silently checks nothing is worse than one that
+ * fails loudly. (SG-E022 is the one exception to the "blame the Gherkin" rule and throws nothing: the
+ * file is still written so the user keeps the artifact to inspect.)
+ * Generation always COMPLETES — the rest of the scenario and the rest of the file still compile.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-E020' | 'SG-W020' | 'SG-W021' | 'SG-W022';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-E022' | 'SG-E023' | 'SG-E024';
 
 export interface Diagnostic {
   code: DiagnosticCode;

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

@@ -25,13 +25,45 @@ const reExpect = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(${VALUE})\\s+is\\s+(no
 const reMatchesSchemaMasked = /^\s*(?:User\s+)?expect\s+\{\{~\}\}\s+matches\s+schema\s+\[~\]\s*$/i;
 const reMatchesSchema = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(\\{\\{[^}]+\\}\\})\\s+matches\\s+schema\\s+\\[([A-Za-z0-9_.-]+)\\]\\s*$`, 'i');
 
+/**
+ * `{{var}}` EMBEDDED in a quoted literal — test-data keys and paths only
+ * (`user.name`, `q.rows[0].id`, `items[*]`, kebab flow namespaces like
+ * `password-reset.email`). `{{$...}}` dynamic tokens are excluded on purpose:
+ * they have no test-data key, so converting one to a get() call throws
+ * "Test data key not found" at runtime — they stay literal.
+ */
+const RE_EMBEDDED_VAR = /\{\{\s*([\w.[\]*-]+?)\s*\}\}/g;
+
+/** Escape static literal text for a template-literal context. */
+const escapeForTemplate = (s: string): string =>
+  s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+
+/**
+ * Render a quoted literal's BODY as a JS expression. Text without vars keeps
+ * its exact JSON.stringify shape; an embedded `{{var}}` interpolates the
+ * runtime value (the literal used to ship verbatim, so the assertion compared
+ * against the raw `{{...}}` text and could never pass with correct data).
+ */
+export function literalExpr(text: string): string {
+  const vars = [...text.matchAll(RE_EMBEDDED_VAR)];
+  if (vars.length === 0) return JSON.stringify(text);
+  if (vars.length === 1 && vars[0][0] === text) return `testData.get(${JSON.stringify(vars[0][1])})`;
+  let out = '';
+  let last = 0;
+  for (const m of vars) {
+    out += escapeForTemplate(text.slice(last, m.index!)) + `\${testData.get(${JSON.stringify(m[1])})}`;
+    last = m.index! + m[0].length;
+  }
+  return `\`${out + escapeForTemplate(text.slice(last))}\``;
+}
+
 /** Render a value token (`{{var}}` | "literal" | 'literal' | number) as a JS expression. */
 function valueExpr(token: string): string {
   const t = token.trim();
   const v = t.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
   if (v) return `testData.get(${JSON.stringify(v[1])})`;
   const q = t.match(/^["'](.*)["']$/);
-  if (q) return JSON.stringify(q[1]);
+  if (q) return literalExpr(q[1]);
   if (/^-?\d+(?:\.\d+)?$/.test(t)) return t;
   return JSON.stringify(t);
 }
@@ -46,7 +78,10 @@ export const expectPatterns: StepPattern[] = [
       // odd chars) can claim the pattern yet not re-match here — emit a clear TODO instead of crashing.
       const m = step.text.match(reMatchesSchema);
       if (!m) return { code: `// TODO: malformed 'matches schema' step (expected: expect {{name.body}} matches schema [Ref]): ${step.text}`, comment: 'Unrecognized matches-schema step' };
-      const value = valueExpr(m[1]);
+      // raw(), not get(): Ajv must receive the NATIVE bound object. get() serializes
+      // to JSON text, so every schema validation failed with "(root) must be object"
+      // no matter how correct the response body was.
+      const value = `testData.raw(${JSON.stringify(m[1].replace(/^\{\{\s*|\s*\}\}$/g, ''))})`;
       const ref = m[2];
       const code = `{ const __schema = api.assertSchema(${value}, ${JSON.stringify(ref)}); expect(__schema.ok, \`matches schema [${ref}]: \${__schema.errors}\`).toBe(true); }`;
       return { code, comment: `Expect ${m[1]} matches schema [${ref}]` };

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

@@ -3,23 +3,13 @@ import { MappedStep } from '../step-mapper';
 import { StepPattern, PatternContext, Platform } from './types';
 import { capabilityRegistry } from '../../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
+import { maskRefsForMatching } from '../utils/mask-refs-for-matching';
+import { unsupportedStepCode } from './unsupported-step-code';
 
-/**
- * Mask the CONTENT of selector refs `[...]` and data placeholders `{{...}}` before verb matching,
- * keeping the delimiters. A step's verb/keywords come from the SENTENCE — never from a selector or
- * variable NAME — but matchers scan `step.text` with substring checks (e.g. `includes('click')`),
- * so a data ref like `{{double_click_guard_account.email}}` would spuriously satisfy the click
- * matcher and pre-empt fill. The content is replaced with an inert placeholder (`~` — carries no
- * verb/keyword/digit substring) rather than emptied, so structural matchers that require a NON-EMPTY
- * ref survive too — e.g. `expect {{a}} is {{b}}` matches `\{\{[^}]+\}\}`, and `in [X] table` /
- * `/\bto\s+\[/` keep their delimiters. The resolver/generator always receives the ORIGINAL step, so
- * value extraction and codegen are unaffected.
- */
-export function maskRefsForMatching(text: string): string {
-  return text
-    .replace(/\{\{[^}]*\}\}/g, '{{~}}')
-    .replace(/\[[^\]]*\]/g, '[~]');
-}
+// Both helpers moved out of this file so the Gherkin parser (state-clause extraction) and the
+// step-mapper (SG-W001 no-pattern fallback) can use them without importing the pattern registry.
+// Re-exported here because their historical import path is `patterns/index.ts`.
+export { maskRefsForMatching, unsupportedStepCode };
 
 /**
  * Gesture forms that OWN the word "tap" — each has its own pattern keyed on it (`mobile-double-tap`
@@ -76,23 +66,6 @@ export function normalizeVerbs(text: string): string {
  */
 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
  */
@@ -170,6 +143,16 @@ export class PatternRegistry {
           const resolved = pattern.resolver(step, context);
           if (!resolved) continue; // resolver declined — fall through
 
+          // State-clause gate. Deliberately AFTER the resolver, not before it: a resolver may return
+          // null to say "not mine after all", and the search then continues to a lower-priority
+          // pattern that may well be the one that asserts the state. Gating earlier judged a pattern
+          // that had not yet claimed the step — `row-count` declines a non-numeric `{{value}}` so
+          // `see [R] row with {{status_label}} is disabled` should reach see-with-variable-disabled,
+          // but the gate short-circuited it into a throw. Only the pattern that actually OWNS the
+          // step gets to be judged on what it drops.
+          const resolverStateMiss = PatternRegistry.stateMiss(pattern, context, step);
+          if (resolverStateMiss) return resolverStateMiss;
+
           // Auto-inject parent scoping if step has parentRef
           // Skip for table-* patterns — they resolve the table name internally from step text
           if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
@@ -186,6 +169,9 @@ export class PatternRegistry {
         }
 
         if (pattern.generator) {
+          // A legacy generator has no decline path, so this pattern owns the step already.
+          const generatorStateMiss = PatternRegistry.stateMiss(pattern, context, step);
+          if (generatorStateMiss) return generatorStateMiss;
           return pattern.generator(step, context);
         }
 
@@ -228,6 +214,45 @@ export class PatternRegistry {
     };
   }
 
+  /**
+   * SG-E021 — the step carries a trailing state clause the matched pattern does not account for.
+   *
+   * Priority decides which pattern wins, and the winner is not always the one that reads the clause:
+   * `see [X] page is hidden` matched `page-assertion` (13) ahead of `is-hidden` (11), so `is hidden`
+   * was dropped and the step compiled to `toHaveURL(...)` — asserting the page IS shown, the exact
+   * inverse of the sentence, and passing. Nothing detected it, because the clause lived only inside
+   * `step.text` and each pattern re-regexed it privately.
+   *
+   * `states` makes the claim explicit and checkable: a pattern declares what its template accounts
+   * for, and anything else lands here. Strict reading — an ABSENT `states` accounts for nothing —
+   * because the failure modes are asymmetric. Under-declaring throws on valid input, which is loud,
+   * local, and fixed by one annotation. Over-declaring restores the silent inversion this exists to
+   * close, and nothing catches it again.
+   */
+  private static stateMiss(
+    pattern: StepPattern, context: PatternContext, step: ParsedStep
+  ): MappedStep | null {
+    const state = step.state;
+    if (!state) return null;
+    if (pattern.states?.includes(state)) return null;
+
+    const reason =
+      `step "${step.text}" carries the state clause "is ${state}", but the pattern that matched it ` +
+      `("${pattern.name}") does not assert that state — the clause would be SILENTLY DROPPED and the ` +
+      `step would check something other than what it reads as. Use a step form that owns the state ` +
+      `(e.g. "User see [Ref] <type> is ${state}" on the element itself), or drop the clause if the ` +
+      `bare assertion is what you meant. If sungen cannot express the check, tag the scenario @manual.`;
+
+    context.diagnostics?.add('SG-E021', reason, {
+      feature: context.featureName,
+      step: step.text,
+    });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `"is ${state}" not asserted by "${pattern.name}" — see SG-E021`,
+    };
+  }
+
   /**
    * 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.

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

@@ -19,6 +19,28 @@ export interface DiagnosticsSink {
  */
 export type Platform = 'web' | 'mobile';
 
+/**
+ * The canonical state clauses an assertion step may carry, exactly as documented for authors in
+ * `README.md` ("States") and in the `sungen-gherkin-syntax` skill. Deliberately CLOSED: real feature
+ * files carry trailing phrases like `is rejected` / `is active` / `is unchanged` that belong to other
+ * grammars or are prose, and reading those as state clauses would put valid steps in front of the
+ * SG-E021 gate. Widening this union widens that gate — add a member only alongside a pattern that
+ * asserts it.
+ */
+export type StateClause =
+  | 'hidden'
+  | 'visible'
+  | 'disabled'
+  | 'enabled'
+  | 'checked'
+  | 'unchecked'
+  | 'focused'
+  | 'empty'
+  | 'loading'
+  | 'selected'
+  | 'sorted ascending'
+  | 'sorted descending';
+
 /**
  * Pattern matcher function or regex
  */
@@ -104,4 +126,18 @@ export interface StepPattern {
    * emitted when absent.
    */
   platformAlternative?: string;
+  /**
+   * State clauses this pattern's generated code ACTUALLY asserts. ABSENT = asserts none.
+   *
+   * The contract runs in one direction and is easy to get backwards: declaring a state is a promise
+   * that the emitted code checks it. A pattern that wins a step carrying an UNDECLARED state clause
+   * emits SG-E021 and compiles to a loud `throw`, because the alternative is what this field exists
+   * to prevent — the clause being silently dropped and the assertion reading as something it is not.
+   * (`see [X] page is hidden` matched `page-assertion` at a higher priority than `is-hidden`, so the
+   * clause vanished and the step asserted the OPPOSITE: that the page IS displayed.)
+   *
+   * So: under-declaring throws on valid input, over-declaring re-opens the silent-drop hole. Declare
+   * a state only after reading the template the resolver names.
+   */
+  states?: ReadonlyArray<StateClause>;
 }

package/src/generators/test-generator/patterns/unsupported-step-code.ts

@@ -0,0 +1,19 @@
+/**
+ * The step body emitted in place of code sungen cannot honestly produce — because the active adapter
+ * ships no template for it (SG-E020), because the pattern is off-platform (SG-W020), because the
+ * matched pattern would silently DROP the author's state clause (SG-E021), or because no pattern
+ * matched at all (SG-W001/SG-W011). A comment alone would let the test go GREEN having asserted
+ * nothing — the silent-loss class these diagnostics exist 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.
+ */
+export function unsupportedStepCode(reason: string): string {
+  return `throw new Error(${JSON.stringify(`[sungen] ${reason}`)});`;
+}

package/src/generators/test-generator/recipe-expander.ts

@@ -103,8 +103,16 @@ function expandPrimitive(prim: unknown, ctx: RecipeExpandContext, itemVar: strin
       return { partial: 'recipe-click-text', targetExpr: expr };
     }
     case 'expectText': {
+      // `exact: true` asserts the element's WHOLE text (toHaveText) instead of a substring
+      // (toContainText) — same opt-in flag `clickText` carries. Substring stays the default so
+      // existing recipes keep their behavior.
       const o = (typeof arg === 'object' && arg !== null ? arg : {}) as Record<string, unknown>;
-      return { partial: 'recipe-expect-text', targetExpr: targetExpr(o.locator ?? '$trigger'), valueExpr: valueExpr(o.value ?? '$value') };
+      return {
+        partial: 'recipe-expect-text',
+        targetExpr: targetExpr(o.locator ?? '$trigger'),
+        valueExpr: valueExpr(o.value ?? '$value'),
+        exact: o.exact === true,
+      };
     }
     case 'expectValue': {
       const o = (typeof arg === 'object' && arg !== null ? arg : {}) as Record<string, unknown>;

package/src/generators/test-generator/reset-tier.ts

@@ -0,0 +1,93 @@
+/**
+ * Mobile reset tiers — how much state a scenario starts from.
+ *
+ * Web gets a clean slate for free: a URL reload is effectively a fresh state. Mobile does not. To save
+ * time, mobile automation keeps the app alive across a whole session, so the end state of one scenario
+ * becomes the start state of the next — which breaks test independence three ways: scenarios can no
+ * longer run in isolation or in parallel, a "nearly right" leftover state makes the FOLLOWING scenario
+ * fail for reasons that have nothing to do with it, and a scenario that dies mid-flow poisons every
+ * scenario after it.
+ *
+ * The reason nobody just reinstalls between scenarios is cost: a cold start is 5–30s, which across a
+ * large suite is the whole CI budget. So the state layers (local DB, cache, prefs, keychain, OS
+ * permissions) need a LADDER rather than one all-or-nothing switch — the same conclusion every major
+ * framework reached (Appium's `mobile: clearApp`, Detox's `device.reloadReactNative()`, the OS-level
+ * reset APIs in XCUITest/Espresso).
+ *
+ *   none — nothing is reset. State carries over BY DESIGN (a cart that accumulates across scenarios).
+ *   soft — terminateApp + activateApp. Clears in-memory state and the navigation stack. THE DEFAULT,
+ *          and exactly what the compiler emitted before tiers existed, so no existing suite changes.
+ *   data — soft + wipe the app's data layer (local DB, cache, prefs, keychain).
+ *   full — remove + reinstall. Also resets permissions and any install-time state.
+ *
+ * Declared per feature via `@reset:<tier>`; a run can RAISE the floor with SUNGEN_RESET_TIER without
+ * regenerating specs (resolved inside the generated spec, the same runtime model as test-data overlays).
+ */
+
+/** Ordered weakest → strongest. Index order IS the comparison, so never reorder this. */
+export const RESET_TIERS = ['none', 'soft', 'data', 'full'] as const;
+
+export type ResetTier = (typeof RESET_TIERS)[number];
+
+/**
+ * `soft` — the behaviour the appium adapter emitted before tiers existed. Keeping it the default is
+ * what makes this feature additive: an untagged feature compiles to the same spec it did before.
+ */
+export const DEFAULT_RESET_TIER: ResetTier = 'soft';
+
+function isResetTier(value: string): value is ResetTier {
+  return (RESET_TIERS as readonly string[]).includes(value);
+}
+
+/**
+ * Read the `@reset:<tier>` tag off a tag list.
+ *
+ * Returns `undefined` when no `@reset:` tag is present — deliberately NOT the default. Callers need to
+ * tell "absent" from "explicitly soft": a scenario with no tag must inherit its feature's tier, and
+ * collapsing absent into `soft` here would silently RAISE a `@reset:none` feature.
+ *
+ * An unrecognized value warns and yields the default rather than throwing, matching how `@cleanup:`
+ * handles an unknown key — a typo in a tag should not stop a build.
+ */
+export function parseResetTier(tags: string[]): ResetTier | undefined {
+  const tag = tags.find((t) => t.startsWith('@reset:'));
+  if (!tag) return undefined;
+  const value = tag.slice('@reset:'.length).trim().toLowerCase();
+  if (isResetTier(value)) return value;
+  console.warn(`⚠ Unknown @reset:${value} — valid tiers: ${RESET_TIERS.join(', ')}. Using '${DEFAULT_RESET_TIER}'.`);
+  return DEFAULT_RESET_TIER;
+}
+
+/** The stronger of two tiers. Used to combine a declared tier with a run-level floor. */
+export function maxResetTier(a: ResetTier, b: ResetTier): ResetTier {
+  return RESET_TIERS.indexOf(a) >= RESET_TIERS.indexOf(b) ? a : b;
+}
+
+/**
+ * One rung harder — what the NEXT scenario resets to after this one failed.
+ *
+ * A failed scenario left unknown state behind (a half-written local DB, an open modal) that a plain
+ * process relaunch does not undo, so the scenario after it deserves a stronger reset than it asked for.
+ *
+ * `none` is a FIXED POINT, on purpose. It is an explicit "state carries over" contract — a chain of
+ * scenarios building up one cart. Escalating it would silently break that contract, and the chain is
+ * already dead once one link fails, so the relaunch would only change how the rest fail, not whether.
+ *
+ * Applies to the next DIFFERENT scenario only — never to a RETRY of the one that just failed. The
+ * runner re-runs a failed scenario, and giving attempt 2 a stronger reset would break the guarantee
+ * `mochaOpts.retries` rests on: race victims recover on attempt 2, real failures fail both attempts.
+ * A dirty-state failure IS a real failure; if its retry silently got a wiped data layer it would pass,
+ * the reporter keeps the last attempt, and a scenario that only works after a wipe would ship as a
+ * clean `Passed`. That false pass is worse than the flakiness escalation was added to fix.
+ *
+ * The generated spec emits this same ladder inline; both exist so the compiler and the runtime cannot
+ * drift apart, and a test asserts they agree.
+ */
+export function escalateResetTier(tier: ResetTier): ResetTier {
+  switch (tier) {
+    case 'none': return 'none';
+    case 'soft': return 'data';
+    case 'data': return 'full';
+    case 'full': return 'full';
+  }
+}