@reventlessdev/reventless-core 3.0.0-alpha.237 → 3.0.0-alpha.239

package/src/plugin/component/Plugin_Structure.res

@@ -108,19 +108,57 @@ let retiredFieldFromStateSchema = (stateSchema: S.t<unknown>): option<string> =>
 let retiredValuesFromStateSchema = (stateSchema: S.t<unknown>): option<array<string>> =>
   retiredFromStateSchema(stateSchema)->Option.flatMap(r => r.values)
 
+// Whether a reference to a retired row of this view still resolves its name —
+// `@namedWhenRetired`. Read off the retirement rather than from a second
+// annotation, so a record cannot declare the reach of a retirement it does not
+// have; the PPX refuses that pairing, and reading it here from the same place
+// keeps the two halves agreeing by construction rather than by review.
+let namedWhenRetiredFromStateSchema = (stateSchema: S.t<unknown>): bool =>
+  retiredFromStateSchema(stateSchema)->Option.mapOr(false, r => r.namedWhenRetired)
+
+// What one record's `@retired` declaration could be told about its own field.
+//
+// Three outcomes rather than a bool, because "nothing to check" and "could not
+// check" are different facts and only the second is worth a plugin's attention.
+type retiredCheck =
+  | NotDeclared
+  // Why the names could not be compared. A fatal rule that is invisible when it
+  // does not run is the failure mode the transition check spends a counter to
+  // avoid, so this is reported rather than skipped in silence.
+  | Unchecked(string)
+  | Checked(array<string>)
+
 // The check the PPX cannot make, in the one place that can: the payload is a
 // constructor reference the PPX only ever sees as a name, and whether that name
 // is a case of the field's enum needs the schema.
 //
-// Two rules, and the second is the one the form exists for. A `value` on a field
-// that is not the record's lifecycle would keep the read narrowing while silently
-// losing the command filtering that motivates it — `@allowedStates` is written in
-// terms of the lifecycle field, so a retirement state anywhere else is a state no
-// command can name.
-let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =>
+// Two rules, and they are held to different standards on purpose.
+//
+// **A name the field's enum does not declare is unambiguously wrong** — no domain
+// means it — and the symptom is a data-exposure bug: the retirement predicate
+// compares every row against a state no row is ever in, so every row stays
+// visible to every caller while the annotation sits on the schema looking like
+// enforcement. That is returned as a failure for the caller to raise on.
+//
+// It is the same fault the PPX already refuses to compile when the enum is
+// declared in the same file, and the PPX says so in its own message. This is the
+// residue that a per-file pass cannot reach: field form, enum imported from
+// elsewhere. Two rungs of one ladder — until this was promoted, which rung you
+// landed on decided whether a data-exposure bug stopped the build, and the
+// arbiter was where the enum happened to be declared.
+//
+// **A `value` on a field that is not the record's lifecycle stays a warning.**
+// It would keep the read narrowing while silently losing the command filtering
+// that motivates it — `@transition` is written in terms of the lifecycle field,
+// so a retirement state anywhere else is a state no command can name. That is a
+// modelling judgement rather than a wrong name, and judgement calls are what the
+// withdrawn dead-end rule taught us not to hard-fail on.
+let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): retiredCheck =>
   switch retiredFromStateSchema(stateSchema) {
+  // The boolean form names no state, so there is nothing to compare. Not a skip.
+  | None | Some({values: None}) => NotDeclared
   | Some({field, values: Some(values)}) =>
-    let named = values->Array.joinWith(", ")
+    let named = values->Array.join(", ")
     let lifecycle = lifecycleFieldFromStateSchema(~entityName, stateSchema)
     if lifecycle != Some(field) {
       log.warn(
@@ -129,7 +167,7 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =
           ->Option.map(f => ` (that is "${f}")`)
           ->Option.getOr(
             " (it declares none)",
-          )}. A retirement state no command's @allowedStates can name loses the command filtering the state form exists for.`,
+          )}. A retirement state no command's @transition can name loses the command filtering the state form exists for.`,
       )
     }
     let declared = switch stateSchema {
@@ -146,24 +184,292 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =
       ->Option.getOr([])
     | _ => []
     }
-    // Reported per state rather than as a set: one wrong entry among three still
-    // narrows something, so the symptom is a subset of rows leaking rather than
-    // all of them — which is harder to spot than the single-value case was.
-    if Array.length(declared) > 0 {
-      values
-      ->Array.filter(v => !(declared->Array.includes(v)))
-      ->Array.forEach(v =>
-        log.warn(
-          ~comp="Plugin_Structure",
-          `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.joinWith(
-              ", ",
-            )}.`,
-        )
+    if Array.length(declared) == 0 {
+      Unchecked(
+        `${entityName}: @retired(${named}) is on "${field}", whose shape carries no cases to check the names against.`,
+      )
+    } else {
+      // Reported per state rather than as a set: one wrong entry among three still
+      // narrows something, so the symptom is a subset of rows leaking rather than
+      // all of them — which is harder to spot than the single-value case was.
+      Checked(
+        values
+        ->Array.filter(v => !(declared->Array.includes(v)))
+        ->Array.map(
+          v =>
+            `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.join(
+                ", ",
+              )}.`,
+        ),
       )
     }
-  | _ => ()
   }
 
+// Raised together, after every view has been walked, so an author sees every bad
+// name at once rather than the first one and then a rebuild.
+//
+// Retroactive in a way the transition check was not: `@transition` was new when
+// its check landed, so nothing deployed could carry a stale name, while `@retired`
+// has been shipping. A deployed plugin holding a misspelled retired value gets a
+// red build on its next deploy — which is the point, and is why the examples were
+// swept before this was promoted.
+let reportRetiredStates = (
+  ~pluginName: string,
+  ~failures: array<string>,
+  ~unchecked: array<string>,
+): unit => {
+  if Array.length(unchecked) > 0 {
+    log.warn(
+      ~comp="Plugin_Structure",
+      `${pluginName}: ${unchecked
+        ->Array.length
+        ->Int.toString} @retired declaration(s) could not be checked.\n` ++
+      unchecked->Array.join("\n"),
+    )
+  }
+  if Array.length(failures) > 0 {
+    JsError.throwWithMessage(
+      `${pluginName}: @retired names states that do not exist.\n` ++ failures->Array.join("\n"),
+    )
+  }
+}
+
+// The states a record's lifecycle field can hold. The same extraction
+// `checkRetiredValue` does, keyed on the declared lifecycle field rather than the
+// retired one — which is the field a command's `@transition` is written in terms
+// of. `None` means the record declares no lifecycle at all; `Some([])` means it
+// declares one whose shape carries no cases to compare against.
+let lifecycleStatesFromStateSchema = (
+  ~entityName: string,
+  stateSchema: S.t<unknown>,
+): option<array<string>> =>
+  lifecycleFieldFromStateSchema(~entityName, stateSchema)->Option.flatMap(field =>
+    switch stateSchema {
+    | Object({items}) =>
+      items
+      ->Array.find(item => item.location == field)
+      ->Option.map(item =>
+        switch shapeOfItem(~entityName, item) {
+        | Enum(_, values) => values
+        | Nullable(Enum(_, values)) => values
+        | _ => []
+        }
+      )
+    | _ => None
+    }
+  )
+
+// The other check the PPX cannot make, and the reason `@transition` is worth
+// more than a rename.
+//
+// A command declares the states it may run from and the state it lands in, but
+// those states belong to ANOTHER component's lifecycle enum. The PPX only ever
+// sees them as names — it strips the attribute before the typechecker, and a
+// synthetic reference to the constructor does not survive ReScript's pre-PPX
+// dependency walk. So a misspelled state compiles clean, ships, and produces a
+// command that is legal in a state no row is ever in: a menu entry that never
+// appears, with nothing anywhere saying why.
+//
+// Here both sides are in hand. This runs at plugin-structure assembly, which
+// happens in the deploy program and at local-platform start — never inside a
+// deployed Lambda, which reads a persisted structure rather than building one.
+// So raising is a failed deploy, not a dead function.
+//
+// Two severities, and the split is deliberate:
+//   - a state the linked views do not declare  → RAISE. The author named
+//     something that does not exist.
+//   - no resolvable linked view, or none declaring a lifecycle → warn. The
+//     metadata gap is real but hard-failing on it would turn "this plugin's
+//     views could not be resolved" into a deploy outage, and that population is
+//     broad.
+//
+// Checked against the UNION of the linked views' lifecycles rather than a single
+// view: a command whose slice feeds two views is not claiming which one, and
+// failing on an ambiguity the author never expressed would be a false positive
+// on correct code.
+let checkDeclaredTransitions = (
+  ~pluginName: string,
+  ~writables: array<Reventless.Plugin.writableDef>,
+  ~lifecycleStatesByView: dict<array<string>>,
+): unit => {
+  let unvalidated = ref(0)
+  let failures = []
+
+  writables->Array.forEach(w =>
+    w.commands->Array.forEach(cmd => {
+      let declared = Array.concat(
+        cmd.allowedStates->Option.getOr([]),
+        switch cmd.targetState {
+        | Some(t) => [t]
+        | None => []
+        },
+      )
+      if Array.length(declared) > 0 {
+        let known =
+          w.linkedViews->Array.reduce([], (acc, view) =>
+            switch lifecycleStatesByView->Dict.get(view) {
+            | Some(states) => Array.concat(acc, states)
+            | None => acc
+            }
+          )
+        if Array.length(known) == 0 {
+          unvalidated := unvalidated.contents + 1
+        } else {
+          declared
+          ->Array.filter(state => !(known->Array.includes(state)))
+          ->Array.forEach(state =>
+            failures
+            ->Array.push(
+              `${w.name}.${cmd.name}: @transition names "${state}", which none of its ` ++
+              `linked views declare — ${w.linkedViews->Array.join(
+                  ", ",
+                )} know ${known->Array.join(", ")}.`,
+            )
+            ->ignore
+          )
+        }
+      }
+    })
+  )
+
+  // Reported rather than silent: a plugin nothing could be checked against looks
+  // exactly like a plugin that passed, and that population is the one most
+  // likely to be carrying a stale name.
+  if unvalidated.contents > 0 {
+    log.warn(
+      ~comp="Plugin_Structure",
+      `${pluginName}: ${unvalidated.contents->Int.toString} command(s) declare a @transition ` ++
+      `but no linked view declares a lifecycle to check it against.`,
+    )
+  }
+
+  if Array.length(failures) > 0 {
+    JsError.throwWithMessage(
+      `${pluginName}: @transition names states that do not exist.\n` ++
+      failures->Array.join("\n"),
+    )
+  }
+}
+
+// Beyond "does this state exist" — does the declared graph make sense?
+//
+// A separate pass from the name check on purpose. That one asks whether a name
+// is a case of an enum, which is a question about one annotation in isolation.
+// These ask whether the annotations AGREE with each other across an entity, and
+// a graph can be built entirely out of valid names and still be wrong: a state
+// nothing reaches, or one nothing can leave that was never marked as an ending.
+//
+// Reported as warnings rather than raised. The name check fails a build because
+// a state that does not exist is unambiguously a mistake — there is no domain in
+// which it is what the author meant. These are weaker signals: a state with no
+// way out may be a genuine dead end nobody has marked yet, or a legitimate
+// terminal the model reaches by a route this metadata cannot see (an automation,
+// an external system). Failing a deploy on a modelling smell would be the wrong
+// trade, and a smell that stops a deploy gets silenced rather than fixed.
+// Pure, and returns its findings rather than logging them, so the rule can be
+// tested without reading a log. `checkLifecycleTopology` below is the thin part
+// that reports them.
+let lifecycleTopologyFindings = (
+  ~writables: array<Reventless.Plugin.writableDef>,
+  ~lifecycleStatesByView: dict<array<string>>,
+): array<(string, string)> => {
+  let findings = []
+  lifecycleStatesByView
+  ->Dict.toArray
+  ->Array.forEach(((view, states)) => {
+    // Every edge any command declares into or out of this view's lifecycle.
+    let edges = writables->Array.reduce([], (acc, w) =>
+      w.linkedViews->Array.includes(view)
+        ? Array.concat(
+            acc,
+            w.commands->Array.reduce([], (inner, cmd) =>
+              switch (cmd.allowedStates, cmd.targetState) {
+              | (Some(froms), Some(to)) =>
+                Array.concat(inner, froms->Array.map(from => (from, to)))
+              | _ => inner
+              }
+            ),
+          )
+        : acc
+    )
+    if Array.length(edges) > 0 {
+      // Rows start in the first declared state — the same convention the
+      // lifecycle diagram uses — so nothing pointing at it is expected rather
+      // than suspicious.
+      let initial = states->Array.get(0)
+      let reachable = edges->Array.map(((_, to)) => to)
+
+      states->Array.forEach(state => {
+        if !(reachable->Array.includes(state)) && Some(state) != initial {
+          findings
+          ->Array.push((
+            view,
+            `no command declares a transition INTO "${state}" — it is unreachable ` ++
+            `unless something outside this plugin's declarations puts a row there.`,
+          ))
+          ->ignore
+        }
+        // NOT checked: a state with no way out.
+        //
+        // The obvious second rule — "a dead end that is not `@retired` is
+        // suspicious" — was written, run against the shipped examples, and
+        // removed, because it is wrong twice over.
+        //
+        // It fires on correct models: `Shipped` and `Refunded` are terminal in
+        // the aggregates shop, as terminal states are in most lifecycles, and
+        // there is nothing to fix about either.
+        //
+        // Worse, its suggested fix is harmful. `@retired` does not mean
+        // "terminal" — it means WITHDRAWN FROM ORDINARY READS. Marking a shipped
+        // order retired to silence a lint would hide every shipped order from
+        // every caller who cannot widen their read. An ending and a withdrawal
+        // are different facts, and nothing in the vocabulary currently
+        // distinguishes an intentional terminal from an accidental one, so the
+        // check cannot tell them apart and should not pretend to.
+      })
+    }
+  })
+  findings
+}
+
+let checkLifecycleTopology = (
+  ~pluginName: string,
+  ~writables: array<Reventless.Plugin.writableDef>,
+  ~lifecycleStatesByView: dict<array<string>>,
+): unit =>
+  lifecycleTopologyFindings(~writables, ~lifecycleStatesByView)->Array.forEach(((view, message)) =>
+    log.warn(~comp="Plugin_Structure", `${pluginName}/${view}: ${message}`)
+  )
+
+// NOT here: the event-consumption completeness check.
+//
+// The failure it would catch is real and has already happened: a command emitted
+// an event, the slice that owned the opposite command folded it, and the view
+// that renders the entity did not — so the row kept rendering the state it was
+// in before, with every annotation in the plugin correct. That is a class of bug
+// no declaration check can see, because nothing declared is wrong.
+//
+// It is not computable from this metadata, and the reason is worth recording so
+// the attempt is not repeated. Two narrowings were needed and only one was
+// available:
+//
+//   1. The event must belong to the view's own entity, not merely be something a
+//      slice looked up. Available: require it to be PRODUCED by a writable
+//      linked to the same view. Without this the check fires on ordinary DCB —
+//      `AddProduct` folds `CategoryAdded` to check a category exists, and the
+//      `Products` view is right to ignore it.
+//
+//   2. The slice must be known to fold the event. NOT available:
+//      `consumedEventTypes` is built from `eventVariantNames`, which drops
+//      payload-less variants — and a lifecycle-moving event is usually
+//      payload-less in the slice that folds it. Measured on the shipped example:
+//      both order slices publish `consumedEventTypes: ["Ordering.OrderPlaced"]`
+//      and nothing else, though each folds three more.
+//
+// So the exact events the rule is about are the ones the metadata does not
+// record. Making it work means publishing the payload-less consumed variants,
+// which is a platform change with its own consequences, not a lint.
+
 // Which rung of the ladder below produced the label. Published on `queryableDef`
 // as `labelFieldSource`, because the four rungs are not equally believable and a
 // consumer with a name rule of its own has to rank the declaration against it:
@@ -338,7 +644,7 @@ let make = (
   // spec name has no entry (or lives directly under a kind-folder) carries no chapter
   // and renders flat. Keyed by `Spec.name`, which equals the source filename stem for
   // every graph-node kind, so the generator can build this map from the discovered
-  // file paths. See `Codegen.chapterOf` and docs/plans/deployed-chapter-grouping.md.
+  // file paths. See `Codegen.chapterOf` and docs/plans/done/deployed-chapter-grouping.md.
   ~componentChapters: dict<string>=Dict.make(),
 ): Reventless.Plugin.pluginStructure => {
   let chapterOf = (compName: string): option<string> => componentChapters->Dict.get(compName)
@@ -454,9 +760,9 @@ let make = (
       // Per-variant `allowedStates` lives on the *parent* command schema
       // (the PPX attaches a single dict<variantName, [|states|]> via
       // markAllowedStates). Look it up by variant name; back-compat
-      // None when the variant lacks an @allowedStates annotation.
+      // None when the variant lacks a @transition annotation.
       let allowedStates = ApiAllowedStatesHelpers.getAllowedStates(parentSchema, ~variantName)
-      // Declared `@targetState` (the command's *to* status), read the same way
+      // The `@transition` target (the command's *to* status), read the same way
       // as allowedStates. None ⇒ AutoUI's board resolver falls back to its
       // name-stem heuristic.
       let targetState = ApiTargetStateHelpers.getTargetState(parentSchema, ~variantName)
@@ -824,6 +1130,28 @@ let make = (
     | Internal => Some("Internal")
     }
 
+  // View name -> the states its lifecycle field can hold, collected as the view
+  // defs are built so the transition check below has both sides in one place.
+  let lifecycleStatesByView: dict<array<string>> = Dict.make()
+  let recordLifecycle = (~entityName, stateSchema) => {
+    switch lifecycleStatesFromStateSchema(~entityName, stateSchema) {
+    | Some(states) if Array.length(states) > 0 =>
+      lifecycleStatesByView->Dict.set(entityName, states)
+    | _ => ()
+    }
+  }
+
+  // Collected as the view defs are built and reported once, so a plugin with
+  // three bad names fails naming three rather than one at a time.
+  let retiredFailures = []
+  let retiredUnchecked = []
+  let recordRetired = (~entityName, stateSchema) =>
+    switch checkRetiredValue(~entityName, stateSchema) {
+    | NotDeclared => ()
+    | Unchecked(why) => retiredUnchecked->Array.push(why)->ignore
+    | Checked(failures) => failures->Array.forEach(f => retiredFailures->Array.push(f)->ignore)
+    }
+
   let readModelDefs =
     readModels
     ->Array.map((
@@ -843,7 +1171,8 @@ let make = (
       // edges for any event reaching the read model via a DCB-log-sourced mapping (a classic
       // aggregate→view link is also drawn from the producer's linkedViews, deduped downstream).
       let consumed = qualify(~prefix=name, R.consumedEventNames)
-      checkRetiredValue(~entityName=R.Spec.name, stateSchema)
+      recordRetired(~entityName=R.Spec.name, stateSchema)
+      recordLifecycle(~entityName=R.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: R.Spec.name,
         queryField: qf.listFieldName,
@@ -859,6 +1188,7 @@ let make = (
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
         retiredField: retiredFieldFromStateSchema(stateSchema),
         retiredValues: retiredValuesFromStateSchema(stateSchema),
+        namedWhenRetired: Some(namedWhenRetiredFromStateSchema(stateSchema)),
         visibility: visibilityTag(R.Spec.visibility),
         chapter: chapterOf(R.Spec.name),
         // Taken from the `qf` record, never re-derived: `Api_Naming` is the only
@@ -881,7 +1211,8 @@ let make = (
         ~entityName=SVS.Spec.name,
         stateSchema,
       )
-      checkRetiredValue(~entityName=SVS.Spec.name, stateSchema)
+      recordRetired(~entityName=SVS.Spec.name, stateSchema)
+      recordLifecycle(~entityName=SVS.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: SVS.Spec.name,
         queryField: qf.listFieldName,
@@ -895,6 +1226,7 @@ let make = (
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
         retiredField: retiredFieldFromStateSchema(stateSchema),
         retiredValues: retiredValuesFromStateSchema(stateSchema),
+        namedWhenRetired: Some(namedWhenRetiredFromStateSchema(stateSchema)),
         visibility: visibilityTag(SVS.Spec.visibility),
         chapter: chapterOf(SVS.Spec.name),
         singleQueryField: Some(qf.singleFieldName),
@@ -1052,6 +1384,23 @@ let make = (
       commandTypes: Some(dedupe(cmds)),
     }: Reventless.Plugin.extensionPointDef))
 
+  // Second pass, on purpose: commands are built well before `linkedViews` is
+  // assembled, so the check cannot run inline where the defs are made.
+  checkDeclaredTransitions(
+    ~pluginName=name,
+    ~writables=Array.concat(stateChangeDefs, aggregateDefs),
+    ~lifecycleStatesByView,
+  )
+  checkLifecycleTopology(
+    ~pluginName=name,
+    ~writables=Array.concat(stateChangeDefs, aggregateDefs),
+    ~lifecycleStatesByView,
+  )
+  // Also a second pass, for a different reason: the failures are gathered per
+  // view as those defs are built, and raising inline would report the first bad
+  // name and hide the rest.
+  reportRetiredStates(~pluginName=name, ~failures=retiredFailures, ~unchecked=retiredUnchecked)
+
   {
     readModels: readModelDefs,
     stateViewSlices: stateViewDefs,