@reventlessdev/reventless-core 3.0.0-alpha.236 → 3.0.0-alpha.238

package/tests/plugin/PluginStructureTest.res

@@ -144,6 +144,29 @@ module PsReserveStockSlice: ReventlessInfra.StateChangeSlice.T = {
   let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
 }
 
+module PsDispatchShipmentSlice: ReventlessInfra.StateChangeSlice.T = {
+  module Spec = PsDispatchShipment
+  module Behavior = {
+    type state = PsDispatchShipment.state
+    let initialState = PsDispatchShipment.initialState
+    let evolve = PsDispatchShipment.evolve
+    let decide = PsDispatchShipment.decide
+    let moduleUrl = PsDispatchShipment.moduleUrl
+  }
+  let isAsync = false
+  type component = scsComponent
+  let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
+module PsShipmentsViewSlice: ReventlessInfra.StateViewSlice.T = {
+  module Spec = PsShipmentsView
+  module Projection = {
+    let project = PsShipmentsView.project
+    let moduleUrl = PsShipmentsView.moduleUrl
+  }
+  type component = svsComponent
+  let make = (~dcbEventLog as _, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
+
 let structure = Plugin_Structure.make(
   ~name="TestPlugin",
   ~stateChangeSlices=[module(PsPlaceOrderSlice), module(PsShipOrderSlice)],
@@ -155,6 +178,132 @@ let structure = Plugin_Structure.make(
   ],
 )
 
+describe("lifecycle topology", () => {
+  let ordersStates = Dict.fromArray([("Orders", ["Placed", "Shipped", "Cancelled"])])
+  let writableWith = (commands): Reventless.Plugin.writableDef => {
+    name: "Ordering",
+    commands,
+    producedEventTypes: [],
+    consumedEventTypes: [],
+    linkedViews: ["Orders"],
+    consistencyRead: None,
+    events: [],
+    errors: [],
+    chapter: None,
+  }
+  let command = (~name, ~allowedStates=?, ~targetState=?, ()): Reventless.Plugin.commandDef => {
+    name,
+    schema: "",
+    level: Instance,
+    aggregateIdField: None,
+    mutationField: "",
+    references: [],
+    allowedStates,
+    targetState,
+    apiExposed: None,
+    requiredAccess: None,
+    ownerField: None,
+  }
+
+  testSync("names a state no command can reach", () => {
+    // `Cancelled` is in the enum and nothing declares an edge into it.
+    let findings = Plugin_Structure.lifecycleTopologyFindings(
+      ~writables=[
+        writableWith([command(~name="Ship", ~allowedStates=["Placed"], ~targetState="Shipped", ())]),
+      ],
+      ~lifecycleStatesByView=ordersStates,
+    )
+    expect(findings->Array.map(((_, m)) => m->String.includes("Cancelled")))->toEqual([true])
+  })
+
+  testSync("says nothing when every state is reachable", () => {
+    let findings = Plugin_Structure.lifecycleTopologyFindings(
+      ~writables=[
+        writableWith([
+          command(~name="Ship", ~allowedStates=["Placed"], ~targetState="Shipped", ()),
+          command(~name="Cancel", ~allowedStates=["Placed"], ~targetState="Cancelled", ()),
+        ]),
+      ],
+      ~lifecycleStatesByView=ordersStates,
+    )
+    expect(findings->Array.length)->toBe(0)
+  })
+
+  // The first declared state is where rows begin, so nothing pointing at it is
+  // expected rather than suspicious.
+  testSync("does not call the initial state unreachable", () => {
+    let findings = Plugin_Structure.lifecycleTopologyFindings(
+      ~writables=[
+        writableWith([
+          command(~name="Ship", ~allowedStates=["Placed"], ~targetState="Shipped", ()),
+          command(~name="Cancel", ~allowedStates=["Placed"], ~targetState="Cancelled", ()),
+        ]),
+      ],
+      ~lifecycleStatesByView=ordersStates,
+    )
+    expect(findings->Array.map(((_, m)) => m->String.includes("Placed")))->toEqual([])
+  })
+
+  // A terminal state is not a finding. `Shipped` and `Refunded` have no way out
+  // in the shipped aggregates example, and both are correct — which is why the
+  // "dead end" rule this pass was going to carry was dropped rather than
+  // silenced. See the comment in Plugin_Structure.
+  testSync("does not report a state with no way out", () => {
+    let findings = Plugin_Structure.lifecycleTopologyFindings(
+      ~writables=[
+        writableWith([
+          command(~name="Ship", ~allowedStates=["Placed"], ~targetState="Shipped", ()),
+          command(~name="Cancel", ~allowedStates=["Placed"], ~targetState="Cancelled", ()),
+        ]),
+      ],
+      ~lifecycleStatesByView=ordersStates,
+    )
+    expect(findings->Array.length)->toBe(0)
+  })
+})
+
+describe("@transition cross-check", () => {
+  // The exit criterion: a state no linked view declares stops the build, and the
+  // message says which command, which state, and what it was checked against.
+  // `DispatchShipment` produces `ShipmentDispatched`, which the `Shipments` view
+  // consumes — so the two are linked, the view's lifecycle is in hand, and
+  // "Dispatchd" has somewhere to be wrong.
+  let buildBad = () =>
+    try {
+      Plugin_Structure.make(
+        ~name="TransitionPlugin",
+        ~stateChangeSlices=[module(PsDispatchShipmentSlice)],
+        ~stateViewSlices=[module(PsShipmentsViewSlice)],
+      )->ignore
+      None
+    } catch {
+    | Exn.Error(e) => Some(Exn.message(e)->Option.getOr(""))
+    | _ => Some("")
+    }
+
+  testSync("a state no linked view declares fails the build", () => {
+    expect(buildBad()->Option.isSome)->toBe(true)
+  })
+
+  testSync("the failure names the command, the state and the view", () => {
+    let message = buildBad()->Option.getOr("")
+    expect((
+      message->String.includes("DispatchShipment"),
+      message->String.includes("Dispatchd"),
+      message->String.includes("Shipments"),
+      message->String.includes("Booked"),
+    ))->toEqual((true, true, true, true))
+  })
+
+  // The other half of the rule: a correctly-spelled edge passes, and a command
+  // whose linked views declare no lifecycle is warned about rather than failed —
+  // `PsShipOrder` is exactly that shape, and the suite's main `structure` above
+  // builds without throwing, which is that path already exercised.
+  testSync("a plugin whose views declare no lifecycle still builds", () => {
+    expect(structure.stateChangeSlices->Array.length)->toBe(2)
+  })
+})
+
 describe("Plugin_Structure.make — Phase 2 graph fields", () => {
   describe("stateChangeSlices", () => {
     testSync("produces two SCS entries in declaration order", () => {
@@ -233,8 +382,8 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       ))->toEqual((Some(true), Some(false)))
     })
 
-    testSync("ShipOrder: @targetState(\"Shipped\") flows through the PPX to commandDef.targetState", () => {
-      // End-to-end: the reventless-ppx @targetState annotation → markTargetState
+    testSync("ShipOrder: @transition's target flows through the PPX to commandDef.targetState", () => {
+      // End-to-end: the reventless-ppx @transition annotation → markTargetState
       // metadata → ApiTargetStateHelpers.getTargetState → commandDef. The
       // un-annotated CancelShipment carries None (resolver falls back to
       // name-stem).
@@ -246,6 +395,18 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       ))->toEqual((Some("Shipped"), None))
     })
 
+    testSync("ShipOrder: @transition's from-set flows through to commandDef.allowedStates", () => {
+      // The other half of the same annotation, which the removed pair spelled
+      // separately: one attribute now fills both fields, so a command that
+      // declares a target cannot end up without the states it may run from.
+      let shipOrder = structure.stateChangeSlices->Array.getUnsafe(1)
+      let byName = name => shipOrder.commands->Array.find(c => c.name == name)
+      expect((
+        byName("ShipOrder")->Option.flatMap(c => c.allowedStates),
+        byName("CancelShipment")->Option.flatMap(c => c.allowedStates),
+      ))->toEqual((Some(["Placed"]), None))
+    })
+
     testSync("ShipOrder: the @noApi variant carries no callable mutation field (no sibling leak)", () => {
       // Regression: for a single-exposed-command slice, `mutationFieldFor`
       // resolves every variant — including the @noApi one — to the slice's one
@@ -670,33 +831,189 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     )
   })
 
-  describe("statusField — the shape rule", () => {
-    let statusOf = schema =>
-      Plugin_Structure.statusFieldFromStateSchema(~entityName="Test", schema->S.castToUnknown)
+  describe("lifecycleField — the name rule and the shape rule", () => {
+    let lifecycleOf = schema =>
+      Plugin_Structure.lifecycleFieldFromStateSchema(~entityName="Test", schema->S.castToUnknown)
 
-    testSync("a `status` field holding a closed set of values is the lifecycle field", () => {
+    let withLifecycle = (schema, ~field) =>
+      schema->S.castToUnknown->S.Metadata.set(
+        ~id=Reventless.StateAnnotations.stateAnnotationsId,
+        {
+          ids: [],
+          compositeIds: [],
+          subIds: [],
+          compositeSubIds: [],
+          indexes: [],
+          hidden: [],
+          summary: [],
+          drillTargets: [],
+          drillTargetKeys: [],
+          collapsed: [],
+          scan: [],
+          scanSort: [],
+          semantic: [],
+          metric: [],
+          lifecycle: Some(field),
+          groupBy: None,
+          visibility: None,
+          live: None,
+          retired: None,
+        },
+      )
+
+    testSync("a `lifecycle` field holding a closed set of values is the lifecycle field", () => {
       let schema = S.schema(s =>
         {
-          "status": s.matches(S.union([S.literal("Placed"), S.literal("Shipped")])),
+          "lifecycle": s.matches(S.union([S.literal("Placed"), S.literal("Shipped")])),
         }
       )
-      expect(statusOf(schema))->toEqual(Some("status"))
+      expect(lifecycleOf(schema))->toEqual(Some("lifecycle"))
     })
 
     testSync("an optional one counts too", () => {
       let schema = S.schema(s =>
         {
-          "status": s.matches(S.option(S.union([S.literal("Placed"), S.literal("Shipped")]))),
+          "lifecycle": s.matches(S.option(S.union([S.literal("Placed"), S.literal("Shipped")]))),
         }
       )
-      expect(statusOf(schema))->toEqual(Some("status"))
+      expect(lifecycleOf(schema))->toEqual(Some("lifecycle"))
     })
 
-    testSync("free text named `status` is not a lifecycle", () => {
+    testSync("free text named `lifecycle` is not a lifecycle", () => {
       // `allowedStates` filtering needs states to compare against; a string
-      // field named `status` gives a command menu nothing to match.
-      let schema = S.schema(s => {"status": s.matches(S.string)})
-      expect(statusOf(schema))->toEqual(None)
+      // field named `lifecycle` gives a command menu nothing to match.
+      let schema = S.schema(s => {"lifecycle": s.matches(S.string)})
+      expect(lifecycleOf(schema))->toEqual(None)
+    })
+
+    // The one behaviour the rename deliberately changes, so it is asserted rather
+    // than assumed. `status` is a promiscuous name — geocoding progress, todo-queue
+    // progress, translation audit outcome — and a convention keyed on it guessed
+    // often. A record whose lifecycle really does live in a field called `status`
+    // says so with `@lifecycle`.
+    testSync("an unannotated field named `status` resolves to None", () => {
+      let schema = S.schema(s =>
+        {
+          "status": s.matches(S.union([S.literal("Placed"), S.literal("Shipped")])),
+        }
+      )
+      expect(lifecycleOf(schema))->toEqual(None)
+    })
+
+    testSync("the annotation names a field the convention would never reach", () => {
+      let schema = S.schema(s =>
+        {
+          "locationStatus": s.matches(S.union([S.literal("Pending"), S.literal("Located")])),
+        }
+      )
+      expect(lifecycleOf(schema->withLifecycle(~field="locationStatus")))->toEqual(
+        Some("locationStatus"),
+      )
+    })
+  })
+
+  describe("retiredField — annotation and nothing else", () => {
+    let retiredOf = schema =>
+      Plugin_Structure.retiredFieldFromStateSchema(schema->S.castToUnknown)
+
+    let withRetired = (schema, ~field) =>
+      schema->S.castToUnknown->S.Metadata.set(
+        ~id=Reventless.StateAnnotations.stateAnnotationsId,
+        {
+          ids: [],
+          compositeIds: [],
+          subIds: [],
+          compositeSubIds: [],
+          indexes: [],
+          hidden: [],
+          summary: [],
+          drillTargets: [],
+          drillTargetKeys: [],
+          collapsed: [],
+          scan: [],
+          scanSort: [],
+          semantic: [],
+          metric: [],
+          lifecycle: None,
+          groupBy: None,
+          visibility: None,
+          live: None,
+          retired: Some({field, label: "", showWhenFalse: false, values: None}),
+        },
+      )
+
+    // The state form. The value is published beside the field so a client holding
+    // the def holds the whole predicate — two places deriving one comparison is
+    // how they come to disagree about which rows a caller may see.
+    testSync("publishes the retirement state beside the field", () => {
+      let withState = schema =>
+        schema->S.castToUnknown->S.Metadata.set(
+          ~id=Reventless.StateAnnotations.stateAnnotationsId,
+          {
+            ids: [],
+            compositeIds: [],
+            subIds: [],
+            compositeSubIds: [],
+            indexes: [],
+            hidden: [],
+            summary: [],
+            drillTargets: [],
+            drillTargetKeys: [],
+            collapsed: [],
+            scan: [],
+            scanSort: [],
+            semantic: [],
+            metric: [],
+            lifecycle: Some("accountStatus"),
+            groupBy: None,
+            visibility: None,
+            live: None,
+            retired: Some({
+              field: "accountStatus",
+              label: "",
+              showWhenFalse: false,
+              values: Some(["Deactivated", "Closed"]),
+            }),
+          },
+        )
+      let schema = S.schema(s => {"accountStatus": s.matches(S.string)})->withState
+      expect((
+        Plugin_Structure.retiredFieldFromStateSchema(schema),
+        Plugin_Structure.retiredValuesFromStateSchema(schema),
+      ))->toEqual((Some("accountStatus"), Some(["Deactivated", "Closed"])))
+    })
+
+    // Absent is what says "boolean form", so it has to stay tellable from a state
+    // form — including one naming nothing, which is `Some([])`.
+    testSync("publishes no states on the boolean form", () => {
+      let schema = S.schema(s => {"archived": s.matches(S.bool)})
+      expect(
+        Plugin_Structure.retiredValuesFromStateSchema(schema->withRetired(~field="archived")),
+      )->toEqual(None)
+    })
+
+    testSync("names the annotated field", () => {
+      let schema = S.schema(s => {"archived": s.matches(S.bool)})
+      expect(retiredOf(schema->withRetired(~field="archived")))->toEqual(Some("archived"))
+    })
+
+    // The whole reason this has no convention rung. `lifecycleField` may still fall
+    // back to a field literally named `lifecycle` because guessing wrong there makes
+    // a command menu filter oddly; guessing wrong here makes rows disappear for every caller who is not
+    // elevated, so an unannotated boolean stays as visible as it was.
+    testSync("declines a conventionally-named boolean nobody annotated", () => {
+      let schema = S.schema(s =>
+        {
+          "archived": s.matches(S.bool),
+          "deactivated": s.matches(S.bool),
+        }
+      )
+      expect(retiredOf(schema))->toEqual(None)
+    })
+
+    testSync("declines a schema carrying no annotation spec at all", () => {
+      let schema = S.schema(s => {"id": s.matches(S.string)})
+      expect(retiredOf(schema))->toEqual(None)
     })
   })
 
@@ -806,7 +1123,7 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
   // The generator captures each component's chapter (source-folder grouping band)
   // and passes it as ~componentChapters; Plugin_Structure looks it up by Spec.name
   // and threads it onto every def, so a deployed-graph consumer can render chapter
-  // bands without workspace access. See docs/plans/deployed-chapter-grouping.md.
+  // bands without workspace access. See docs/plans/done/deployed-chapter-grouping.md.
   describe("componentChapters threading", () => {
     let chaptered = Plugin_Structure.make(
       ~name="TestPlugin",