@sun-asterisk/sungen 3.2.24 → 3.2.25

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

@@ -5,6 +5,7 @@ import { PatternRegistry, PatternContext, Platform } from './patterns';
 import { SelectorResolver } from './utils/selector-resolver';
 import { DataResolver } from './utils/data-resolver';
 import { DiagnosticsCollector } from './diagnostics';
+import { unsupportedStepCode } from './patterns/unsupported-step-code';
 import { loadAppProfile, ResolvedAppProfile } from './app-profile';
 import { capabilityRegistry } from '../../capabilities/registry';
 
@@ -280,6 +281,28 @@ export class StepMapper {
       this.templateEngine.setBaseContext({ inDialog: false });
       return { code: '', comment: 'Exit dialog scope' };
     }
+    // `is on [X] <type>` supports exactly two shapes: `page` (URL from the page-type selector
+    // entry) and `dialog` (the scope directive below). Anything else used to fall through to the
+    // navigate-to-route pattern, whose draft-era catch-all read every `is on` as a real
+    // navigation: Given/When emitted page.goto(<the SCREEN's path> — [X] was never even read),
+    // a full reload that wipes the state a multi-step flow just built; Then emitted a URL
+    // assertion against that same path, which on a single-URL SPA can never fail. Both were
+    // silent, and the one diagnostic that describes this class (SG-W013) is scoped to `page`.
+    // Refusing here is the point: "the user is at step X" is a state, not a navigation.
+    // `screen` is the mobile analog of `page` — the appium adapter renders it as the app-launch
+    // no-op, and a shipped fixture pins that — so it belongs in the supported set.
+    const IS_ON_TYPES = ['page', 'screen', 'dialog'];
+    if (/\bis\s+on\s+\[/i.test(step.text) && step.elementType &&
+        !IS_ON_TYPES.includes(step.elementType)) {
+      throw new Error(
+        `"${step.text}" — \`is on\` names a navigation target, and only \`[X] page\` (\`screen\` on mobile) and ` +
+        `\`[X] dialog\` are supported; ` +
+        `"${step.elementType}" is neither. If [${step.selectorRef}] is a state inside the current page (a wizard step, ` +
+        `a panel), assert it instead: \`Then User see [${step.selectorRef}] section\` (or \`see [X] text with {{v}}\`), ` +
+        `and reach that state with the flow's own When steps or an @steps/@extend base scenario. ` +
+        `If it really is a separate URL, declare it in selectors.yaml as "type: page" and write \`[${step.selectorRef}] page\`.`
+      );
+    }
     // Given User is on [...] dialog — set dialog scope (3 cases)
     if (step.text.includes('is on') && step.elementType === 'dialog') {
       this.inDialogScope = true;
@@ -372,30 +395,42 @@ export class StepMapper {
       }
       this.checkDataRefConsumed(step, mappedStep);
       this.checkPageAssertionNoOpOnMobile(step, mappedStep);
+      this.checkSetupNoOpOnMobile(step, mappedStep);
       this.checkPageAssertionFallback(step, mappedStep);
       this.checkDeclaredUrlHasNoQuery(step, mappedStep);
+      const swallowed = this.checkAssertionClauseSwallowed(step, mappedStep);
+      if (swallowed) return swallowed;
       return mappedStep;
     }
 
-    // No pattern matched - return TODO comment
+    // No pattern matched. The step is, by definition, vocabulary sungen does not have — so it
+    // compiles to a loud `throw`, not a comment. A comment let the scenario go GREEN having asserted
+    // nothing, which is the silent-loss class this channel exists to close; SG-E020/SG-W020/SG-E021
+    // already treat their own unsupported steps this way and this is the same fact about the step.
+    // `@manual` remains the way to park a check sungen genuinely cannot express — it is skipped
+    // before mapping, so it never reaches here.
+    let reason: string;
     if (/\bexpect\b.*\b(?:local|session)\s+storage\b/i.test(step.text)) {
       // The natural first guess for a storage check — but `expect` steps only read
       // {{response}} refs, so this shape silently compiles to nothing. Point at the
       // supported grammar instead of emitting the generic no-pattern warning.
-      this.diagnostics?.add('SG-W011',
-        'storage assertions use `User see [KEY] in local storage exists` (also: does not exist / is not empty / has length {{n}} / key matching "PATTERN") — the `expect …` form compiles to a no-op', {
+      // Kept deliberately more specific than the generic reason below: this shape is the natural
+      // first guess for a storage check, so it earns a pointer to the real grammar.
+      reason = 'storage assertions use `User see [KEY] in local storage exists` (also: does not exist / is not empty / has length {{n}} / key matching "PATTERN") — the `expect …` form matches no pattern';
+      this.diagnostics?.add('SG-W011', reason, {
         feature: this.featureName,
         step: step.text,
       });
     } else {
-      this.diagnostics?.add('SG-W001', 'step matched no pattern — compiled to a no-op // TODO comment', {
+      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.`;
+      this.diagnostics?.add('SG-W001', reason, {
         feature: this.featureName,
         step: step.text,
       });
     }
     return {
-      code: `// TODO: Implement step: ${step.text}`,
-      comment: `Unrecognized step pattern: ${step.text}`,
+      code: unsupportedStepCode(reason),
+      comment: `Unrecognized step pattern — see SG-W001/SG-W011: ${step.text}`,
     };
   }
 
@@ -500,6 +535,64 @@ export class StepMapper {
    * disappears from the output (e.g. issue #464). Warning-only: loose containment
    * checks err on the side of NOT flagging.
    */
+  /**
+   * SG-E023 — an assertion CLAUSE was swallowed and the step became a bare visibility check.
+   *
+   * The sibling of SG-E021, for the clauses that are not states. SG-E021 closed the state case
+   * declaratively — a pattern lists the states it accounts for and anything else throws — but a
+   * dropped `matches` / `contains` / `has text` still slid through: reproduced live, a `matches
+   * "<format>"` step compiled by a sungen predating that step lost the assertion entirely, emitted
+   * no warning, and left a `toBeVisible()` that passed whatever the label said.
+   *
+   * So: if the code is a bare visibility assertion while the text still carries a clause that
+   * means something STRONGER, compile a throw instead (the SG-W001/SG-E020 treatment). A red test
+   * naming the swallowed clause costs minutes; a green one that asserts nothing costs a release.
+   *
+   * 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.
+   */
+  private checkAssertionClauseSwallowed(step: ParsedStep, mapped: MappedStep): MappedStep | null {
+    const code = mapped.code || '';
+    // Bare visibility: nothing but a visible/displayed assertion on one locator.
+    // A NEGATED visibility assert is a real state assertion, not a bare one — mobile spells
+    // `is hidden` as `.not.toBeDisplayed()`, which carries no `toBeHidden` token to exclude on.
+    // A golden fixture caught this: without the `.not.` exclusion the guard refused a correct step.
+    const isBareVisibility = /toBeVisible\(\)|toBeDisplayed\(\)|__assertVisible\(/.test(code)
+      && !/\.not\./.test(code)
+      // `.filter(` counts as consumed: `contains` on a list member compiles to
+      // `filter({ hasText: … }) … toBeVisible()`, where the clause shaped the LOCATOR rather than
+      // the matcher. Without this the guard refused that legitimate form — a sibling test on main
+      // caught it during the merge.
+      && !/\.filter\(/.test(code)
+      && !/toHaveText|toContainText|toBeHidden|toBeDisabled|toBeChecked|RegExp|\/\^|getAttribute|testData\./.test(code);
+    if (!isBareVisibility) return null;
+
+    // Only the clauses no other channel owns. Deliberately NOT `is <state>`: SG-E021 already
+    // covers that, and better — a pattern DECLARES the states it accounts for (`StepPattern.states`)
+    // and anything else throws, which is checkable at the pattern layer instead of sniffed from the
+    // emitted code here. `with {{v}}` belongs to SG-W002 for the same reason.
+    const CLAUSES: Array<[RegExp, string]> = [
+      // Bare `\bmatches\b`, not `matches "`: the quote-less phrasing is the likelier authoring
+      // slip AND what an older compiler leaves behind, and both must be caught.
+      [/\bmatches\b/i, 'matches "<format>"'],
+      [/\bcontains\b/i, 'contains'],
+      [/\b(?:should\s+have|has)\s+text\b/i, 'has text'],
+    ];
+    const hit = CLAUSES.find(([re]) => re.test(step.text));
+    if (!hit) return null;
+
+    const reason = `step "${step.text}" carries the clause \`${hit[1]}\` but compiled to a bare `
+      + `visibility check — the clause was dropped, so the assertion would pass whatever the element `
+      + `says. Either the phrasing is not the supported one for that clause (see the `
+      + `sungen-gherkin-syntax reference), or this sungen predates the step: check you are running `
+      + `the project-local compiler (\`npx sungen\`), not an older global one.`;
+    this.diagnostics?.add('SG-E023', reason, { feature: this.featureName, step: step.text });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `Assertion clause dropped — see SG-E023: ${step.text}`,
+    };
+  }
+
   private checkDataRefConsumed(step: ParsedStep, mapped: MappedStep): void {
     if (!step.dataRef || !this.diagnostics) return;
     const code = mapped.code || '';
@@ -572,6 +665,56 @@ export class StepMapper {
   /**
    * Create pattern context for generators
    */
+  /**
+   * SG-W023 — a mobile SETUP step that emitted no executable code, so a declared precondition is
+   * never actually established.
+   *
+   * `Given the user is logged out` matches `user-not-logged-in` → the `clear-auth` template, which on
+   * Appium is a bare comment: mobile auth lives in the keychain and prefs, not in cookies, so there
+   * is nothing a per-step action can clear. The step therefore READS as establishing a precondition
+   * and establishes nothing — the scenario runs against whatever the previous one left signed in.
+   * Same false-pass class as SG-W022, reached through setup instead of assertion.
+   *
+   * Keyed on the EMITTED CODE, not on a template name (MappedStep does not carry one), so any future
+   * setup template that degrades to a comment is caught by the same check. The phrasings mirror the
+   * matchers in driver-ui's `setupPatterns`; `application is running` and `user is logged in` are
+   * absent on purpose — the first is legitimately empty on mobile (wdio capabilities already launched
+   * the app) and the second is a TODO template on BOTH adapters, so neither is a mobile-specific gap.
+   *
+   * Deliberately NOT compiled to a `throw`, unlike SG-W020/SG-E021: an unestablished precondition
+   * weakens the setup rather than inverting an assertion, and throwing would break every mobile suite
+   * that already carries one of these steps. The remedy named in the message is a feature-level reset
+   * tier, because app state is reset in the `beforeEach` hook — not mid-scenario by a step.
+   */
+  private checkSetupNoOpOnMobile(step: ParsedStep, mapped: MappedStep): void {
+    if (this.platform !== 'mobile' || !this.diagnostics) return;
+
+    const text = step.text.toLowerCase();
+    // App-state preconditions → a reset tier clears the layers they name. Backend state is a
+    // different remedy entirely, so it carries its own message.
+    const isAppState = /\blogged out\b|\bnot logged in\b|clean browser state|fresh browser|new browser session/.test(text);
+    const isBackendState = /database is empty|database is cleared|clear database/.test(text);
+    if (!isAppState && !isBackendState) return;
+
+    // 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;
+
+    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'
+      : 'mobile auth and app storage live in the keychain/prefs, which no per-step action can clear — declare `@reset:data` on the Feature so each scenario starts from a wiped data layer';
+    this.diagnostics.add('SG-W023',
+      `this setup step compiled to a COMMENT — the precondition it reads as establishing is never established, so the scenario runs against whatever the previous one left behind and passes regardless. ${remedy}`,
+      { feature: this.featureName, step: step.text });
+  }
+
   /**
    * SG-W022 — a `page` assertion that emitted no executable code on mobile.
    *

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

@@ -1,6 +1,7 @@
 import Handlebars from 'handlebars';
 import fs from 'fs';
 import path from 'path';
+import type { RenderImportsOptions } from './adapters/adapter-interface';
 
 export class TemplateEngine {
   private templates: Map<string, HandlebarsTemplateDelegate> = new Map();
@@ -38,9 +39,23 @@ export class TemplateEngine {
         .replace(/\t/g, '\\t');
     });
 
+    // 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
+    // escaping an escape. The line terminators are not cosmetic: a regex literal cannot span
+    // lines, so a value carrying a newline (a multi-line heading, a Flutter composite label)
+    // produced `/^line one<LF>line two$/` — "Unterminated regular expression", and the ENTIRE
+    // .spec.ts stopped parsing. escapeQuotes has always escaped \n/\r/\t for its own
+    // container; this helper omitting them was an oversight, not a design choice. U+2028/U+2029
+    // terminate a regex literal too, though a JS string literal tolerates them.
     Handlebars.registerHelper('escapeRegex', function(text: string) {
       if (text == null) return '';
-      return String(text).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+      return String(text)
+        .replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
     });
 
     Handlebars.registerHelper('includes', function(text: string, search: string) {
@@ -281,8 +296,8 @@ export class TemplateEngine {
     this.baseContext = { ...this.persistentContext };
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): 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 });
+  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 });
   }
 
   renderTestFile(data: {

package/src/generators/test-generator/utils/format-pattern.ts

@@ -0,0 +1,79 @@
+/**
+ * Format placeholders → a regex source, for `see [T] <type> matches "<format>"`.
+ *
+ * QA specs state a label's contract as a SHAPE, not a value: "Format: yyyy/mm/dd ~ yyyy/mm/dd",
+ * "Format: 残りX個". Neither existing text assertion can express that — an exact-value assert
+ * pins data that changes daily (red while the app is right), and `contains` proves almost
+ * nothing ("abc ~ def" passes). This translator keeps the spec's own vocabulary in the Gherkin
+ * so the step reads like the requirement, and no regex reaches a file QA has to review.
+ *
+ * Tokens (everything else is a literal, regex-escaped):
+ *   yyyy → a 4-digit year          mm | dd | hh | ss → a zero-padded 2-digit part
+ *   X    → an integer, thousand separators allowed (the app renders prices as "2,800円")
+ *   *    → any run of characters, for a label that carries surrounding content
+ *
+ * A token only counts when it is not glued to an ASCII letter, so a literal English prefix
+ * survives ("Comment" keeps its "mm"; "yyyy/mm/dd" does not). Japanese/symbol literals are
+ * unaffected either way.
+ */
+
+/** Longest-first: `yyyy` must win over a bare `yy`-style prefix of another token. */
+const TOKENS: Array<[string, string]> = [
+  ['yyyy', '\\d{4}'],
+  ['mm', '\\d{2}'],
+  ['dd', '\\d{2}'],
+  ['hh', '\\d{2}'],
+  ['ss', '\\d{2}'],
+  ['X', '\\d+(?:,\\d{3})*'],
+  ['*', '[\\s\\S]*'],
+];
+
+const isAsciiLetter = (ch: string | undefined): boolean => !!ch && /[A-Za-z]/.test(ch);
+const escapeLiteral = (ch: string): string => ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Translate a format string into an ANCHORED regex source (no delimiters, no flags).
+ * Anchored because the spec means the whole label: "Format: X件" is not satisfied by "12件です".
+ * Use the `*` token where the label legitimately carries more (a fused mobile node).
+ */
+export function formatToRegexSource(format: string): string {
+  let out = '';
+  let i = 0;
+  while (i < format.length) {
+    const prev = i > 0 ? format[i - 1] : undefined;
+    let matched = false;
+    for (const [token, regex] of TOKENS) {
+      if (!format.startsWith(token, i)) continue;
+      // `*` is punctuation — the letter-adjacency rule protects word-like tokens only.
+      if (token !== '*') {
+        const next = format[i + token.length];
+        if (isAsciiLetter(prev) || isAsciiLetter(next)) continue;
+      }
+      out += regex;
+      i += token.length;
+      matched = true;
+      break;
+    }
+    if (!matched) {
+      out += escapeLiteral(format[i]);
+      i += 1;
+    }
+  }
+  return `^${out}$`;
+}
+
+/** True when the string carries at least one token — i.e. it is a FORMAT, not a plain value. */
+export function hasFormatToken(format: string): boolean {
+  return formatToRegexSource(format) !== `^${format.split('').map(escapeLiteral).join('')}$`;
+}
+
+/**
+ * The same pattern as a JS **regex literal**, ready to paste into generated code.
+ *
+ * Not a string: `new RegExp('^\d{4}$')` is a trap — in a single-quoted JS literal `\d` collapses
+ * to `d`, so the compiled test would silently match the letter instead of a digit. A regex literal
+ * carries the backslashes verbatim; only `/` needs escaping, and date formats are full of them.
+ */
+export function formatToRegexLiteral(format: string): string {
+  return `/${formatToRegexSource(format).replace(/\//g, '\\/')}/`;
+}

package/src/generators/test-generator/utils/js-literal-scanner.ts

@@ -0,0 +1,132 @@
+/**
+ * Minimal left-to-right lexer that segments generated JS into the four contexts a
+ * post-processor must tell apart: string/template literals, regex literals,
+ * comments, and everything else.
+ *
+ * WHY this exists instead of a regex pass per context: independent global regexes
+ * have no idea where a literal actually STARTS. `String.replace` retries at every
+ * offset, so a pattern that wants "quote … marker … quote" happily pairs the
+ * CLOSING quote of one literal with the OPENING quote of the next and rewrites the
+ * code in between. Field report (3.2.23, every version 2.0.0+):
+ *
+ *   await page.getByText('Tìm thấy').filter({ hasText: /^§marker§$/ }).waitFor({ state: 'visible' });
+ *
+ * The marker sits in a REGEX literal, but the string-literal pass matched from the
+ * `'` after `thấy` to the `'` before `visible` and emitted
+ * `getByText('Tìm thấy`)` … `state: `visible' })` — the whole .spec.ts stopped
+ * parsing. Scanning once, in order, makes that class of fault unrepresentable: a
+ * quote can only ever open a literal when the scanner is not already inside one.
+ *
+ * Deliberately NOT a full JS parser — it only needs to find literal boundaries:
+ *   - `${…}` inside a template literal is body text, not nested code (matches what
+ *     the previous passes did, and generated templates never nest a literal there).
+ *   - A `'`/`"` literal must close on its own line; an unterminated one is treated
+ *     as ordinary code so a stray apostrophe (prose in a comment) cannot desync the
+ *     rest of the file. Backticks may span lines, but an unterminated one to EOF is
+ *     likewise demoted to code.
+ *   - A `/` opens a regex only in expression position and only when it closes on the
+ *     same line. Both guards keep a division (or a stray slash) from swallowing the
+ *     literals after it.
+ */
+
+export type SegmentKind = 'code' | 'string' | 'regex' | 'comment';
+
+export interface Segment {
+  kind: SegmentKind;
+  /** Verbatim source slice, INCLUDING delimiters (quotes, slashes, `//`). */
+  text: string;
+}
+
+/** Chars that, immediately before a `/`, make it division or a member access — never a regex. */
+const NOT_REGEX_PREFIX = /[\w$)\]]/;
+const REGEX_FLAGS = /[dgimsuvy]/;
+
+/** Index just past the closing quote, or -1 when the literal never closes (see module note). */
+function scanQuoted(code: string, start: number, quote: string): number {
+  const spansLines = quote === '`';
+  for (let i = start + 1; i < code.length; i++) {
+    const c = code[i];
+    if (c === '\\') { i++; continue; }
+    if (c === quote) return i + 1;
+    if (c === '\n' && !spansLines) return -1;
+  }
+  return -1;
+}
+
+/** Index just past the regex's flags, or -1 when it is not a single-line regex literal. */
+function scanRegex(code: string, start: number): number {
+  // Expression-position guard: skip back over spaces/tabs to the last significant char.
+  let p = start - 1;
+  while (p >= 0 && (code[p] === ' ' || code[p] === '\t')) p--;
+  if (p >= 0 && NOT_REGEX_PREFIX.test(code[p])) return -1;
+
+  let inClass = false;
+  for (let i = start + 1; i < code.length; i++) {
+    const c = code[i];
+    if (c === '\n') return -1;
+    if (c === '\\') { i++; continue; }
+    if (inClass) { if (c === ']') inClass = false; continue; }
+    if (c === '[') { inClass = true; continue; }
+    if (c === '/') {
+      let j = i + 1;
+      while (j < code.length && REGEX_FLAGS.test(code[j])) j++;
+      return j;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Split `code` into ordered segments. Concatenating every `text` reproduces the
+ * input byte for byte — callers rewrite only the segments they care about.
+ */
+export function scanSegments(code: string): Segment[] {
+  const out: Segment[] = [];
+  let codeStart = 0;
+  let i = 0;
+
+  const flushCode = (end: number): void => {
+    if (end > codeStart) out.push({ kind: 'code', text: code.slice(codeStart, end) });
+  };
+  const take = (kind: SegmentKind, end: number): void => {
+    flushCode(i);
+    out.push({ kind, text: code.slice(i, end) });
+    i = codeStart = end;
+  };
+
+  while (i < code.length) {
+    const c = code[i];
+
+    // Comments first: a `//` or `/*` reached in code position can never be a regex,
+    // and consuming them keeps an apostrophe in prose from opening a literal.
+    if (c === '/' && code[i + 1] === '/') {
+      const nl = code.indexOf('\n', i);
+      take('comment', nl === -1 ? code.length : nl);
+      continue;
+    }
+    if (c === '/' && code[i + 1] === '*') {
+      const close = code.indexOf('*/', i + 2);
+      take('comment', close === -1 ? code.length : close + 2);
+      continue;
+    }
+
+    if (c === '\'' || c === '"' || c === '`') {
+      const end = scanQuoted(code, i, c);
+      if (end !== -1) { take('string', end); continue; }
+      i++; // unterminated → ordinary code
+      continue;
+    }
+
+    if (c === '/') {
+      const end = scanRegex(code, i);
+      if (end !== -1) { take('regex', end); continue; }
+      i++; // division or stray slash → ordinary code
+      continue;
+    }
+
+    i++;
+  }
+
+  flushCode(code.length);
+  return out;
+}

package/src/generators/test-generator/utils/mask-refs-for-matching.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ *
+ * Lives in `utils/` rather than in `patterns/index.ts` so the Gherkin parser can reuse it for
+ * state-clause extraction (SG-E021) without importing the pattern registry — which would pull the
+ * whole capability graph into the parser and close a require cycle. `patterns/index.ts` re-exports
+ * it, so its historical import path still resolves.
+ */
+export function maskRefsForMatching(text: string): string {
+  return text
+    .replace(/\{\{[^}]*\}\}/g, '{{~}}')
+    .replace(/\[[^\]]*\]/g, '[~]');
+}