@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

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

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

@@ -6,7 +6,7 @@ import { readYaml, readYamlIfExists } from '../../../utils/yaml-io';
 
 import { SelectorType } from '../../../utils/selector-types';
 import { DataResolver } from './data-resolver';
-import { DiagnosticsCollector } from '../diagnostics';
+import { DiagnosticsCollector, type DiagnosticCode } from '../diagnostics';
 import { DEFAULT_CONTENT_NAMED_ROLES } from '../app-profile';
 import { reportUnknownEntryFields } from './selector-entry-fields';
 import { reportUnknownSelectorTypes } from './selector-type-validation';
@@ -33,6 +33,25 @@ interface SelectorEntry {
   // that bounces the user after the URL has already matched turns the step red instead of green.
   anchor?: SelectorEntry;
 
+  // === Page query identity (#748) ===
+  // For a `type: page` entry: `any` means the query string is NOT part of this page's identity.
+  //
+  // A bare `see [X] page` asserts that the URL carries NO query at all (#464 — a filter/search
+  // regression read as green while the query was wrong or gone). That is right for a page whose
+  // identity IS its path, and unsatisfiable for one keyed by a query — `/admins/detail?id=5`,
+  // where the id comes from the row the previous step clicked and is unknowable when the scenario
+  // is written. `with {{v}}` cannot rescue it: that asserts a LITERAL value.
+  //
+  // Declared on the ENTRY rather than added to the step grammar because it is a fact about the
+  // PAGE — every step targeting it needs the same reading — and because `wait for [X] page`
+  // already ignores the query. A step-form escape hatch would serve only the Then side and widen
+  // the very drift the shared url-assertion partial was written to end.
+  //
+  // It does NOT weaken a step that declares its own query: `with {{v}}` still asserts every
+  // declared param. This changes only what SILENCE means — from "there must be no query" to
+  // "the query is not mine to judge".
+  query?: 'any';
+
   // === Mobile per-platform variant (issue #392) ===
   // `android:`/`ios:` sub-selectors for one logical element whose locator differs per OS (composite
   // content-desc, partial/dynamic text, native predicate). Each is a full SelectorEntry.
@@ -166,12 +185,114 @@ export interface ResolvedSelector {
   checkedClass?: string;
   checkedAttribute?: string;
   anchor?: ResolvedSelector;  // page entries only — the rendered-content proof behind `see [X] page` (#662)
+  query?: 'any';        // page entries only — the query is not part of this page's identity (#748)
 }
 
 /**
  * SelectorResolver - Resolves selector references to direct Playwright locator code
  * Supports natural language references with auto-generated keys
  */
+/**
+ * Read an OWN property of a lookup table, or undefined.
+ *
+ * Every type table here — the alias map, the strategy map, the reverse index, and the parsed
+ * selectors.yaml itself — is a bare object literal, so it inherits Object.prototype and answers for
+ * keys it does not have. `elementType` is whatever word the author wrote after `]`, and the three
+ * readers failed three different ways on an inherited one: normalizeElementType is declared
+ * `: string` and returned a FUNCTION to be interpolated into a selector key; inferFromElementType
+ * CALLED that function with no receiver and crashed the compiler with "Cannot convert undefined or
+ * null to object"; and `ALIAS_SPELLINGS[t] ?? []` sailed past its own `??` guard, because a
+ * function is neither null nor undefined, and died on `.map`.
+ *
+ * No real feature file says `[X] valueOf`. The rule is the point: a lookup table must not answer
+ * for a key it does not have, and one helper is cheaper to keep right than four call sites.
+ */
+function own<T>(table: Record<string, T>, key: string): T | undefined {
+  return Object.prototype.hasOwnProperty.call(table, key) ? table[key] : undefined;
+}
+
+/**
+ * Gherkin element-type spelling → the canonical suffix used in selectors.yaml keys.
+ *
+ * Module-scope so the table has exactly ONE reader-facing definition and the reverse index below
+ * can be DERIVED from it. A second, hand-written reverse table is the failure mode issue #728
+ * recorded: a hand-maintained mirror of something the source already states drifts, quietly, for
+ * months. Declaration order is meaningful — it decides which alias wins when a selectors.yaml
+ * declares two spellings of one canonical type (see ALIAS_SPELLINGS).
+ */
+const ELEMENT_TYPE_ALIASES: Record<string, string> = {
+      // Text-like aliases → "text"
+      'title': 'text',
+      'label': 'text',
+      'caption': 'text',
+      // Heading aliases → "heading" (role-based)
+      'heading': 'heading',
+      'header': 'heading',
+      'message': 'text',
+      // Table-related aliases
+      'column': 'columnheader',
+      // List-related aliases
+      'list-item': 'listitem',
+      // Image aliases
+      'logo': 'img',
+      'image': 'img',
+      'icon': 'img',
+      // Button aliases
+      'btn': 'button',
+      // Field aliases
+      'input': 'field',
+      'textbox': 'field',
+      'textarea': 'field',
+      'editor': 'field',
+      // Search alias → searchbox role
+      'search': 'searchbox',
+      // Toggle alias → switch role
+      'toggle': 'switch',
+      // Alert alias → alertdialog role.
+      // UNREACHABLE in practice, kept for the same reason it is not changed: in sungen's grammar
+      // `alert` means the BROWSER system dialog, so `see [X] alert` matches a dedicated step pattern
+      // and compiles to `page.on('dialog', …)` without ever entering the selector resolver
+      // (verified by compiling the step; target-dictionary.mdx documents it as `page.on('dialog')`).
+      // This entry only answers a step form that reaches the resolver with the type `alert`, and
+      // none does. Removing it would be a behaviour change with no caller to benefit, so it stays.
+      'alert': 'alertdialog',
+      // Modal/drawer alias → dialog role
+      'modal': 'dialog',
+      'drawer': 'dialog',
+      // Dropdown/select alias -> combobox role
+      'dropdown': 'combobox',
+      'select': 'combobox',
+      // Data aliases
+      'item': 'listitem',
+      'card': 'article',
+      'cell': 'cell',
+      'section': 'region',
+      // Feedback aliases
+      'badge': 'text',
+      'tooltip': 'text',
+      'tag': 'text',
+      // Trigger aliases
+      'menuitem': 'menuitem',
+      // System aliases
+      'progressbar': 'progressbar',
+      'spinner': 'status',
+      'breadcrumb': 'navigation',
+};
+
+/**
+ * Canonical type → every alias spelling that normalizes to it, in ELEMENT_TYPE_ALIASES declaration
+ * order. Derived, never authored. Identity entries ('heading': 'heading') are excluded: they are
+ * already covered by the canonical candidate and would only duplicate a lookup.
+ */
+const ALIAS_SPELLINGS: Record<string, string[]> = (() => {
+  const out: Record<string, string[]> = {};
+  for (const [alias, canonical] of Object.entries(ELEMENT_TYPE_ALIASES)) {
+    if (alias === canonical) continue;
+    (out[canonical] ??= []).push(alias);
+  }
+  return out;
+})();
+
 export class SelectorResolver {
   private selectorCache = new Map<string, SelectorFile | LegacySelectorFile>();
   private selectorsDir: string;
@@ -393,69 +514,54 @@ export class SelectorResolver {
       'navigation': () => ({ strategy: 'role', role: 'navigation', name: label, value: 'navigation' }),
     };
 
-    const factory = strategyMap[normalized];
+    const factory = own(strategyMap, normalized);
     return factory ? factory() : null;
   }
 
+  /**
+   * Does the compiler have an OPINION about this element type — is it an alias it normalizes, or a
+   * type auto-infer can serve?
+   *
+   * The distinction decides whether the last-resort sweep may run, and it exists because
+   * `step.elementType` is not always an element type. The parser takes the first word after `]`
+   * (gherkin-parser/index.ts), so `see [Quick Panel] is hidden` arrives here with the "type" `is`
+   * and `drag [Item] to [Drop Zone]` with `to`. Nine such function words appear across the shipped
+   * features. A word the compiler cannot reason about carries no type information at all, so it must
+   * not be treated as a narrowing signal — a step like that has to keep the same open fallback a
+   * bare `[Ref]` gets, or a project whose label needs suffixed keys loses every state-clause step.
+   *
+   * Derived from the two maps rather than listed, so a new alias or strategy is known here the day
+   * it is added. tests/docs/element-type-vocabulary-parity.run.ts pins the maps against the parser's
+   * own list and the published table.
+   */
+  private static isKnownElementType(elementType: string): boolean {
+    if (own(ELEMENT_TYPE_ALIASES, elementType) !== undefined) return true;
+    return SelectorResolver.inferFromElementType(elementType, '') !== null;
+  }
+
+  /**
+   * Every selectors.yaml key that could legitimately hold the entry for `[label] <elementType>`.
+   *
+   * Shared by the lookup and by the not-found message, so the error can never advertise a key the
+   * resolver did not actually try — the two drifting apart is how #752 stayed invisible: the throw
+   * that would have named the missing key was unreachable, and when it did fire it listed two
+   * candidates while the resolver had its own idea of which to check.
+   */
+  private static typedKeyCandidates(key: string, elementType: string, normalizedType: string): string[] {
+    return [...new Set([
+      `${key}--${normalizedType}`,
+      `${key}--${elementType}`,
+      ...(own(ALIAS_SPELLINGS, normalizedType) ?? []).map((alias) => `${key}--${alias}`),
+    ])];
+  }
+
   /**
    * Normalize elementType aliases to canonical YAML suffix
    * Gherkin writers may use: title, label, heading, text → all map to "text"
    * Similarly: btn → button, link → link, input/field → field
    */
   private static normalizeElementType(elementType: string): string {
-    const aliasMap: Record<string, string> = {
-      // Text-like aliases → "text"
-      'title': 'text',
-      'label': 'text',
-      'caption': 'text',
-      // Heading aliases → "heading" (role-based)
-      'heading': 'heading',
-      'header': 'heading',
-      'message': 'text',
-      // Table-related aliases
-      'column': 'columnheader',
-      // List-related aliases
-      'list-item': 'listitem',
-      // Image aliases
-      'logo': 'img',
-      'image': 'img',
-      'icon': 'img',
-      // Button aliases
-      'btn': 'button',
-      // Field aliases
-      'input': 'field',
-      'textbox': 'field',
-      'textarea': 'field',
-      'editor': 'field',
-      // Search alias → searchbox role
-      'search': 'searchbox',
-      // Toggle alias → switch role
-      'toggle': 'switch',
-      // Alert alias → alertdialog role
-      'alert': 'alertdialog',
-      // Modal/drawer alias → dialog role
-      'modal': 'dialog',
-      'drawer': 'dialog',
-      // Dropdown/select alias -> combobox role
-      'dropdown': 'combobox',
-      'select': 'combobox',
-      // Data aliases
-      'item': 'listitem',
-      'card': 'article',
-      'cell': 'cell',
-      'section': 'region',
-      // Feedback aliases
-      'badge': 'text',
-      'tooltip': 'text',
-      'tag': 'text',
-      // Trigger aliases
-      'menuitem': 'menuitem',
-      // System aliases
-      'progressbar': 'progressbar',
-      'spinner': 'status',
-      'breadcrumb': 'navigation',
-    };
-    return aliasMap[elementType] || elementType;
+    return own(ELEMENT_TYPE_ALIASES, elementType) ?? elementType;
   }
 
   /**
@@ -475,33 +581,37 @@ export class SelectorResolver {
     // Try nth-suffixed key first: hay.gui.loi.cam.on--3
     if (nth && nth > 0) {
       const nthKey = `${key}--${nth}`;
-      const nthEntry = selectorFile[nthKey];
+      const nthEntry = own(selectorFile, nthKey);
       if (nthEntry) {
         return this.resolveFromEntry(nthEntry, displayLabel);
       }
     }
 
-    // Try type-suffixed key first: add.campaign--button, add.campaign--text
+    // Try type-suffixed keys: add.campaign--button, add.campaign--text
+    //
+    // EVERY spelling of the step's type is tried, not just the two the step itself could have been
+    // written with (#752). The alias table maps a Gherkin spelling onto a canonical one, but it was
+    // only ever applied to the STEP; the file's keys were compared raw. So `confirm--modal` was
+    // invisible to `[Confirm] dialog` while `confirm--dialog` resolved for `[Confirm] modal` —
+    // the mapping is one-directional and the lookup inherited that. The hole was not specific to
+    // modal/drawer: all 30 non-identity aliases had it.
+    //
+    // Order is deterministic and NOT file order: canonical first (the spelling the compiler thinks
+    // in), then whatever the author literally typed, then the remaining aliases in alias-table
+    // declaration order. A file declaring both `--modal` and `--drawer` therefore resolves the same
+    // way on every machine.
     if (elementType) {
       const normalizedType = SelectorResolver.normalizeElementType(elementType);
-      const typedKey = `${key}--${normalizedType}`;
-      const typedEntry = selectorFile[typedKey];
-      if (typedEntry) {
-        return this.resolveFromEntry(typedEntry, displayLabel);
-      }
-
-      // If normalized differs from original, also try original as-is
-      if (normalizedType !== elementType) {
-        const originalKey = `${key}--${elementType}`;
-        const originalEntry = selectorFile[originalKey];
-        if (originalEntry) {
-          return this.resolveFromEntry(originalEntry, displayLabel);
+      for (const candidate of SelectorResolver.typedKeyCandidates(key, elementType, normalizedType)) {
+        const typedEntry = own(selectorFile, candidate);
+        if (typedEntry) {
+          return this.resolveFromEntry(typedEntry, displayLabel);
         }
       }
     }
 
     // Fallback to base key
-    const entry = selectorFile[key];
+    const entry = own(selectorFile, key);
     if (entry) {
       return this.resolveFromEntry(entry, displayLabel);
     }
@@ -545,20 +655,30 @@ export class SelectorResolver {
       }
     }
 
-    // Last resort: find any suffixed key matching key--*
-    const suffixedKeys = Object.keys(selectorFile).filter(k => k.startsWith(`${key}--`));
-    if (suffixedKeys.length > 0) {
-      return this.resolveFromEntry(selectorFile[suffixedKeys[0]], displayLabel);
-    }
-
-    const tried: string[] = [];
-    if (elementType) {
-      const normalizedType = SelectorResolver.normalizeElementType(elementType);
-      tried.push(`${key}--${normalizedType}`);
-      if (normalizedType !== elementType) {
-        tried.push(`${key}--${elementType}`);
+    // Last resort: any suffixed key matching key--*, for a [Ref] the compiler could not type.
+    //
+    // Two cases reach here and they are the same case: a bare [Ref] with no word after it, and a
+    // [Ref] followed by a word that is not an element type. The parser cannot tell the two apart —
+    // it takes the FIRST word after `]`, so `see [Quick Panel] is hidden` arrives typed `is`. In
+    // both, nothing is known about what kind of element is wanted, so any suffixed key is as good a
+    // guess as the next, and a project whose label needs suffixed keys keeps its state-clause steps.
+    //
+    // A step the compiler CAN type gets no such guess. The candidate scan above already tried every
+    // spelling that normalizes to that type, so whatever is still sitting under `key--` is a
+    // DIFFERENT element, and handing it back is the silent-wrong-answer shape of #752 itself.
+    // Falling through to the throw is better: it names the keys that were tried, and "add an entry"
+    // is an instruction the author can act on.
+    if (!elementType || !SelectorResolver.isKnownElementType(elementType)) {
+      const suffixedKeys = Object.keys(selectorFile).filter(k => k.startsWith(`${key}--`));
+      if (suffixedKeys.length > 0) {
+        return this.resolveFromEntry(selectorFile[suffixedKeys[0]], displayLabel);
       }
     }
+
+    const tried: string[] = elementType
+      ? SelectorResolver.typedKeyCandidates(
+          key, elementType, SelectorResolver.normalizeElementType(elementType))
+      : [];
     const suffix = tried.length > 0 ? ` (also tried ${tried.join(', ')})` : '';
     throw new Error(
       `Selector "${label}" (key: ${key}) not found in ${featureName}.yaml${suffix}. ` +
@@ -751,6 +871,20 @@ export class SelectorResolver {
     return out.class || out.attribute ? out : undefined;
   }
 
+  /**
+   * Report a selectors.yaml problem ONCE per entry+field, not once per step that resolves it.
+   *
+   * An entry is resolved again for every step that names it, so an unguarded `diagnostics.add`
+   * here repeats the same sentence a dozen times for one typo and buries everything else in the
+   * channel. `warnedContentNamed` is the existing de-dupe set; `key` namespaces the callers so two
+   * diagnostics about one entry cannot silence each other.
+   */
+  private warnOnce(key: string, code: DiagnosticCode, message: string): void {
+    if (this.warnedContentNamed.has(key)) return;
+    this.warnedContentNamed.add(key);
+    this.diagnostics?.add(code, message, { feature: this.featureName });
+  }
+
   /**
    * Resolve a selectors.yaml entry that is NOT reachable by key — a `columns.<col>.elements.cell`
    * declaration, which lives nested under a table entry. Public for that one caller; everything
@@ -824,6 +958,28 @@ export class SelectorResolver {
     // The anchor is a selector in its own right; it must not inherit the PAGE's label as its
     // accessible name, so it resolves against its own name (or nothing).
     if (entry.anchor) v2Fields.anchor = this.resolveFromEntry(entry.anchor, entry.anchor.name ?? '');
+    // Gated on the entry KIND, like the value check below: `query:` means nothing on a non-page
+    // entry, and both the field and its diagnostic are worded purely in page terms. Today's two
+    // consumers re-check `selectorType === 'page'` at the read site (the `anchor:` precedent), so
+    // this is belt-and-braces — but a third consumer that forgets the guard would otherwise inherit
+    // a field that was never meant for it.
+    if (type === 'page' && entry.query !== undefined) {
+      const declared = String(entry.query).trim().toLowerCase();
+      // Exactly one value is legal today. A typo must NOT read as the permissive form: it would
+      // silently turn off the bare-page query assertion (#464) on a page the author meant to keep
+      // strict, which is the class of quiet weakening this whole diagnostic channel exists for.
+      if (declared === 'any') v2Fields.query = 'any';
+      else this.warnOnce(`w037:${originalLabel}:query`, 'SG-W037',
+        `selector "${originalLabel}": query: ${JSON.stringify(String(entry.query))} is not a query rule — the only value is \`any\` ("the query is not part of this page's identity"). The declaration is ignored, so a bare \`see [${originalLabel}] page\` still requires the URL to carry NO query at all.`);
+    }
+    // A page `value` is the PATH only — pathToRegexSource strips a `?`/`#` before building the
+    // pattern. Silently, until now: an author who hit the bare-page query rule (#464) and reached
+    // for the obvious workaround got byte-identical output and no hint why, which is exactly how
+    // #748 was misdiagnosed in the field as a regex-escaping bug.
+    if (type === 'page' && typeof entry.value === 'string' && /[?#]/.test(entry.value)) {
+      this.warnOnce(`w037:${originalLabel}:value`, 'SG-W037',
+        `selector "${originalLabel}": the page value ${JSON.stringify(entry.value)} carries a query/fragment, which is DROPPED — a page value is the path only, and the pattern is matched against \`u.pathname\`, which never holds one. Writing it here changes nothing. To assert the query, declare it on the step (\`see [${originalLabel}] page with {{v}}\`); to say the query is not part of this page's identity, add \`query: any\` to the entry.`);
+    }
 
     // Helper to attach v2 fields and inputMethod
     const withExtras = (resolved: ResolvedSelector): ResolvedSelector => {