rastack 0.0.45 → 0.0.47

package/src/validate/machine.ts

@@ -0,0 +1,525 @@
+/**
+ * The constraint state machine — the validation core of the database generator.
+ *
+ * A field's constraints are not a bag of ad-hoc checks: they are compiled into
+ * a **deterministic finite state machine** whose intermediate states are the
+ * constraint gates a value must pass through, in a fixed order, to reach the
+ * accepting `valid` state:
+ *
+ * ```
+ * pristine → present → typed → bounded → member → unique → resolved → valid
+ *                └────────┴───── any gate fails ─────┴────────┘
+ *                                    ↓
+ *                                 invalid
+ * ```
+ *
+ * Compiling (`compileFieldMachine`) *builds the constraints*: each constraint
+ * on the field spec becomes exactly one gate (a guarded transition), and gates
+ * whose constraint is absent are simply not emitted — an unconstrained string
+ * field's machine is just `pristine → present → typed → valid`. Running
+ * (`runFieldMachine`) walks the gates with a raw value, coercing it along the
+ * way (`typed` parses `"12"` into `12`), and halts at the first failing gate,
+ * reporting the state reached and the constraint that rejected the value.
+ *
+ * Because the machine is pure data + pure functions (no filesystem, no DOM),
+ * the *same* machine drives every surface: the form hooks derive per-field
+ * machines from the write JSON Schema (`specFromSchemaProperty`), and the data
+ * import pipeline derives them from `schema.rastack.json`
+ * (`specFromManifestField`) — one validation brain, two adapters, mirroring
+ * how `rastack-api-core` is one request brain behind two transports.
+ *
+ * The `unique` and `resolved` (foreign-key) gates are dataset-level: they only
+ * engage when the {@link ValidationContext} provides the capability (a seen-set
+ * or a relation resolver). A context-free run — a form field validating a
+ * single keystroke — passes through them untouched, exactly like the server,
+ * where uniqueness and FK existence are checked against the table, not the
+ * payload.
+ */
+
+// ---------------------------------------------------------------------------
+// The field spec — the normalised constraint set a machine is compiled from
+// ---------------------------------------------------------------------------
+
+/** The `{ app, model }` a foreign-key field points at. */
+export interface SpecRelation {
+  app: string;
+  model: string;
+}
+
+/** Scalar kinds, matching the manifest's `ScalarType` plus `fk`. */
+export type SpecType =
+  | "string"
+  | "int"
+  | "float"
+  | "bool"
+  | "datetime"
+  | "uuid"
+  | "fk";
+
+/**
+ * The normalised constraint set for one field. Both adapters (manifest field,
+ * JSON-Schema property) lower to this shape; the machine compiler only ever
+ * sees a `FieldSpec`.
+ */
+export interface FieldSpec {
+  name: string;
+  type: SpecType;
+  /** Whether a value must be present (`required` short of a default). */
+  required: boolean;
+  /** Whether `null` is an accepted value. */
+  nullable: boolean;
+  /** Max string length (the `bounded` gate). */
+  maxLength?: number;
+  /** Dataset-level uniqueness (the `unique` gate). */
+  unique?: boolean;
+  /** String format refinement: `email` | `url` | `date` | `date-time` | `uuid`. */
+  format?: string;
+  /** Enum membership (the `member` gate). */
+  options?: Array<string | number>;
+  /** FK target — present iff `type === "fk"` (the `resolved` gate). */
+  relation?: SpecRelation;
+  /** Default applied when an optional field is empty. */
+  default?: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// States, gates, machines
+// ---------------------------------------------------------------------------
+
+/** Every state a field machine can be in. */
+export type FieldState =
+  | "pristine"
+  | "present"
+  | "typed"
+  | "bounded"
+  | "member"
+  | "unique"
+  | "resolved"
+  | "valid"
+  | "invalid";
+
+/** The intermediate (gate) states, in canonical machine order. */
+export const GATE_ORDER: readonly FieldState[] = [
+  "present",
+  "typed",
+  "bounded",
+  "member",
+  "unique",
+  "resolved",
+];
+
+/** The outcome of one gate check: pass (with the possibly-coerced value) or fail. */
+export type GateResult =
+  | { ok: true; value: unknown }
+  | { ok: false; message: string };
+
+/**
+ * One guarded transition of the machine. Passing the guard enters state `to`
+ * and threads the (possibly coerced) value into the next gate.
+ */
+export interface Gate {
+  to: FieldState;
+  /** Human-readable constraint, e.g. `"maxLength ≤ 3"` — drives UI hints and import reports. */
+  constraint: string;
+  check: (value: unknown, ctx: ValidationContext) => GateResult;
+}
+
+/** A compiled field machine: the spec, its gates, and the full state chain. */
+export interface FieldMachine {
+  spec: FieldSpec;
+  gates: Gate[];
+  /** `["pristine", ...gate states..., "valid"]` — the happy path. */
+  states: FieldState[];
+}
+
+/**
+ * Dataset-level capabilities. Absent capabilities leave the corresponding
+ * gates inert (they pass), so a machine runs identically in a browser form
+ * (no context) and in the import pipeline (full context) minus the
+ * dataset-level checks.
+ */
+export interface ValidationContext {
+  /** Per-field sets of already-seen values, keyed by field name (the `unique` gate). */
+  seen?: Map<string, Set<string>>;
+  /** Resolve whether a FK value exists on the target resource (the `resolved` gate). */
+  resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+}
+
+/** The result of running a value through a field machine. */
+export interface FieldRun {
+  /** Terminal state: `valid` or `invalid`. */
+  state: "valid" | "invalid";
+  /** Every state entered, `pristine` first. Ends in `valid` or `invalid`. */
+  path: FieldState[];
+  /** The coerced value (e.g. `"12"` → `12`; empty optional → default/null). */
+  value: unknown;
+  /** Present iff `state === "invalid"`: the gate that rejected the value. */
+  failed?: { gate: FieldState; constraint: string; message: string };
+}
+
+const EMPTY_CTX: ValidationContext = {};
+
+// ---------------------------------------------------------------------------
+// Value predicates (shared by gates)
+// ---------------------------------------------------------------------------
+
+function isEmpty(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === null ||
+    (typeof value === "string" && value.trim() === "")
+  );
+}
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const URL_RE = /^https?:\/\/[^\s]+$/i;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
+
+/** Coerce a raw value to the spec's scalar type, or explain why it can't be. */
+function coerce(spec: FieldSpec, value: unknown): GateResult {
+  switch (spec.type) {
+    case "int": {
+      if (typeof value === "number" && Number.isInteger(value))
+        return { ok: true, value };
+      if (typeof value === "string" && /^-?\d+$/.test(value.trim()))
+        return { ok: true, value: parseInt(value.trim(), 10) };
+      return { ok: false, message: `"${String(value)}" is not an integer` };
+    }
+    case "float": {
+      if (typeof value === "number" && Number.isFinite(value))
+        return { ok: true, value };
+      if (
+        typeof value === "string" &&
+        /^-?\d+(\.\d+)?$/.test(value.trim())
+      )
+        return { ok: true, value: parseFloat(value.trim()) };
+      return { ok: false, message: `"${String(value)}" is not a number` };
+    }
+    case "bool": {
+      if (typeof value === "boolean") return { ok: true, value };
+      if (typeof value === "string") {
+        const v = value.trim().toLowerCase();
+        if (["true", "yes", "1"].includes(v)) return { ok: true, value: true };
+        if (["false", "no", "0"].includes(v))
+          return { ok: true, value: false };
+      }
+      if (value === 1) return { ok: true, value: true };
+      if (value === 0) return { ok: true, value: false };
+      return { ok: false, message: `"${String(value)}" is not a boolean` };
+    }
+    case "datetime": {
+      if (value instanceof Date && !isNaN(value.getTime()))
+        return { ok: true, value: value.toISOString() };
+      if (
+        typeof value === "string" &&
+        (DATETIME_RE.test(value.trim()) || DATE_RE.test(value.trim())) &&
+        !isNaN(Date.parse(value.trim()))
+      )
+        return { ok: true, value: value.trim() };
+      return { ok: false, message: `"${String(value)}" is not a datetime` };
+    }
+    case "uuid": {
+      if (typeof value === "string" && UUID_RE.test(value.trim()))
+        return { ok: true, value: value.trim() };
+      return { ok: false, message: `"${String(value)}" is not a uuid` };
+    }
+    case "fk": {
+      // FK values are opaque ids — integer or string, but never structured.
+      if (typeof value === "number" && Number.isInteger(value))
+        return { ok: true, value };
+      if (typeof value === "string" && value.trim() !== "") {
+        const v = value.trim();
+        return { ok: true, value: /^\d+$/.test(v) ? parseInt(v, 10) : v };
+      }
+      return { ok: false, message: `"${String(value)}" is not a valid id` };
+    }
+    default: {
+      // string (+ format refinement)
+      if (
+        typeof value !== "string" &&
+        typeof value !== "number" &&
+        typeof value !== "boolean"
+      )
+        return { ok: false, message: "value is not a string" };
+      const str = String(value);
+      switch (spec.format) {
+        case "email":
+          if (!EMAIL_RE.test(str))
+            return { ok: false, message: `"${str}" is not an email address` };
+          break;
+        case "uri":
+        case "url":
+          if (!URL_RE.test(str))
+            return { ok: false, message: `"${str}" is not a URL` };
+          break;
+        case "date":
+          if (!DATE_RE.test(str) || isNaN(Date.parse(str)))
+            return { ok: false, message: `"${str}" is not a date` };
+          break;
+        case "date-time":
+          if (!DATETIME_RE.test(str) || isNaN(Date.parse(str)))
+            return { ok: false, message: `"${str}" is not a datetime` };
+          break;
+        case "uuid":
+          if (!UUID_RE.test(str))
+            return { ok: false, message: `"${str}" is not a uuid` };
+          break;
+      }
+      return { ok: true, value: str };
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Compilation — the machine *is* the constraints
+// ---------------------------------------------------------------------------
+
+function typeConstraint(spec: FieldSpec): string {
+  if (spec.type === "fk")
+    return `references ${spec.relation ? `${spec.relation.app}.${spec.relation.model}` : "a related record"}`;
+  return spec.format ? `${spec.type} (${spec.format})` : spec.type;
+}
+
+/**
+ * Compile a field spec into its constraint state machine. Every present
+ * constraint becomes one gate; absent constraints emit no gate, so the state
+ * chain is exactly the field's constraint set.
+ */
+export function compileFieldMachine(spec: FieldSpec): FieldMachine {
+  const gates: Gate[] = [];
+
+  gates.push({
+    to: "present",
+    constraint: spec.required ? "required" : "optional",
+    check: (value) =>
+      spec.required && isEmpty(value)
+        ? { ok: false, message: `${spec.name} is required` }
+        : { ok: true, value },
+  });
+
+  gates.push({
+    to: "typed",
+    constraint: typeConstraint(spec),
+    check: (value) => coerce(spec, value),
+  });
+
+  if (spec.maxLength !== undefined) {
+    const max = spec.maxLength;
+    gates.push({
+      to: "bounded",
+      constraint: `maxLength ≤ ${max}`,
+      check: (value) =>
+        typeof value === "string" && value.length > max
+          ? {
+              ok: false,
+              message: `"${value}" is longer than ${max} characters`,
+            }
+          : { ok: true, value },
+    });
+  }
+
+  if (spec.options && spec.options.length > 0) {
+    const options = spec.options;
+    gates.push({
+      to: "member",
+      constraint: `one of ${options.map(String).join(", ")}`,
+      check: (value) =>
+        options.some((o) => o === value || String(o) === String(value))
+          ? { ok: true, value }
+          : {
+              ok: false,
+              message: `"${String(value)}" is not one of the allowed values`,
+            },
+    });
+  }
+
+  if (spec.unique) {
+    gates.push({
+      to: "unique",
+      constraint: "unique",
+      check: (value, ctx) => {
+        const seen = ctx.seen?.get(spec.name);
+        if (!seen) return { ok: true, value }; // no dataset context — gate is inert
+        const key = String(value);
+        if (seen.has(key))
+          return { ok: false, message: `duplicate value "${key}"` };
+        seen.add(key);
+        return { ok: true, value };
+      },
+    });
+  }
+
+  if (spec.type === "fk" && spec.relation) {
+    const relation = spec.relation;
+    gates.push({
+      to: "resolved",
+      constraint: `exists on ${relation.app}.${relation.model}`,
+      check: (value, ctx) => {
+        if (!ctx.resolveRelation) return { ok: true, value }; // inert without a resolver
+        return ctx.resolveRelation(relation, value)
+          ? { ok: true, value }
+          : {
+              ok: false,
+              message: `no ${relation.app}.${relation.model} with id "${String(value)}"`,
+            };
+      },
+    });
+  }
+
+  return {
+    spec,
+    gates,
+    states: ["pristine", ...gates.map((g) => g.to), "valid"],
+  };
+}
+
+/** The human-readable constraint chain — what the machine enforces, in order. */
+export function describeMachine(machine: FieldMachine): string[] {
+  return machine.gates.map((g) => g.constraint);
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a raw value through a field machine. Walks the gates in order, coercing
+ * the value as it goes; the first failing guard sends the machine to
+ * `invalid` with the offending constraint attached.
+ *
+ * An empty value on an optional field short-circuits from `present` straight
+ * to `valid` (yielding the default, else `null`) — there is nothing further
+ * to constrain, exactly like a nullable column.
+ */
+export function runFieldMachine(
+  machine: FieldMachine,
+  rawValue: unknown,
+  ctx: ValidationContext = EMPTY_CTX,
+): FieldRun {
+  const path: FieldState[] = ["pristine"];
+  let value: unknown = rawValue;
+
+  for (const gate of machine.gates) {
+    const result = gate.check(value, ctx);
+    if (!result.ok) {
+      path.push("invalid");
+      return {
+        state: "invalid",
+        path,
+        value,
+        failed: {
+          gate: gate.to,
+          constraint: gate.constraint,
+          message: result.message,
+        },
+      };
+    }
+    value = result.value;
+    path.push(gate.to);
+
+    // Optional + empty: nothing left to constrain — accept with the default.
+    if (gate.to === "present" && isEmpty(value)) {
+      path.push("valid");
+      return {
+        state: "valid",
+        path,
+        value: machine.spec.default !== undefined ? machine.spec.default : null,
+      };
+    }
+  }
+
+  path.push("valid");
+  return { state: "valid", path, value };
+}
+
+// ---------------------------------------------------------------------------
+// Record machines — one machine per field, run over a whole record
+// ---------------------------------------------------------------------------
+
+/** A record machine is the composition of its fields' machines. */
+export interface RecordMachine {
+  fields: FieldMachine[];
+}
+
+/** One field's failure inside a record run. */
+export interface RecordError {
+  field: string;
+  gate: FieldState;
+  constraint: string;
+  message: string;
+}
+
+/** The result of running one record through a record machine. */
+export interface RecordRun {
+  state: "valid" | "invalid";
+  /** The coerced record — only meaningful when `state === "valid"`. */
+  values: Record<string, unknown>;
+  /** Per-field machine runs, keyed by field name. */
+  fields: Record<string, FieldRun>;
+  errors: RecordError[];
+}
+
+export function compileRecordMachine(specs: FieldSpec[]): RecordMachine {
+  return { fields: specs.map(compileFieldMachine) };
+}
+
+export function runRecordMachine(
+  machine: RecordMachine,
+  record: Record<string, unknown>,
+  ctx: ValidationContext = EMPTY_CTX,
+): RecordRun {
+  const fields: Record<string, FieldRun> = {};
+  const values: Record<string, unknown> = {};
+  const errors: RecordError[] = [];
+
+  for (const fieldMachine of machine.fields) {
+    const name = fieldMachine.spec.name;
+    const run = runFieldMachine(fieldMachine, record[name], ctx);
+    fields[name] = run;
+    values[name] = run.value;
+    if (run.failed) {
+      errors.push({ field: name, ...run.failed });
+    }
+  }
+
+  return {
+    state: errors.length === 0 ? "valid" : "invalid",
+    values,
+    fields,
+    errors,
+  };
+}
+
+/**
+ * Build the dataset-level context for a record machine: a seen-set per
+ * `unique` field (so the `unique` gate engages), and — when related ids are
+ * supplied — a resolver for the `resolved` gate. `relatedIds` is keyed by
+ * `"app.model"`.
+ */
+export function createDatasetContext(
+  machine: RecordMachine,
+  opts: {
+    relatedIds?: Record<string, Set<string>>;
+    resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+  } = {},
+): ValidationContext {
+  const seen = new Map<string, Set<string>>();
+  for (const field of machine.fields) {
+    if (field.spec.unique) seen.set(field.spec.name, new Set());
+  }
+
+  const resolveRelation =
+    opts.resolveRelation ??
+    (opts.relatedIds
+      ? (relation: SpecRelation, value: unknown) => {
+          const ids = opts.relatedIds![`${relation.app}.${relation.model}`];
+          // Unknown target tables are out of scope for the check — stay inert.
+          return ids ? ids.has(String(value)) : true;
+        }
+      : undefined);
+
+  return { seen, resolveRelation };
+}