@ultimat3/schema 30.5.0 → 30.7.0

package/CLAUDE.md

@@ -64,7 +64,11 @@ overlay already holds the raw body. `describe-value.test.ts` is the enforcement.
 
 `t.array(items, { min, max })` (`array-schema.ts`) carries its bounds as `minItems`/`maxItems` ON
 the node — JSON Schema's names — and `json-schema.ts` and `wire-schema.ts` publish both;
-`sample.ts`'s walker samples `minItems` items. A bound no count meets is
+`sample.ts`'s walker samples `minItems` items.
+A `pattern` is sampled by walking it (`sample-pattern.ts`, `patternSamples`): the ONE regex
+generator, also what `@ultimat3/testing` seeds `matches()` columns with. Past its subset
+(lookaround, backreference, `\b`, `\p{…}`) it yields nothing and `sampleGaps` names the field.
+`sample-random.ts` (mulberry32) is the leaf both it and `sample-seeded.ts` draw from. A bound no count meets is
 `X_SCHEMA_BOUNDS_INVALID` where it is declared, the same rule as the discriminant below.
 
 `X_SCHEMA_DISCRIMINANT_INVALID` is thrown where a `discriminatedUnion` is BUILT, not where a value

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/schema",
-  "version": "30.5.0",
+  "version": "30.7.0",
   "description": "Ultimate's validation seam: Standard Schema interface, the t namespace, JSON Schema output",
   "keywords": [
     "ultimate",

package/src/sample-draw.ts

@@ -4,7 +4,9 @@
  * share every rule about what a node accepts; only the choices differ.
  */
 
+import { charCount } from './char-count';
 import type { SchemaFormat, SchemaNode } from './node';
+import { patternSamples } from './sample-pattern';
 
 /** Every choice a walk makes that its node leaves open. Answers stay inside the node's own bounds. */
 export interface Draw {
@@ -74,12 +76,47 @@ export function owedItems(node: SchemaNode): number | undefined {
 }
 
 /** `'sample'`, padded to `minLength` and cut to `maxLength`. */
-export function minimalString(node: SchemaNode): string {
+function paddedSample(node: SchemaNode): string {
   const min = node.minLength ?? 0;
   const padded = SAMPLE_STRING.length >= min ? SAMPLE_STRING : SAMPLE_STRING.padEnd(min, 'x');
   return node.maxLength === undefined ? padded : padded.slice(0, node.maxLength);
 }
 
+/** The seed the minimal draw walks a pattern with: fixed, so the minimal sample never varies. */
+const MINIMAL_PATTERN_SEED = 1;
+
+/** How many candidates a pattern draw offers before the length bounds pick among them. */
+const PATTERN_CANDIDATES = 8;
+
+/**
+ * A string the node's `pattern` accepts, built from the pattern itself (`sample-pattern.ts`) and
+ * inside `minLength`/`maxLength`; `undefined` when the pattern is past the generator's subset,
+ * uncompilable, or meets no length bound — which `sampleGaps` then reports, never a guess.
+ */
+export function patternString(node: SchemaNode, seed: number): string | undefined {
+  if (node.pattern === undefined) return undefined;
+  let pattern: RegExp;
+  try {
+    pattern = new RegExp(node.pattern, node.patternFlags ?? '');
+  } catch {
+    return undefined;
+  }
+  const fits = (value: string): boolean =>
+    charCount(value) >= (node.minLength ?? 0) &&
+    (node.maxLength === undefined || charCount(value) <= node.maxLength);
+  return patternSamples(pattern, seed, PATTERN_CANDIDATES).find(fits);
+}
+
+/**
+ * `'sample'`, padded to `minLength` and cut to `maxLength` — or, when the node's `pattern` refuses
+ * that, the first value the pattern itself yields. A pattern `'sample'` meets keeps `'sample'`.
+ */
+export function minimalString(node: SchemaNode): string {
+  const padded = paddedSample(node);
+  if (satisfiesPattern(node, padded)) return padded;
+  return patternString(node, MINIMAL_PATTERN_SEED) ?? padded;
+}
+
 /** The lower bound, rounded inward for an integer, or the upper one when the lower overshoots. */
 export function minimalNumber(node: SchemaNode): number {
   const low = node.minimum ?? 0;

package/src/sample-pattern.ts

@@ -0,0 +1,216 @@
+// Strings a `pattern` accepts, built by walking the pattern rather than guessing shapes — the ONE
+// generator, read by the input walker (`sample-draw.ts`, `sample-seeded.ts`) and by
+// `@ultimat3/testing`'s seed values. The common subset only — literals, classes, `.`, groups,
+// alternation, quantifiers, anchors — and an honest `[]` past it (lookaround, `\b`, `\p{…}`).
+
+import { mulberry32 } from './sample-random';
+
+type Node =
+  | { readonly kind: 'chars'; readonly chars: readonly string[] }
+  | { readonly kind: 'alt'; readonly branches: readonly (readonly Piece[])[] }
+  | { readonly kind: 'empty' };
+
+interface Piece {
+  readonly node: Node;
+  readonly min: number;
+  readonly max: number;
+}
+
+/** How far past its floor an unbounded quantifier draws: enough to vary, short enough to store. */
+const UNBOUNDED_SPAN = 6;
+
+/** The universe a class or `.` picks from: printable ASCII, so every sample is plain text. */
+const PRINTABLE = Array.from({ length: 95 }, (_, i) => String.fromCharCode(32 + i));
+const DIGITS = PRINTABLE.filter((c) => c >= '0' && c <= '9');
+const WORD = PRINTABLE.filter((c) => /\w/.test(c));
+const SPACE = [' ', '\t'];
+
+const SHORTHAND: Readonly<Record<string, readonly string[]>> = {
+  d: DIGITS,
+  D: PRINTABLE.filter((c) => !DIGITS.includes(c)),
+  w: WORD,
+  W: PRINTABLE.filter((c) => !WORD.includes(c)),
+  s: SPACE,
+  S: PRINTABLE.filter((c) => c !== ' '),
+};
+
+const CONTROL: Readonly<Record<string, string>> = { t: '\t', n: '\n', r: '\r', f: '\f', v: '\v' };
+
+class Parser {
+  private at = 0;
+  /** The first construct past the subset; set once, and it ends the walk. */
+  private refused: string | undefined;
+  constructor(private readonly source: string) {}
+
+  /** The tree, or `undefined` when any part of the pattern is past the subset. */
+  parse(): Node | undefined {
+    const node = this.alternation();
+    if (this.refused === undefined && this.at < this.source.length) this.refuse('a stray ")"');
+    return this.refused === undefined ? node : undefined;
+  }
+
+  /** Records the refusal and moves to the end, so every loop above stops on its next look. */
+  private refuse(construct: string): readonly string[] {
+    this.refused ??= construct;
+    this.at = this.source.length;
+    return [];
+  }
+
+  private peek(): string | undefined {
+    return this.source[this.at];
+  }
+
+  private alternation(): Node {
+    const branches: Piece[][] = [this.sequence()];
+    while (this.peek() === '|') {
+      this.at += 1;
+      branches.push(this.sequence());
+    }
+    return { kind: 'alt', branches };
+  }
+
+  private sequence(): Piece[] {
+    const pieces: Piece[] = [];
+    for (let c = this.peek(); c !== undefined && c !== '|' && c !== ')'; c = this.peek()) {
+      const node = this.atom();
+      const [min, max] = this.quantifier();
+      pieces.push({ node, min, max });
+    }
+    return pieces;
+  }
+
+  private quantifier(): readonly [number, number] {
+    const c = this.peek();
+    const bounds = /^\{(\d+)(,(\d*))?\}/.exec(this.source.slice(this.at));
+    let range: readonly [number, number] | undefined;
+    if (c === '*') range = [0, UNBOUNDED_SPAN];
+    else if (c === '+') range = [1, 1 + UNBOUNDED_SPAN];
+    else if (c === '?') range = [0, 1];
+    else if (bounds !== null) {
+      const low = Number(bounds[1]);
+      const high =
+        bounds[2] === undefined ? low : bounds[3] === '' ? low + UNBOUNDED_SPAN : Number(bounds[3]);
+      range = [low, high];
+    }
+    if (range === undefined) return [1, 1];
+    this.at += bounds !== null && c === '{' ? bounds[0].length : 1;
+    // A lazy quantifier matches the same strings; only the engine's preference differs.
+    if (this.peek() === '?') this.at += 1;
+    return range;
+  }
+
+  private atom(): Node {
+    const c = this.peek() as string;
+    this.at += 1;
+    if (c === '^' || c === '$') return { kind: 'empty' };
+    if (c === '.') return { kind: 'chars', chars: PRINTABLE };
+    if (c === '[') return { kind: 'chars', chars: this.charClass() };
+    if (c === '(') return this.group();
+    if (c === '\\') return { kind: 'chars', chars: this.escape(false) };
+    if (c === '*' || c === '+' || c === '?' || c === '{')
+      return { kind: 'chars', chars: this.refuse(`a bare "${c}"`) };
+    return { kind: 'chars', chars: [c] };
+  }
+
+  private group(): Node {
+    if (this.peek() === '?') {
+      const head = this.source.slice(this.at, this.at + 3);
+      if (head.startsWith('?:')) this.at += 2;
+      else if (/^\?<[A-Za-z_$]/.test(head) && this.source.includes('>', this.at)) {
+        this.at = this.source.indexOf('>', this.at) + 1;
+      } else return { kind: 'chars', chars: this.refuse(`the lookaround "(${head}"`) };
+    }
+    const inner = this.alternation();
+    if (this.peek() !== ')') return { kind: 'chars', chars: this.refuse('an unclosed group') };
+    this.at += 1;
+    return inner;
+  }
+
+  private escape(inClass: boolean): readonly string[] {
+    const c = this.peek();
+    if (c === undefined) return this.refuse('a trailing backslash');
+    this.at += 1;
+    const shorthand = Object.hasOwn(SHORTHAND, c) ? SHORTHAND[c] : undefined;
+    if (shorthand !== undefined) return shorthand;
+    const control = Object.hasOwn(CONTROL, c) ? CONTROL[c] : undefined;
+    if (control !== undefined) return [control];
+    const hex = c === 'x' ? 2 : c === 'u' ? 4 : 0;
+    if (hex > 0) {
+      const digits = this.source.slice(this.at, this.at + hex);
+      if (!/^[0-9a-fA-F]+$/.test(digits) || digits.length !== hex) return this.refuse(`\\${c}`);
+      this.at += hex;
+      return [String.fromCharCode(Number.parseInt(digits, 16))];
+    }
+    // `\b`, `\B`, a backreference, `\p{…}`, `\k<…>`, `\0`: a position or a reference, not a char.
+    if (/[A-Za-z0-9]/.test(c)) return this.refuse(`\\${c}${inClass ? ' in a class' : ''}`);
+    return [c];
+  }
+
+  /** The members of `[…]`, drawn from printable ASCII; a negated class is its complement there. */
+  private charClass(): readonly string[] {
+    const negated = this.peek() === '^';
+    if (negated) this.at += 1;
+    const members = new Set<string>();
+    let first = true;
+    for (let c = this.peek(); c !== ']' || first; c = this.peek()) {
+      if (c === undefined) return this.refuse('an unclosed class');
+      first = false;
+      const low = this.classMember();
+      if (low.length === 1 && this.peek() === '-' && this.source[this.at + 1] !== ']') {
+        this.at += 1;
+        const high = this.classMember();
+        if (high.length !== 1) return this.refuse('a range ending in a shorthand');
+        const [from, to] = [(low[0] as string).charCodeAt(0), (high[0] as string).charCodeAt(0)];
+        // Past printable ASCII the range's own first member stands in, so `[À-ÿ]` still yields one.
+        const inside = PRINTABLE.filter((ch) => ch.charCodeAt(0) >= from && ch.charCodeAt(0) <= to);
+        for (const ch of inside.length > 0 ? inside : [String.fromCharCode(from)]) members.add(ch);
+      } else {
+        for (const ch of low) members.add(ch);
+      }
+    }
+    this.at += 1;
+    return negated ? PRINTABLE.filter((ch) => !members.has(ch)) : [...members];
+  }
+
+  private classMember(): readonly string[] {
+    const c = this.peek() as string;
+    this.at += 1;
+    return c === '\\' ? this.escape(true) : [c];
+  }
+}
+
+const draw = (node: Node, random: () => number): string => {
+  const pick = <T>(items: readonly T[]): T | undefined =>
+    items[Math.floor(random() * items.length)];
+  if (node.kind === 'empty') return '';
+  if (node.kind === 'chars') return pick(node.chars) ?? '';
+  const branch = pick(node.branches) ?? [];
+  return branch
+    .map((piece) => {
+      const count = piece.min + Math.floor(random() * (piece.max - piece.min + 1));
+      return Array.from({ length: count }, () => draw(piece.node, random)).join('');
+    })
+    .join('');
+};
+
+/** Tries per sample: a draw that crosses an anchor (`a^b`) or a flag is retried, never returned. */
+const ATTEMPTS = 8;
+
+/**
+ * Up to `count` distinct strings `pattern.test` accepts, the same ones for the same `seed` on any
+ * machine. Empty when the pattern is past the subset, or when no draw lands inside it. `seed` is a
+ * number because this tier cannot import `fnv1a`; a caller with a text seed hashes it first.
+ */
+export function patternSamples(pattern: RegExp, seed: number, count = 4): readonly string[] {
+  const tree = new Parser(pattern.source).parse();
+  if (tree === undefined) return [];
+  const random = mulberry32(seed);
+  // `lastIndex` would make `test` stateful under `g`/`y`; a copy without them judges each draw.
+  const judge = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''));
+  const out: string[] = [];
+  for (let attempt = 0; attempt < count * ATTEMPTS && out.length < count; attempt += 1) {
+    const sample = draw(tree, random);
+    if (judge.test(sample) && !out.includes(sample)) out.push(sample);
+  }
+  return out;
+}

package/src/sample-random.ts

@@ -0,0 +1,14 @@
+// The one PRNG the sample walkers draw from. A leaf: `sample-seeded.ts` and `sample-pattern.ts`
+// both read it, and the second is imported by `sample-draw.ts`, which the first imports.
+
+/** mulberry32: 32 bits of state, a uniform float in [0, 1) per call, identical on every platform. */
+export function mulberry32(state: number): () => number {
+  let s = state >>> 0;
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0;
+    let x = s;
+    x = Math.imul(x ^ (x >>> 15), x | 1);
+    x ^= x + Math.imul(x ^ (x >>> 7), x | 61);
+    return ((x ^ (x >>> 14)) >>> 0) / 4_294_967_296;
+  };
+}

package/src/sample-seeded.ts

@@ -10,9 +10,11 @@ import {
   minimalNumber,
   minimalString,
   owedItems,
+  patternString,
   SAMPLE_ITEMS_MAX,
   satisfiesPattern,
 } from './sample-draw';
+import { mulberry32 } from './sample-random';
 
 /** Runs below this one are boundaries, not draws. */
 export const BOUNDARY_RUNS = 4;
@@ -52,18 +54,6 @@ const INTEGER_HIGH = 2 ** 31 - 1;
 /** An array draws at most this many items past what `minItems` owes. */
 const ITEMS_SPAN = 4;
 
-/** mulberry32: 32 bits of state, a uniform float in [0, 1) per call. */
-function generator(state: number): () => number {
-  let s = state >>> 0;
-  return () => {
-    s = (s + 0x6d2b79f5) >>> 0;
-    let x = s;
-    x = Math.imul(x ^ (x >>> 15), x | 1);
-    x ^= x + Math.imul(x ^ (x >>> 7), x | 61);
-    return ((x ^ (x >>> 14)) >>> 0) / 4_294_967_296;
-  };
-}
-
 /** Which side of every bound a boundary run takes, and whether it reaches for the optional parts. */
 interface Boundary {
   readonly high: boolean;
@@ -99,7 +89,7 @@ function lengthRange(node: SchemaNode): readonly [number, number] {
  * `@ultimat3/query` hand it `fnv1a(<name>)`, which this tier cannot import.
  */
 export function seededDraw(seed: number, run: number): Draw {
-  const next = generator((seed ^ Math.imul(run + 1, 0x9e3779b1)) >>> 0);
+  const next = mulberry32((seed ^ Math.imul(run + 1, 0x9e3779b1)) >>> 0);
   const between = (low: number, high: number): number =>
     low + Math.floor(next() * (high - low + 1));
   const edge = run >= 0 && run < BOUNDARY_RUNS ? BOUNDARIES[run] : undefined;
@@ -109,9 +99,11 @@ export function seededDraw(seed: number, run: number): Draw {
     const length = edge === undefined ? between(low, high) : edge.high ? high : low;
     const chars = Array.from({ length }, () => ALPHABET[between(0, ALPHABET.length - 1)] ?? 'a');
     const value = chars.join('');
-    // A regex cannot be inverted: a drawn value that misses it would test only the validator, so
-    // the one value the walk can build for it stands in (and `sampleGaps` reports when it cannot).
-    return satisfiesPattern(node, value) ? value : minimalString(node);
+    // A drawn value that misses the pattern would test only the validator, so a value walked from
+    // the pattern on this run's stream stands in; past the subset, the minimal one (a `sampleGaps`
+    // gap when it misses too).
+    if (satisfiesPattern(node, value)) return value;
+    return patternString(node, Math.floor(next() * 4_294_967_296)) ?? minimalString(node);
   };
 
   const number = (node: SchemaNode): number => {

package/src/sample.ts

@@ -21,6 +21,7 @@ import type { StandardSchemaV1 } from './standard';
 
 export type { Draw } from './sample-draw';
 export { minimalDraw, SAMPLE_ITEMS_MAX } from './sample-draw';
+export { patternSamples } from './sample-pattern';
 export { BOUNDARY_RUNS, seededDraw } from './sample-seeded';
 
 /**