rastack 0.0.46 → 0.0.48

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 };
+}

package/test/entities.spec.ts

@@ -16,6 +16,7 @@ import {
  */
 const workRoot = join(__dirname, "entities-fixtures");
 const appDir = join(workRoot, "app");
+const classesDir = join(workRoot, "classes");
 const cycleDir = join(workRoot, "cycles");
 const hardCycleDir = join(workRoot, "hard-cycles");
 const mixedDir = join(workRoot, "mixed");
@@ -150,6 +151,39 @@ declare function useEntity<T>(name: string): T;
 export const a = useEntity<Airport>("airport");
 `;
 
+const CLASSES_TS = `
+import { MaxLength, Unique } from "rastack/types";
+
+/** @rastackSearch code,name */
+export class Airport {
+  code!: string & Unique & MaxLength<3>;
+  /** @maxLength 120 */
+  name!: string;
+  region = "EU";        // initializer → type inferred, value is the default
+  active = true;
+  /** @int */
+  gates = 0;
+}
+
+export class Terminal {
+  airport!: Airport;    // FK — inferred from the property type
+  /** @maxLength 20 */
+  label!: string;
+  opened?: Date;
+  static kind = "terminal";        // not a column
+  private secret!: string;         // not a column
+}
+
+/** Not a plain data class — a method means it must opt in explicitly. */
+export class BoardingService {
+  queue: string[] = [];
+  board(): void {}
+}
+
+/** Heritage means app code, not a table. */
+export class SplashScreen extends BoardingService {}
+`;
+
 function findResource(
   resources: ResourceModel[],
   app: string,
@@ -166,6 +200,8 @@ beforeAll(() => {
   writeFileSync(join(appDir, "flights.ts"), FLIGHTS_TS);
   writeFileSync(join(appDir, "passengers.ts"), PASSENGERS_TS);
   writeFileSync(join(appDir, "screens.tsx"), SCREENS_TSX);
+  mkdirSync(classesDir, { recursive: true });
+  writeFileSync(join(classesDir, "airports.ts"), CLASSES_TS);
   mkdirSync(cycleDir, { recursive: true });
   writeFileSync(join(cycleDir, "org.ts"), SOFT_CYCLE_TS);
   mkdirSync(hardCycleDir, { recursive: true });
@@ -307,6 +343,69 @@ describe("interface entities — FK inference", () => {
   });
 });
 
+describe("class entities — plain data classes", () => {
+  it("roots a plain data class by declaration — no hook, tag, or DSL needed", () => {
+    const { resources } = analyzeProject(classesDir);
+    const keys = resources.map((r) => `${r.app}.${r.model}`);
+    expect(keys).toContain("airports.airport");
+    expect(keys).toContain("airports.terminal");
+  });
+
+  it("does not root classes with methods or heritage clauses", () => {
+    const { resources } = analyzeProject(classesDir);
+    const keys = resources.map((r) => `${r.app}.${r.model}`);
+    expect(keys).not.toContain("airports.boardingService");
+    expect(keys).not.toContain("airports.splashScreen");
+  });
+
+  it("reads DbConfig brands and JSDoc tags off class fields", () => {
+    const { resources } = analyzeProject(classesDir);
+    const airport = findResource(resources, "airports", "airport");
+    expect(airport.search).toEqual(["code", "name"]);
+    expect(airport.fields.find((f) => f.name === "code")).toMatchObject({
+      type: "string",
+      maxLength: 3,
+      unique: true,
+    });
+    expect(airport.fields.find((f) => f.name === "name")).toMatchObject({
+      type: "string",
+      maxLength: 120,
+    });
+  });
+
+  it("infers types and defaults from field initializers", () => {
+    const { resources } = analyzeProject(classesDir);
+    const airport = findResource(resources, "airports", "airport");
+    const field = (name: string) => airport.fields.find((f) => f.name === name);
+    expect(field("region")).toMatchObject({ type: "string", default: "EU" });
+    expect(field("active")).toMatchObject({ type: "bool", default: true });
+    expect(field("gates")).toMatchObject({ type: "int", default: 0 });
+  });
+
+  it("treats a class-typed field as a foreign key", () => {
+    const { resources } = analyzeProject(classesDir);
+    const terminal = findResource(resources, "airports", "terminal");
+    expect(terminal.fields.find((f) => f.name === "airport")).toMatchObject({
+      type: "fk",
+      relation: { app: "airports", model: "airport" },
+    });
+    expect(terminal.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+    expect(terminal.fields.find((f) => f.name === "opened")).toMatchObject({
+      type: "datetime",
+      null: true,
+    });
+  });
+
+  it("ignores static and private class members", () => {
+    const { resources } = analyzeProject(classesDir);
+    const terminal = findResource(resources, "airports", "terminal");
+    expect(terminal.fields.find((f) => f.name === "kind")).toBeUndefined();
+    expect(terminal.fields.find((f) => f.name === "secret")).toBeUndefined();
+  });
+});
+
 describe("interface entities — circular dependencies", () => {
   it("reports a breakable cycle (optional self-FK) as a warning", () => {
     const { diagnostics } = analyzeProject(cycleDir);