@sun-asterisk/sungen 3.2.9 → 3.2.10-beta.1

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

@@ -0,0 +1,51 @@
+/**
+ * Compile-time diagnostics — the warning channel for "the compiler knows something
+ * and would otherwise silently discard or invent it" (spec: sungen_app_profile_spec.md §4).
+ *
+ * Codes:
+ *   SG-W001 — step matched no pattern (compiles to a no-op `// TODO` comment)
+ *   SG-W002 — step parsed a {{dataRef}} value but the generated code never uses it
+ *   SG-W003 — `name` filter defaulted from the Gherkin reference on a name-from-content
+ *             role (status/alert/…) — such a filter can never match; opt out with `name: null`
+ *   SG-W005 — qa/app.yaml problem (unknown key, unknown preset, unparseable)
+ *   SG-W006 — qa/app.<env>.yaml found (per-environment profiles are unsupported by design)
+ *   SG-W007 — browser-alert handler step written AFTER an action step: the listener
+ *             registers too late, an earlier dialog auto-dismisses with no error
+ *
+ * Diagnostics never block generation by themselves; `sungen generate --strict`
+ * turns any collected diagnostic into a non-zero exit.
+ */
+
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007';
+
+export interface Diagnostic {
+  code: DiagnosticCode;
+  message: string;
+  feature?: string;
+  step?: string;
+}
+
+export class DiagnosticsCollector {
+  private items: Diagnostic[] = [];
+
+  add(code: DiagnosticCode, message: string, context: { feature?: string; step?: string } = {}): void {
+    this.items.push({ code, message, ...context });
+  }
+
+  all(): Diagnostic[] {
+    return this.items;
+  }
+
+  get count(): number {
+    return this.items.length;
+  }
+
+  /** One line per diagnostic, ready for CLI output. */
+  formatLines(): string[] {
+    return this.items.map((d) => {
+      const where = d.feature ? `${d.feature}: ` : '';
+      const step = d.step ? ` — "${d.step}"` : '';
+      return `[${d.code}] ${where}${d.message}${step}`;
+    });
+  }
+}

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

@@ -44,6 +44,18 @@ export interface PatternContext {
   scenarioSteps?: ParsedStep[];
   /** Effective Gherkin keyword (Given/When/Then), resolved from And/But */
   effectiveKeyword?: 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. */
+  appProfile?: {
+    widgetVariants: Record<string, string>;
+    recipes: Record<string, Record<string, unknown[]>>;
+    loadingIndicator: string;
+    tableRowBase: number;
+    tableHeaderIsRow: boolean;
+    portalRoles: string[];
+    contentNamedRoles: string[];
+  };
 }
 
 /**

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

@@ -0,0 +1,129 @@
+/**
+ * Widget-recipe expander (spec: sungen_app_profile_spec.md §3.1 [recipes]).
+ *
+ * A recipe is a LINEAR sequence of closed primitives that describes one widget
+ * intent ("select", "fill", …). Recipes come from `qa/app.yaml` `recipes:` or from
+ * driver-shipped built-ins (the reserved `builtin` preset), selected by the widget's
+ * variant name (per-element `variant:` > profile `widgets.<kind>`).
+ *
+ * This expander holds ZERO framework syntax. It resolves each primitive to a
+ * `{ partial, ...data }` NODE; the actual Playwright code lives in the per-primitive
+ * `recipe-*.hbs` partials, rendered by the template engine via `recipe-sequence.hbs`
+ * (dynamic partial lookup). The only strings it builds are locator/value EXPRESSIONS
+ * (data — the same split every resolver uses when it hands the locator template a value).
+ *
+ * Placeholders: `$trigger` = the resolved widget element; `$value` = the step's data
+ * value (a runtime marker in runtime mode, transformed to testData.get later); `$item`
+ * = the current forEach item. Throws on an unknown primitive/shape — callers fall back
+ * to the generic template.
+ */
+
+export interface RecipeExpandContext {
+  /** Pre-rendered locator code for the widget element (dialog/frame scoping included). */
+  triggerCode: string;
+  /** The step's value — a literal or a __SUNGEN_TD__ runtime marker. */
+  value: string;
+}
+
+/** A render node: the partial name plus the data it interpolates. */
+export interface RecipeNode {
+  partial: string;
+  [key: string]: unknown;
+}
+
+const escape = (s: string): string => String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+
+export function expandRecipe(primitives: unknown[], ctx: RecipeExpandContext): RecipeNode[] {
+  if (!Array.isArray(primitives) || primitives.length === 0) {
+    throw new Error('recipe intent is not a primitive list');
+  }
+  return primitives.map((p) => expandPrimitive(p, ctx, null));
+}
+
+/** `itemVar` is non-null inside a forEach body — `$item` renders as that identifier. */
+function expandPrimitive(prim: unknown, ctx: RecipeExpandContext, itemVar: string | null): RecipeNode {
+  if (typeof prim !== 'object' || prim === null || Array.isArray(prim)) {
+    throw new Error(`invalid primitive: ${JSON.stringify(prim)}`);
+  }
+  const entries = Object.entries(prim as Record<string, unknown>);
+  if (entries.length !== 1) throw new Error(`a primitive must have exactly one key: ${JSON.stringify(prim)}`);
+  const [kind, arg] = entries[0];
+
+  // Resolve a `$trigger`/css target into a locator EXPRESSION (data for the partial).
+  const targetExpr = (v: unknown): string =>
+    v === '$trigger' ? ctx.triggerCode : `page.locator('${escape(String(v))}')`;
+  // Resolve a `$value`/`$item`/literal into a JS value EXPRESSION (quoted unless $item;
+  // a quoted __SUNGEN_TD__ marker is rewritten to testData.get(...) by the runtime transform).
+  const valueExpr = (v: unknown): string => {
+    if (v === '$item') {
+      if (!itemVar) throw new Error('$item is only valid inside forEach');
+      return itemVar;
+    }
+    const s = v === '$value' ? ctx.value : String(v);
+    return `'${escape(s)}'`;
+  };
+
+  switch (kind) {
+    case 'click':
+      return { partial: 'recipe-click', targetExpr: targetExpr(arg) };
+    case 'hover':
+      return { partial: 'recipe-hover', targetExpr: targetExpr(arg) };
+    case 'type': {
+      const v = typeof arg === 'object' && arg !== null ? (arg as any).value : arg;
+      return { partial: 'recipe-type', valueExpr: valueExpr(v ?? '$value') };
+    }
+    case 'press':
+      return { partial: 'recipe-press', key: escape(String(arg)) };
+    case 'waitFor': {
+      // `waitFor: '<css>'` → wait visible. `waitFor: { target, state }` allows an explicit
+      // state ('attached' | 'visible' | 'hidden' | 'detached'); `attached` covers the AntD
+      // case where a selected chip collapses the input to ~0px (node exists before actionable).
+      const o = (typeof arg === 'object' && arg !== null ? arg : { target: arg }) as Record<string, unknown>;
+      const state = ['attached', 'visible', 'hidden', 'detached'].includes(String(o.state)) ? String(o.state) : 'visible';
+      return { partial: 'recipe-wait-for', targetExpr: targetExpr(o.target), state };
+    }
+    case 'waitForHidden':
+      return { partial: 'recipe-wait-for', targetExpr: targetExpr(arg), state: 'hidden' };
+    case 'scrollIntoView':
+      // Playwright's own actionability scroll (not arbitrary evaluate) — nudges a lazy list
+      // to render+reveal the target before a click. Deterministic, no loop.
+      return { partial: 'recipe-scroll-into-view', targetExpr: targetExpr(arg) };
+    case 'blur':
+      // One bounded el.blur() to dismiss a widget's own overlay (AntD DatePicker panel keeps
+      // pointer-blocking after fill; Escape/force-click are unreliable). No retry loop.
+      return { partial: 'recipe-blur', targetExpr: targetExpr(arg) };
+    case 'clickText': {
+      const o = (typeof arg === 'object' && arg !== null ? arg : { text: arg }) as Record<string, unknown>;
+      const text = valueExpr(o.text ?? '$value');
+      const exact = o.exact === true;
+      // Build the option-locator expression; the partial scrolls it into view then clicks.
+      const expr = o.role
+        ? `page.getByRole('${escape(String(o.role))}', { name: ${text}${exact ? ', exact: true' : ''} })`
+        : `${o.within ? `page.locator('${escape(String(o.within))}')` : 'page'}.getByText(${text}${exact ? ', { exact: true }' : ''}).first()`;
+      return { partial: 'recipe-click-text', targetExpr: expr };
+    }
+    case 'expectText': {
+      const o = (typeof arg === 'object' && arg !== null ? arg : {}) as Record<string, unknown>;
+      return { partial: 'recipe-expect-text', targetExpr: targetExpr(o.locator ?? '$trigger'), valueExpr: valueExpr(o.value ?? '$value') };
+    }
+    case 'expectValue': {
+      const o = (typeof arg === 'object' && arg !== null ? arg : {}) as Record<string, unknown>;
+      return { partial: 'recipe-expect-value', targetExpr: targetExpr(o.locator ?? '$trigger'), valueExpr: valueExpr(o.value ?? '$value') };
+    }
+    case 'forEach': {
+      const o = (typeof arg === 'object' && arg !== null ? arg : {}) as Record<string, unknown>;
+      if (itemVar) throw new Error('nested forEach is not supported');
+      const inner = o.do;
+      if (!Array.isArray(inner) || inner.length === 0) throw new Error('forEach.do must be a primitive list');
+      const source = o.in === '$values' || o.in === undefined ? '$value' : o.in;
+      return {
+        partial: 'recipe-for-each',
+        sourceExpr: valueExpr(source),
+        split: escape(String(o.split ?? '>')),
+        body: inner.map((p) => expandPrimitive(p, ctx, 'item')),
+      };
+    }
+    default:
+      throw new Error(`unknown recipe primitive "${kind}"`);
+  }
+}

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

@@ -4,6 +4,9 @@ import { adapterRegistry } from './adapters';
 import { PatternRegistry, PatternContext } from './patterns';
 import { SelectorResolver } from './utils/selector-resolver';
 import { DataResolver } from './utils/data-resolver';
+import { DiagnosticsCollector } from './diagnostics';
+import { loadAppProfile, ResolvedAppProfile } from './app-profile';
+import { capabilityRegistry } from '../../capabilities/registry';
 
 export interface MappedStep {
   code: string; // Generated Playwright code
@@ -34,6 +37,12 @@ export class StepMapper {
   /** Row scope: when active, column assertions are scoped to this row */
   private inRowScope: boolean = false;
   private rowScopeTable: string = '';
+  /** SG-W007: an action step already ran in this scenario (alert handlers registered after it are too late) */
+  private sawActionStep: boolean = false;
+  /** Compile-time warning channel (SG-W001/W002); optional — absent means silent legacy behavior */
+  private diagnostics?: DiagnosticsCollector;
+  /** App profile (qa/app.yaml merged over presets/defaults) — the per-project BEHAVIOR layer */
+  private appProfile: ResolvedAppProfile;
 
   constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean; framework?: string } = {}) {
     this.verbose = options.verbose ?? false;
@@ -51,11 +60,26 @@ export class StepMapper {
     this.selectorResolver = new SelectorResolver(undefined, options.screenName);
     this.dataResolver = new DataResolver(undefined, options.screenName, options.runtimeData);
 
+    // App profile (qa/app.yaml) — loaded after PatternRegistry so capability discovery has
+    // populated the preset registry (driver-ui ships native/radix/antd). Missing file →
+    // built-in defaults → pre-profile behavior.
+    this.appProfile = loadAppProfile(process.cwd(), capabilityRegistry.appProfilePresets());
+    this.templateEngine.setPersistentContext({ portalRoles: this.appProfile.portalRoles });
+    this.selectorResolver.setContentNamedRoles(this.appProfile.contentNamedRoles);
+
     if (this.verbose) {
       console.log(`  [StepMapper] ${this.patternRegistry.getPatternCount()} patterns loaded`);
     }
   }
 
+  /** Attach the compile-diagnostics collector (owned by CodeGenerator) */
+  setDiagnostics(collector: DiagnosticsCollector): void {
+    this.diagnostics = collector;
+    this.selectorResolver.setDiagnostics(collector);
+    // Flush profile-load warnings (SG-W005/W006) gathered before the collector existed.
+    for (const w of this.appProfile.warnings) collector.add(w.code, w.message);
+  }
+
   /**
    * Set feature context for data and selector resolution
    */
@@ -92,6 +116,7 @@ export class StepMapper {
     this.inFrameScope = false;
     this.inRowScope = false;
     this.rowScopeTable = '';
+    this.sawActionStep = false;
     this.lastPrimaryKeyword = 'Given';
     this.dataResolver.clearCaptured(); // captured vars are scenario-scoped
     this.templateEngine.resetBaseContext();
@@ -119,6 +144,23 @@ export class StepMapper {
       this.lastPrimaryKeyword = keyword;
     }
 
+    // SG-W007 — a two-step-form browser-alert handler (`click [OK] alert`) written AFTER
+    // an action step registers its page.once('dialog') listener too late: a dialog
+    // triggered by the earlier action auto-dismisses with no error (issue #472).
+    // Fix: move the alert step BEFORE the trigger, or use the compound form
+    // `click [X] button and accept [OK] alert`.
+    const isAlertHandlerStep = step.elementType === 'alert' &&
+      /\b(click|clicks|fill|fills)\b/.test(step.text) &&
+      !/\band\s+(accept|accepts|dismiss|dismisses)\b/i.test(step.text);
+    if (isAlertHandlerStep && this.sawActionStep) {
+      this.diagnostics?.add('SG-W007',
+        'browser-alert handler registered AFTER an action step — a dialog triggered earlier auto-dismisses silently. Move the alert step before the trigger, or use `click [X] button and accept [OK] alert`',
+        { feature: this.featureName, step: step.text });
+    } else if (!isAlertHandlerStep &&
+      /\b(click|clicks|fill|fills|select|selects|press|presses|check|checks|uncheck|unchecks|drag|drags)\b/.test(step.text)) {
+      this.sawActionStep = true;
+    }
+
     // Frame scope directives — intercept before pattern matching
     if (/\bswitch(?:es)?\s+to\b/i.test(step.text) &&
         (step.elementType === 'frame' || step.elementType === 'iframe')) {
@@ -215,16 +257,46 @@ export class StepMapper {
       if (this.verbose) {
         console.log(`  ✓ Pattern matched: ${step.text.substring(0, 50)}...`);
       }
+      this.checkDataRefConsumed(step, mappedStep);
       return mappedStep;
     }
 
     // No pattern matched - return TODO comment
+    this.diagnostics?.add('SG-W001', 'step matched no pattern — compiled to a no-op // TODO comment', {
+      feature: this.featureName,
+      step: step.text,
+    });
     return {
       code: `// TODO: Implement step: ${step.text}`,
       comment: `Unrecognized step pattern: ${step.text}`,
     };
   }
 
+  /**
+   * SG-W002 — a step carried a parsed {{dataRef}} but the matched pattern's generated
+   * code never uses it (neither the runtime marker, the ${ref} fallback, nor the
+   * inline-resolved value). This is the class of bug where `with {{v}}` silently
+   * disappears from the output (e.g. issue #464). Warning-only: loose containment
+   * checks err on the side of NOT flagging.
+   */
+  private checkDataRefConsumed(step: ParsedStep, mapped: MappedStep): void {
+    if (!step.dataRef || !this.diagnostics) return;
+    const code = mapped.code || '';
+    if (code.includes(DataResolver.encodeMarker(step.dataRef))) return; // runtime marker
+    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);
+      if (value && (code.includes(value) || code.includes(value.replace(/'/g, "\\'")))) return; // inline mode
+    } catch {
+      return; // unresolvable ref → other errors surface elsewhere; don't double-report
+    }
+    this.diagnostics.add('SG-W002', `parsed {{${step.dataRef}}} but the generated code does not use it`, {
+      feature: this.featureName,
+      step: step.text,
+    });
+  }
+
   /**
    * Generate column assertion scoped to the current row.
    * Uses columns config for exact cell targeting (nth), or filter fallback.
@@ -296,6 +368,7 @@ export class StepMapper {
       selectorResolver: this.selectorResolver,
       dataResolver: this.dataResolver,
       renderLocator: (resolved) => this.templateEngine.renderStep('locator', resolved),
+      appProfile: this.appProfile,
       baseURL: this.baseURL,
       featureName: this.featureName,
       screenName: this.screenName,

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

@@ -7,6 +7,8 @@ export class TemplateEngine {
   private templatesDir: string;
   private stepsTemplatesDir: string;
   private baseContext: Record<string, any> = {};
+  /** Per-project context that survives scenario resets (e.g. app-profile portalRoles) */
+  private persistentContext: Record<string, any> = {};
 
   constructor(templatesDir: string) {
     this.templatesDir = templatesDir;
@@ -127,7 +129,17 @@ export class TemplateEngine {
     Handlebars.registerHelper('pageRoot', function(this: any) {
       // Frame scope takes precedence (frame > dialog > page)
       if (this.inFrame) return 'frame';
-      if (!this.inDialog) return 'page';
+      // `scope: dialog` on the selector entry is the explicit opt-IN sentinel — the
+      // element is dialog-rooted even if its role is portal-exempt (issue #465).
+      const explicitDialog = this.scope === 'dialog';
+      if (!this.inDialog && !explicitDialog) return 'page';
+      // Portal-rendered roles (Radix/MUI/Headless UI/antd render option/menu/tooltip
+      // layers onto document.body) live OUTSIDE the dialog's DOM subtree — wrapping
+      // them in the dialog root guarantees a timeout. List comes from the app profile
+      // (qa/app.yaml layers.portal_roles), default DEFAULT_PORTAL_ROLES.
+      if (!explicitDialog && this.role && Array.isArray(this.portalRoles) && this.portalRoles.includes(this.role)) {
+        return 'page';
+      }
       const partial = Handlebars.partials['dialog-root'];
       if (partial) {
         const fn = typeof partial === 'string' ? Handlebars.compile(partial) : partial;
@@ -152,6 +164,14 @@ export class TemplateEngine {
       Handlebars.registerPartial('locator-base', locatorBaseContent);
     }
 
+    // Register has-text-value partial — the ONE place that renders a .filter({ hasText })
+    // value, so action templates cannot drift from the exact/anchored-regex standard the
+    // assertion templates follow (issue #466).
+    const hasTextValuePath = path.join(this.stepsTemplatesDir, 'partials', 'has-text-value.hbs');
+    if (fs.existsSync(hasTextValuePath)) {
+      Handlebars.registerPartial('has-text-value', fs.readFileSync(hasTextValuePath, 'utf-8'));
+    }
+
     // Register locator strategy partials
     const strategiesDir = path.join(this.stepsTemplatesDir, 'partials', 'locator-strategies');
     if (fs.existsSync(strategiesDir)) {
@@ -246,9 +266,15 @@ export class TemplateEngine {
     this.baseContext = { ...this.baseContext, ...ctx };
   }
 
-  /** Reset base context (e.g., on new scenario) */
+  /** Context that survives resetBaseContext (per-project facts, e.g. app-profile portalRoles) */
+  setPersistentContext(ctx: Record<string, any>): void {
+    this.persistentContext = { ...this.persistentContext, ...ctx };
+    this.baseContext = { ...this.baseContext, ...ctx };
+  }
+
+  /** Reset base context (e.g., on new scenario) — persistent (per-project) context stays */
   resetBaseContext(): void {
-    this.baseContext = {};
+    this.baseContext = { ...this.persistentContext };
   }
 
   renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {

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

@@ -5,6 +5,8 @@ import { readYaml, readYamlIfExists } from '../../../utils/yaml-io';
 
 import { SelectorType } from '../../../utils/selector-types';
 import { DataResolver } from './data-resolver';
+import { DiagnosticsCollector } from '../diagnostics';
+import { DEFAULT_CONTENT_NAMED_ROLES } from '../app-profile';
 
 // Structured selector format v2
 interface SelectorEntry {
@@ -27,7 +29,9 @@ interface SelectorEntry {
   ios?: SelectorEntry;
 
   // === v2: Complex Elements ===
-  variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload subtype
+  // Dropdown/upload subtype: 'native' | 'custom' | 'dragdrop', or a widget-recipe/variant
+  // name ('radix-select', 'office-datepicker', …) — wins over qa/app.yaml widgets.<kind>.
+  variant?: string;
   trigger?: string;       // Visible button that triggers hidden file input
   frame?: string;         // iframe selector for cross-frame elements
   contenteditable?: boolean;  // Rich text editor (contenteditable div)
@@ -96,7 +100,7 @@ export interface ResolvedSelector {
   // === v2 fields ===
   scope?: string;       // Parent landmark to scope within
   match?: 'exact' | 'partial';  // For getByText exact matching
-  variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload type
+  variant?: string;     // Dropdown/upload subtype or widget-recipe name
   trigger?: string;     // Button that triggers hidden file input
   frame?: string;       // iframe selector
   contenteditable?: boolean;  // Rich text editor
@@ -117,12 +121,26 @@ export class SelectorResolver {
   private featureName?: string;
   private screenName?: string;
   private flowMode: boolean = false;
+  /** SG-W003 channel + config: roles whose accessible name derives from content. */
+  private diagnostics?: DiagnosticsCollector;
+  private contentNamedRoles: string[] = DEFAULT_CONTENT_NAMED_ROLES;
+  private warnedContentNamed = new Set<string>();
 
   constructor(selectorsDir?: string, screenName?: string) {
     this.selectorsDir = selectorsDir || path.join(process.cwd(), 'qa', 'selectors', 'screens');
     this.screenName = screenName;
   }
 
+  /** Attach the compile-diagnostics collector (SG-W003) */
+  setDiagnostics(collector: DiagnosticsCollector): void {
+    this.diagnostics = collector;
+  }
+
+  /** Override the name-from-content role list from the app profile (qa/app.yaml feedback.toast) */
+  setContentNamedRoles(roles: string[]): void {
+    this.contentNamedRoles = roles;
+  }
+
   setFlowMode(enabled: boolean): void {
     this.flowMode = enabled;
   }
@@ -390,6 +408,20 @@ export class SelectorResolver {
     if (elementType) {
       const inferred = SelectorResolver.inferFromElementType(elementType, displayLabel);
       if (inferred) {
+        // Same SG-W003 class as the explicit-entry path: an auto-inferred name on a
+        // name-from-content role ([Loading] spinner → getByRole('status', { name: 'Loading' }))
+        // can never match. Add a YAML entry with name: null to opt out.
+        if (inferred.strategy === 'role' && inferred.name && inferred.role && this.contentNamedRoles.includes(inferred.role)) {
+          const warnKey = `${inferred.role}:${displayLabel}`;
+          if (!this.warnedContentNamed.has(warnKey)) {
+            this.warnedContentNamed.add(warnKey);
+            this.diagnostics?.add(
+              'SG-W003',
+              `role "${inferred.role}" derives its accessible name from content, but "[${displayLabel}]" auto-inferred { name: '${inferred.name}' } which will likely never match. Add a selectors.yaml entry with an explicit name: or name: null`,
+              { feature: this.featureName }
+            );
+          }
+        }
         return inferred;
       }
     }
@@ -566,6 +598,21 @@ export class SelectorResolver {
         });
 
       case 'role':
+        // SG-W003 — the entry has no `name:` so the compiler defaulted it to the Gherkin
+        // reference text. For name-from-content roles (status/alert/…) that filter can
+        // never match the live element (its accessible name is computed from its content,
+        // e.g. a toast's message text) — issue #467. Opt out with `name: null`.
+        if (entry.name === undefined && name && this.contentNamedRoles.includes(value)) {
+          const warnKey = `${value}:${originalLabel}`;
+          if (!this.warnedContentNamed.has(warnKey)) {
+            this.warnedContentNamed.add(warnKey);
+            this.diagnostics?.add(
+              'SG-W003',
+              `role "${value}" derives its accessible name from content, but the entry for "${originalLabel}" has no name: — the defaulted { name: '${name}' } will likely never match. Set an explicit name: or opt out with name: null`,
+              { feature: this.featureName }
+            );
+          }
+        }
         return withExtras({
           strategy: 'role',
           role: value,

package/src/harness/catalog/drivers.yaml

@@ -51,7 +51,7 @@ drivers:
   data-factory:
     kind: capability
     package: "@sungen/driver-data-factory"
-    status: planned
+    status: shipped
     capabilities: ["@dataFactory"]
     unblocks: [M1]
   mock:

package/src/index.ts

@@ -14,6 +14,9 @@ export type { DiscoveredContext } from './orchestrator/context-discovery';
 
 // --- Step-pattern authoring (a driver contributes step patterns via its descriptor) ---
 export type { PatternContext, StepPattern, StepTemplateData } from './generators/test-generator/patterns/types';
+export { expandRecipe } from './generators/test-generator/recipe-expander';
+export type { RecipeExpandContext, RecipeNode } from './generators/test-generator/recipe-expander';
+export type { ResolvedAppProfile } from './generators/test-generator/app-profile';
 export type { MappedStep } from './generators/test-generator/step-mapper';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
@@ -22,8 +25,8 @@ export { getPathCode, inferPath, resolvePathVariables } from './generators/test-
 export { parseQueryOverrides } from './harness/annotation-overrides';
 
 // --- Named-query catalog (shared: the DB driver's codegen + core's data-driven advisory lint) ---
-export { resolveQuery, compileQuery, lintCatalog } from './harness/query-catalog';
-export type { QueryEntry } from './harness/query-catalog';
+export { resolveQuery, compileQuery, compileShape, isShapeEntry, lintCatalog } from './harness/query-catalog';
+export type { QueryEntry, MongoFind, MongoPipeline } from './harness/query-catalog';
 
 // --- Shared harness: viewpoint catalog + coverage gate / assertion depth ---
 // (the UI capability's gateProvider composes these; they also back core's ingest + audit fallback)

package/src/orchestrator/templates/ai-src/commands/create-data-test.md

@@ -0,0 +1,83 @@
+---
+name: create-data-test
+description: "Generate standardized test-data for a screen/flow from the Data Factory catalog — valid/boundary/invalid values with CHK-* traceability (no free-form guessing)"
+argument-hint: [screen-or-flow-name]
+order: 25
+claude-tools: "Read, Grep, Bash, Glob, Write, Edit, AskUserQuestion, Skill"
+copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
+codex-trigger: "Run when the user asks to CREATE, generate, or standardize TEST DATA / test values for a screen or flow (valid/boundary/invalid, boundary values, negative data). Uses the Data Factory driver. Not for generating the .feature scenarios themselves (that is create-test)."
+---
+
+**Input**: A screen or flow name (e.g., `/sungen:create-data-test login`), OR **no name** to do every unit (with a confirmation — see ALL mode). Load the `sungen-data-factory` skill for the full method.
+
+## Role
+
+You are a **Senior QA Engineer** producing **test data to a standard**, not by guessing. You do NOT invent values field-by-field. You follow the 4-source method (spec rules → field-type catalog → design technique → DB mapping), driven by the **Data Factory** capability driver. Values come from the catalog (`common/` + the project's `.overwrite`), each tagged with a `CHK-*` id that traces back to the spec. Where the catalog cannot cover a project-specific field, you **ask the QA** — you never fabricate domain data.
+
+## Preconditions
+
+1. **Capability present** — check `qa/capabilities.yaml`. If `data-factory` is not enabled, tell the user and run `sungen capability add data-factory` (it is runtime-free — safe to enable). Then continue.
+2. Determine mode from `$ARGUMENTS`:
+   - A **name** given → single-unit mode (that screen/flow only).
+   - **No name** → **ALL mode** (see below — always confirm first).
+
+## ALL mode (no name) — confirm before doing everything
+
+If no name was given, the user wants **all** screens/flows — but this is wide, and a missing name is often a typo (they meant `create-data-test home`). So:
+
+1. List every unit under `qa/screens/*` and `qa/flows/*`, and classify each as **new** (no `test-data/<name>.yaml` yet) vs **would-overwrite**.
+2. Show the list and use `AskUserQuestion` to confirm: *"Generate test-data for ALL N units? (X new · Y would overwrite)"* — default to **No**.
+3. Only proceed when the user confirms. Then run the per-unit flow below for each (the CLI `sungen data gen --all` also enforces this confirm; `--yes` after the user agrees).
+
+## Per-unit flow (single unit, or each unit in ALL mode)
+
+Auto-detect: `qa/flows/<name>/` → flow; else `qa/screens/<name>/` → screen. (API units carry their contract in `apis.yaml` — data there is `@cases` in create-test, not this command.)
+
+### 1. Read the sources (Nguồn 1 + 4)
+
+Read `qa/<screens|flows>/<name>/requirements/spec.md` and `test-viewpoint.md`. For **each input field / parameter**, extract:
+- data **type** (map to a catalog field-type: email · password · phone · string · number-integer · number-float · currency · postcode · katakana …),
+- `required`, format, **min/max** length or value,
+- the real **error/message code** the spec shows when a rule is violated,
+- any **DB mapping** (unique, cross-entity dependency) noted in the spec.
+
+Viewpoint tells you which fields are high-priority → give them the fullest data.
+
+### 2. Write the field-map — `qa/data-factory/<name>.fields.yaml`
+
+This is the input the deterministic generator expands. One entry per field:
+
+```yaml
+screen: <name>            # or: flow: <name>
+fields:
+  - name: email
+    type: email
+    required: true
+    constraints: { maxLocal: 64, maxTotal: 254 }   # project's real limits
+    errorMap: { M13: E1042, M02: E1001 }            # catalog placeholder → project's real code
+  - name: password
+    type: password
+    constraints: { minLength: 8, maxLength: 32 }
+```
+
+Map every placeholder error code you can (`errorMap`) to the spec's real code. Leave a code unmapped only if the spec truly has none — the lint will flag it as an open point to confirm with BA/Dev.
+
+### 3. Blind spots — ask, do not invent
+
+If a field's type is **not** in the catalog (a business enum, a cross-entity constraint, a project data model), **stop and ask the QA** with `AskUserQuestion` for: (1) the valid set, (2) invalid / non-existent values, (3) the error code when wrong, (4) dependencies on other fields. Record the answer in `qa/data-factory/project/<entity>.yaml` for reuse. Never fabricate domain values.
+
+### 4. Lint the coverage
+
+Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen <name> || npx sungen data lint --screen <name>`. Fix what it reports: add missing boundary values, resolve `UNRESOLVED` items (supply the constraint), map `OPEN_ERRORREF` codes. The bar is the phuong-phap §6 checklist — every required field has valid + boundary + invalid, one invalid per rule.
+
+### 5. Generate the test-data
+
+Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data gen --screen <name> || npx sungen data gen --screen <name>`. If `test-data/<name>.yaml` already exists it **asks before overwriting** — respect the user's choice (in ALL mode after they confirmed, add `--yes`; use `--force` only when the user explicitly wants an unconditional overwrite). The output is standardized `valid/boundary/invalid` values with `CHK-*` traceability.
+
+### 6. Weave into scenarios (if create-test already ran)
+
+If the `.feature` exists, turn the generated invalid/boundary sets into data-driven `Scenario Outline` + `Examples` (`@cases`) referencing the values — following `sungen-gherkin-syntax`. Otherwise leave the standardized `test-data/<name>.yaml` for `/sungen:run-test` to consume.
+
+## After running
+
+Use `AskUserQuestion` to offer the next step: review the generated data, run `/sungen:create-test <name>` (if scenarios don't exist yet), or `/sungen:run-test <name>`.

package/src/orchestrator/templates/ai-src/config/claude.md

@@ -18,14 +18,16 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
+| `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
 
-## Workflow (7 AI commands)
+## Workflow (8 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen:add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen:add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
 | `/sungen:create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen:create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen:review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen:run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen:delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |

package/src/orchestrator/templates/ai-src/config/copilot.md

@@ -18,14 +18,16 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
+| `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
 
-## Workflow (7 AI commands)
+## Workflow (8 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen-add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen-add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
 | `/sungen-create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen-create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen-run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen-delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |