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

package/src/precondition.ts

@@ -0,0 +1,70 @@
+/**
+ * Data Factory runtime binding — `@dataFactory:<recipe>` precondition codegen (P4, beta).
+ *
+ * A scenario tagged `@dataFactory:<recipe>` needs a standardized set of seed values available at
+ * runtime (M1 "missing data setup"). This emits a compile-time `testData.bind('<recipe>', {...})`
+ * with **valid** representative values drawn deterministically from the field-type catalog (+ the
+ * project's `.overwrite`), so the scenario's create steps (`@api:create…` or a UI form) consume
+ * `{{recipe.field}}` instead of hand-picked literals.
+ *
+ * Scope (beta): this binds the standardized DATA. The actual record CREATE is performed by the
+ * scenario's own steps — Data Factory does NOT open a DB/API connection or issue writes itself
+ * (that stays with the api/db drivers, whose datasource owns execution). Fully deterministic and
+ * backend-free: same recipe + catalog → same bound values. Full backend record-orchestration
+ * (calling a create endpoint from the recipe) is a later enhancement.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { loadEffectiveCatalog } from './catalog-loader';
+import { expandField, type FieldDef } from './generator';
+
+interface Recipe {
+  description?: string;
+  fields: FieldDef[];
+}
+interface RecipesFile { recipes?: Record<string, Recipe>; }
+
+const TAG = /^@dataFactory:([A-Za-z_][A-Za-z0-9_]*)$/;
+
+function loadRecipes(cwd: string): Record<string, Recipe> {
+  const p = join(cwd, 'qa', 'data-factory', 'recipes.yaml');
+  if (!existsSync(p)) return {};
+  try { return (parseYaml(readFileSync(p, 'utf8')) as RecipesFile)?.recipes || {}; } catch { return {}; }
+}
+
+/** Pick the first concrete valid value for a field from the catalog (deterministic). */
+function validValue(field: FieldDef, catalog: ReturnType<typeof loadEffectiveCatalog>['catalog']): string | null {
+  const ex = expandField(field, catalog);
+  if (ex.blindSpot) return null;
+  const v = ex.points.find((p) => p.group === 'valid' && p.value != null);
+  return v?.value ?? null;
+}
+
+export function dfPreconditionCodegen(input: { tags: string[]; screenName: string; cwd: string }): Array<{ comment?: string; code: string; boundVars?: string[] }> {
+  const recipeTags = input.tags.map((t) => t.match(TAG)).filter(Boolean).map((m) => (m as RegExpMatchArray)[1]);
+  if (!recipeTags.length) return [];
+
+  const recipes = loadRecipes(input.cwd);
+  const { catalog } = loadEffectiveCatalog(input.cwd);
+  const out: Array<{ comment?: string; code: string; boundVars?: string[] }> = [];
+
+  for (const name of recipeTags) {
+    const recipe = recipes[name];
+    if (!recipe || !Array.isArray(recipe.fields)) {
+      // Fail-soft with a visible comment (mirrors how a missing catalog entry surfaces) — the scenario
+      // still compiles; the bind is empty so `{{name.*}}` resolves to nothing and the run flags it.
+      out.push({ comment: `@dataFactory:${name} — no recipe "${name}" in qa/data-factory/recipes.yaml (add it, or the bind is empty)`, code: `testData.bind(${JSON.stringify(name)}, {});`, boundVars: [name] });
+      continue;
+    }
+    const obj: Record<string, string | null> = {};
+    for (const f of recipe.fields) obj[f.name] = validValue(f, catalog);
+    const label = recipe.description ? `recipe "${name}" — ${recipe.description}` : `recipe "${name}"`;
+    out.push({
+      comment: `@dataFactory:${name} → bind {{${name}.*}} with standardized valid values (${label})`,
+      code: `testData.bind(${JSON.stringify(name)}, ${JSON.stringify(obj)});`,
+      boundVars: [name],
+    });
+  }
+  return out;
+}

package/src/sensor.ts

@@ -0,0 +1,64 @@
+/**
+ * Data Factory coverage sensor — an ADVISORY harness sensor (runs at `sungen generate`, never blocks).
+ *
+ * For a screen/flow that has a field-map (`qa/data-factory/<name>.fields.yaml`), it runs the same
+ * coverage lint as `sungen data lint` and surfaces the gaps in the generate output — so weak
+ * test-data coverage (missing boundary/invalid, unresolved values, unmapped error codes, blind
+ * spots) is visible in the standard harness flow, not only when you remember to run `data lint`.
+ * A unit with no field-map produces no findings (Data Factory is opt-in per unit).
+ *
+ * Advisory, not gate: the ContextRouter scopes gate sensors by the annotation tags a feature carries,
+ * and test-data generation is a design-time concern with no `.feature` tag — so gating here would
+ * never route. Escalation to a gate axis (intent-aware threshold) is a later phase.
+ */
+import { basename, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { parse as parseYaml } from 'yaml';
+import type { Sensor } from '@sun-asterisk/sungen';
+import { loadEffectiveCatalog } from './catalog-loader';
+import { lintFieldMap, summarize } from './lint';
+import type { FieldMap } from './generator';
+
+export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
+  id: 'data-factory-coverage',
+  capability: 'data-factory',
+  kind: 'advisory',
+  run: ({ dir, cwd }) => {
+    const name = basename(dir);
+    const fieldMapPath = join(cwd, 'qa', 'data-factory', `${name}.fields.yaml`);
+    if (!existsSync(fieldMapPath)) return []; // opt-in per unit — no field-map, nothing to say
+    let map: FieldMap;
+    try { map = parseYaml(readFileSync(fieldMapPath, 'utf8')) as FieldMap; } catch { return []; }
+    if (!map || !Array.isArray(map.fields)) return [];
+
+    const { catalog, warnings } = loadEffectiveCatalog(cwd);
+    const { issues } = lintFieldMap(map, catalog);
+    const findings = issues.map((i) => ({
+      sensorId: 'data-factory-coverage',
+      capability: 'data-factory',
+      scenario: i.field,
+      message: `DATA-FACTORY-${i.code}: ${i.message}`,
+      severity: i.severity, // error → shown; still advisory (generate never blocks)
+    }));
+    for (const w of warnings) {
+      findings.push({
+        sensorId: 'data-factory-coverage',
+        capability: 'data-factory',
+        scenario: w.fieldType,
+        message: `DATA-FACTORY-OVERWRITE-STALE: ${w.detail} → ${w.suggestion}`,
+        severity: 'warn',
+      });
+    }
+    if (findings.length) {
+      const s = summarize(issues);
+      findings.unshift({
+        sensorId: 'data-factory-coverage',
+        capability: 'data-factory',
+        scenario: name,
+        message: `DATA-FACTORY-COVERAGE: ${name} test-data — ${s.errors} error · ${s.warns} warn · ${s.infos} info (run \`sungen data lint --screen ${name}\`)`,
+        severity: s.errors ? 'warn' : 'info',
+      });
+    }
+    return findings;
+  },
+};

package/src/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Data Factory — catalog types. These mirror the YAML seed files under `common/`.
+ * Design-time only; no runtime deps.
+ */
+
+/** One representative test value in a field-type's valid/boundary/invalid group. */
+export interface DataPoint {
+  /** Traceability id, e.g. CHK-EMAIL-01. Unique within a field-type after overlay merge. */
+  id: string;
+  /** Literal value (present for concrete cases). */
+  value?: string;
+  /** Human instruction to synthesize the value when it depends on project constraints (e.g. "local@ đúng maxLocal"). */
+  gen?: string;
+  /** Why this value is invalid (invalid group only). */
+  reason?: string;
+  /** Placeholder message-code (Mxx). Mapped onto the project's real codes at generation; if the spec has none it becomes a chua-chot (open) point. */
+  errorRef?: string;
+  /** Pull values from a security bank (e.g. `security/sqli`) into this group. */
+  from?: string;
+  note?: string;
+}
+
+export interface FieldType {
+  type: string;
+  description?: string;
+  format?: string;
+  constraints?: Record<string, unknown>;
+  /** Security banks whose payloads are appended to the `invalid` group. */
+  uses_security?: string[];
+  valid?: DataPoint[];
+  boundary?: DataPoint[];
+  invalid?: DataPoint[];
+  notes?: string[];
+}
+
+export interface SecurityBank {
+  class: string;
+  description?: string;
+  payloads: Array<Record<string, unknown> & { id: string }>;
+  oracle?: string;
+}
+
+export interface Technique {
+  technique: string;
+  description?: string;
+  rule?: string;
+  applies_to?: string[];
+  [k: string]: unknown;
+}
+
+export interface Catalog {
+  fieldTypes: Record<string, FieldType>;
+  security: Record<string, SecurityBank>;
+  techniques: Record<string, Technique>;
+}
+
+/** A warning that a project's common.overwrite.yaml entry looks stale against the shipped common. */
+export interface OverwriteWarning {
+  fieldType: string;
+  detail: string;
+  suggestion: string;
+}