@sun-asterisk/sungen 3.2.32 → 3.2.33

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/url-assertion.hbs

@@ -23,8 +23,12 @@
       `https://admin.example.com/jobs` asserted the PATH on any host, and the public site's /jobs
       satisfied it.
 
+      `ignoreQuery` comes from the page ENTRY's `query: any`, not from the step, because it is a fact
+      about the page rather than about one assertion (#748). It relaxes only the bare-page rule; the
+      declared-value half below is untouched, so the two compose rather than override each other.
+
       The declared-value half is gated on `dataRef`, not on `query`. The step wrote `with {{v}}`
       either way; gating on the resolved VALUE meant an empty test-data entry silently dropped the
       whole check and fell back to the bare-page rule, which is the one case specs/url-assert.ts
       exists to throw on. --}}
-await expectPage(page, { pathname: /^{{pathRegex}}\/?$/{{#if hostRegex}}, hostname: /^{{hostRegex}}$/{{/if}}{{#if dataRef}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} });
+await expectPage(page, { pathname: /^{{pathRegex}}\/?$/{{#if hostRegex}}, hostname: /^{{hostRegex}}$/{{/if}}{{#if ignoreQuery}}, ignoreQuery: true{{/if}}{{#if dataRef}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} });

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

@@ -210,7 +210,7 @@ function getAuthMode(
  * Grouping key for the anonymous bucket. A literal that no `@auth:<role>` can produce, so an
  * imaginative role name can never land in the same group as `@no-auth`.
  */
-const NO_AUTH_GROUP_KEY = 'no-auth';
+const NO_AUTH_GROUP_KEY = '\0no-auth';
 
 
 /**
@@ -266,6 +266,56 @@ function warnMultipleAuthTags(tags: string[], context: string): void {
   }
 }
 
+/**
+ * Drop the YAML comment from ONE line: a `#` at line start or preceded by whitespace,
+ * and not inside a quoted scalar. Line-level only — see `yamlWithoutComments` for the
+ * block-scalar case, which this function cannot see from a single line.
+ */
+function stripYamlComment(line: string): string {
+  let quote: string | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (quote === '"' && c === '\\') { i++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i);
+  }
+  return line;
+}
+
+/**
+ * The YAML text a `${QA_*}` scan may look at: comments removed, block scalars kept whole.
+ *
+ * SG-W009's reference scan used to run over the whole raw file, so a `${QA_*}` that only ever
+ * appeared in a `#` comment counted as a live reference — including the one sungen's own
+ * scaffolded "HOW TO FILL VALUES" block writes into every test-data file. The declared side has
+ * always been line-wise; this brings the reference side to the same footing.
+ *
+ * Inside a `|`/`>` block scalar every character is literal content, `#` included, so those lines
+ * pass through untouched. Stripping them would send the check the other way — a real, undeclared
+ * `${QA_*}` written after a `#` in a block scalar would go unreported, and the run would only fail
+ * later with "environment variable not set". A missed warning is worse than a noisy one.
+ */
+function yamlWithoutComments(text: string): string {
+  const out: string[] = [];
+  let blockIndent: number | null = null;
+  for (const line of text.split('\n')) {
+    if (blockIndent !== null) {
+      const indent = line.search(/\S/);
+      // blank lines and anything indented deeper than the key stay inside the scalar
+      if (indent === -1 || indent > blockIndent) { out.push(line); continue; }
+      blockIndent = null;
+    }
+    const block = /^(\s*)[^#\s][^:]*:\s*[|>][+-]?\d*[+-]?\s*$/.exec(line);
+    if (block) { blockIndent = block[1].length; out.push(line); continue; }
+    out.push(stripYamlComment(line));
+  }
+  return out.join('\n');
+}
+
 /**
  * Result of test generation for a single feature file
  */
@@ -1314,7 +1364,8 @@ export class CodeGenerator {
    * a name in the committed .env.qa.example. An undeclared ref means the test throws
    * "environment variable not set" the moment the key is used — surface it at compile
    * time instead. Only the `${QA_*}` shape is checked: any other `${...}` text is
-   * ordinary literal data by design (never resolved, never warned about).
+   * ordinary literal data by design (never resolved, never warned about). A `${QA_*}`
+   * that appears only inside a `#` comment is prose, not a reference, and is ignored.
    */
   private reportedEnvRefs = new Set<string>();
   private checkEnvSecretRefs(featureFile: string): void {
@@ -1322,7 +1373,7 @@ export class CodeGenerator {
     if (!fs.existsSync(testDataDir)) return;
     const referenced = new Set<string>();
     for (const f of fs.readdirSync(testDataDir).filter((x) => x.endsWith('.yaml') || x.endsWith('.yml'))) {
-      const text = fs.readFileSync(path.join(testDataDir, f), 'utf-8');
+      const text = yamlWithoutComments(fs.readFileSync(path.join(testDataDir, f), 'utf-8'));
       for (const m of text.matchAll(/\$\{(QA_[A-Z0-9_]+)\}/g)) referenced.add(m[1]);
     }
     if (!referenced.size) return;

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

@@ -186,12 +186,29 @@
  *             build names itself at generate time instead of one step further downstream
  *
  *   SG-W028 — a step's trailing scope clause was DROPPED, so the step runs against more of the page
- *             than its sentence names. Two causes, one code: the `<word>` after `in [X]` is not a
+ *             than its sentence names. Three causes, one code: the `<word>` after `in [X]` is not a
  *             container type (a typo, or a leaf element used as a parent), or the by-content form
  *             `in [X] <type> with {{v}}` was written for the mobile adapter, which chains a parent
  *             element and has no content filter. Before this, both compiled clean and silently
  *             widened the assertion to the whole screen — the failure mode that only a diff of the
- *             generated spec against the Gherkin could reveal (#667)
+ *             generated spec against the Gherkin could reveal (#667).
+ *             The third is the RENDER-time half #667 could not reach: the clause parsed and the
+ *             container resolved, but the step form that won the sentence emits a locator built
+ *             inline and never applies it. Judged on the emitted code — every path that honours a
+ *             scope emits the resolved container locator verbatim, so its absence IS the drop —
+ *             which makes the check total rather than a list of templates to keep in sync. Found
+ *             via `see [学科] label with {{v}} in [Education Card 6] card` compiling to a page-wide
+ *             `getByText` on a screen repeating ten identical cards (#747)
+ *   SG-W037 — a `type: page` entry says something about the QUERY that the compiler cannot use.
+ *             Two causes, one code, and the same root confusion behind both: a bare `see [X] page`
+ *             asserts the URL carries NO query (#464), which is unsatisfiable for a page keyed by
+ *             one (`/admins/detail?id=5`, where the id comes from the row just clicked). Either the
+ *             entry's `value` carries a `?`/`#` — dropped, because a page value is the path only and
+ *             the pattern is matched against `u.pathname`, which never holds a query — or `query:`
+ *             declares something other than `any`, which is ignored rather than read as permissive,
+ *             since a typo must never quietly switch off the #464 assertion. Both used to be silent,
+ *             and the first is how #748 was misdiagnosed in the field as a regex-escaping bug: the
+ *             obvious workaround produced byte-identical output and no hint why
  *   SG-W029 — a mobile (appium) feature compiled with NO usable app-package `Path:` — either the line
  *             is missing outright, or it holds a web-style route (`Path: /applied-jobs`) that the
  *             package guard rejects. Both used to be silent, and both cost the same two things: the
@@ -255,9 +272,21 @@
  *             than the one the scenario means, and nothing else would ever say so. Not reported for
  *             testid/label/placeholder/role+name/text entries, which name a particular thing —
  *             warning there would fire on nearly every capture in a suite
+ *   SG-E038 — a `{{var}}` the compiler cannot resolve: no test-data file for the feature, no such
+ *             key, or a key holding a list/map where a value was needed. Twenty-four step patterns
+ *             used to catch this and emit the PLACEHOLDER TEXT as the value — `fill [ID] with
+ *             {{valid_partner_id}}` compiled to `fill('${valid_partner_id}')`, generate exited 0,
+ *             and the literal 20 characters were typed into the app. The field under test applied
+ *             no format validation, so the string was accepted, the server saw an unknown user, and
+ *             the scenario failed at the assertion it was written to fail at, for the reason it was
+ *             written to fail: a suite that looked exactly right while feeding the system garbage.
+ *             Worse than one wrong value — every run shared the SAME literal id, so a scenario
+ *             needing a fresh user silently reused one and its state leaked between runs (#781).
+ *             Note a feature resolves `{{var}}` against a data file named after ITSELF, so the
+ *             second `.feature` in a screen directory starts life with no data file at all
  * Diagnostics never change the EXIT CODE by themselves; `sungen generate --strict` turns any
  * collected diagnostic into a non-zero exit. They are not all inert, though: SG-W001, SG-W011,
- * SG-E020, SG-E021, SG-W020, SG-E023, SG-E024, SG-E025, SG-E026, SG-E027 and SG-E035 additionally compile
+ * SG-E020, SG-E021, SG-W020, SG-E023, SG-E024, SG-E025, SG-E026, SG-E027, SG-E035 and SG-E038 additionally compile
  * the offending step to a runtime `throw` — a step that reads as a check and silently checks
  * nothing is worse than one that fails loudly — and SG-E031 refuses the file outright. (SG-E022 is
  * the one exception to the "blame the Gherkin" rule and throws nothing: the file is still written
@@ -265,7 +294,7 @@
  * Generation always COMPLETES — the rest of the scenario and the rest of the file still compile.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W004' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-W016' | 'SG-W017' | 'SG-W018' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-W026' | 'SG-E025' | 'SG-E026' | 'SG-E022' | 'SG-E023' | 'SG-E024' | 'SG-E027' | 'SG-W028' | 'SG-W029' | 'SG-W030' | 'SG-E031' | 'SG-W032' | 'SG-W034' | 'SG-E035' | 'SG-W036';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W004' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-W016' | 'SG-W017' | 'SG-W018' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-W026' | 'SG-E025' | 'SG-E026' | 'SG-E022' | 'SG-E023' | 'SG-E024' | 'SG-E027' | 'SG-W028' | 'SG-W029' | 'SG-W030' | 'SG-E031' | 'SG-W032' | 'SG-W034' | 'SG-E035' | 'SG-W036' | 'SG-W037' | 'SG-E038';
 
 export interface Diagnostic {
   code: DiagnosticCode;

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

@@ -193,6 +193,7 @@ export class PatternRegistry {
             comment: resolved.comment,
             pattern: pattern.name,
             templateData: resolved.data,
+            parentLocator,
           };
         }
 
@@ -202,7 +203,7 @@ export class PatternRegistry {
           if (generatorStateMiss) return generatorStateMiss;
           // A generator returning nothing still falls through to the no-pattern path.
           const generated = pattern.generator(step, scoped);
-          return generated ? { ...generated, pattern: pattern.name } : null;
+          return generated ? { ...generated, pattern: pattern.name, parentLocator } : null;
         }
 
         return null;
@@ -447,17 +448,23 @@ export class PatternRegistry {
 
   /**
    * Resolve a `{{var}}` written where literal text is expected, leaving anything else untouched.
-   * An unknown variable stays as written rather than throwing — the locator is then wrong in a way
-   * the author can read, which beats losing the whole step.
+   *
+   * An unresolvable ref is NOT kept as written. That was the last of the #781 swallows, and the
+   * hardest to see, because the old rationale — "the locator is then wrong in a way the author can
+   * read, which beats losing the whole step" — is true of a locator NAME and false here. The second
+   * `with` in `see [Tag] header with {{label}} in [Job Card] card with {{job_title}}` binds to the
+   * PARENT scope, so the value lands in `.filter({ hasText: '{{job_title}}' })`: a scope that can
+   * never match, compiled with ZERO diagnostics and `generate` exiting 0. The author then reads a
+   * "element not found" timeout that says nothing about the missing test-data key.
+   *
+   * Letting it throw routes it to StepMapper.mapStep like every other ref, so the step names the
+   * ref and the file it wanted. Only a string that IS exactly `{{ref}}` is ever resolved here;
+   * anything else is returned untouched, so ordinary literal text is unaffected.
    */
   private static resolveInlineData(text: string, context: PatternContext): string {
     const match = text.match(/^\{\{([a-z0-9\-._]+)\}\}$/i);
     if (!match) return text;
-    try {
-      return context.dataResolver.resolveData(match[1], context.featureName);
-    } catch {
-      return text;
-    }
+    return context.dataResolver.resolveData(match[1], context.featureName);
   }
 
   /**

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

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

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

@@ -14,6 +14,11 @@ import { PatternContext } from './types';
  * Only the target's own scope is stamped; anything a pattern resolves that ALREADY carries a
  * `parentLocator` is left alone, so a pattern that builds its own container chain (table rows) keeps
  * winning over the generic one.
+ *
+ * The scope also rides on the CONTEXT itself, not only on what the pattern resolves. A pattern whose
+ * locator is built inline — `see [X] label with {{v}}` matches on-screen caption text and usually
+ * has no selectors.yaml entry at all, so `resolveSelector` throws and the branch renders from `{}` —
+ * has no `resolved` object for the stamp to land on, and lost the scope silently (#747).
  */
 export function withParentScope(context: PatternContext, parentLocator: string): PatternContext {
   const scope = <T>(resolved: T): T =>
@@ -35,6 +40,7 @@ export function withParentScope(context: PatternContext, parentLocator: string):
 
   return {
     ...context,
+    parentLocator,
     selectorResolver,
     renderLocator: (resolved: any) => context.renderLocator(scope(resolved)),
   };

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

@@ -4,7 +4,7 @@ import { TemplateEngine } from './template-engine';
 import { adapterRegistry } from './adapters';
 import { PatternRegistry, PatternContext, Platform } from './patterns';
 import { SelectorResolver, type ResolvedSelector } from './utils/selector-resolver';
-import { DataResolver } from './utils/data-resolver';
+import { DataResolver, DataRefError } from './utils/data-resolver';
 import { locatorIdentityKey } from './utils/dialog-scope-identity';
 import { DiagnosticsCollector } from './diagnostics';
 import { unsupportedStepCode } from './patterns/unsupported-step-code';
@@ -44,6 +44,9 @@ export interface MappedStep {
   imports?: string[]; // Required imports
   pattern?: string; // Name of the step form that produced the code (post-map guards read it)
   templateData?: Record<string, any>; // What the resolver handed the template (e.g. a recorded refusal)
+  /** The container locator the step's `in [Parent] <type>` clause resolved to, when it carried one.
+   *  Recorded so a post-map guard can check the scope actually reached the code (SG-W028, #747). */
+  parentLocator?: string;
 }
 
 /**
@@ -226,7 +229,45 @@ export class StepMapper {
    * Map a Gherkin step to Playwright code
    * Uses pattern registry first, falls back to AI if enabled
    */
+  /**
+   * SG-E038 — the ONE place an unresolvable `{{var}}` is answered.
+   *
+   * Twenty-four step patterns used to catch the resolver's failure each in their own way and
+   * substitute the placeholder TEXT as the value, so `fill [ID] with {{valid_partner_id}}` shipped
+   * `fill('${valid_partner_id}')` — 20 literal characters typed into the app, `generate` exiting 0,
+   * and a scenario that failed exactly where it was written to fail, for the reason it was written
+   * to fail. Nothing told the run apart from a correct one (#781).
+   *
+   * The step now compiles to a throw naming the ref and the file, which is the house answer to
+   * "the compiler would otherwise invent something" (SG-E023/E024/E026 all work this way). A throw
+   * is preferred over letting the error kill the feature file, because one run then reports EVERY
+   * unresolved ref instead of the first; `--strict` turns the diagnostic into exit 1.
+   */
   mapStep(step: ParsedStep): MappedStep | Promise<MappedStep> {
+    try {
+      return this.mapStepResolving(step);
+    } catch (err) {
+      if (err instanceof DataRefError) return this.unresolvedDataRef(step, err);
+      throw err;
+    }
+  }
+
+  private unresolvedDataRef(step: ParsedStep, err: DataRefError): MappedStep {
+    const fix = err.file
+      ? `add a "${err.dataRef}" key to ${err.file}`
+      : `define "${err.dataRef}" in the feature's test-data file`;
+    const reason =
+      `step "${step.text}": {{${err.dataRef}}} does not resolve — ${err.message}. `
+      + `${fix}, or reference a key that exists. The step compiles to this throw rather than `
+      + `typing the literal text "\${${err.dataRef}}" into the app as if it were data.`;
+    this.diagnostics?.add('SG-E038', reason, { feature: this.featureName, step: step.text });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `Unresolved {{${err.dataRef}}} — see SG-E038: ${step.text}`,
+    };
+  }
+
+  private mapStepResolving(step: ParsedStep): MappedStep | Promise<MappedStep> {
     this.stepCounter++;
 
     // Track effective keyword: And/But inherit from previous Given/When/Then
@@ -377,12 +418,7 @@ export class StepMapper {
         // Case 3: [panel] dialog with {{value}}
         // Use dataRef as filter text — the dialog name is dynamic (from test-data),
         // so use .filter({ hasText }) instead of { name } for reliable matching
-        let filterText = '';
-        try {
-          filterText = this.dataResolver.resolveData(step.dataRef, this.featureName);
-        } catch {
-          filterText = `\${${step.dataRef}}`;
-        }
+        const filterText = this.dataResolver.resolveData(step.dataRef, this.featureName);
         contextVars.dialogFilterText = filterText;
         // The declared entry still owns the ROOT the filter applies to — but only when it
         // is a non-role strategy (locator/testid/css). A role entry keeps the bare
@@ -474,6 +510,10 @@ export class StepMapper {
       if (rowFilterDropped) return rowFilterDropped;
       const badType = this.checkUnknownSelectorType(step, mappedStep);
       if (badType) return badType;
+      // LAST of the guards, and deliberately so: every check above can REPLACE the step with a
+      // refusal, and reporting a dropped scope against code that is about to be discarded is the
+      // "two contradictory messages about one step" this guard's own doc rules out.
+      this.checkParentScopeDropped(step, mappedStep);
       return mappedStep;
     }
 
@@ -745,6 +785,49 @@ export class StepMapper {
     return null;
   }
 
+  /**
+   * The container scope parsed, resolved — and then never reached the emitted code.
+   *
+   * #667 closed the parse-time half of this: an `in [X] <word>` whose `<word>` is not a container
+   * type is reported (SG-W028) rather than truncated. It could not close the render-time half,
+   * because honouring the scope is per-template work: the registry stamps `parentLocator` on what a
+   * RESOLVER hands back and `withParentScope` stamps it on what any pattern RESOLVES, but a branch
+   * that builds its locator inline and renders from hand-picked fields receives neither. Three did,
+   * and `see [学科] label with {{v}} in [Education Card 6] card` compiled to a page-wide
+   * `getByText` with no diagnostic at all (#747) — a green test reading a card the sentence never
+   * names, findable only by diffing the generated spec against the Gherkin.
+   *
+   * So the fact is taken from the OUTPUT, exactly as SG-W032 takes the row filter from `.filter(`:
+   * every path that honours a container scope emits the resolved container locator verbatim, so its
+   * absence from the code IS the drop. That makes the guard total — it covers every template that
+   * exists now and every one added later, without a list to keep in sync.
+   *
+   * A step already refused elsewhere is excluded: it compiles to a `throw`, and a second opinion on
+   * top of a refusal is two contradictory messages about one step (SG-W032's reasoning, unchanged).
+   * The `throw` test covers a refusal the PATTERN layer recorded; a refusal one of the guards above
+   * substitutes is covered by call order instead — this one runs last.
+   *
+   * Returns `void`, not `MappedStep | null` like its siblings: it only ever REPORTS. Typed that way
+   * on purpose, so a future edit copying the sibling shape cannot assume a replacement step is being
+   * consumed when nothing is looking at one.
+   */
+  private checkParentScopeDropped(step: ParsedStep, mapped: MappedStep): void {
+    const parent = mapped.parentLocator;
+    if (!parent) return;
+    const code = mapped.code || '';
+    if (code.startsWith('throw new Error(')) return;
+    if (code.includes(parent)) return;
+
+    this.diagnostics?.add('SG-W028',
+      `step "${step.text}" names the container [${step.parentRef}] but the generated code does not `
+      + `scope to it — the step runs against the WHOLE page, so it fails where the target repeats and `
+      + `passes on a DIFFERENT [${step.parentRef}] where it does not. The "${mapped.pattern}" step `
+      + `form does not carry a container scope. Assert on an element the container owns (give it a `
+      + `selectors.yaml entry and use "has text"/"contains"), or drop the clause so the sentence `
+      + `matches what is actually checked.`,
+      { feature: this.featureName, step: step.text });
+  }
+
   private checkAssertionClauseSwallowed(step: ParsedStep, mapped: MappedStep): MappedStep | null {
     const code = mapped.code || '';
     // Bare visibility: nothing but a visible/displayed assertion on one locator.
@@ -831,7 +914,6 @@ export class StepMapper {
     // delimiters, so the code may carry `__SUNGEN_TD\$key\$__` instead of the plain form.
     const marker = DataResolver.encodeMarker(step.dataRef);
     if (code.includes(marker) || code.includes(marker.replace(/\$/g, '\\$'))) return;
-    if (code.includes(`\${${step.dataRef}}`)) return;                    // unresolved fallback
     if (code.includes(step.dataRef)) return;                             // testData.set('ref'), comments
     try {
       const value = this.dataResolver.resolveData(step.dataRef, this.featureName);

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

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

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

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