@sungen/driver-data-factory 3.2.34-beta.1 → 3.3.0-alpha.1

package/package.json

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

package/src/boundary.ts

@@ -90,8 +90,9 @@ function readOffset(seg: string): { base: 'min' | 'max' | 'length' | null; off:
   let off = 0;
   if (/\+\s*1|plus one|one extra/.test(s)) off = 1;
   else if (/-\s*1|minus one/.test(s)) off = -1;
-  else if (/<|below|under|less than|shorter/.test(s)) off = -1;
-  else if (/>|over|above|exceed|greater than|longer|too long/.test(s)) off = 1;
+  // `<=` / `>=` include the bound itself (off 0), only a strict `<` / `>` steps past it (#904).
+  else if (/<(?!=)|below|under|less than|shorter/.test(s)) off = -1;
+  else if (/>(?!=)|over|above|exceed|greater than|longer|too long/.test(s)) off = 1;
   const sign = off > 0 ? '+1' : off < 0 ? '-1' : '';
   const label = (base || 'bound') + sign;
   return { base, off, label };
@@ -101,7 +102,23 @@ function readOffset(seg: string): { base: 'min' | 'max' | 'length' | null; off:
  * Expand a length-bounded string hint into one BoundaryPoint per segment.
  * min/max come from the constraints; a point OUTSIDE [min,max] is invalid, inside/on-edge is valid.
  */
-function expandLength(type: string, hint: string, c: Record<string, any>): BoundaryPoint[] {
+/** What a length judgement needs beyond the constraints: whether the field must be filled at all. */
+export interface FieldContext { required?: boolean }
+
+/**
+ * Is a length within the field's rules? Length 0 is "not provided", which `required` decides — not
+ * `minLength` (an HTML `minlength` is not enforced on an empty optional field). Only an explicit
+ * `required: false` accepts it: an unset `required` counts as required, the same rule the catalog's
+ * own empty case (`when: { required: true }`) is admitted by, so the two never disagree on "".
+ * Any other length is judged by [minLength, maxLength]. A hard `n >= 1` used to make "" invalid even
+ * for an optional field, so a Bio that may be cleared got an "expect an error" oracle (#901).
+ */
+function lengthValid(n: number, min: number | undefined, max: number | undefined, ctx: FieldContext): boolean {
+  if (n === 0) return ctx.required === false;
+  return (!Number.isFinite(min) || n >= (min as number)) && (!Number.isFinite(max) || n <= (max as number));
+}
+
+function expandLength(type: string, hint: string, c: Record<string, any>, ctx: FieldContext = {}): BoundaryPoint[] {
   const min = c.minLength ?? c.length ?? c.minlength;
   const max = c.maxLength ?? c.length ?? c.maxlength;
   const segs = segments(hint);
@@ -109,16 +126,23 @@ function expandLength(type: string, hint: string, c: Record<string, any>): Bound
   let idx = 0;
   for (const seg of segs) {
     const { base, off, label } = readOffset(seg);
+    // The suffix follows the SEGMENT, skipped or not, so `CHK-STR-I2a` is max+1 whether or not its
+    // min-1 sibling exists — a per-field `disable:` names points by these ids (#902).
+    const suffix = suffixOf(idx++);
     const anchor = base === 'max' ? max : base === 'length' ? (c.length ?? max ?? min) : min;
     if (!Number.isFinite(anchor)) {
-      out.push({ suffix: suffixOf(idx++), value: null, validity: base === null ? 'valid' : 'valid', label, todo: 'minLength/maxLength/length' });
+      out.push({ suffix, value: null, validity: 'valid', label, todo: 'minLength/maxLength/length' });
       continue;
     }
     const n = anchor + off;
-    const lo = Number.isFinite(min) ? min : 0;
-    const hi = Number.isFinite(max) ? max : Infinity;
-    const validity: Validity = n >= lo && n <= hi && n >= 1 ? 'valid' : 'invalid';
-    out.push({ suffix: suffixOf(idx++), value: fillString(type, Math.max(0, n)), validity, label });
+    // No such length: min-1 of `minLength: 0`. It used to be clamped to "", a second empty-string
+    // case with the opposite meaning (#901).
+    if (n < 0) continue;
+    const valid = lengthValid(n, min, max, ctx);
+    // A below-min point exists to be OUT of bounds. One that is not — an optional field's empty value
+    // under `minLength: 1` — is no boundary violation, so it is not emitted as one.
+    if (off < 0 && base !== 'max' && valid) continue;
+    out.push({ suffix, value: fillString(type, n), validity: valid ? 'valid' : 'invalid', label });
   }
   return out.length ? out : [{ suffix: '', value: null, validity: 'valid', label: 'bound', todo: 'minLength/maxLength' }];
 }
@@ -201,9 +225,9 @@ function suffixOf(i: number): string {
  * Public entry: expand a boundary/invalid hint into structured points.
  * Returns one point per segment; each carries the value AND the oracle's expected validity.
  */
-export function expandBoundaryHint(hint: string, type: string, c: Record<string, any>): BoundaryPoint[] {
+export function expandBoundaryHint(hint: string, type: string, c: Record<string, any>, ctx: FieldContext = {}): BoundaryPoint[] {
   if (type === 'email') return expandEmail(hint, c);
-  if (STR_TYPES.has(type)) return expandLength(type, hint, c);
+  if (STR_TYPES.has(type)) return expandLength(type, hint, c, ctx);
   if (NUM_TYPES.has(type)) return expandNumeric(type, hint, c);
   return [{ suffix: '', value: null, validity: 'valid', label: 'bound', todo: 'value/gen not resolvable' }];
 }
@@ -232,12 +256,8 @@ export function emailOfTotalLength(n: number): string | null {
   return 'a@' + 'b'.repeat(rest - 2) + '.c';     // e.g. n=5 → "a@b.c", n=6 → "a@bb.c"
 }
 
-function satisfiesLength(type: string, value: string, c: Record<string, any>): boolean {
-  const min = c.minLength ?? c.length;
-  const max = c.maxLength ?? c.length;
-  if (Number.isFinite(min) && value.length < min) return false;
-  if (Number.isFinite(max) && value.length > max) return false;
-  return true;
+function satisfiesLength(type: string, value: string, c: Record<string, any>, ctx: FieldContext = {}): boolean {
+  return lengthValid(value.length, c.minLength ?? c.length, c.maxLength ?? c.length, ctx);
 }
 
 function satisfiesNumeric(type: string, value: string, c: Record<string, any>): boolean {
@@ -258,12 +278,12 @@ function satisfiesNumeric(type: string, value: string, c: Record<string, any>):
  * them (length/range/precision — NOT charset/format, which the catalog encodes as literal invalids).
  * Returns null when the type has no numeric/length constraint to check against (nothing to assert).
  */
-export function satisfiesConstraints(type: string, value: string | null, c: Record<string, any>): boolean | null {
+export function satisfiesConstraints(type: string, value: string | null, c: Record<string, any>, ctx: FieldContext = {}): boolean | null {
   if (value == null) return null;
   if (type === 'email') return satisfiesEmail(value, c);
   if (STR_TYPES.has(type)) {
     if (!Number.isFinite(c.minLength ?? c.length) && !Number.isFinite(c.maxLength ?? c.length)) return null;
-    return satisfiesLength(type, value, c);
+    return satisfiesLength(type, value, c, ctx);
   }
   if (NUM_TYPES.has(type)) {
     if (!Number.isFinite(c.min) && !Number.isFinite(c.max) && !Number.isFinite(c.decimalPlaces)) return null;
@@ -284,12 +304,14 @@ export interface BvaExtra { label: string; value: string; validity: Validity; gr
  * MISSING points (dedup by exact value), so a type whose catalog already covers a dimension (string /
  * password / number) yields nothing — no churn.
  */
-export function ensureBvaComplete(type: string, c: Record<string, any>, existing: Array<string | null>): BvaExtra[] {
+export function ensureBvaComplete(type: string, c: Record<string, any>, existing: Array<string | null>, ctx: FieldContext = {}): BvaExtra[] {
   const have = new Set(existing.filter((v): v is string => v != null));
   const out: BvaExtra[] = [];
   const push = (label: string, value: string | null) => {
     if (value == null || have.has(value)) return;
-    const ok = satisfiesConstraints(type, value, c);
+    const ok = satisfiesConstraints(type, value, c, ctx);
+    // A below-min point that is in range (an optional field's empty value) is not a boundary case (#901).
+    if (label === 'minLen-1' && ok !== false) return;
     const validity: Validity = ok === false ? 'invalid' : 'valid';
     out.push({ label, value, validity, group: validity === 'invalid' ? 'invalid' : 'boundary' });
     have.add(value);
@@ -305,7 +327,7 @@ export function ensureBvaComplete(type: string, c: Record<string, any>, existing
   }
   if (STR_TYPES.has(type)) {
     const min = c.minLength ?? c.length, max = c.maxLength ?? c.length;
-    if (Number.isFinite(min)) { push('minLen-1', fillString(type, min - 1)); push('minLen', fillString(type, min)); push('minLen+1', fillString(type, min + 1)); }
+    if (Number.isFinite(min)) { if (min >= 1) push('minLen-1', fillString(type, min - 1)); push('minLen', fillString(type, min)); push('minLen+1', fillString(type, min + 1)); }
     if (Number.isFinite(max)) { push('maxLen-1', fillString(type, max - 1)); push('maxLen', fillString(type, max)); push('maxLen+1', fillString(type, max + 1)); }
     return out;
   }

package/src/catalog-loader.ts

@@ -22,24 +22,41 @@ export function commonDir(): string {
   return join(__dirname, '..', 'common');
 }
 
-function readYamlFilesDeep(dir: string): Array<{ file: string; data: any }> {
-  const out: Array<{ file: string; data: any }> = [];
+function readYamlFilesDeep(dir: string): Array<{ file: string; data: any; text: string }> {
+  const out: Array<{ file: string; data: any; text: string }> = [];
   if (!existsSync(dir)) return out;
   for (const name of readdirSync(dir)) {
     const full = join(dir, name);
     if (statSync(full).isDirectory()) out.push(...readYamlFilesDeep(full));
     else if (name.endsWith('.yaml') || name.endsWith('.yml')) {
-      out.push({ file: full, data: parseYaml(readFileSync(full, 'utf8')) });
+      const text = readFileSync(full, 'utf8');
+      out.push({ file: full, data: parseYaml(text), text });
     }
   }
   return out;
 }
 
+/** The keys of the top-level `constraints:` block whose line carries a `# placeholder` comment. */
+export function placeholderKeys(text: string): string[] {
+  const keys: string[] = [];
+  let inBlock = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^constraints:\s*(#.*)?$/.test(line)) { inBlock = true; continue; }
+    if (!inBlock || !line.trim() || /^\s*#/.test(line)) continue;
+    if (!/^\s/.test(line)) break; // the next top-level key ends the block
+    const m = line.match(/^\s+([A-Za-z_][\w-]*)\s*:.*#\s*placeholder\b/i);
+    if (m) keys.push(m[1]);
+  }
+  return keys;
+}
+
 /** Load the shipped common catalog (no project overlay). */
 export function loadShippedCatalog(root = commonDir()): Catalog {
   const fieldTypes: Record<string, FieldType> = {};
-  for (const { data } of readYamlFilesDeep(join(root, 'field-types'))) {
-    if (data?.type) fieldTypes[data.type] = data as FieldType;
+  for (const { data, text } of readYamlFilesDeep(join(root, 'field-types'))) {
+    if (!data?.type) continue;
+    const placeholders = placeholderKeys(text);
+    fieldTypes[data.type] = { ...data, ...(placeholders.length ? { placeholderConstraints: placeholders } : {}) } as FieldType;
   }
   const security: Record<string, SecurityBank> = {};
   for (const { data } of readYamlFilesDeep(join(root, 'security'))) {
@@ -97,6 +114,8 @@ function mergeFieldType(base: FieldType, overlay: FieldTypeOverlay, prov: FieldT
     ...base,
     ...rest,
     constraints: { ...(base.constraints || {}), ...(overlay.constraints || {}) },
+    // A constraint the project's overwrite sets is a real value, no longer the shipped placeholder.
+    placeholderConstraints: (base.placeholderConstraints || []).filter((k) => !(k in (overlay.constraints || {}))),
     uses_security: overlay.uses_security ?? base.uses_security,
     valid: mergeGroup(base.valid, overlay.valid, disableSet, prov),
     boundary: mergeGroup(base.boundary, overlay.boundary, disableSet, prov),

package/src/generator.ts

@@ -18,6 +18,12 @@ export interface FieldDef {
   /** 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;
+  /**
+   * Point ids to drop for THIS field only (#902) — an expanded id such as `CHK-STR-I2` (min-1) or
+   * `CHK-STR-I2a` (max+1). The overwrite's `disable:` removes a case for every field of the type;
+   * this removes one boundary for one field. Dropped points are reported in `excluded`, never silent.
+   */
+  disable?: string[];
   /** 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. */
@@ -89,6 +95,10 @@ export interface ExpandedField {
   dependsOn?: { field: string; value?: string };
   /** Cases NOT materialized for the selection context (applicability) — surfaced, never silent. */
   excluded?: Array<{ id: string; reason: string }>;
+  /** Catalog placeholder constraints this field relies on (it set no value of its own) — e.g. `minLength`. */
+  placeholders?: string[];
+  /** `disable:` ids that matched no point generated for this field (a typo, or a case not emitted here). */
+  disableUnmatched?: string[];
 }
 
 /**
@@ -112,9 +122,15 @@ function coerceValidNumeric(type: string, value: string, c: Record<string, any>)
   return String(Math.round(out));
 }
 
-/** A gen hint that references a numeric/length boundary the generator can expand structurally. */
+/**
+ * A gen hint that references a numeric/length boundary the generator can expand structurally.
+ * `<` / `>` count only as a comparison against a named bound (`< min length`, `local > maxLocal`):
+ * a bare one is a character in a charset list (`special chars …<>?`, `forbidden chars …<>\?`), and
+ * matching it turned those cases into meaningless `bound-1 / bound` lengths (#904). A bare number
+ * (`> 20 chars`) is not read either — the expansion has no way to use it — so it stays an open case.
+ */
 function isBoundaryHint(hint: string): boolean {
-  return /\bmin\b|\bmax\b|minimum|maximum|length|byte|exact|decimal|precision|local|total|over|below|under|exceed|\+\s*1|-\s*1|<|>/.test(
+  return /\bmin\b|\bmax\b|minimum|maximum|length|byte|exact|decimal|precision|local|total|over|below|under|exceed|\+\s*1|-\s*1|[<>]=?\s*(?:min|max|length|local|total)/.test(
     hint.toLowerCase(),
   );
 }
@@ -160,6 +176,8 @@ export function expandField(field: FieldDef, catalog: Catalog, ctx: SelectionCon
   const points: ExpandedPoint[] = [];
   const excluded: Array<{ id: string; reason: string }> = [];
   const facts = fieldFacts(field, c);
+  // Length 0 is judged by `required`, not by minLength (#901) — every oracle call gets the field context.
+  const fctx = { required: field.required };
 
   // Gate a catalog case by applicability (`when`) then by the selection profile. A `when` miss is
   // reported as excluded (not silently dropped); a profile miss is an explicit selection (not reported).
@@ -178,7 +196,7 @@ export function expandField(field: FieldDef, catalog: Catalog, ctx: SelectionCon
   const pushLiteral = (dp: DataPoint, group: ExpandedPoint['group'], value: string | null, opts: { validity?: Validity; label?: string; todo?: string } = {}) => {
     // A valid representative must be valid for the project: clamp an out-of-range numeric literal.
     let coerceNote: string | undefined;
-    if (group === 'valid' && value != null && satisfiesConstraints(type, value, c) === false) {
+    if (group === 'valid' && value != null && satisfiesConstraints(type, value, c, fctx) === false) {
       const fixed = coerceValidNumeric(type, value, c);
       if (fixed != null) { value = fixed; coerceNote = 'adjusted to fit constraints'; }
     }
@@ -193,7 +211,7 @@ export function expandField(field: FieldDef, catalog: Catalog, ctx: SelectionCon
     let validity: Validity;
     if (dp.validity) validity = dp.validity;
     else if (group === 'boundary') {
-      const oracle = satisfiesConstraints(type, isUniqueValid ? value : v, c);
+      const oracle = satisfiesConstraints(type, isUniqueValid ? value : v, c, fctx);
       validity = oracle == null ? (opts.validity ?? 'valid') : oracle ? 'valid' : 'invalid';
     } else validity = opts.validity ?? groupValidity(group);
     emit({
@@ -217,7 +235,7 @@ export function expandField(field: FieldDef, catalog: Catalog, ctx: SelectionCon
     const hint = `${dp.gen || ''} ${dp.note || ''}`.trim();
     // A boundary/length/numeric hint → expand to one case PER boundary point, each with its validity.
     if (hint && isBoundaryHint(hint)) {
-      const pts = expandBoundaryHint(hint, type, c);
+      const pts = expandBoundaryHint(hint, type, c, fctx);
       for (const bp of pts) {
         emit({
           id: dp.id + bp.suffix,
@@ -270,7 +288,7 @@ export function expandField(field: FieldDef, catalog: Catalog, ctx: SelectionCon
   // email `minLength` the catalog didn't model). Only in-range points are `boundary`; out-of-range are
   // `invalid`. Appended after the catalog cases so it never overrides an authored one.
   const idCode = type.toUpperCase().replace(/[^A-Z0-9]/g, '');
-  for (const ex of ensureBvaComplete(type, c, points.map((p) => p.value))) {
+  for (const ex of ensureBvaComplete(type, c, points.map((p) => p.value), fctx)) {
     points.push({
       id: `CHK-${idCode}-BVA-${ex.label}`,
       group: ex.group,
@@ -282,13 +300,22 @@ export function expandField(field: FieldDef, catalog: Catalog, ctx: SelectionCon
     });
   }
 
+  // Field-level disable (#902): drop exactly the named points, and say so.
+  const disabled = new Set(field.disable || []);
+  const kept = disabled.size ? points.filter((p) => !disabled.has(p.id)) : points;
+  for (const p of points) if (disabled.has(p.id)) excluded.push({ id: p.id, reason: 'disabled for this field' });
+  const disableUnmatched = [...disabled].filter((id) => !points.some((p) => p.id === id));
+
+  const placeholders = (ft.placeholderConstraints || []).filter((k) => !(field.constraints && k in field.constraints));
   return {
     name: field.name,
     type: field.type,
     blindSpot: false,
-    points,
+    points: kept,
     ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}),
     ...(excluded.length ? { excluded } : {}),
+    ...(placeholders.length ? { placeholders } : {}),
+    ...(disableUnmatched.length ? { disableUnmatched } : {}),
   };
 }
 

package/src/lint.ts

@@ -85,6 +85,18 @@ export function lintFieldMap(map: FieldMap, catalog: Catalog, ctx: SelectionCont
         message: `${live.join(', ')} is a real mailbox provider — a registration or reset test using it sends mail to whoever owns that address. Use the project domain (@sun-asterisk.com) or the reserved @example.com.` });
     }
 
+    // A generic catalog stand-in (string minLength 1, phone 8..15 …) silently became this field's rule.
+    if (f.placeholders?.length) {
+      const vals = f.placeholders.map((k) => `${k}: ${JSON.stringify(f.type ? catalog.fieldTypes[f.type]?.constraints?.[k] : undefined)}`);
+      issues.push({ field: path, severity: 'warn', code: 'PLACEHOLDER_CONSTRAINT',
+        message: `uses the catalog's placeholder ${vals.join(', ')} — set the real value from the spec in the field-map's constraints (the boundary cases are built from it)` });
+    }
+
+    if (f.disableUnmatched?.length) {
+      issues.push({ field: path, severity: 'warn', code: 'DISABLE_UNMATCHED',
+        message: `disable: ${f.disableUnmatched.join(', ')} matches no case generated for this field — check the id (a boundary point carries its suffix, e.g. CHK-STR-I2a)` });
+    }
+
     // Applicability (M2b): cases NOT materialized for this field/context — surfaced, never silent.
     if (f.excluded?.length) {
       issues.push({ field: path, severity: 'info', code: 'NOT_APPLICABLE',

package/src/types.ts

@@ -52,6 +52,12 @@ export interface FieldType {
   description?: string;
   format?: string;
   constraints?: Record<string, unknown>;
+  /**
+   * Constraint keys the shipped catalog marks `# placeholder` (a generic stand-in such as string
+   * `minLength: 1`). Read from the yaml text by the loader — the parsed yaml has no comments. A field
+   * that relies on one without its own value is warned about (lint PLACEHOLDER_CONSTRAINT).
+   */
+  placeholderConstraints?: string[];
   /** Security banks whose payloads are appended to the `invalid` group. */
   uses_security?: string[];
   valid?: DataPoint[];

package/src/validate.ts

@@ -10,7 +10,7 @@
  */
 import type { Catalog, SelectionContext } from './types';
 import { expandFieldMap, type FieldMap, type FieldDef, type ExpandedField, type ExpandedPoint } from './generator';
-import { satisfiesConstraints } from './boundary';
+import { satisfiesConstraints, type FieldContext } from './boundary';
 
 export interface ValidationFinding {
   field: string;
@@ -21,12 +21,12 @@ export interface ValidationFinding {
 }
 
 /** 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[] {
+export function validatePoints(field: string, type: string | undefined, points: ExpandedPoint[], c: Record<string, any>, ctx: FieldContext = {}): 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);
+    const oracle = satisfiesConstraints(type, p.value, c, ctx);
     if (oracle == null) continue; // no length/range constraint to judge against
     if (p.expectedValidity === 'valid' && oracle === false) {
       out.push({
@@ -69,7 +69,7 @@ export function validateGenerated(map: FieldMap, catalog: Catalog, ctx: Selectio
       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));
+      out.push(...validatePoints(path, ef.type, ef.points, c, { required: def?.required }));
     }
   };
   walk(expanded, map.fields, '');