@reventlessdev/reventless-spec 3.0.0-alpha.129 → 3.0.0-alpha.131

package/src/lifecycle/loadPluginStructure.mjs

@@ -0,0 +1,66 @@
+// Reading a built plugin's declared structure.
+//
+// A plugin's generated definition module is a functor over the platform type
+// that exposes `pluginStructure` as an ordinary value, and the local platform's
+// `Make` takes no configuration — so applying one to the other is enough to hold
+// a real structure. No deploy program, no database, no server, nothing left
+// running.
+//
+// This lives in a companion `.mjs` because it is untyped reflection: `import` is
+// syntax rather than a value, so a computed specifier cannot be bound as an
+// external, and the value that comes back is shaped by the plugin rather than by
+// anything this repository can name.
+//
+// The structure is handed back as plain JSON and read field by field on the
+// ReScript side, rather than parsed through the published schema. A
+// `pluginStructure` has two legitimate representations — an absent optional is
+// `undefined` in memory and an explicit `null` on the wire — and the published
+// schema describes the wire form, so validating an in-memory structure against
+// it fails on every optional that happens to be empty.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const localPlatformPath = (pluginDir) =>
+  join(
+    pluginDir,
+    "node_modules/@reventlessdev/reventless-local/src/Platform.res.mjs",
+  );
+
+const pluginEntryPath = (pluginDir) => join(pluginDir, "src/Plugin.res.mjs");
+
+/**
+ * @returns {Promise<{ok: true, structure: unknown} | {ok: false, error: string}>}
+ */
+export const loadPluginStructure = async (pluginDir) => {
+  const entry = pluginEntryPath(pluginDir);
+  const local = localPlatformPath(pluginDir);
+  if (!existsSync(entry)) {
+    return {
+      ok: false,
+      error: `no compiled plugin at ${entry} — build the plugin first`,
+    };
+  }
+  if (!existsSync(local)) {
+    return {
+      ok: false,
+      error: `no local platform installed at ${local}`,
+    };
+  }
+  try {
+    const localMod = await import(local);
+    const pluginMod = await import(entry);
+    const structure = pluginMod.Make(localMod.Make()).pluginStructure;
+    // A structure whose component arrays are absent came from a release this
+    // reader cannot understand. Saying so beats reporting a model that is
+    // quietly half-empty.
+    const present = ["readModels", "stateViewSlices", "stateChangeSlices", "aggregates"].every(
+      (k) => Array.isArray(structure?.[k]),
+    );
+    return present
+      ? { ok: true, structure }
+      : { ok: false, error: "the plugin structure declares no component arrays" };
+  } catch (e) {
+    const message = e && (e.message || e.RE_EXN_ID) ? String(e.message || e.RE_EXN_ID) : "unknown error";
+    return { ok: false, error: `reading the plugin structure: ${message}` };
+  }
+};

package/src/types/Transition.res

@@ -36,10 +36,23 @@
 // plugin structure is assembled, and what leaves is the pair of names the
 // structure already carried.
 type t<'state> =
-  /** No edge declared: legal in every state, moves the row nowhere. The honest
-      answer for a report a slice publishes, which must not be refused because
-      the row moved on while the report was in flight. */
+  /** Legal in every state, and moves the row nowhere. The honest answer for a
+      report a slice publishes, which must not be refused because the row moved
+      on while the report was in flight. A claim, not an omission — see
+      `Undeclared`, which is the omission. */
   | Unrestricted
+  /** The spec wrote no switch, and the ppx injected this. Never write it: say
+      `Unrestricted` if you mean the command is legal everywhere.
+
+      It reads exactly like `Unrestricted` — no from-set, no target — everywhere
+      but one place, and that place is why it exists. The harvested lifecycle
+      model may answer for silence; it may not narrow a claim. A corpus only
+      covers the states somebody wrote a scenario for, so letting it answer for
+      `Unrestricted` would shrink "legal in every state" down to an accident of
+      coverage, and the command would quietly stop being offered on the rows
+      nobody tested. With the two spelled apart, that shrinkage cannot happen and
+      a scenario that genuinely refutes the claim is a contradiction instead. */
+  | Undeclared
   /** Brings the row into existence, so there is no state it could come from.
       Distinct from `Unrestricted`, which draws no edge at all. */
   | Creates('state)
@@ -54,6 +67,7 @@ type t<'state> =
     tells apart. */
 let allowedStates = (transition: t<'state>): option<array<'state>> =>
   switch transition {
+  | Undeclared
   | Unrestricted
   | Creates(_) => None
   | Guards(states)
@@ -63,8 +77,21 @@ let allowedStates = (transition: t<'state>): option<array<'state>> =>
 /** The state the command's handler writes, or `None` for one that moves nothing. */
 let targetState = (transition: t<'state>): option<'state> =>
   switch transition {
+  | Undeclared
   | Unrestricted
   | Guards(_) => None
   | Creates(state)
   | Moves(_, state) => Some(state)
   }
+
+/** Whether the command is claimed legal in every state, as opposed to nothing
+    being claimed at all. The two erase to the same pair of `None`s above, so this
+    is the only thing that can tell a reader of the erased form which it holds. */
+let isUnrestricted = (transition: t<'state>): bool =>
+  switch transition {
+  | Unrestricted => true
+  | Undeclared
+  | Creates(_)
+  | Guards(_)
+  | Moves(_, _) => false
+  }

package/src/types/Transition.res.mjs

@@ -7,11 +7,11 @@ function allowedStates(transition) {
     return;
   }
   switch (transition.TAG) {
-    case "Creates" :
-      return;
     case "Guards" :
     case "Moves" :
       return transition._0;
+    default:
+      return;
   }
 }
 
@@ -22,15 +22,24 @@ function targetState(transition) {
   switch (transition.TAG) {
     case "Creates" :
       return Primitive_option.some(transition._0);
-    case "Guards" :
-      return;
     case "Moves" :
       return Primitive_option.some(transition._1);
+    default:
+      return;
+  }
+}
+
+function isUnrestricted(transition) {
+  if (typeof transition !== "object") {
+    return transition === "Unrestricted";
+  } else {
+    return false;
   }
 }
 
 export {
   allowedStates,
   targetState,
+  isUnrestricted,
 }
 /* No side effect */