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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-data-factory",
-  "version": "3.2.10-beta.12",
+  "version": "3.2.10-beta.14",
   "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.12",
+    "@sun-asterisk/sungen": "3.2.10-beta.14",
     "yaml": "^2.4.0"
   },
   "files": [

package/src/cli.ts

@@ -14,6 +14,7 @@ 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`);
@@ -96,6 +97,7 @@ 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).');
@@ -123,6 +125,7 @@ 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);
@@ -152,6 +155,7 @@ export function registerDataFactoryCommand(program: any): void {
     .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);

package/src/readme.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 */
+  }
+}