@sungen/driver-data-factory 3.2.12-beta.7 → 3.2.12-beta.9

package/package.json

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

package/src/cli.ts

@@ -13,8 +13,9 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { loadEffectiveCatalog, describeProvenance } from './catalog-loader';
 import { expandFieldMap, renderTestData, type FieldMap } from './generator';
 import { buildRequest, fingerprint } from './contract';
-import { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, hasDatasource } from './state';
+import { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, hasDatasource, scaffoldRecipe, renderRecipeYaml } from './state';
 import { crosscheckUnit, crosscheckShared } from './crosscheck';
+import { detectPreconditionSignals } from './detect';
 import { lintFieldMap, summarize } from './lint';
 import { validateGenerated } from './validate';
 import { generateFixture } from './fixture';
@@ -259,9 +260,34 @@ export function registerDataFactoryCommand(program: any): void {
     .command('state')
     .description('Domain/stateful data (M3-A Layer 0): validate the state-recipes in recipes.yaml and render each as a standardized manual precondition block (+ a resolved .state.yaml plan)')
     .option('--recipe <name>', 'Only this recipe (default: all recipes with a `resources`/`shared` graph)')
-    .action((opts: { recipe?: string }) => {
+    .option('--scaffold <unit>', 'Auto-draft a state-recipe SKELETON from the unit\'s spec.md precondition signals (Layer-C auto-draft), then review/fill it')
+    .option('--force', 'With --scaffold: overwrite an existing recipe of the same name')
+    .action((opts: { recipe?: string; scaffold?: string; force?: boolean }) => {
       const cwd = process.cwd();
       ensureDataFactoryReadme(cwd);
+
+      // --scaffold: auto-draft a recipe skeleton from the unit's spec precondition signals.
+      if (opts.scaffold) {
+        const unit = opts.scaffold;
+        const specPath = ['screens', 'flows'].map((k) => join(cwd, 'qa', k, unit, 'requirements', 'spec.md')).find(existsSync);
+        const specText = specPath ? readFileSync(specPath, 'utf8') : '';
+        const signals = detectPreconditionSignals(specText);
+        const recipe = scaffoldRecipe(unit, signals);
+        if (!recipe) { console.log(`No stateful-precondition signals found in ${unit}'s spec — nothing to scaffold (a screen may simply have no precondition).`); return; }
+        const recipesPath = join(FIELDMAP_DIR(cwd), 'recipes.yaml');
+        const doc: any = existsSync(recipesPath) ? (parseYaml(readFileSync(recipesPath, 'utf8')) || {}) : {};
+        doc.recipes = doc.recipes || {};
+        if (doc.recipes[recipe.name] && !opts.force) { console.error(`✗ recipe "${recipe.name}" already exists — edit it, or pass --force to overwrite the scaffold.`); process.exitCode = 1; return; }
+        // Splice the human-friendly (commented) block rather than a bare re-serialize, to preserve TODO hints.
+        const header = existsSync(recipesPath) ? readFileSync(recipesPath, 'utf8').replace(/\s*$/, '') + '\n' : 'recipes:\n';
+        const block = renderRecipeYaml(recipe);
+        writeFileSync(recipesPath, (header.includes('recipes:') ? header : 'recipes:\n' + header) + block, 'utf8');
+        console.log(`  ✓ scaffolded recipe "${recipe.name}" → ${recipesPath.replace(cwd + '/', '')} (${signals.length} signal(s))`);
+        console.log(`  → REVIEW: name each entity, set desiredState/bindings, confirm domain values with QA, then \`sungen data state --recipe ${recipe.name}\`.`);
+        for (const s of signals) console.log(`    · signal: ${s}`);
+        return;
+      }
+
       let recipes = loadStateRecipes(cwd);
       if (opts.recipe) recipes = recipes.filter((r) => r.name === opts.recipe);
       if (recipes.length === 0) { console.error('No state-recipes (recipes with a `resources` or `shared` graph) in qa/data-factory/recipes.yaml.'); process.exitCode = 1; return; }

package/src/detect.ts

@@ -0,0 +1,122 @@
+/**
+ * Data Factory — auto-detection (Layer A of the auto-orchestration design).
+ *
+ * Makes Sungen NOTICE what test-data work a unit needs, without QA having to know to run a command:
+ *   - a unit that HAS input fields but has NO field-map → its data was never standardized;
+ *   - a spec that describes a STATEFUL PRECONDITION (a required entity/state) with no state-recipe and
+ *     no Background/@manual precondition → the stateful setup is undeclared.
+ * Both are surfaced as advisory findings at `sungen generate`/`sungen audit` (the DF advisory sensor).
+ * Deterministic heuristics over spec.md + the feature; no runtime, no LLM. Advisory only — a nudge +
+ * an auto-draft prompt, never a hard fail (the fuzzy precondition scan must not block).
+ */
+import { join } from 'path';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { loadStateRecipes } from './state';
+
+export interface DetectFinding {
+  code: 'UNSTANDARDIZED' | 'PRECONDITION_UNDECLARED';
+  scenario: string;
+  message: string;
+  severity: 'warn' | 'info';
+}
+
+function readIfExists(path: string): string {
+  try { return existsSync(path) ? readFileSync(path, 'utf8') : ''; } catch { return ''; }
+}
+
+function readSpec(dir: string): string {
+  return readIfExists(join(dir, 'requirements', 'spec.md'));
+}
+
+function readFeature(dir: string): string {
+  const fdir = join(dir, 'features');
+  if (!existsSync(fdir)) return '';
+  try {
+    return readdirSync(fdir).filter((f) => f.endsWith('.feature')).map((f) => readIfExists(join(fdir, f))).join('\n');
+  } catch { return ''; }
+}
+
+/**
+ * Does the unit take user input? Strongest signal: a Gherkin `fill [X] field` / `type` step; plus a
+ * spec field table row typed as input/select/textarea. A pure navigation / list / capture screen has
+ * none → we must NOT nag it ("no input fields → nothing to generate").
+ */
+export function hasInputFields(specText: string, featureText: string): boolean {
+  if (/\b(fill|type|enter|input|select|choose)\b\s+\[[^\]]+\]\s*(field|input|dropdown|textbox)?/i.test(featureText)) return true;
+  if (/\|\s*(input|select|textarea|checkbox|radio|combobox)\b/i.test(specText)) return true;
+  if (/\binput\s*\(|\bselect\s*\(|\btextarea\b/i.test(specText)) return true;
+  return false;
+}
+
+/** A field-map exists for this unit. */
+export function hasFieldMap(cwd: string, name: string): boolean {
+  return existsSync(join(cwd, 'qa', 'data-factory', `${name}.fields.yaml`));
+}
+
+/** Precondition signal phrases — a spec sentence hinting the test needs a pre-existing entity/state. */
+const PRECONDITION_SIGNALS = [
+  'requires', 'required before', 'precondition', 'pre-condition', 'prerequisite',
+  'logged in', 'authenticated', 'signed in', 'must be logged',
+  'already exists', 'already registered', 'existing ', 'pre-existing', 'must exist',
+  'reset token', 'verification', 'provisional account', 'session-storage', 'session storage',
+  'buffer', 'seeded', 'must have', 'previously', 'valid token', 'auth token',
+];
+
+/** Extract spec sentences that look like a stateful precondition (deduped, capped). */
+export function detectPreconditionSignals(specText: string): string[] {
+  if (!specText) return [];
+  const hits: string[] = [];
+  const seen = new Set<string>();
+  // Split into sentence-ish units (lines / bullet items / sentences).
+  const units = specText.split(/\n|(?<=[.。])\s+/).map((s) => s.replace(/\s+/g, ' ').trim()).filter(Boolean);
+  for (const u of units) {
+    const low = u.toLowerCase();
+    // Skip markdown headings/table separators, and spec-template meta lines (US labels, rationale)
+    // that mention auth/priority only descriptively — not an actual precondition.
+    if (/^#{1,6}\s|^\|?\s*-{3,}/.test(u)) continue;
+    if (/^\*\*(why|independent test|acceptance|business context|target users|priority)\b/i.test(u)) continue;
+    if (/\bpriority\b/i.test(low) && /\bp[0-9]\b/i.test(low)) continue;
+    const sig = PRECONDITION_SIGNALS.find((s) => low.includes(s));
+    if (sig) {
+      const key = low.slice(0, 60);
+      if (!seen.has(key)) { seen.add(key); hits.push(u.length > 160 ? u.slice(0, 157) + '…' : u); }
+    }
+    if (hits.length >= 4) break;
+  }
+  return hits;
+}
+
+/** Is a stateful precondition already declared — a state-recipe with resources, or a Background/@manual? */
+export function hasStateDeclaration(cwd: string, featureText: string): boolean {
+  if (/^\s*Background:/m.test(featureText) || /@manual\b/.test(featureText)) return true;
+  return loadStateRecipes(cwd).some((r) => (r.resources && r.resources.length) || r.shared);
+}
+
+/** Run Layer-A detection for one unit dir. Returns advisory findings (possibly empty). */
+export function detectUnit(cwd: string, dir: string, name: string): DetectFinding[] {
+  const spec = readSpec(dir);
+  const feature = readFeature(dir);
+  const out: DetectFinding[] = [];
+
+  // 1. Inputs exist but never standardized.
+  if (!hasFieldMap(cwd, name) && hasInputFields(spec, feature)) {
+    out.push({
+      code: 'UNSTANDARDIZED',
+      scenario: name,
+      severity: 'warn',
+      message: `DATA-FACTORY-UNSTANDARDIZED: ${name} has input fields but no standardized test-data (no qa/data-factory/${name}.fields.yaml) — run \`/sungen:create-data-test ${name}\` (or it is authored inline by \`/sungen:create-test\`) so values are standardized valid/boundary/invalid, not hand-invented.`,
+    });
+  }
+
+  // 2. Stateful precondition described in the spec but not declared anywhere.
+  const signals = detectPreconditionSignals(spec);
+  if (signals.length && !hasStateDeclaration(cwd, feature)) {
+    out.push({
+      code: 'PRECONDITION_UNDECLARED',
+      scenario: name,
+      severity: 'info',
+      message: `DATA-FACTORY-PRECONDITION-UNDECLARED: ${name}'s spec describes a stateful precondition but the test declares none (no state-recipe, no Background/@manual). Declare it with a state-recipe + \`sungen data state\` so it renders a @manual:data-setup Background. Signals: ${signals.map((s) => `"${s}"`).join('; ')}`,
+    });
+  }
+  return out;
+}

package/src/index.ts

@@ -30,10 +30,12 @@ export type { Validity, BoundaryPoint } from './boundary';
 export { evaluateWhen, inProfile, fieldFacts } from './applicability';
 export { generate, buildRequest, validateRequest, fingerprint, GENERATOR_VERSION, SCHEMA_VERSION } from './contract';
 export type { DataFactoryRequest, DataFactoryResult } from './contract';
-export { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, topoSort, hasDatasource } from './state';
+export { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, topoSort, hasDatasource, scaffoldRecipe, renderRecipeYaml, guessProvenance } from './state';
 export type { StateRecipe, StateResource, StatePlan, StateFinding, Provenance, Lifecycle } from './state';
 export { crosscheckUnit, crosscheckShared, crosscheckAll, referencedVars } from './crosscheck';
 export type { CrossFinding } from './crosscheck';
+export { detectUnit, hasInputFields, hasFieldMap, detectPreconditionSignals, hasStateDeclaration } from './detect';
+export type { DetectFinding } from './detect';
 export { registerDataFactoryCommand } from './cli';
 export { generateFixture } from './fixture';
 export type { FixtureResult, FixtureExpected, ExpectedRow } from './fixture';

package/src/sensor.ts

@@ -5,7 +5,10 @@
  * 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).
+ *
+ * Auto-detection (Layer A): even with NO field-map, it NOTICES what's missing — a unit with input
+ * fields but no standardized data, or a spec that describes a stateful precondition the test never
+ * declares — so Sungen nudges QA instead of staying silent (was: "no field-map → nothing to say").
  *
  * 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
@@ -18,6 +21,7 @@ import type { Sensor } from '@sun-asterisk/sungen';
 import { loadEffectiveCatalog } from './catalog-loader';
 import { lintFieldMap, summarize } from './lint';
 import { validateGenerated } from './validate';
+import { detectUnit } from './detect';
 import type { FieldMap } from './generator';
 
 export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
@@ -26,11 +30,21 @@ export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
   kind: 'advisory',
   run: ({ dir, cwd }) => {
     const name = basename(dir);
+    // Layer A auto-detection — runs regardless of whether a field-map exists, so a unit that needs
+    // standardization or a declared precondition is NOTICED, not silently skipped.
+    const detected = detectUnit(cwd, dir, name).map((d) => ({
+      sensorId: 'data-factory-coverage',
+      capability: 'data-factory',
+      scenario: d.scenario,
+      message: d.message,
+      severity: d.severity,
+    }));
+
     const fieldMapPath = join(cwd, 'qa', 'data-factory', `${name}.fields.yaml`);
-    if (!existsSync(fieldMapPath)) return []; // opt-in per unit — no field-map, nothing to say
+    if (!existsSync(fieldMapPath)) return detected; // no field-map: report only what detection noticed
     let map: FieldMap;
-    try { map = parseYaml(readFileSync(fieldMapPath, 'utf8')) as FieldMap; } catch { return []; }
-    if (!map || !Array.isArray(map.fields)) return [];
+    try { map = parseYaml(readFileSync(fieldMapPath, 'utf8')) as FieldMap; } catch { return detected; }
+    if (!map || !Array.isArray(map.fields)) return detected;
 
     const { catalog, warnings } = loadEffectiveCatalog(cwd);
     const { issues } = lintFieldMap(map, catalog);
@@ -71,6 +85,8 @@ export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
         severity: s.errors ? 'warn' : 'info',
       });
     }
+    // Detection findings (e.g. an undeclared stateful precondition) are still relevant with a field-map.
+    findings.push(...detected);
     return findings;
   },
 };

package/src/state.ts

@@ -171,6 +171,53 @@ 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)';