rastack 0.0.48 → 0.0.50

package/test/transitions.spec.ts

@@ -0,0 +1,372 @@
+import { mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import {
+  analyzeProject,
+  analyzeResources,
+  buildOpenApi,
+  writeSchema,
+} from "../src/compile";
+import {
+  allowedTransitions,
+  applyTransition,
+  compileRecordMachine,
+  describeTransitions,
+  findTransition,
+  normalizeTransitions,
+  runRecordMachine,
+  specsFromResource,
+  transitionGuard,
+  transitionProblems,
+  type TransitionsModel,
+} from "../src/validate";
+import { validateDataset } from "../src/import/tabular";
+
+/** The flight lifecycle used throughout — mirrors `resources/airports.ts`. */
+const FLIGHT: TransitionsModel = {
+  field: "status",
+  states: ["scheduled", "boarding", "departed", "cancelled"],
+  initial: "scheduled",
+  on: {
+    board: { from: ["scheduled"], to: "boarding" },
+    depart: { from: ["boarding"], to: "departed", set: { gate: null } },
+    cancel: { from: ["scheduled", "boarding"], to: "cancelled" },
+  },
+};
+
+describe("transitions — the pure core", () => {
+  it("normalises an authored block (scalar `from` becomes a list)", () => {
+    const model = normalizeTransitions({
+      field: "status",
+      states: ["a", "b"],
+      initial: "a",
+      on: { go: { from: "a", to: "b" } },
+    });
+    expect(model).toEqual({
+      field: "status",
+      states: ["a", "b"],
+      initial: "a",
+      on: { go: { from: ["a"], to: "b" } },
+    });
+  });
+
+  it("rejects structurally broken blocks and drops malformed edges", () => {
+    expect(normalizeTransitions(undefined)).toBeUndefined();
+    expect(normalizeTransitions("nope")).toBeUndefined();
+    expect(normalizeTransitions({ field: "s", states: [] })).toBeUndefined();
+    const model = normalizeTransitions({
+      field: "s",
+      states: ["a", "b"],
+      on: { ok: { from: "a", to: "b" }, broken: { from: "a" } },
+    });
+    expect(Object.keys(model!.on)).toEqual(["ok"]);
+  });
+
+  it("reports authoring problems against the resource's fields", () => {
+    const fields = [{ name: "status" }, { name: "gate" }];
+    expect(transitionProblems(FLIGHT, fields)).toEqual([]);
+
+    const broken: TransitionsModel = {
+      field: "state", // not a field
+      states: ["a"],
+      initial: "b", // not a state
+      on: {
+        go: { from: ["a"], to: "z", set: { state: "x", ghost: 1 } }, // bad to/set
+      },
+    };
+    const problems = transitionProblems(broken, [{ name: "status" }]);
+    expect(problems).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('"state" is not a field'),
+        expect.stringContaining('initial state "b"'),
+        expect.stringContaining('to-state "z"'),
+        expect.stringContaining("must not patch the state field"),
+        expect.stringContaining('unknown field "ghost"'),
+      ]),
+    );
+  });
+
+  it("lists the transitions available from a state", () => {
+    expect(allowedTransitions(FLIGHT, "scheduled").map((t) => t.name)).toEqual([
+      "board",
+      "cancel",
+    ]);
+    expect(allowedTransitions(FLIGHT, "departed")).toEqual([]);
+    // No state falls back to the initial state.
+    expect(allowedTransitions(FLIGHT, undefined).map((t) => t.name)).toEqual([
+      "board",
+      "cancel",
+    ]);
+  });
+
+  it("finds the declared edge covering a jump", () => {
+    expect(findTransition(FLIGHT, "boarding", "departed")?.name).toBe("depart");
+    expect(findTransition(FLIGHT, "scheduled", "departed")).toBeUndefined();
+  });
+
+  it("guards creates: records start at the initial state", () => {
+    expect(transitionGuard(FLIGHT, undefined, {}).ok).toBe(true);
+    expect(transitionGuard(FLIGHT, undefined, { status: "scheduled" }).ok).toBe(true);
+    const rejected = transitionGuard(FLIGHT, undefined, { status: "departed" });
+    expect(rejected).toMatchObject({
+      ok: false,
+      message: expect.stringContaining('start at "scheduled"'),
+    });
+  });
+
+  it("guards updates: a state change must follow a declared edge", () => {
+    const previous = { status: "scheduled" };
+    expect(transitionGuard(FLIGHT, previous, { number: "BA1" }).ok).toBe(true);
+    expect(transitionGuard(FLIGHT, previous, { status: "scheduled" }).ok).toBe(true);
+    expect(transitionGuard(FLIGHT, previous, { status: "boarding" }).ok).toBe(true);
+    expect(transitionGuard(FLIGHT, previous, { status: "departed" })).toMatchObject({
+      ok: false,
+      message: 'status: no transition from "scheduled" to "departed"',
+    });
+  });
+
+  it("carries the matched edge's `set` patches through the guard", () => {
+    const result = transitionGuard(FLIGHT, { status: "boarding" }, { status: "departed" });
+    expect(result).toEqual({ ok: true, patch: { gate: null } });
+  });
+
+  it("fires a named transition into a full write patch", () => {
+    const applied = applyTransition(FLIGHT, "depart", { status: "boarding" });
+    expect(applied).toEqual({
+      ok: true,
+      patch: { status: "departed", gate: null },
+    });
+
+    expect(applyTransition(FLIGHT, "depart", { status: "scheduled" })).toMatchObject({
+      ok: false,
+      message: expect.stringContaining('not available from "scheduled"'),
+    });
+    expect(applyTransition(FLIGHT, "teleport", {})).toMatchObject({
+      ok: false,
+      message: expect.stringContaining("unknown transition"),
+    });
+  });
+
+  it("describes the machine for UI hints", () => {
+    expect(describeTransitions(FLIGHT)).toEqual([
+      "board: scheduled → boarding",
+      "depart: boarding → departed",
+      "cancel: scheduled | boarding → cancelled",
+    ]);
+  });
+});
+
+describe("transitions — the record-level gate in the record machine", () => {
+  const resource = {
+    fields: [
+      { name: "number", type: "string" as const, maxLength: 8 },
+      {
+        name: "status",
+        type: "string" as const,
+        options: FLIGHT.states,
+        default: "scheduled",
+      },
+      { name: "gate", type: "string" as const, null: true },
+    ],
+  };
+  const machine = compileRecordMachine(specsFromResource(resource), FLIGHT);
+
+  it("passes a legal edge with the persisted row in context", () => {
+    const run = runRecordMachine(
+      machine,
+      { number: "BA1", status: "boarding" },
+      { previous: { status: "scheduled" } },
+    );
+    expect(run.state).toBe("valid");
+  });
+
+  it("fails an undeclared jump at the `transition` gate", () => {
+    const run = runRecordMachine(
+      machine,
+      { number: "BA1", status: "departed" },
+      { previous: { status: "scheduled" } },
+    );
+    expect(run.state).toBe("invalid");
+    expect(run.errors).toEqual([
+      expect.objectContaining({
+        field: "status",
+        gate: "transition",
+        message: 'status: no transition from "scheduled" to "departed"',
+      }),
+    ]);
+  });
+
+  it("treats a run without `previous` as a create", () => {
+    const born = runRecordMachine(machine, { number: "BA1", status: "departed" });
+    expect(born.state).toBe("invalid");
+    expect(born.errors[0].gate).toBe("transition");
+
+    const fresh = runRecordMachine(machine, { number: "BA1" });
+    expect(fresh.state).toBe("valid");
+    // The state field's default (the initial state) fills in.
+    expect(fresh.values.status).toBe("scheduled");
+  });
+
+  it("lets the `member` gate explain an undeclared state first", () => {
+    const run = runRecordMachine(machine, { number: "BA1", status: "teleported" });
+    expect(run.state).toBe("invalid");
+    expect(run.errors).toHaveLength(1);
+    expect(run.errors[0].gate).toBe("member");
+  });
+
+  it("rejects import rows born mid-machine (dataset surface)", () => {
+    const report = validateDataset(
+      specsFromResource(resource),
+      {
+        headers: ["number", "status"],
+        rows: [
+          ["BA1", "scheduled"],
+          ["BA2", "departed"],
+          ["BA3", ""],
+        ],
+      },
+      { transitions: FLIGHT },
+    );
+    expect(report.valid).toBe(2);
+    expect(report.issues).toEqual([
+      expect.objectContaining({ row: 1, gate: "transition" }),
+    ]);
+  });
+});
+
+describe("transitions — through the compiler", () => {
+  const workRoot = join(__dirname, "transitions-fixtures");
+  const resourcesDir = join(workRoot, "resources");
+
+  const FLIGHTS_TS = `
+import { resource, s } from "rastack/define";
+
+export const Flight = resource("airports", "flight", {
+  number: s.string({ maxLength: 8 }),
+  status: s.string({ maxLength: 20 }),
+  gate: s.string({ maxLength: 5, null: true }),
+}, {
+  transitions: {
+    field: "status",
+    states: ["scheduled", "boarding", "departed", "cancelled"],
+    initial: "scheduled",
+    on: {
+      board: { from: "scheduled", to: "boarding" },
+      depart: { from: "boarding", to: "departed", set: { gate: null } },
+      cancel: { from: ["scheduled", "boarding"], to: "cancelled" },
+    },
+  },
+});
+`;
+
+  const ORDERS_TS = `
+// A plain data class with a \`static transitions\` block — the class-authored
+// twin of the DSL option. Statics are never columns.
+export class Order {
+  reference!: string;
+  status = "draft";
+
+  static transitions = {
+    field: "status",
+    states: ["draft", "placed", "shipped"],
+    initial: "draft",
+    on: {
+      place: { from: "draft", to: "placed" },
+      ship: { from: "placed", to: "shipped" },
+    },
+  };
+}
+`;
+
+  beforeAll(() => {
+    mkdirSync(resourcesDir, { recursive: true });
+    writeFileSync(join(resourcesDir, "flights.ts"), FLIGHTS_TS);
+    writeFileSync(join(resourcesDir, "orders.ts"), ORDERS_TS);
+  });
+
+  afterAll(() => {
+    rmSync(workRoot, { recursive: true, force: true });
+  });
+
+  it("compiles a DSL transitions block into the manifest, normalised", () => {
+    const resources = analyzeResources(resourcesDir);
+    const flight = resources.find((r) => r.model === "flight")!;
+    expect(flight.transitions).toEqual({
+      field: "status",
+      states: ["scheduled", "boarding", "departed", "cancelled"],
+      initial: "scheduled",
+      on: {
+        board: { from: ["scheduled"], to: "boarding" },
+        depart: { from: ["boarding"], to: "departed", set: { gate: null } },
+        cancel: { from: ["scheduled", "boarding"], to: "cancelled" },
+      },
+    });
+  });
+
+  it("stamps the state field with the states and the initial default", () => {
+    const resources = analyzeResources(resourcesDir);
+    const flight = resources.find((r) => r.model === "flight")!;
+    const status = flight.fields.find((f) => f.name === "status");
+    expect(status).toMatchObject({
+      options: ["scheduled", "boarding", "departed", "cancelled"],
+      default: "scheduled",
+    });
+  });
+
+  it("reads a class's `static transitions` (and keeps it out of the columns)", () => {
+    const resources = analyzeResources(resourcesDir);
+    const order = resources.find((r) => r.model === "order")!;
+    expect(order.transitions).toMatchObject({
+      field: "status",
+      states: ["draft", "placed", "shipped"],
+      on: { place: { from: ["draft"], to: "placed" } },
+    });
+    expect(order.fields.map((f) => f.name)).toEqual(["reference", "status"]);
+    const status = order.fields.find((f) => f.name === "status");
+    expect(status?.options).toEqual(["draft", "placed", "shipped"]);
+  });
+
+  it("emits `enum` and `x-rastack-transitions` into the OpenAPI contract", () => {
+    const resources = analyzeResources(resourcesDir);
+    const flight = resources.find((r) => r.model === "flight")!;
+    const doc = buildOpenApi(resources);
+
+    const status = doc.components.schemas.Flight.properties.status;
+    expect(status.enum).toEqual(["scheduled", "boarding", "departed", "cancelled"]);
+
+    const write = doc.components.schemas.FlightRequest;
+    expect(write["x-rastack-transitions"]).toEqual(flight.transitions);
+    expect(doc.components.schemas.PatchedFlightRequest["x-rastack-transitions"])
+      .toEqual(flight.transitions);
+
+    // The exported `writeSchema` (what `useForm(Entity)` derives at runtime)
+    // is the same schema the document publishes.
+    expect(writeSchema(flight, false)).toEqual(write);
+  });
+
+  it("surfaces authoring mistakes as compile diagnostics", () => {
+    const brokenDir = join(workRoot, "broken");
+    mkdirSync(brokenDir, { recursive: true });
+    writeFileSync(
+      join(brokenDir, "broken.ts"),
+      `
+import { resource, s } from "rastack/define";
+export const Thing = resource("app", "thing", {
+  status: s.string({ maxLength: 10 }),
+}, {
+  transitions: {
+    field: "status",
+    states: ["a", "b"],
+    on: { go: { from: "a", to: "missing" } },
+  },
+});
+`,
+    );
+    const { diagnostics } = analyzeProject(brokenDir);
+    expect(diagnostics).toEqual([
+      expect.objectContaining({
+        severity: "error",
+        message: expect.stringContaining('to-state "missing"'),
+      }),
+    ]);
+  });
+});