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

package/src/plugin/component/Plugin_Structure.res.mjs

@@ -39,7 +39,7 @@ function isLabelShape(_t) {
   };
 }
 
-function isStatusShape(_t) {
+function isLifecycleShape(_t) {
   while (true) {
     let t = _t;
     if (typeof t !== "object") {
@@ -68,15 +68,15 @@ function shapeOfItem(entityName, item) {
   return SchemaType$ReventlessCore.fromSury(entityName, item.location, item.schema);
 }
 
-function statusFieldFromStateSchema(entityName, stateSchema) {
+function lifecycleFieldFromStateSchema(entityName, stateSchema) {
   let spec = StateAnnotations$Reventless.getSpec(stateSchema);
-  let annotated = spec !== undefined ? spec.status : undefined;
+  let annotated = spec !== undefined ? spec.lifecycle : undefined;
   if (annotated !== undefined) {
     return annotated;
   } else if (stateSchema.type === "object") {
     return Stdlib_Option.map(stateSchema.items.find(item => {
-      if (item.location === "status") {
-        return isStatusShape(shapeOfItem(entityName, item));
+      if (item.location === "lifecycle") {
+        return isLifecycleShape(shapeOfItem(entityName, item));
       } else {
         return false;
       }
@@ -86,6 +86,64 @@ function statusFieldFromStateSchema(entityName, stateSchema) {
   }
 }
 
+function retiredFromStateSchema(stateSchema) {
+  let spec = StateAnnotations$Reventless.getSpec(stateSchema);
+  if (spec !== undefined) {
+    return spec.retired;
+  }
+}
+
+function retiredFieldFromStateSchema(stateSchema) {
+  return Stdlib_Option.map(retiredFromStateSchema(stateSchema), r => r.field);
+}
+
+function retiredValuesFromStateSchema(stateSchema) {
+  return Stdlib_Option.flatMap(retiredFromStateSchema(stateSchema), r => r.values);
+}
+
+function checkRetiredValue(entityName, stateSchema) {
+  let match = retiredFromStateSchema(stateSchema);
+  if (match === undefined) {
+    return;
+  }
+  let values = match.values;
+  if (values === undefined) {
+    return;
+  }
+  let field = match.field;
+  let named = values.join(", ");
+  let lifecycle = lifecycleFieldFromStateSchema(entityName, stateSchema);
+  if (Primitive_object.notequal(lifecycle, field)) {
+    log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + named + `) is on "` + field + `", which is not this record's lifecycle field` + Stdlib_Option.getOr(Stdlib_Option.map(lifecycle, f => ` (that is "` + f + `")`), " (it declares none)") + `. A retirement state no command's @allowedStates can name loses the command filtering the state form exists for.`);
+  }
+  let declared;
+  declared = stateSchema.type === "object" ? Stdlib_Option.getOr(Stdlib_Option.map(stateSchema.items.find(item => item.location === field), item => {
+      let match = shapeOfItem(entityName, item);
+      if (typeof match !== "object") {
+        return [];
+      }
+      switch (match.TAG) {
+        case "Nullable" :
+          let match$1 = match._0;
+          if (typeof match$1 !== "object") {
+            return [];
+          } else if (match$1.TAG === "Enum") {
+            return match$1._1;
+          } else {
+            return [];
+          }
+        case "Enum" :
+          return match._1;
+        default:
+          return [];
+      }
+    }), []) : [];
+  if (declared.length !== 0) {
+    values.filter(v => !declared.includes(v)).forEach(v => log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + v + `) names a state "` + field + `" does not declare — known values: ` + declared.join(", ") + `.`));
+    return;
+  }
+}
+
 function labelFieldSourceToString(s) {
   switch (s) {
     case "Annotation" :
@@ -535,6 +593,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let label = labelFieldsFromStateSchema(R.Spec.name, stateSchema);
     let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(R.Spec.name, stateSchema);
     let consumed = qualify(name, R.consumedEventNames);
+    checkRetiredValue(R.Spec.name, stateSchema);
     return {
       name: R.Spec.name,
       queryField: qf.listFieldName,
@@ -544,8 +603,10 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelField: label.field,
       searchableFields: label.searchableFields,
       labelFieldSource: labelFieldSourceToString(label.source),
-      statusField: statusFieldFromStateSchema(R.Spec.name, stateSchema),
+      lifecycleField: lifecycleFieldFromStateSchema(R.Spec.name, stateSchema),
       ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
+      retiredField: retiredFieldFromStateSchema(stateSchema),
+      retiredValues: retiredValuesFromStateSchema(stateSchema),
       visibility: visibilityTag(R.Spec.visibility),
       chapter: componentChapters[R.Spec.name],
       singleQueryField: qf.singleFieldName,
@@ -561,6 +622,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let stateSchema = SVS.Spec.stateSchema;
     let label = labelFieldsFromStateSchema(SVS.Spec.name, stateSchema);
     let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(SVS.Spec.name, stateSchema);
+    checkRetiredValue(SVS.Spec.name, stateSchema);
     return {
       name: SVS.Spec.name,
       queryField: qf.listFieldName,
@@ -570,8 +632,10 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelField: label.field,
       searchableFields: label.searchableFields,
       labelFieldSource: labelFieldSourceToString(label.source),
-      statusField: statusFieldFromStateSchema(SVS.Spec.name, stateSchema),
+      lifecycleField: lifecycleFieldFromStateSchema(SVS.Spec.name, stateSchema),
       ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
+      retiredField: retiredFieldFromStateSchema(stateSchema),
+      retiredValues: retiredValuesFromStateSchema(stateSchema),
       visibility: visibilityTag(SVS.Spec.visibility),
       chapter: componentChapters[SVS.Spec.name],
       singleQueryField: qf.singleFieldName,
@@ -689,10 +753,14 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
 export {
   log,
   isLabelShape,
-  isStatusShape,
+  isLifecycleShape,
   conventionalLabelNames,
   shapeOfItem,
-  statusFieldFromStateSchema,
+  lifecycleFieldFromStateSchema,
+  retiredFromStateSchema,
+  retiredFieldFromStateSchema,
+  retiredValuesFromStateSchema,
+  checkRetiredValue,
   labelFieldSourceToString,
   labelFieldsFromStateSchema,
   extractReferences,

package/src/plugin/lifecycle/PluginsReadModelSpec.res.mjs

@@ -48,10 +48,11 @@ let stateSchema$1 = S.Metadata.set(stateSchema, StateAnnotations$Reventless.stat
   scanSort: [],
   semantic: [],
   metric: [],
-  status: undefined,
+  lifecycle: undefined,
   groupBy: "kind",
   visibility: undefined,
-  live: undefined
+  live: undefined,
+  retired: undefined
 });
 
 let name = "Plugins";

package/tests/admin/Platform_Admin_StructureTest.res

@@ -0,0 +1,49 @@
+// The platform's own admin components, as `Platform_ComponentDefinitions` serves
+// them. The Plugins read model is a framework-generated queryable: its field names
+// are chosen here and read by every client, so the rule that applies to it is the
+// opposite of the one that applies to an authored record.
+//
+// An authored record may follow the convention — name the field `lifecycle` and
+// write no annotation. A generated row cannot, because its field name is a
+// published wire name: `status` in the SDL, in stored QueryDb rows, and in any
+// client selecting it. Renaming it to satisfy a convention would move the
+// contract, break selecting clients and require re-projection. So it declares
+// instead, and the declaration is what this asserts — the failure mode otherwise
+// is silent (a board loses its columns, a command menu stops filtering, and
+// nothing fails to compile).
+
+open JestGlobals
+open Reventless.Plugin
+
+describe("the Plugins read model declares its lifecycle", () => {
+  let rm: queryableDef = Platform_Admin_Structure.pluginReadModel
+
+  testSync("names the field commands branch on", () =>
+    expect(rm.lifecycleField)->toEqual(Some("status"))
+  )
+
+  testSync("and the published wire name is unchanged by the rename", () => {
+    // Stated as its own assertion rather than folded into the one above: the two
+    // say different things. That the field is declared is the fix; that it is
+    // still called `status` is the constraint the fix had to respect.
+    let sdlDeclaresStatus =
+      rm.lifecycleField->Option.mapOr(false, f => f == "status") &&
+        rm.queryField->String.startsWith("Platform_")
+    expect(sdlDeclaresStatus)->toEqual(true)
+  })
+
+  testSync("is served on the encoded def under the new key", () => {
+    let json =
+      rm->Platform_ComponentDefinitionsApi.encodeQueryableDef->JSON.stringify
+    expect(json->String.includes(`"lifecycleField":"status"`))->toEqual(true)
+  })
+
+  testSync("and never under the old one", () =>
+    expect(
+      rm
+      ->Platform_ComponentDefinitionsApi.encodeQueryableDef
+      ->JSON.stringify
+      ->String.includes(`"statusField"`),
+    )->toEqual(false)
+  )
+})

package/tests/admin/Platform_Admin_StructureTest.res.mjs

@@ -0,0 +1,24 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Platform_Admin_Structure$ReventlessCore from "../../src/admin/Platform_Admin_Structure.res.mjs";
+import * as Platform_ComponentDefinitionsApi$ReventlessCore from "../../src/admin/Platform_ComponentDefinitionsApi.res.mjs";
+
+globalThis.describe("the Plugins read model declares its lifecycle", () => {
+  globalThis.test("names the field commands branch on", () => {
+    globalThis.expect(Platform_Admin_Structure$ReventlessCore.pluginReadModel.lifecycleField).toEqual("status");
+  });
+  globalThis.test("and the published wire name is unchanged by the rename", () => {
+    let sdlDeclaresStatus = Stdlib_Option.mapOr(Platform_Admin_Structure$ReventlessCore.pluginReadModel.lifecycleField, false, f => f === "status") && Platform_Admin_Structure$ReventlessCore.pluginReadModel.queryField.startsWith("Platform_");
+    globalThis.expect(sdlDeclaresStatus).toEqual(true);
+  });
+  globalThis.test("is served on the encoded def under the new key", () => {
+    let json = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodeQueryableDef(Platform_Admin_Structure$ReventlessCore.pluginReadModel));
+    globalThis.expect(json.includes(`"lifecycleField":"status"`)).toEqual(true);
+  });
+  globalThis.test("and never under the old one", () => {
+    globalThis.expect(JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodeQueryableDef(Platform_Admin_Structure$ReventlessCore.pluginReadModel)).includes(`"statusField"`)).toEqual(false);
+  });
+});
+
+/*  Not a pure module */

package/tests/admin/Platform_BakedManifestTest.res

@@ -15,7 +15,7 @@ let queryable = (~name, ~visibility=?, ~ownerField=?, ()): queryableDef => {
   labelField: "displayName",
   searchableFields: ["displayName"],
   labelFieldSource: None,
-  statusField: None,
+  lifecycleField: None,
   visibility,
   chapter: None,
   singleQueryField: Some(`Ordering_${name}Single`),
@@ -23,6 +23,8 @@ let queryable = (~name, ~visibility=?, ~ownerField=?, ()): queryableDef => {
   idFieldSource: Some("convention"),
   requiredAccess: None,
   ownerField,
+  retiredField: None,
+  retiredValues: None,
 }
 
 let command = (~name, ~references=[], ~ownerField=?, ()): commandDef => {

package/tests/admin/Platform_BakedManifestTest.res.mjs

@@ -18,8 +18,10 @@ function queryable(name, visibility, ownerField, param) {
     labelField: "displayName",
     searchableFields: ["displayName"],
     labelFieldSource: undefined,
-    statusField: undefined,
+    lifecycleField: undefined,
     ownerField: ownerField,
+    retiredField: undefined,
+    retiredValues: undefined,
     visibility: visibility,
     chapter: undefined,
     singleQueryField: `Ordering_` + name + `Single`,

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -30,7 +30,7 @@ let qbl: queryableDef = {
   labelField: "displayName",
   searchableFields: ["displayName"],
   labelFieldSource: Some("annotation"),
-  statusField: None,
+  lifecycleField: None,
   visibility: None,
   chapter: None,
   singleQueryField: Some("Catalog_Product"),
@@ -38,6 +38,8 @@ let qbl: queryableDef = {
   idFieldSource: Some("convention"),
   requiredAccess: None,
   ownerField: None,
+  retiredField: None,
+  retiredValues: None,
 }
 
 let wbl: writableDef = {
@@ -162,8 +164,8 @@ describe("encodePluginStructureEntry", () => {
     expect(json->String.includes("\"apiExposed\":true"))->toEqual(true)
   )
 
-  testSync("encodes None statusField as null", () =>
-    expect(json->String.includes("\"statusField\":null"))->toEqual(true)
+  testSync("encodes None lifecycleField as null", () =>
+    expect(json->String.includes("\"lifecycleField\":null"))->toEqual(true)
   )
 
   // Phase 6.3: write-side emitted-event field schemas.
@@ -256,7 +258,7 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     labelField: "name",
     searchableFields: ["name"],
     labelFieldSource: Some("convention"),
-    statusField: None,
+    lifecycleField: None,
     visibility: Some("Internal"),
     chapter: None,
     singleQueryField: Some("Ordering_AvailableProduct"),
@@ -264,6 +266,8 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     idFieldSource: Some("sole"),
     requiredAccess: None,
       ownerField: None,
+      retiredField: None,
+      retiredValues: None,
   }
   // A distinct name per source array: the complement has to be fed by both, and
   // reusing one def would hide a version that only walks `readModels`.
@@ -329,7 +333,7 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
   })
 })
 
-describe("allowedStates + statusField populated", () => {
+describe("allowedStates + lifecycleField populated", () => {
   let cmdWithStates: commandDef = {
     name: "Activate",
     schema: "{}",
@@ -353,7 +357,7 @@ describe("allowedStates + statusField populated", () => {
     labelField: "name",
     searchableFields: ["name"],
     labelFieldSource: Some("convention"),
-    statusField: Some("status"),
+    lifecycleField: Some("status"),
     visibility: None,
     chapter: None,
     singleQueryField: Some("Platform_Plugin"),
@@ -361,6 +365,8 @@ describe("allowedStates + statusField populated", () => {
     idFieldSource: None,
     requiredAccess: None,
       ownerField: None,
+      retiredField: None,
+      retiredValues: None,
   }
 
   let wblWithStates: writableDef = {
@@ -402,8 +408,8 @@ describe("allowedStates + statusField populated", () => {
     expect(json->String.includes("\"targetState\":\"Active\""))->toEqual(true)
   )
 
-  testSync("encodes populated statusField as the field name string", () =>
-    expect(json->String.includes("\"statusField\":\"status\""))->toEqual(true)
+  testSync("encodes populated lifecycleField as the field name string", () =>
+    expect(json->String.includes("\"lifecycleField\":\"status\""))->toEqual(true)
   )
 
   // "declares no errors" is an empty list, never null — the SDL types `errors` as

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -51,8 +51,10 @@ let qbl = {
   labelField: "displayName",
   searchableFields: qbl_searchableFields,
   labelFieldSource: qbl_labelFieldSource,
-  statusField: undefined,
+  lifecycleField: undefined,
   ownerField: undefined,
+  retiredField: undefined,
+  retiredValues: undefined,
   visibility: undefined,
   chapter: undefined,
   singleQueryField: qbl_singleQueryField,
@@ -198,8 +200,8 @@ globalThis.describe("encodePluginStructureEntry", () => {
   globalThis.test("encodes the command's apiExposed flag (drives the event-graph API badge)", () => {
     globalThis.expect(json.includes("\"apiExposed\":true")).toEqual(true);
   });
-  globalThis.test("encodes None statusField as null", () => {
-    globalThis.expect(json.includes("\"statusField\":null")).toEqual(true);
+  globalThis.test("encodes None lifecycleField as null", () => {
+    globalThis.expect(json.includes("\"lifecycleField\":null")).toEqual(true);
   });
   globalThis.test("encodes writableDef events", () => {
     globalThis.expect(json.includes("\"events\":[{\"name\":\"ProductAdded\"")).toEqual(true);
@@ -282,8 +284,10 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     labelField: "name",
     searchableFields: internalQbl_searchableFields,
     labelFieldSource: internalQbl_labelFieldSource,
-    statusField: undefined,
+    lifecycleField: undefined,
     ownerField: undefined,
+    retiredField: undefined,
+    retiredValues: undefined,
     visibility: internalQbl_visibility,
     chapter: undefined,
     singleQueryField: internalQbl_singleQueryField,
@@ -308,8 +312,10 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     labelField: "name",
     searchableFields: internalSlice_searchableFields,
     labelFieldSource: internalSlice_labelFieldSource,
-    statusField: undefined,
+    lifecycleField: undefined,
     ownerField: undefined,
+    retiredField: undefined,
+    retiredValues: undefined,
     visibility: internalSlice_visibility,
     chapter: undefined,
     singleQueryField: internalSlice_singleQueryField,
@@ -378,7 +384,7 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
   });
 });
 
-globalThis.describe("allowedStates + statusField populated", () => {
+globalThis.describe("allowedStates + lifecycleField populated", () => {
   let cmdWithStates_aggregateIdField = "id";
   let cmdWithStates_references = [];
   let cmdWithStates_allowedStates = ["Inactive"];
@@ -401,7 +407,7 @@ globalThis.describe("allowedStates + statusField populated", () => {
   let qblWithStatus_linkedWriteSide = ["Plugin"];
   let qblWithStatus_searchableFields = ["name"];
   let qblWithStatus_labelFieldSource = "convention";
-  let qblWithStatus_statusField = "status";
+  let qblWithStatus_lifecycleField = "status";
   let qblWithStatus_singleQueryField = "Platform_Plugin";
   let qblWithStatus = {
     name: "Plugin",
@@ -412,8 +418,10 @@ globalThis.describe("allowedStates + statusField populated", () => {
     labelField: "name",
     searchableFields: qblWithStatus_searchableFields,
     labelFieldSource: qblWithStatus_labelFieldSource,
-    statusField: qblWithStatus_statusField,
+    lifecycleField: qblWithStatus_lifecycleField,
     ownerField: undefined,
+    retiredField: undefined,
+    retiredValues: undefined,
     visibility: undefined,
     chapter: undefined,
     singleQueryField: qblWithStatus_singleQueryField,
@@ -466,8 +474,8 @@ globalThis.describe("allowedStates + statusField populated", () => {
   globalThis.test("round-trips a declared targetState as the status string", () => {
     globalThis.expect(json.includes("\"targetState\":\"Active\"")).toEqual(true);
   });
-  globalThis.test("encodes populated statusField as the field name string", () => {
-    globalThis.expect(json.includes("\"statusField\":\"status\"")).toEqual(true);
+  globalThis.test("encodes populated lifecycleField as the field name string", () => {
+    globalThis.expect(json.includes("\"lifecycleField\":\"status\"")).toEqual(true);
   });
   globalThis.test("encodes a component with no declared errors as an empty array, not null", () => {
     globalThis.expect(json.includes("\"errors\":[]")).toEqual(true);
@@ -491,8 +499,10 @@ globalThis.describe("singleQueryField reaches the caller", () => {
           labelField: "displayName",
           searchableFields: qbl_searchableFields,
           labelFieldSource: "annotation",
-          statusField: undefined,
+          lifecycleField: undefined,
           ownerField: undefined,
+          retiredField: undefined,
+          retiredValues: undefined,
           visibility: undefined,
           chapter: undefined,
           singleQueryField: undefined,
@@ -536,8 +546,10 @@ globalThis.describe("idField / idFieldSource reach the caller", () => {
           labelField: "displayName",
           searchableFields: qbl_searchableFields,
           labelFieldSource: "annotation",
-          statusField: undefined,
+          lifecycleField: undefined,
           ownerField: undefined,
+          retiredField: undefined,
+          retiredValues: undefined,
           visibility: undefined,
           chapter: undefined,
           singleQueryField: "Catalog_Product",

package/tests/admin/Platform_PluginStructuresApiTest.res

@@ -16,7 +16,7 @@ let publicRm: queryableDef = {
   labelField: "displayName",
   searchableFields: ["displayName"],
   labelFieldSource: Some("annotation"),
-  statusField: None,
+  lifecycleField: None,
   visibility: None,
   chapter: Some("Inventory"),
   singleQueryField: Some("Catalog_Product"),
@@ -24,6 +24,8 @@ let publicRm: queryableDef = {
   idFieldSource: Some("convention"),
   requiredAccess: None,
   ownerField: None,
+  retiredField: None,
+  retiredValues: None,
 }
 
 // The component `Platform_ComponentDefinitions` drops and this query must keep.

package/tests/admin/Platform_PluginStructuresApiTest.res.mjs

@@ -31,8 +31,10 @@ let publicRm = {
   labelField: "displayName",
   searchableFields: publicRm_searchableFields,
   labelFieldSource: publicRm_labelFieldSource,
-  statusField: undefined,
+  lifecycleField: undefined,
   ownerField: undefined,
+  retiredField: undefined,
+  retiredValues: undefined,
   visibility: undefined,
   chapter: publicRm_chapter,
   singleQueryField: publicRm_singleQueryField,
@@ -68,8 +70,10 @@ let internalRm = {
   labelField: "displayName",
   searchableFields: internalRm_searchableFields,
   labelFieldSource: internalRm_labelFieldSource,
-  statusField: undefined,
+  lifecycleField: undefined,
   ownerField: undefined,
+  retiredField: undefined,
+  retiredValues: undefined,
   visibility: internalRm_visibility,
   chapter: internalRm_chapter,
   singleQueryField: internalRm_singleQueryField,

package/tests/api/Api_IdsTest.res.mjs

@@ -77,7 +77,7 @@ globalThis.describe("filter.ids matches whichever form each side holds", () => {
         "ids",
         filterIds.map(prim => prim)
       ]]);
-    let conn = QueryDbListQuery$ReventlessCore.run([row(rowId)], args, GraphQL_FragmentGenerator$ReventlessCore.emptyCapability, "name", undefined, undefined);
+    let conn = QueryDbListQuery$ReventlessCore.run([row(rowId)], args, GraphQL_FragmentGenerator$ReventlessCore.emptyCapability, "name", undefined, undefined, undefined);
     return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(conn), d => d["edges"]), Stdlib_JSON.Decode.array), []).length;
   };
   globalThis.test("storage key row, storage key filter", () => {