@sungen/driver-data-factory 3.2.10-beta.14 → 3.2.10-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-data-factory",
-  "version": "3.2.10-beta.14",
+  "version": "3.2.10-beta.2",
   "description": "Sungen Data Factory capability — standardized test-data generation from a field-type + security knowledge catalog (valid/boundary/invalid + traceability), the .overwrite merge layer, and (opt-in) @dataFactory runtime seeding. Design-time knowledge is runtime-free. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,7 +14,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.10-beta.14",
+    "@sun-asterisk/sungen": "3.2.10-beta.2",
     "yaml": "^2.4.0"
   },
   "files": [

package/src/cli.ts

@@ -13,8 +13,6 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { loadEffectiveCatalog } from './catalog-loader';
 import { expandFieldMap, renderTestData, type FieldMap } from './generator';
 import { lintFieldMap, summarize } from './lint';
-import { generateFixture } from './fixture';
-import { ensureDataFactoryReadme } from './readme';
 
 const FIELDMAP_DIR = (cwd: string) => join(cwd, 'qa', 'data-factory');
 const fieldMapPath = (cwd: string, name: string) => join(FIELDMAP_DIR(cwd), `${name}.fields.yaml`);
@@ -57,31 +55,14 @@ async function genOne(cwd: string, name: string, opts: { force?: boolean }): Pro
   const out = testDataPath(cwd, name);
   if (!out) { console.error(`  ✗ ${name}: no qa/screens/${name} or qa/flows/${name}`); return 'missing'; }
 
-  const dfData = renderTestData(expanded) as Record<string, any>;
-  const exists = existsSync(out);
-
-  // MERGE, don't clobber. Data Factory owns only the keys it generates (`_generated_by` + each
-  // field name); every OTHER key in the existing test-data (create-test's data, flow-namespaced
-  // keys like `login.email`, @cases datasets, overrides) is preserved. A regenerated field key is
-  // replaced by its standardized version (that's the point). Fixes the whole-file clobber.
-  let final = dfData;
-  let mergedInto = false;
-  if (exists) {
-    if (!opts.force) {
-      const a = (await ask(`  ? ${name}: test-data exists — merge standardized field data in (keeps other keys)? [y/N] `)).toLowerCase();
-      if (a !== 'y' && a !== 'yes') { console.log(`  · ${name}: skipped`); return 'skipped'; }
-    }
-    let existing: Record<string, any> = {};
-    try { existing = (parseYaml(readFileSync(out, 'utf8')) as Record<string, any>) || {}; } catch { existing = {}; }
-    final = { ...existing, ...dfData }; // DF-owned keys win; all other existing keys preserved
-    mergedInto = true;
+  if (existsSync(out) && !opts.force) {
+    const a = (await ask(`  ? ${name}: test-data already exists — overwrite? [y/N] `)).toLowerCase();
+    if (a !== 'y' && a !== 'yes') { console.log(`  · ${name}: skipped`); return 'skipped'; }
   }
   mkdirSync(dirname(out), { recursive: true });
-  writeFileSync(out, stringifyYaml(final), 'utf8');
+  writeFileSync(out, stringifyYaml(renderTestData(expanded)), 'utf8');
   const blind = expanded.filter((f) => f.blindSpot).map((f) => f.name);
-  const verb = mergedInto ? 'merged into' : 'wrote';
-  const fieldKeys = expanded.map((f) => f.name).length;
-  console.log(`  ✓ ${name}: ${verb} ${out.replace(cwd + '/', '')} (${fieldKeys} field key(s)${mergedInto ? ', other keys preserved' : ''})${blind.length ? ` — blind spots: ${blind.join(', ')}` : ''}`);
+  console.log(`  ✓ ${name}: wrote ${out.replace(cwd + '/', '')}${blind.length ? ` (blind spots: ${blind.join(', ')})` : ''}`);
   return 'written';
 }
 
@@ -97,7 +78,6 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--force', 'Overwrite existing test-data without asking (implies --yes)')
     .action(async (opts: { screen?: string; all?: boolean; yes?: boolean; force?: boolean }) => {
       const cwd = process.cwd();
-      ensureDataFactoryReadme(cwd);
       if (opts.screen) { await genOne(cwd, opts.screen, opts); return; }
       if (!opts.all) {
         console.error('Specify --screen <name> for one unit, or --all for every unit (with confirmation).');
@@ -125,7 +105,6 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--screen <name>', 'Lint one unit (default: all field-maps)')
     .action((opts: { screen?: string }) => {
       const cwd = process.cwd();
-      ensureDataFactoryReadme(cwd);
       const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
       if (names.length === 0) { console.error('No field-maps under qa/data-factory/*.fields.yaml.'); process.exitCode = 1; return; }
       const { catalog } = loadEffectiveCatalog(cwd);
@@ -145,32 +124,4 @@ export function registerDataFactoryCommand(program: any): void {
       }
       if (totalErrors) process.exitCode = 1;
     });
-
-  data
-    .command('fixture')
-    .description('Generate a CSV import fixture from the field-map (bulk-import / file-upload testing)')
-    .requiredOption('--screen <name>', 'Unit whose field-map to build a fixture from')
-    .option('--rows <n>', 'Number of valid rows', '3')
-    .option('--invalid', 'Also write <name>.invalid.csv (one seeded-bad row per field + _violation column)')
-    .option('--force', 'Overwrite existing fixture file(s) without asking')
-    .action(async (opts: { screen: string; rows?: string; invalid?: boolean; force?: boolean }) => {
-      const cwd = process.cwd();
-      ensureDataFactoryReadme(cwd);
-      const map = loadFieldMap(cwd, opts.screen);
-      if (!map) { console.error(`✗ ${opts.screen}: no field-map at qa/data-factory/${opts.screen}.fields.yaml`); process.exitCode = 1; return; }
-      const { catalog } = loadEffectiveCatalog(cwd);
-      const res = generateFixture(map, catalog, { rows: parseInt(opts.rows || '3', 10), includeInvalid: !!opts.invalid });
-      const dir = join(cwd, 'qa', 'fixtures');
-      mkdirSync(dir, { recursive: true });
-      const validPath = join(dir, `${opts.screen}.csv`);
-      const writes: Array<[string, string]> = [[validPath, res.valid]];
-      if (res.invalid) writes.push([join(dir, `${opts.screen}.invalid.csv`), res.invalid]);
-      for (const [p] of writes) {
-        if (existsSync(p) && !opts.force) {
-          const a = (await ask(`  ? ${p.replace(cwd + '/', '')} exists — overwrite? [y/N] `)).toLowerCase();
-          if (a !== 'y' && a !== 'yes') { console.log('  · skipped'); return; }
-        }
-      }
-      for (const [p, content] of writes) { writeFileSync(p, content, 'utf8'); console.log(`  ✓ wrote ${p.replace(cwd + '/', '')} (${res.headers.length} columns)`); }
-    });
 }

package/src/generator.ts

@@ -13,31 +13,13 @@ import type { Catalog, FieldType, DataPoint } from './types';
 
 export interface FieldDef {
   name: string;
-  /** Catalog field-type id (email/password/…). Omit for a GROUP (a field with nested `fields`). A type absent from the catalog → blind spot. */
-  type?: string;
+  /** Catalog field-type id (email/password/…). A type absent from the catalog → blind spot. */
+  type: string;
   required?: boolean;
   /** Project overrides merged over the catalog constraints (maxLength, min, max, …). */
   constraints?: Record<string, any>;
   /** Placeholder errorRef (Mxx) → real project message code. Unmapped refs are flagged open. */
   errorMap?: Record<string, string>;
-  /**
-   * Field must be fresh/unique per test run (e.g. a register email/username that can't collide
-   * with a record left by a previous run). When true, the VALID value(s) get a runtime `{{$timestamp}}`
-   * suffix so `resolveDynamicVars` produces a new value every run — no cross-run cache, no flakiness.
-   */
-  unique?: boolean;
-  /**
-   * Nested / group field (complex form): sub-fields expanded recursively under this name
-   * (e.g. `address` → `city`, `postcode`). A field with `fields` is a group and needs no `type`.
-   */
-  fields?: FieldDef[];
-  /**
-   * Inter-field dependency: this field's rule/format depends on another field's value
-   * (e.g. postcode format `dependsOn: { field: country, value: JP }`). Carried through as metadata
-   * so the scenario weave + QA honor the relationship — the generator does not resolve the runtime
-   * condition (that is scenario/@cases logic), it records it.
-   */
-  dependsOn?: { field: string; value?: string };
 }
 
 export interface FieldMap {
@@ -61,13 +43,9 @@ export interface ExpandedPoint {
 
 export interface ExpandedField {
   name: string;
-  type?: string;
+  type: string;
   blindSpot: boolean;
   points: ExpandedPoint[];
-  /** Nested sub-fields (a group field). When present, `points` is empty and children hold the data. */
-  children?: ExpandedField[];
-  /** Recorded inter-field dependency (metadata only — not resolved deterministically). */
-  dependsOn?: { field: string; value?: string };
 }
 
 /** Deterministic filler: a string of exactly `n` chars from a charset seed. */
@@ -148,53 +126,23 @@ function resolveError(dp: DataPoint, errorMap?: Record<string, string>): { expec
   return { expectedError: dp.errorRef, open: true }; // placeholder survives; flagged open to confirm
 }
 
-/**
- * Make a valid value fresh-per-run by injecting a `{{$timestamp}}` token (resolved at runtime by the
- * TestDataLoader's resolveDynamicVars). Email keeps validity via a `+tag` in the local part; other
- * types append the token. Deterministic at compile time (same token string) — uniqueness is at run time.
- */
-function makeUnique(value: string, type: string): string {
-  if (value.includes('{{$')) return value; // already dynamic
-  if (type === 'email' && value.includes('@')) {
-    const at = value.indexOf('@');
-    return `${value.slice(0, at)}+{{$timestamp}}${value.slice(at)}`;
-  }
-  return `${value}{{$timestamp}}`;
-}
-
 /** Expand one field into valid/boundary/invalid data points using the effective catalog. */
 export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
-  // Group / nested field: no own type — expand each sub-field recursively.
-  if (field.fields && field.fields.length) {
-    return {
-      name: field.name,
-      type: undefined,
-      blindSpot: false,
-      points: [],
-      children: field.fields.map((sub) => expandField(sub, catalog)),
-      ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}),
-    };
-  }
-  const ft: FieldType | undefined = field.type ? catalog.fieldTypes[field.type] : undefined;
-  if (!ft) return { name: field.name, type: field.type, blindSpot: true, points: [], ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}) };
+  const ft: FieldType | undefined = catalog.fieldTypes[field.type];
+  if (!ft) return { name: field.name, type: field.type, blindSpot: true, points: [] };
 
   const c = { ...(ft.constraints || {}), ...(field.constraints || {}) };
   const points: ExpandedPoint[] = [];
 
   const push = (dp: DataPoint, group: ExpandedPoint['group']) => {
     const s = synthesize(dp, field.type, c);
-    // Uniqueness: only the VALID (happy-path create) value gets a fresh-per-run suffix. Boundary/invalid
-    // stay literal — they test rules, not record creation.
-    const value = group === 'valid' && field.unique && s.value != null
-      ? makeUnique(s.value, field.type)
-      : s.value;
     points.push({
       id: dp.id,
       group,
-      value,
+      value: s.value,
       todo: s.todo,
       reason: dp.reason,
-      note: field.unique && group === 'valid' && s.value != null ? `${dp.note ? dp.note + ' · ' : ''}fresh per run` : dp.note,
+      note: dp.note,
       ...resolveError(dp, field.errorMap),
     });
   };
@@ -222,7 +170,7 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
     }
   }
 
-  return { name: field.name, type: field.type, blindSpot: false, points, ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}) };
+  return { name: field.name, type: field.type, blindSpot: false, points };
 }
 
 /** Expand a whole field-map. */
@@ -238,30 +186,21 @@ export function renderTestData(expanded: ExpandedField[]): Record<string, any> {
   const out: Record<string, any> = {
     _generated_by: 'sungen data gen — standardized test-data (valid/boundary/invalid + CHK trace). Do not hand-edit values; edit the .fields.yaml or common.overwrite.yaml and re-run.',
   };
-  for (const f of expanded) out[f.name] = renderOne(f);
-  return out;
-}
-
-/** Render one expanded field — recurses for nested groups; carries a dependsOn note. */
-function renderOne(f: ExpandedField): Record<string, any> {
-  const dep = f.dependsOn ? { _depends_on: f.dependsOn.value != null ? `${f.dependsOn.field} = ${f.dependsOn.value}` : f.dependsOn.field } : {};
-  if (f.children) {
-    const group: Record<string, any> = { ...dep };
-    for (const c of f.children) group[c.name] = renderOne(c);
-    return group;
-  }
-  if (f.blindSpot) {
-    return { _blind_spot: `type "${f.type}" not in Data Factory catalog — provide qa/data-factory/project/${f.name}.yaml`, ...dep };
+  for (const f of expanded) {
+    if (f.blindSpot) {
+      out[f.name] = { _blind_spot: `type "${f.type}" not in Data Factory catalog — provide qa/data-factory/project/${f.name}.yaml` };
+      continue;
+    }
+    const valid = f.points.filter((p) => p.group === 'valid');
+    const boundary = f.points.filter((p) => p.group === 'boundary');
+    const invalid = f.points.filter((p) => p.group === 'invalid');
+    out[f.name] = {
+      valid: valid[0]?.value ?? null,
+      boundary: boundary.map((p) => trim({ id: p.id, value: p.value, note: p.note, todo: p.todo })),
+      invalid: invalid.map((p) => trim({ id: p.id, value: p.value, expected_error: p.expectedError, open: p.open, reason: p.reason, todo: p.todo })),
+    };
   }
-  const valid = f.points.filter((p) => p.group === 'valid');
-  const boundary = f.points.filter((p) => p.group === 'boundary');
-  const invalid = f.points.filter((p) => p.group === 'invalid');
-  return {
-    ...dep,
-    valid: valid[0]?.value ?? null,
-    boundary: boundary.map((p) => trim({ id: p.id, value: p.value, note: p.note, todo: p.todo })),
-    invalid: invalid.map((p) => trim({ id: p.id, value: p.value, expected_error: p.expectedError, open: p.open, reason: p.reason, todo: p.todo })),
-  };
+  return out;
 }
 
 function trim(o: Record<string, any>): Record<string, any> {

package/src/index.ts

@@ -24,8 +24,6 @@ export type { FieldDef, FieldMap, ExpandedField, ExpandedPoint } from './generat
 export { lintFieldMap, summarize } from './lint';
 export type { LintIssue } from './lint';
 export { registerDataFactoryCommand } from './cli';
-export { generateFixture } from './fixture';
-export type { FixtureResult } from './fixture';
 export { dataFactoryCoverageSensor } from './sensor';
 export { dfPreconditionCodegen } from './precondition';
 export type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning } from './types';

package/src/lint.ts

@@ -7,7 +7,7 @@
  * stale `.overwrite` warnings. Pure functions; no side effects.
  */
 import type { Catalog } from './types';
-import type { FieldMap, ExpandedField, FieldDef } from './generator';
+import type { FieldMap, ExpandedField } from './generator';
 import { expandFieldMap } from './generator';
 
 export interface LintIssue {
@@ -22,22 +22,11 @@ const BOUNDED = new Set(['email', 'string', 'password', 'phone', 'postcode', 'ka
 export function lintFieldMap(map: FieldMap, catalog: Catalog): { issues: LintIssue[]; expanded: ExpandedField[] } {
   const expanded = expandFieldMap(map, catalog);
   const issues: LintIssue[] = [];
+  const byName = new Map(map.fields.map((f) => [f.name, f]));
 
-  // Flatten nested groups to leaf fields (dotted path), pairing each with its FieldDef (for `required`).
-  const leaves: Array<{ f: ExpandedField; def?: FieldDef; path: string }> = [];
-  const walk = (efs: ExpandedField[], defs: FieldDef[], prefix: string) => {
-    for (const ef of efs) {
-      const def = defs.find((d) => d.name === ef.name);
-      const path = prefix ? `${prefix}.${ef.name}` : ef.name;
-      if (ef.children) walk(ef.children, def?.fields || [], path);
-      else leaves.push({ f: ef, def, path });
-    }
-  };
-  walk(expanded, map.fields, '');
-
-  for (const { f, def, path } of leaves) {
+  for (const f of expanded) {
     if (f.blindSpot) {
-      issues.push({ field: path, severity: 'error', code: 'BLIND_SPOT',
+      issues.push({ field: f.name, severity: 'error', code: 'BLIND_SPOT',
         message: `type "${f.type}" is not in the Data Factory catalog — supply qa/data-factory/project/${f.name}.yaml (valid set, invalid/nonexistent values, error code, dependencies)` });
       continue;
     }
@@ -45,25 +34,26 @@ export function lintFieldMap(map: FieldMap, catalog: Catalog): { issues: LintIss
     const boundary = f.points.filter((p) => p.group === 'boundary');
     const invalid = f.points.filter((p) => p.group === 'invalid');
 
-    if (valid.length === 0) issues.push({ field: path, severity: 'error', code: 'NO_VALID', message: 'no valid representative value' });
-    if (invalid.length === 0) issues.push({ field: path, severity: 'error', code: 'NO_INVALID', message: 'no invalid value — every rule needs at least one' });
-    if (f.type && BOUNDED.has(f.type) && boundary.length === 0) {
-      issues.push({ field: path, severity: 'warn', code: 'NO_BOUNDARY', message: `type "${f.type}" usually has min/max — add boundary values or state why not (phuong-phap §6)` });
+    if (valid.length === 0) issues.push({ field: f.name, severity: 'error', code: 'NO_VALID', message: 'no valid representative value' });
+    if (invalid.length === 0) issues.push({ field: f.name, severity: 'error', code: 'NO_INVALID', message: 'no invalid value — every rule needs at least one' });
+    if (BOUNDED.has(f.type) && boundary.length === 0) {
+      issues.push({ field: f.name, severity: 'warn', code: 'NO_BOUNDARY', message: `type "${f.type}" usually has min/max — add boundary values or state why not (phuong-phap §6)` });
     }
 
     // Unresolved (todo) values — a boundary/gen the constraints could not synthesize.
     for (const p of f.points) {
-      if (p.todo) issues.push({ field: path, severity: 'warn', code: 'UNRESOLVED',
+      if (p.todo) issues.push({ field: f.name, severity: 'warn', code: 'UNRESOLVED',
         message: `${p.id} (${p.group}) needs input: ${p.todo}${p.note ? ` — ${p.note}` : ''}` });
     }
     // Placeholder error codes still unmapped.
     const openErrs = invalid.filter((p) => p.open);
     if (openErrs.length) {
-      issues.push({ field: path, severity: 'info', code: 'OPEN_ERRORREF',
+      issues.push({ field: f.name, severity: 'info', code: 'OPEN_ERRORREF',
         message: `${openErrs.length} invalid case(s) use placeholder error codes (${[...new Set(openErrs.map((p) => p.expectedError))].join(', ')}) — map to real codes via errorMap in the field-map, or confirm with BA/Dev` });
     }
+    const def = byName.get(f.name);
     if (def?.required && valid.length === 0) {
-      issues.push({ field: path, severity: 'error', code: 'REQUIRED_NO_VALID', message: 'required field with no valid value' });
+      issues.push({ field: f.name, severity: 'error', code: 'REQUIRED_NO_VALID', message: 'required field with no valid value' });
     }
   }
   return { issues, expanded };

package/src/fixture.ts

@@ -1,79 +0,0 @@
-/**
- * Data Factory — CSV/file fixture generator (5b).
- *
- * Turns a field-map into a **bulk-import fixture file** (a CSV whose columns are the fields and whose
- * rows are standardized data), for testing CSV/Excel import, bulk upload, etc. — the `CSV / Import /
- * Export` checklist area. Two products:
- *   • the VALID fixture  — N rows of valid values (should import cleanly). Unique fields get a
- *     per-row suffix so rows don't collide.
- *   • the INVALID fixture — one row per field's first invalid case (all-valid except that one field),
- *     plus a trailing `_violation` column naming the field + reason + expected error — so a row-level
- *     import-rejection test knows which row should fail and why.
- *
- * Deterministic: same field-map + catalog → same CSV. Columns are the flattened leaf paths (nested
- * groups → dotted headers, e.g. `address.city`). Reference the file from an `@api` upload (`files:`)
- * or a UI file-input step.
- */
-import type { Catalog } from './types';
-import { expandFieldMap, type FieldMap, type ExpandedField } from './generator';
-
-interface Leaf { path: string; field: ExpandedField }
-
-/** Flatten nested groups to leaf fields with dotted-path headers. */
-function leaves(expanded: ExpandedField[], prefix = ''): Leaf[] {
-  const out: Leaf[] = [];
-  for (const f of expanded) {
-    const path = prefix ? `${prefix}.${f.name}` : f.name;
-    if (f.children) out.push(...leaves(f.children, path));
-    else out.push({ path, field: f });
-  }
-  return out;
-}
-
-const validOf = (f: ExpandedField): string => f.points.find((p) => p.group === 'valid' && p.value != null)?.value ?? '';
-const firstInvalid = (f: ExpandedField) => f.points.find((p) => p.group === 'invalid' && p.value != null);
-
-/** RFC-4180-ish CSV cell quoting. */
-function cell(v: string): string {
-  return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
-}
-function row(cells: string[]): string {
-  return cells.map(cell).join(',');
-}
-
-export interface FixtureResult {
-  valid: string;               // CSV text (header + N valid rows)
-  invalid?: string;            // CSV text (header + _violation + one bad row per field)
-  headers: string[];
-}
-
-/** Build the CSV fixture(s) from a field-map. */
-export function generateFixture(map: FieldMap, catalog: Catalog, opts: { rows?: number; includeInvalid?: boolean } = {}): FixtureResult {
-  const rows = Math.max(1, opts.rows ?? 3);
-  const ls = leaves(expandFieldMap(map, catalog));
-  const headers = ls.map((l) => l.path);
-
-  // VALID rows — resolve the valid value per field; a `unique` field's `{{$timestamp}}` token is a
-  // runtime var, not valid in a static file, so replace it with the row index to keep rows distinct.
-  const validRows: string[] = [];
-  for (let i = 1; i <= rows; i++) {
-    validRows.push(row(ls.map((l) => validOf(l.field).replace(/\{\{\$timestamp\}\}/g, String(i)))));
-  }
-  const valid = [row(headers), ...validRows].join('\n') + '\n';
-
-  let invalid: string | undefined;
-  if (opts.includeInvalid) {
-    const invHeaders = [...headers, '_violation'];
-    const invRows: string[] = [];
-    for (const target of ls) {
-      const bad = firstInvalid(target.field);
-      if (!bad) continue; // no concrete invalid value to seed
-      const cells = ls.map((l) => (l === target ? (bad.value as string) : validOf(l.field).replace(/\{\{\$timestamp\}\}/g, '1')));
-      const why = `${target.path}: ${bad.reason || 'invalid'}${bad.expectedError ? ` (${bad.expectedError})` : ''}`;
-      invRows.push(row([...cells, why]));
-    }
-    invalid = [row(invHeaders), ...invRows].join('\n') + '\n';
-  }
-
-  return { valid, invalid, headers };
-}

package/src/readme.ts

@@ -1,52 +0,0 @@
-/**
- * Drops a `qa/data-factory/README.md` into the user's project so the folder explains itself.
- * Write-if-absent (never clobbers a user-edited README), like a config file.
- */
-import { existsSync, mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
-
-const README = `# \`qa/data-factory/\` — Data Factory (your project's test-data knowledge)
-
-This folder is your project's **test-data standard**: machine-readable data rules that
-\`sungen data gen\` / \`/sungen:create-data-test\` (and \`/sungen:create-test\` step 5.3) expand into
-standardized test-data — **valid / boundary / invalid** values, each carrying a \`CHK-*\` trace id back
-to the spec. It is a reusable asset that **survives \`sungen update\`** (only the driver's shipped
-catalog is refreshed; nothing here is touched).
-
-It is **not** a copy of your spec — it is the structured, reusable data-rules layer the deterministic
-generator needs, complementary to \`requirements/spec.md\` (which is prose spec per screen/flow).
-
-## What lives here
-
-| File | What it is |
-|---|---|
-| \`<name>.fields.yaml\` | **Field-map** for a screen/flow — one entry per input field: its catalog \`type\`, the project's real \`constraints\`, an \`errorMap\` (catalog placeholder code → your real message code), and optionally \`unique: true\`, nested \`fields:\`, \`dependsOn:\`. Authored from \`requirements/spec.md\`; expanded deterministically. A unit with **no input fields** (navigation/list) has no field-map — that's correct. |
-| \`common.overwrite.yaml\` | **Project-wide overrides** to the shipped catalog — your real length limits, real error codes, banned values, extra invalid cases. Deep-merged over the common (later-wins, keyed by \`type\` + data-point \`id\`). Genuinely new project knowledge the shipped catalog can't have. |
-| \`project/<entity>.yaml\` | **Blind-spot answers** — business enums, cross-entity rules, data models the catalog can't know. You fill these when Data Factory hits a field \`type\` it doesn't have (instead of it guessing). |
-| \`recipes.yaml\` | Seed recipes for the \`@dataFactory:<recipe>\` annotation — named field sets bound into \`{{recipe.*}}\` at runtime. |
-
-## Good to know
-
-- **\`sungen data gen\` merges** into \`test-data/<name>.yaml\` — it replaces only the field keys it owns
-  and preserves everything else (create-test data, flow-namespaced keys, \`@cases\`, overrides).
-- **\`unique: true\`** makes a field's valid value fresh per run (\`{{$timestamp}}\`) so a register
-  email/username never collides — no cross-run cache.
-- \`sungen data lint\` checks coverage; \`sungen data fixture\` builds a CSV import fixture under
-  \`qa/fixtures/\`.
-- Edit the field-map / \`.overwrite\` and re-run — never hand-edit the generated \`test-data\` values.
-
-Full guide: https://sungen.sun-asterisk.vn/docs/guides/data-factory
-`;
-
-/** Ensure `qa/data-factory/README.md` exists (write-if-absent). */
-export function ensureDataFactoryReadme(cwd: string): void {
-  const dir = join(cwd, 'qa', 'data-factory');
-  const path = join(dir, 'README.md');
-  if (existsSync(path)) return;
-  try {
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(path, README, 'utf8');
-  } catch {
-    /* best-effort — a missing README must never fail a data command */
-  }
-}