@sungen/driver-data-factory 3.2.10-beta.11

package/src/cli.ts

@@ -0,0 +1,172 @@
+/**
+ * Data Factory CLI — `sungen data gen` and `sungen data lint`.
+ *
+ * Deterministic authoring commands (design-time; no runtime). They read the field-map
+ * (`qa/data-factory/<name>.fields.yaml`) + the effective catalog (shipped common + `.overwrite`),
+ * then generate the standardized `test-data/<name>.yaml` or lint its coverage. The slash command
+ * `/sungen:create-data-test` wraps these after the AI has authored the field-map from spec.md.
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { createInterface } from 'readline';
+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';
+
+const FIELDMAP_DIR = (cwd: string) => join(cwd, 'qa', 'data-factory');
+const fieldMapPath = (cwd: string, name: string) => join(FIELDMAP_DIR(cwd), `${name}.fields.yaml`);
+
+/** Resolve where a unit's test-data lives: screen or flow (mirrors sungen auto-detect). */
+function testDataPath(cwd: string, name: string): string | null {
+  const screen = join(cwd, 'qa', 'screens', name);
+  const flow = join(cwd, 'qa', 'flows', name);
+  if (existsSync(screen)) return join(screen, 'test-data', `${name}.yaml`);
+  if (existsSync(flow)) return join(flow, 'test-data', `${name}.yaml`);
+  return null;
+}
+
+function listFieldMaps(cwd: string): string[] {
+  const dir = FIELDMAP_DIR(cwd);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.fields.yaml'))
+    .map((f) => f.replace(/\.fields\.yaml$/, ''));
+}
+
+function ask(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => rl.question(question, (a) => { rl.close(); res(a.trim()); }));
+}
+
+function loadFieldMap(cwd: string, name: string): FieldMap | null {
+  const p = fieldMapPath(cwd, name);
+  if (!existsSync(p)) return null;
+  return parseYaml(readFileSync(p, 'utf8')) as FieldMap;
+}
+
+async function genOne(cwd: string, name: string, opts: { force?: boolean }): Promise<'written' | 'skipped' | 'missing'> {
+  const map = loadFieldMap(cwd, name);
+  if (!map) { console.error(`  ✗ ${name}: no field-map at qa/data-factory/${name}.fields.yaml (author it first, e.g. via /sungen:create-data-test)`); return 'missing'; }
+  const { catalog, warnings } = loadEffectiveCatalog(cwd);
+  for (const w of warnings) console.warn(`  ⚠ overwrite: ${w.detail} → ${w.suggestion}`);
+
+  const expanded = expandFieldMap(map, catalog);
+  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;
+  }
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, stringifyYaml(final), '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(', ')}` : ''}`);
+  return 'written';
+}
+
+export function registerDataFactoryCommand(program: any): void {
+  const data = program.command('data').description('Data Factory — standardized test-data generation');
+
+  data
+    .command('gen')
+    .description('Generate standardized test-data from qa/data-factory/<name>.fields.yaml + the catalog')
+    .option('--screen <name>', 'Generate for one screen or flow')
+    .option('--all', 'Generate for every field-map under qa/data-factory/ (requires confirm)')
+    .option('--yes', 'Assume yes for the --all confirmation')
+    .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();
+      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).');
+        process.exitCode = 1;
+        return;
+      }
+      // ALL mode — guard against a mistyped/omitted name.
+      const names = listFieldMaps(cwd);
+      if (names.length === 0) { console.error('No field-maps under qa/data-factory/*.fields.yaml.'); process.exitCode = 1; return; }
+      const existing = names.filter((n) => { const p = testDataPath(cwd, n); return p && existsSync(p); });
+      console.log(`Data Factory — generate for ALL ${names.length} unit(s): ${names.join(', ')}`);
+      console.log(`  ${names.length - existing.length} new · ${existing.length} would overwrite existing test-data`);
+      if (!opts.yes && !opts.force) {
+        const a = (await ask(`Proceed for ALL ${names.length} unit(s)? [y/N] `)).toLowerCase();
+        if (a !== 'y' && a !== 'yes') { console.log('Cancelled.'); return; }
+      }
+      let written = 0;
+      for (const n of names) if ((await genOne(cwd, n, { force: opts.force })) === 'written') written++;
+      console.log(`Done: ${written}/${names.length} written.`);
+    });
+
+  data
+    .command('lint')
+    .description('Check test-data coverage (valid/boundary/invalid + traceability) per phuong-phap §6')
+    .option('--screen <name>', 'Lint one unit (default: all field-maps)')
+    .action((opts: { screen?: string }) => {
+      const cwd = process.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);
+      let totalErrors = 0;
+      for (const name of names) {
+        const map = loadFieldMap(cwd, name);
+        if (!map) { console.error(`✗ ${name}: no field-map`); totalErrors++; continue; }
+        const { issues } = lintFieldMap(map, catalog);
+        const s = summarize(issues);
+        totalErrors += s.errors;
+        const badge = s.errors ? '✗' : s.warns ? '⚠' : '✓';
+        console.log(`${badge} ${name}: ${s.errors} error · ${s.warns} warn · ${s.infos} info`);
+        for (const i of issues) {
+          const mark = i.severity === 'error' ? '  ✗' : i.severity === 'warn' ? '  ⚠' : '  ·';
+          console.log(`${mark} [${i.field}] ${i.code}: ${i.message}`);
+        }
+      }
+      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();
+      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/fixture.ts

@@ -0,0 +1,79 @@
+/**
+ * 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/generator.ts

@@ -0,0 +1,271 @@
+/**
+ * Data Factory generator — deterministic expansion of a field-map into standardized test-data.
+ *
+ * The AI skill (`/sungen:create-data-test`) reads spec.md/viewpoint and writes the field-MAP
+ * (`qa/data-factory/<name>.fields.yaml`): each field's `type` + project `constraints` + `errorMap`.
+ * This module is the deterministic half: given that field-map + the effective catalog, it expands
+ * every field into valid / boundary / invalid data points — pulling literal values from the catalog,
+ * synthesizing length/number boundaries from the constraints, appending the referenced security
+ * payloads, and resolving placeholder error codes through the field's `errorMap`. Same input →
+ * same output (determinism is an asset). Nothing here reads a live page or an LLM.
+ */
+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;
+  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 {
+  screen?: string;
+  flow?: string;
+  fields: FieldDef[];
+}
+
+export interface ExpandedPoint {
+  id: string;
+  group: 'valid' | 'boundary' | 'invalid';
+  value: string | null;
+  reason?: string;
+  note?: string;
+  /** Resolved expected error (via errorMap) — or the raw placeholder + `open: true` if unmapped. */
+  expectedError?: string;
+  open?: boolean;
+  /** Value could not be synthesized deterministically (missing constraint) — needs input. */
+  todo?: string;
+}
+
+export interface ExpandedField {
+  name: 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. */
+function fillLen(n: number, base = 'a'): string {
+  if (!Number.isFinite(n) || n <= 0) return '';
+  return base.repeat(n).slice(0, n);
+}
+
+/** Build an email of a given total or local length (half-width), with a boundary offset (-1/0/+1). */
+function synthEmail(constraints: Record<string, any>, which: 'maxLocal' | 'maxTotal', offset = 0): string | null {
+  const domain = '@example.com';
+  if (which === 'maxLocal' && Number.isFinite(constraints.maxLocal)) {
+    return fillLen(constraints.maxLocal + offset) + domain;
+  }
+  if (which === 'maxTotal' && Number.isFinite(constraints.maxTotal)) {
+    const localLen = Math.max(1, constraints.maxTotal + offset - domain.length);
+    return fillLen(localLen) + domain;
+  }
+  return null;
+}
+
+/** Try to synthesize a boundary/gen value from constraints. Returns null when data is insufficient. */
+function synthesize(dp: DataPoint, type: string, c: Record<string, any>): { value: string | null; todo?: string } {
+  if (dp.value != null) return { value: dp.value };
+  const hint = `${dp.gen || ''} ${dp.note || ''}`.toLowerCase();
+
+  // Email length boundaries. `>` / "vượt" → over-boundary (invalid, offset +1).
+  if (type === 'email') {
+    const over = hint.includes('>') || hint.includes('vượt') || hint.includes('over');
+    const offset = over ? 1 : hint.includes('-1') ? -1 : hint.includes('+1') ? 1 : 0;
+    if (hint.includes('maxlocal') || (hint.includes('local') && (hint.includes('max') || over))) {
+      const v = synthEmail(c, 'maxLocal', offset); return v ? { value: v } : { value: null, todo: 'maxLocal' };
+    }
+    if (hint.includes('maxtotal') || (hint.includes('tổng') && (hint.includes('max') || over)) || (hint.includes('total'))) {
+      const v = synthEmail(c, 'maxTotal', offset); return v ? { value: v } : { value: null, todo: 'maxTotal' };
+    }
+  }
+
+  // String-length types: min / max length boundaries.
+  const strTypes = ['string', 'password', 'phone', 'postcode', 'katakana'];
+  if (strTypes.includes(type)) {
+    const min = c.minLength ?? c.length;
+    const max = c.maxLength ?? c.length;
+    if (hint.includes('min') && Number.isFinite(min)) {
+      const n = hint.includes('+1') ? min + 1 : min;
+      return { value: fillLen(n, type === 'password' ? 'Aa1' : 'a') };
+    }
+    if (hint.includes('max') && Number.isFinite(max)) {
+      const n = hint.includes('-1') ? max - 1 : max;
+      return { value: fillLen(n, type === 'password' ? 'Aa1' : 'a') };
+    }
+    return { value: null, todo: 'minLength/maxLength' };
+  }
+
+  // Numeric types: min / max value boundaries.
+  const numTypes = ['number-integer', 'number-float', 'currency'];
+  if (numTypes.includes(type)) {
+    const min = c.min, max = c.max;
+    if (hint.includes('min') && Number.isFinite(min)) {
+      if (hint.includes('-1')) return { value: String(min - 1) };
+      if (hint.includes('+1')) return { value: String(min + 1) };
+      return { value: String(min) };
+    }
+    if (hint.includes('max') && Number.isFinite(max)) {
+      if (hint.includes('+1')) return { value: String(max + 1) };
+      if (hint.includes('-1')) return { value: String(max - 1) };
+      return { value: String(max) };
+    }
+    return { value: null, todo: 'min/max' };
+  }
+
+  return { value: null, todo: 'value/gen not resolvable' };
+}
+
+function resolveError(dp: DataPoint, errorMap?: Record<string, string>): { expectedError?: string; open?: boolean } {
+  if (!dp.errorRef) return {};
+  if (errorMap && errorMap[dp.errorRef]) return { expectedError: errorMap[dp.errorRef] };
+  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 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,
+      todo: s.todo,
+      reason: dp.reason,
+      note: field.unique && group === 'valid' && s.value != null ? `${dp.note ? dp.note + ' · ' : ''}fresh per run` : dp.note,
+      ...resolveError(dp, field.errorMap),
+    });
+  };
+
+  for (const dp of ft.valid || []) push(dp, 'valid');
+  for (const dp of ft.boundary || []) push(dp, 'boundary');
+  for (const dp of ft.invalid || []) {
+    if (dp.from) continue; // security refs are expanded below
+    push(dp, 'invalid');
+  }
+
+  // Append security payloads referenced by uses_security.
+  for (const bank of ft.uses_security || []) {
+    const b = catalog.security[bank];
+    if (!b) continue;
+    for (const p of b.payloads || []) {
+      points.push({
+        id: p.id,
+        group: 'invalid',
+        value: (p.value as string) ?? null,
+        todo: p.value == null ? `security technique: ${p.technique || bank}` : undefined,
+        reason: `${bank}: ${(p.reason as string) || (p.kind as string) || (p.technique as string) || ''}`.trim(),
+        note: b.oracle,
+      });
+    }
+  }
+
+  return { name: field.name, type: field.type, blindSpot: false, points, ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}) };
+}
+
+/** Expand a whole field-map. */
+export function expandFieldMap(map: FieldMap, catalog: Catalog): ExpandedField[] {
+  return (map.fields || []).map((f) => expandField(f, catalog));
+}
+
+/**
+ * Render expanded fields into a standardized `test-data/<name>.yaml` object (serialize with `yaml`).
+ * Reviewable + traceable: each value carries its CHK id and resolved expected error.
+ */
+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 };
+  }
+  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 })),
+  };
+}
+
+function trim(o: Record<string, any>): Record<string, any> {
+  const r: Record<string, any> = {};
+  for (const [k, v] of Object.entries(o)) if (v != null) r[k] = v;
+  return r;
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @sungen/driver-data-factory — Sungen Data Factory capability.
+ *
+ * Two layers (see docs/spec/data-factory-driver-spec.md):
+ *  - DF-KNOWLEDGE (design-time, runtime-free): the field-type + security + technique catalog under
+ *    `common/`, the `.overwrite` merge layer (catalog-loader), and — in later phases — the generator
+ *    that writes standardized `test-data/<screen>.yaml` (valid/boundary/invalid + CHK traceability)
+ *    and the `sungen data gen|lint` CLI. Because it embeds no runtime, this layer is safe to bundle
+ *    by default (like core), which is why the driver is registered as a bundled capability.
+ *  - DF-SEEDING (runtime, opt-in): the `@dataFactory:<recipe>` precondition codegen that seeds a
+ *    record and binds its id into `{{var}}` (M1 "missing data setup"). It delegates to the datasource
+ *    of driver-db/api and is only active when a datasource exists — added in a later phase.
+ *
+ * Plugs into core via the capability SPI; core discovers and calls `register()` at runtime.
+ */
+import type { CapabilityRegistry } from '@sun-asterisk/sungen';
+import { registerDataFactoryCommand } from './cli';
+import { dataFactoryCoverageSensor } from './sensor';
+import { dfPreconditionCodegen } from './precondition';
+
+export { loadShippedCatalog, loadEffectiveCatalog, shippedCommonHash, commonDir } from './catalog-loader';
+export { expandField, expandFieldMap, renderTestData } from './generator';
+export type { FieldDef, FieldMap, ExpandedField, ExpandedPoint } from './generator';
+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';
+
+/** Register the Data Factory capability. */
+export function register(registry: CapabilityRegistry): void {
+  registry.register({
+    id: 'data-factory',
+    annotations: ['@dataFactory'],
+    cliCommands: [registerDataFactoryCommand as (program: unknown) => void], // `sungen data gen|lint`
+    sensors: [dataFactoryCoverageSensor], // advisory: test-data coverage surfaced at `sungen generate`
+    preconditionCodegen: dfPreconditionCodegen, // @dataFactory:<recipe> → bind standardized seed values (beta)
+  });
+}
+
+export const sungenDriver = { capability: 'data-factory', register } as const;

package/src/lint.ts

@@ -0,0 +1,78 @@
+/**
+ * Data Factory lint — the deterministic coverage oracle from phuong-phap-tao-test-data.md §6.
+ *
+ * For each field it confirms the "đủ" checklist: ≥1 valid, boundary present when the field has a
+ * length/number bound, ≥1 invalid per rule, no unresolved values, error codes mapped (not left as
+ * placeholders). It also surfaces blind spots (type not in catalog) and — via the catalog loader —
+ * stale `.overwrite` warnings. Pure functions; no side effects.
+ */
+import type { Catalog } from './types';
+import type { FieldMap, ExpandedField, FieldDef } from './generator';
+import { expandFieldMap } from './generator';
+
+export interface LintIssue {
+  field: string;
+  severity: 'error' | 'warn' | 'info';
+  code: string;
+  message: string;
+}
+
+const BOUNDED = new Set(['email', 'string', 'password', 'phone', 'postcode', 'katakana', 'number-integer', 'number-float', 'currency']);
+
+export function lintFieldMap(map: FieldMap, catalog: Catalog): { issues: LintIssue[]; expanded: ExpandedField[] } {
+  const expanded = expandFieldMap(map, catalog);
+  const issues: LintIssue[] = [];
+
+  // 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) {
+    if (f.blindSpot) {
+      issues.push({ field: path, 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;
+    }
+    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');
+
+    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)` });
+    }
+
+    // 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',
+        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',
+        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` });
+    }
+    if (def?.required && valid.length === 0) {
+      issues.push({ field: path, severity: 'error', code: 'REQUIRED_NO_VALID', message: 'required field with no valid value' });
+    }
+  }
+  return { issues, expanded };
+}
+
+export function summarize(issues: LintIssue[]): { errors: number; warns: number; infos: number } {
+  return {
+    errors: issues.filter((i) => i.severity === 'error').length,
+    warns: issues.filter((i) => i.severity === 'warn').length,
+    infos: issues.filter((i) => i.severity === 'info').length,
+  };
+}