@sun-asterisk/sungen 3.2.32 → 3.2.34

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