@sungen/driver-data-factory 3.2.12-beta.1 → 3.2.12-beta.10

package/src/state.ts

@@ -0,0 +1,225 @@
+/**
+ * Data Factory — domain/stateful data, Layer 0: the DECLARATION (M3-A).
+ *
+ * Grounded in a real spec-only project (`examples/nextjp`, web-only, no datasource): domain/stateful
+ * preconditions are everywhere in spec + viewpoint, and QA already writes them by hand in prose + tags
+ * (e.g. "requires a valid, unused reset token ≤24h; seeded via fixture / prior flow; where it cannot be
+ * seeded, treat as @manual"). This module standardizes that: a `state-recipe` (entity graph + relations
+ * + desired state + bindings + lifecycle + PROVENANCE) becomes a reviewable, traceable **manual
+ * precondition** rendered into the testcase — working with only spec + viewpoint, no DB/API, no Core.
+ *
+ * Layer 1 (opt-in runtime provisioning) reuses the SAME declaration where an api/db datasource exists;
+ * this file does not execute anything — it validates + renders the declaration deterministically.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
+
+/** WHERE a resource's state comes from — NOT only api/db (nextjp: prior-flow / fixture / manual dominate). */
+export type Provenance = 'prior-flow' | 'fixture' | 'client-storage' | 'server-context' | 'api' | 'db' | 'manual';
+export type Lifecycle = 'reusable' | 'unique-per-run' | 'consumable' | 'leased' | 'expiring' | 'mutable-state';
+
+const PROVENANCES: Provenance[] = ['prior-flow', 'fixture', 'client-storage', 'server-context', 'api', 'db', 'manual'];
+const LIFECYCLES: Lifecycle[] = ['reusable', 'unique-per-run', 'consumable', 'leased', 'expiring', 'mutable-state'];
+/** Provenances that need a runtime datasource — Layer 1. The rest resolve at design time (Layer 0). */
+const RUNTIME_PROVENANCE = new Set<Provenance>(['api', 'db']);
+
+export interface StateResource {
+  ref: string;
+  entity: string;
+  provenance?: Provenance;      // default 'manual'
+  provider?: string;            // @api:x / @query:x — required only for api/db provenance (Layer 1)
+  transition?: string;          // endpoint that moves the entity to desiredState (Layer 1)
+  dependsOn?: string[];
+  with?: Record<string, unknown>;
+  desiredState?: string;
+  lifecycle?: Lifecycle;
+  note?: string;
+}
+
+export interface StateRecipe {
+  name: string;
+  description?: string;
+  resources?: StateResource[];
+  bindings?: Record<string, string>;
+  cleanup?: string | { keep: true; reason: string };
+  /** 1b — cross-screen flow-shared dataset: `entity`'s data is shared verbatim across `screens`. */
+  shared?: { entity: string; screens: string[] };
+}
+
+export interface StateFinding {
+  recipe: string;
+  severity: 'error' | 'warn' | 'info';
+  code: string;
+  message: string;
+}
+
+export interface StatePlan {
+  recipe: string;
+  /** Topologically ordered resources (dependencies first). */
+  order: string[];
+  resources: StateResource[];
+  bindings: Record<string, string>;
+  /** True when NO resource can be auto-provisioned here (no api/db provenance, or missing datasource). */
+  manual: boolean;
+  /** The identity pairs a shared dataset implies (for the Cross-artifact Gate). */
+  sharedIdentity?: { entity: string; screens: string[] };
+  /** Human-readable precondition lines (Gherkin Given/And) for weaving into a Background. */
+  preconditionLines: string[];
+  cleanup?: string;
+}
+
+/** Load state-recipes (recipes with a `resources` graph) from qa/data-factory/recipes.yaml. */
+export function loadStateRecipes(cwd: string): StateRecipe[] {
+  const p = join(cwd, 'qa', 'data-factory', 'recipes.yaml');
+  if (!existsSync(p)) return [];
+  const doc = parseYaml(readFileSync(p, 'utf8')) || {};
+  const recipes = doc.recipes || {};
+  const out: StateRecipe[] = [];
+  for (const [name, r] of Object.entries<any>(recipes)) {
+    if (r && (Array.isArray(r.resources) || r.shared)) out.push({ name, ...r });
+  }
+  return out;
+}
+
+/** Topologically sort resources by dependsOn. Returns { order, cycle } — cycle non-empty ⇒ error. */
+export function topoSort(resources: StateResource[]): { order: string[]; cycle: string[] } {
+  const byRef = new Map(resources.map((r) => [r.ref, r]));
+  const state = new Map<string, 0 | 1 | 2>(); // 0=unseen,1=in-stack,2=done
+  const order: string[] = [];
+  let cycle: string[] = [];
+  const visit = (ref: string, stack: string[]): boolean => {
+    const s = state.get(ref) || 0;
+    if (s === 2) return true;
+    if (s === 1) { cycle = [...stack.slice(stack.indexOf(ref)), ref]; return false; }
+    state.set(ref, 1);
+    for (const dep of byRef.get(ref)?.dependsOn || []) {
+      if (!byRef.has(dep)) continue; // dangling dep reported separately
+      if (!visit(dep, [...stack, ref])) return false;
+    }
+    state.set(ref, 2);
+    order.push(ref);
+    return true;
+  };
+  for (const r of resources) if (!visit(r.ref, [])) break;
+  return { order, cycle };
+}
+
+/** Validate a state-recipe (structure only — no runtime). */
+export function validateStateRecipe(recipe: StateRecipe): StateFinding[] {
+  const out: StateFinding[] = [];
+  const F = (severity: StateFinding['severity'], code: string, message: string) => out.push({ recipe: recipe.name, severity, code, message });
+  const resources = recipe.resources || [];
+  const refs = new Set(resources.map((r) => r.ref));
+  if (!resources.length && !recipe.shared) F('warn', 'EMPTY', 'recipe has neither resources nor a shared dataset');
+  for (const r of resources) {
+    if (!r.ref) F('error', 'NO_REF', 'a resource has no `ref`');
+    if (!r.entity) F('error', 'NO_ENTITY', `resource "${r.ref}" has no \`entity\``);
+    if (r.provenance && !PROVENANCES.includes(r.provenance)) F('error', 'BAD_PROVENANCE', `resource "${r.ref}" provenance "${r.provenance}" ∉ ${PROVENANCES.join('|')}`);
+    if (r.lifecycle && !LIFECYCLES.includes(r.lifecycle)) F('error', 'BAD_LIFECYCLE', `resource "${r.ref}" lifecycle "${r.lifecycle}" ∉ ${LIFECYCLES.join('|')}`);
+    for (const dep of r.dependsOn || []) if (!refs.has(dep)) F('error', 'DANGLING_DEP', `resource "${r.ref}" dependsOn "${dep}" which is not a resource`);
+    // api/db provenance needs a provider endpoint (Layer 1); others must NOT pretend to auto-provision.
+    if (RUNTIME_PROVENANCE.has(r.provenance as Provenance) && !r.provider) F('error', 'NO_PROVIDER', `resource "${r.ref}" provenance "${r.provenance}" needs a \`provider\` endpoint (@api:/@query:)`);
+    if (r.desiredState && !r.transition && RUNTIME_PROVENANCE.has(r.provenance as Provenance)) F('warn', 'NO_TRANSITION', `resource "${r.ref}" desiredState "${r.desiredState}" has no \`transition\` endpoint — Layer 1 cannot move it automatically`);
+  }
+  // Bindings must reference a real ${ref.field}.
+  for (const [k, v] of Object.entries(recipe.bindings || {})) {
+    const m = /^\$\{([^.}]+)\.[^}]+\}$/.exec(String(v));
+    if (!m) F('warn', 'BINDING_SHAPE', `binding "${k}: ${v}" is not of the form \${ref.field}`);
+    else if (!refs.has(m[1])) F('error', 'BINDING_REF', `binding "${k}" references unknown resource "${m[1]}"`);
+  }
+  const { cycle } = topoSort(resources);
+  if (cycle.length) F('error', 'CYCLE', `dependsOn cycle: ${cycle.join(' → ')}`);
+  return out;
+}
+
+const article = (w: string) => (/^[aeiou]/i.test(w) ? 'an' : 'a');
+
+/** Build the deterministic plan + the human-readable precondition block for a state-recipe. */
+export function buildStatePlan(recipe: StateRecipe, opts: { datasource?: boolean } = {}): StatePlan {
+  const resources = (recipe.resources || []).map((r) => ({ provenance: 'manual' as Provenance, ...r }));
+  const { order } = topoSort(resources);
+  const ordered = order.length ? order.map((ref) => resources.find((r) => r.ref === ref)!) : resources;
+  // A resource is auto-provisionable only when its provenance is api/db AND a datasource is configured.
+  const autoable = (r: StateResource) => RUNTIME_PROVENANCE.has(r.provenance as Provenance) && !!opts.datasource;
+  const manual = ordered.length > 0 && !ordered.every(autoable);
+
+  const lines: string[] = [];
+  for (const r of ordered) {
+    const withStr = r.with && Object.keys(r.with).length ? '  ' + Object.entries(r.with).map(([k, v]) => `${k}=${v}`).join(', ') : '';
+    const owner = (r.dependsOn || []).length ? ` owned by ${r.dependsOn!.join('/')}` : '';
+    const stateStr = r.desiredState ? ` in state "${r.desiredState}"` : '';
+    const meta = `[provenance: ${r.provenance}${r.lifecycle ? `; lifecycle: ${r.lifecycle}` : ''}${autoable(r) ? `; auto: ${r.provider}` : ''}]`;
+    lines.push(`Given ${article(r.entity)} ${r.entity} "${r.ref}"${owner} exists${stateStr}  ${meta}${withStr}`);
+  }
+  for (const [k, v] of Object.entries(recipe.bindings || {})) lines.push(`# binding: ${k} ← ${v}`);
+
+  return {
+    recipe: recipe.name,
+    order: ordered.map((r) => r.ref),
+    resources: ordered,
+    bindings: recipe.bindings || {},
+    manual,
+    ...(recipe.shared ? { sharedIdentity: recipe.shared } : {}),
+    preconditionLines: lines,
+    cleanup: typeof recipe.cleanup === 'string' ? recipe.cleanup : recipe.cleanup ? `keep — ${recipe.cleanup.reason}` : undefined,
+  };
+}
+
+/** Whether the project has a datasource (⇒ Layer 1 possible). */
+export function hasDatasource(cwd: string): boolean {
+  return existsSync(join(cwd, 'datasources.yaml')) || existsSync(join(cwd, 'qa', 'datasources.yaml'));
+}
+
+/** Guess a provenance from a precondition sentence — best-effort; QA confirms. */
+export function guessProvenance(signal: string): Provenance {
+  const s = signal.toLowerCase();
+  if (/session-storage|session storage|local ?storage|cookie|buffer/.test(s)) return 'client-storage';
+  if (/token|reset|verification|otp|invitation|seeded/.test(s)) return 'fixture';
+  if (/logged in|authenticated|signed in|auth token|session/.test(s)) return 'server-context';
+  if (/already|existing|registered|must exist|previously|prior/.test(s)) return 'prior-flow';
+  return 'manual';
+}
+
+/**
+ * Auto-scaffold a state-recipe SKELETON from a spec's precondition sentences (Layer-C auto-draft).
+ * Deterministic: one resource per detected signal, provenance guessed, entity left as a TODO for the
+ * AI/QA to fill (never fabricates a domain entity). Returns null when no precondition signal is found.
+ */
+export function scaffoldRecipe(unit: string, signals: string[]): StateRecipe | null {
+  if (!signals.length) return null;
+  const resources: StateResource[] = signals.slice(0, 4).map((sig, i) => ({
+    ref: `r${i + 1}`,
+    entity: 'TODO',                 // ← name the real entity (from the signal); do not invent domain values
+    provenance: guessProvenance(sig),
+    lifecycle: 'reusable',
+    note: sig,
+  }));
+  return {
+    name: `${unit}_precondition`,
+    description: `stateful precondition for ${unit} — AUTO-SCAFFOLDED from spec; REVIEW: name each entity, set desiredState/bindings, confirm with QA`,
+    resources,
+  };
+}
+
+/** Serialize a scaffolded recipe as a YAML block to splice under `recipes:` (2-space indented). */
+export function renderRecipeYaml(recipe: StateRecipe): string {
+  const lines: string[] = [`  ${recipe.name}:`];
+  if (recipe.description) lines.push(`    description: "${recipe.description}"`);
+  lines.push('    resources:');
+  for (const r of recipe.resources || []) {
+    lines.push(`      - ref: ${r.ref}`);
+    lines.push(`        entity: ${r.entity}        # ← name the real entity`);
+    lines.push(`        provenance: ${r.provenance}   # guessed — confirm (prior-flow|fixture|client-storage|server-context|manual|api|db)`);
+    if (r.lifecycle) lines.push(`        lifecycle: ${r.lifecycle}`);
+    if (r.note) lines.push(`        note: ${JSON.stringify(r.note)}`);
+  }
+  lines.push('    # bindings: { someId: "${r1.id}" }   # ← wire ids the test needs');
+  return lines.join('\n') + '\n';
+}
+
+/** Render the precondition block for weaving into a Gherkin Background (with the @manual tag if needed). */
+export function renderPreconditionBlock(plan: StatePlan): string {
+  const tag = plan.manual ? '# @manual:data-setup — required state (auto-provisions when an api/db datasource is added)' : '# required state (Layer 1: auto-provisioned via the referenced endpoints)';
+  return [`${tag}`, `# recipe: ${plan.recipe}`, ...plan.preconditionLines].join('\n');
+}

package/src/types.ts

@@ -18,6 +18,33 @@ export interface DataPoint {
   /** Pull values from a security bank (e.g. `security/sqli`) into this group. */
   from?: string;
   note?: string;
+  /**
+   * Optional explicit validity for this point (`valid` | `invalid`). Normally the generator's oracle
+   * computes it from the constraints; set this only to pin an intent the constraints can't express
+   * (e.g. a format-invalid value whose length happens to sit inside the range).
+   */
+  validity?: 'valid' | 'invalid';
+  /**
+   * Where this point ended up coming from after the `.overwrite` merge — `shipped` (company common) or
+   * `overwrite` (the project replaced/added it). Set by the loader; carried through to the generated
+   * value so a reader can answer "why is this value here?". Not authored by hand.
+   */
+  source?: 'shipped' | 'overwrite';
+  /**
+   * Applicability conditions (M2b). The point is materialized only when ALL conditions hold for the
+   * field + selection context. Field-derived keys are always enforced; environment keys only filter
+   * when the context supplies them (a missing context value = "no filter", so the point is kept):
+   *   - `required: true`  — applies only to a REQUIRED field (dropped when the field is explicitly optional).
+   *   - `negativesAllowed: true` — applies only when the numeric field allows negatives (min < 0 / no min).
+   *   - `locale: <prefix>` — applies only when ctx.locale starts with the prefix (e.g. `ja`).
+   *   - `channel: api|ui` / `sink: html|text|…` — applies only when ctx.channel/ctx.sink matches.
+   */
+  when?: Record<string, unknown>;
+  /**
+   * Bucket for output + profile selection. `adversarial` = a security/injection payload (kept out of
+   * the plain `invalid` bucket so a QA sees attack cases separately). Default (unset) = functional.
+   */
+  category?: 'adversarial';
 }
 
 export interface FieldType {
@@ -48,10 +75,40 @@ export interface Technique {
   [k: string]: unknown;
 }
 
+/**
+ * A domain-EXPERIENCE checklist — cases that come from real-world testing experience, not from a
+ * field's format (e.g. the credential/account states a login screen must cover: soft-deleted, locked,
+ * unverified…). Each case is a SCENARIO that usually needs a domain-state precondition, so it is
+ * knowledge for the login/auth viewpoint + a state-recipe — not a field-level value.
+ */
+export interface Experience {
+  experience: string;
+  description?: string;
+  applies_when?: string;
+  cases: Array<Record<string, unknown> & { id: string; expect?: string }>;
+  oracle?: string;
+}
+
 export interface Catalog {
   fieldTypes: Record<string, FieldType>;
   security: Record<string, SecurityBank>;
   techniques: Record<string, Technique>;
+  experience: Record<string, Experience>;
+}
+
+/** Named case-selection profiles (which groups/categories a run wants). */
+export type Profile = 'regression' | 'functional' | 'smoke' | 'security-min';
+
+/**
+ * The selection context Core (or a CLI flag) passes to the generator to pick applicable cases.
+ * All fields optional — an absent field means "no filter on that axis" (permissive default).
+ */
+export interface SelectionContext {
+  locale?: string;
+  channel?: 'api' | 'ui';
+  sink?: string;
+  /** `regression` (default) = every case; see Profile for the reduced sets. */
+  profile?: Profile;
 }
 
 /** A warning that a project's common.overwrite.yaml entry looks stale against the shipped common. */
@@ -60,3 +117,27 @@ export interface OverwriteWarning {
   detail: string;
   suggestion: string;
 }
+
+/** What the `.overwrite` layer changed for one field-type (provenance — "no silent overwrite"). */
+export interface FieldTypeProvenance {
+  type: string;
+  /** Ids removed via `disable:` (an id that was not in the shipped common is reported as a warning). */
+  disabled: string[];
+  /** Ids that existed in shipped AND the overlay — the overlay value won. */
+  replaced: string[];
+  /** Ids new from the overlay (a project-specific case). */
+  added: string[];
+  /** Constraint keys the overlay changed. */
+  constraintsOverridden: string[];
+  /** True when the overlay replaced `uses_security`. */
+  securityChanged: boolean;
+}
+
+/** Catalog-wide provenance of the shipped-common → project-overwrite merge. */
+export interface CatalogProvenance {
+  fieldTypes: Record<string, FieldTypeProvenance>;
+  /** Wholly new field-types added by the project (not in shipped common). */
+  newFieldTypes: string[];
+  security: { added: string[]; replaced: string[] };
+  techniques: { added: string[]; replaced: string[] };
+}

package/src/validate.ts

@@ -0,0 +1,77 @@
+/**
+ * Data Factory — the deterministic data-quality validator (the Driver's contribution to the harness).
+ *
+ * `lint.ts` answers "is the coverage enough?" (≥1 valid, boundary present, error codes mapped).
+ * This module answers the harder question both reviews flagged: "is each generated value SEMANTICALLY
+ * correct?" — i.e. does a value labeled `valid` actually satisfy the constraints, and does a value
+ * labeled `invalid` actually violate them? It is the machine oracle a future Master "Data Gate"
+ * (see docs/spec/data-factory-quality-roadmap.md) calls; today it powers the golden tests and the
+ * `sungen data validate` CLI. Pure + deterministic — no AI, no runtime.
+ */
+import type { Catalog, SelectionContext } from './types';
+import { expandFieldMap, type FieldMap, type FieldDef, type ExpandedField, type ExpandedPoint } from './generator';
+import { satisfiesConstraints } from './boundary';
+
+export interface ValidationFinding {
+  field: string;
+  pointId: string;
+  severity: 'error' | 'warn';
+  code: 'VALUE_NOT_VALID' | 'INVALID_LOOKS_VALID';
+  message: string;
+}
+
+/** Validate the values a set of expanded points, given the effective constraints for that field. */
+export function validatePoints(field: string, type: string | undefined, points: ExpandedPoint[], c: Record<string, any>): ValidationFinding[] {
+  const out: ValidationFinding[] = [];
+  if (!type) return out;
+  for (const p of points) {
+    if (p.value == null) continue; // open/todo — lint handles these
+    const oracle = satisfiesConstraints(type, p.value, c);
+    if (oracle == null) continue; // no length/range constraint to judge against
+    if (p.expectedValidity === 'valid' && oracle === false) {
+      out.push({
+        field, pointId: p.id, severity: 'error', code: 'VALUE_NOT_VALID',
+        message: `${p.id}: value ${JSON.stringify(p.value)} is expected VALID but violates the field constraints (${describe(type, c)})`,
+      });
+    } else if (p.expectedValidity === 'invalid' && oracle === true && p.synthesized) {
+      // Only second-guess a SYNTHESIZED (boundary/range) invalid: its whole claim is about range, so
+      // satisfying the range means the boundary was mis-synthesized. Literal charset/format invalids and
+      // security payloads legitimately pass the length oracle — not a finding.
+      out.push({
+        field, pointId: p.id, severity: 'warn', code: 'INVALID_LOOKS_VALID',
+        message: `${p.id}: value ${JSON.stringify(p.value)} is expected INVALID (out of range) but satisfies the constraints (${describe(type, c)}) — the boundary was mis-synthesized`,
+      });
+    }
+  }
+  return out;
+}
+
+function describe(type: string, c: Record<string, any>): string {
+  const parts: string[] = [];
+  if (Number.isFinite(c.minLength ?? c.length)) parts.push(`minLen=${c.minLength ?? c.length}`);
+  if (Number.isFinite(c.maxLength ?? c.length)) parts.push(`maxLen=${c.maxLength ?? c.length}`);
+  if (Number.isFinite(c.min)) parts.push(`min=${c.min}`);
+  if (Number.isFinite(c.max)) parts.push(`max=${c.max}`);
+  if (Number.isFinite(c.maxLocal)) parts.push(`maxLocal=${c.maxLocal}`);
+  if (Number.isFinite(c.maxTotal)) parts.push(`maxTotal=${c.maxTotal}`);
+  if (Number.isFinite(c.decimalPlaces)) parts.push(`decimalPlaces=${c.decimalPlaces}`);
+  return parts.join(', ') || type;
+}
+
+/** Validate a whole field-map: expand it, then check every value against its expected validity. */
+export function validateGenerated(map: FieldMap, catalog: Catalog, ctx: SelectionContext = {}): ValidationFinding[] {
+  const expanded = expandFieldMap(map, catalog, ctx);
+  const out: ValidationFinding[] = [];
+  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); continue; }
+      const ft = ef.type ? catalog.fieldTypes[ef.type] : undefined;
+      const c = { ...(ft?.constraints || {}), ...(def?.constraints || {}) };
+      out.push(...validatePoints(path, ef.type, ef.points, c));
+    }
+  };
+  walk(expanded, map.fields, '');
+  return out;
+}