@reventlessdev/reventless-core 3.0.0-alpha.190 → 3.0.0-alpha.192

package/tests/plugin/PluginStructureTest.res

@@ -93,6 +93,20 @@ module PsAttachInvoiceSlice: ReventlessInfra.StateChangeSlice.T = {
   let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
 }
 
+module PsChangePhotoSlice: ReventlessInfra.StateChangeSlice.T = {
+  module Spec = PsChangePhoto
+  module Behavior = {
+    type state = PsChangePhoto.state
+    let initialState = PsChangePhoto.initialState
+    let evolve = PsChangePhoto.evolve
+    let decide = PsChangePhoto.decide
+    let moduleUrl = PsChangePhoto.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)
+}
+
 let structure = Plugin_Structure.make(
   ~name="TestPlugin",
   ~stateChangeSlices=[module(PsPlaceOrderSlice), module(PsShipOrderSlice)],
@@ -275,6 +289,252 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     })
   })
 
+  // What a field *is* comes from `SchemaType`, the IR every other schema
+  // consumer reads, rather than from a `String(_)` match here. These pin the
+  // shapes that separates the two: a date, a reference, a semantic-carrying
+  // string and an optional one all match `String(_)` loosely or not at all, and
+  // each was answered wrong before.
+  describe("labelField — the shape rule", () => {
+    let labelOf = (~entityName="Test", schema) => {
+      let r = Plugin_Structure.labelFieldsFromStateSchema(~entityName, schema->S.castToUnknown)
+      (r.field, r.searchableFields)
+    }
+
+    testSync("a DateTime is not a name — a state whose only string is one falls to id", () => {
+      // The shipped `Orders` case: `placedAt` was added so date views have a
+      // field to key off, and a positional rule let it rename the entity.
+      let schema = S.schema(s =>
+        {
+          "orderId": s.matches(Reventless.Reference.to_("Order")),
+          "placedAt": s.matches(Reventless.DateTime.string),
+          "shippedAt": s.matches(Reventless.DateTime.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("id", []))
+    })
+
+    testSync("a DateTime is skipped, not fatal — a later plain string still wins", () => {
+      let schema = S.schema(s =>
+        {
+          "placedAt": s.matches(Reventless.DateTime.string),
+          "reference": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("reference", ["reference"]))
+    })
+
+    testSync("an optional string is still the entity's name", () => {
+      let schema = S.schema(s =>
+        {
+          "nickname": s.matches(S.option(S.string)),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("nickname", ["nickname"]))
+    })
+
+    testSync("a reference is not a name even when its field is not called `*Id`", () => {
+      let schema = S.schema(s =>
+        {
+          "customer": s.matches(Reventless.Reference.to_("Customer")),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+
+    testSync("a DCB-tagged string is not a name", () => {
+      let schema = S.schema(s =>
+        {
+          "partition": s.matches(Reventless.DcbTag.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+
+    testSync("the `*Id` test is case-insensitive — `productID` is a reference", () => {
+      let schema = S.schema(s =>
+        {
+          "productID": s.matches(S.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+
+    testSync("a semantic-carrying string is a value, not a name", () => {
+      // `imageUrl` names a stored object. A bucket key read as a product's name
+      // is what the previous rule did whenever no plain string preceded it.
+      let schema = S.schema(s =>
+        {
+          "imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages")),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+
+    testSync("a state whose only string is a semantic falls to id", () => {
+      let schema = S.schema(s =>
+        {
+          "imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages")),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("id", []))
+    })
+
+    testSync("`id` itself is still excluded by name", () => {
+      // `SchemaType` reads a name that short as an ordinary string, so the
+      // exclusion cannot come from the IR.
+      let schema = S.schema(s =>
+        {
+          "id": s.matches(S.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+  })
+
+  describe("labelField — the conventional-name rung", () => {
+    let labelOf = schema => {
+      let r = Plugin_Structure.labelFieldsFromStateSchema(~entityName="Test", schema->S.castToUnknown)
+      (r.field, r.searchableFields)
+    }
+
+    testSync("a field named `name` beats an earlier string", () => {
+      let schema = S.schema(s =>
+        {
+          "sku": s.matches(S.string),
+          "name": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("name", ["name"]))
+    })
+
+    testSync("`title` counts too, case-insensitively", () => {
+      let schema = S.schema(s =>
+        {
+          "body": s.matches(S.string),
+          "Title": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("Title", ["Title"]))
+    })
+
+    testSync("the match is exact — `customerName` is a customer's name, not this record's", () => {
+      // The shipped `OrdersView` fixture depends on this: it has exactly one
+      // eligible field and must be picked by position, not by convention.
+      let schema = S.schema(s =>
+        {
+          "customerName": s.matches(S.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("customerName", ["customerName"]))
+    })
+
+    testSync("an optional `name` still outranks an earlier string", () => {
+      let schema = S.schema(s =>
+        {
+          "sku": s.matches(S.string),
+          "name": s.matches(S.option(S.string)),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("name", ["name"]))
+    })
+  })
+
+  // The rung is published because the four are not equally believable: a
+  // consumer with a name rule of its own has to know whether it is ranking
+  // against a declaration or against a guess.
+  describe("labelFieldSource — which rung answered", () => {
+    let sourceOf = schema =>
+      Plugin_Structure.labelFieldsFromStateSchema(
+        ~entityName="Test",
+        schema->S.castToUnknown,
+      ).source->Plugin_Structure.labelFieldSourceToString
+
+    testSync("a @displayName spec is a declaration", () => {
+      let customers = structure.stateViewSlices->Array.getUnsafe(2)
+      expect((customers.labelField, customers.labelFieldSource))->toEqual((
+        "displayName",
+        Some("annotation"),
+      ))
+    })
+
+    testSync("a field named `name` is a guess the consumer can also make", () => {
+      let schema = S.schema(s =>
+        {
+          "sku": s.matches(S.string),
+          "name": s.matches(S.string),
+        }
+      )
+      expect(sourceOf(schema))->toEqual("convention")
+    })
+
+    testSync("declaration order is a guess only this side can make", () => {
+      // `customerName` is eligible and unconventional, so it wins by position —
+      // and a consumer told only "customerName" could not tell that from a
+      // declaration.
+      let schema = S.schema(s =>
+        {
+          "customerName": s.matches(S.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(sourceOf(schema))->toEqual("position")
+    })
+
+    testSync("no candidate at all is the state saying it has no human field", () => {
+      let schema = S.schema(s =>
+        {
+          "orderId": s.matches(Reventless.Reference.to_("Order")),
+          "placedAt": s.matches(Reventless.DateTime.string),
+        }
+      )
+      expect(sourceOf(schema))->toEqual("fallback")
+    })
+
+    testSync("every built def states one", () => {
+      let stated =
+        Array.concat(structure.readModels, structure.stateViewSlices)->Array.every(q =>
+          q.labelFieldSource->Option.isSome
+        )
+      expect(stated)->toEqual(true)
+    })
+  })
+
+  describe("statusField — the shape rule", () => {
+    let statusOf = schema =>
+      Plugin_Structure.statusFieldFromStateSchema(~entityName="Test", schema->S.castToUnknown)
+
+    testSync("a `status` 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")])),
+        }
+      )
+      expect(statusOf(schema))->toEqual(Some("status"))
+    })
+
+    testSync("an optional one counts too", () => {
+      let schema = S.schema(s =>
+        {
+          "status": s.matches(S.option(S.union([S.literal("Placed"), S.literal("Shipped")]))),
+        }
+      )
+      expect(statusOf(schema))->toEqual(Some("status"))
+    })
+
+    testSync("free text named `status` 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)
+    })
+  })
+
   // Phase 4: queryableDef.schema must carry x-reventless-* extension keys for
   // annotated state types. Plugin_Structure now uses SuryToJsonSchema.deriveObjectSchema
   // (annotation-aware) instead of S.toJSONSchema (metadata-blind).
@@ -429,5 +689,136 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     testSync("a plugin declaring no stores collects none — not None", () =>
       expect(structure.requiredStores)->toEqual(Some([]))
     )
+
+    testSync("each requirement keeps its declaring (component, field) sites", () => {
+      // `documents` is declared on a command field AND an event field of the
+      // same component under the same field name — one declaration site, so
+      // the identical triples collapse to one entry.
+      let expected: array<Reventless.Plugin.requiredStoreDeclaration> = [
+        {store: "TestPlugin.documents", component: "AttachInvoice", field: "documentUrl"},
+        {store: "branding.logos", component: "AttachInvoice", field: "logoUrl"},
+      ]
+      expect(withStores.requiredStoreDeclarations)->toEqual(Some(expected))
+    })
+
+    // The manifest is a rendering of the structure. Its key set must be
+    // byte-identical to what the deployed plugin reports as `requiredStores`,
+    // because the deploy-time coverage assertion compares against exactly that
+    // — this equality is the whole contract of `capabilities.json`.
+    describe("capability manifest", () => {
+      let manifest = Reventless.CapabilityManifest.fromStructure(withStores)
+
+      testSync("keys are byte-identical to requiredStores", () =>
+        expect(manifest.capabilities->Array.map(c => c.key))->toEqual(
+          withStores.requiredStores->Option.getOr([]),
+        )
+      )
+
+      testSync("each entry carries its provenance", () => {
+        let entry =
+          manifest.capabilities->Array.find(c => c.key == "TestPlugin.documents")->Option.getOrThrow
+        let expected: array<Reventless.CapabilityManifest.provenance> = [
+          {component: "AttachInvoice", field: "documentUrl"},
+        ]
+        expect(entry.declaredBy)->toEqual(expected)
+      })
+
+      testSync("a structure declaring nothing yields an empty list, not a missing manifest", () =>
+        expect(Reventless.CapabilityManifest.fromStructure(structure).capabilities)->toEqual([])
+      )
+
+      testSync("rendering is deterministic and newline-terminated", () => {
+        let rendered = Reventless.CapabilityManifest.renderForStructure(withStores)
+        expect(rendered)->toBe(
+          `{
+  "capabilities": [
+    {
+      "kind": "ObjectStore",
+      "key": "TestPlugin.documents",
+      "declaredBy": [
+        {
+          "component": "AttachInvoice",
+          "field": "documentUrl"
+        }
+      ]
+    },
+    {
+      "kind": "ObjectStore",
+      "key": "branding.logos",
+      "declaredBy": [
+        {
+          "component": "AttachInvoice",
+          "field": "logoUrl"
+        }
+      ]
+    }
+  ]
+}
+`,
+        )
+      })
+    })
+  })
+
+  // Declarations are authoritative; the name heuristics are a lint. A
+  // heuristic-only match warns and never reaches the manifest, so nothing is
+  // provisioned from a guess — `imageUrl` is genuinely ambiguous between an
+  // uploaded object and an external URL, and only the author can settle it.
+  describe("capability inference", () => {
+    let commandWarnings = Capability_Inference.scanSchema(
+      ~component="ChangePhoto",
+      PsChangePhoto.commandSchema->S.castToUnknown,
+    )
+    let eventWarnings = Capability_Inference.scanSchema(
+      ~component="ChangePhoto",
+      PsChangePhoto.eventSchema->S.castToUnknown,
+    )
+
+    testSync("a heuristic-only match produces a warning", () => {
+      let expected: array<Capability_Inference.warning> = [
+        {component: "ChangePhoto", field: "photoUrl"},
+      ]
+      expect(commandWarnings)->toEqual(expected)
+    })
+
+    testSync("a declared field with a heuristic name does not warn", () => {
+      // The event's `thumbnail` matches the name heuristic but carries
+      // @storageRef — only the undeclared `photoUrl` warns.
+      let expected: array<Capability_Inference.warning> = [
+        {component: "ChangePhoto", field: "photoUrl"},
+      ]
+      expect(eventWarnings)->toEqual(expected)
+    })
+
+    testSync("a heuristic-only match reaches no manifest entry", () => {
+      let withHeuristicField = Plugin_Structure.make(
+        ~name="TestPlugin",
+        ~stateChangeSlices=[module(PsChangePhotoSlice)],
+      )
+      // Only the *declared* `thumbnail` store is collected; `photoUrl` — the
+      // heuristic-only match — provisions nothing.
+      expect(withHeuristicField.requiredStores)->toEqual(Some(["TestPlugin.productPhotos"]))
+      let manifest = Reventless.CapabilityManifest.fromStructure(withHeuristicField)
+      expect(
+        manifest.capabilities->Array.every(entry =>
+          entry.declaredBy->Array.every(site => site.field != "photoUrl")
+        ),
+      )->toBe(true)
+    })
+
+    testSync("the warning names the field and the settling annotation", () => {
+      let text =
+        commandWarnings->Array.getUnsafe(0)->Capability_Inference.message
+      expect(text->String.includes("ChangePhoto.photoUrl"))->toBe(true)
+      expect(text->String.includes("@storageRef"))->toBe(true)
+    })
+
+    testSync("suffix and exact name rules match; ordinary names do not", () => {
+      expect(
+        ["invoiceFileRef", "upload", "thumbnail", "customerName", "documentUrl"]->Array.map(
+          Capability_Inference.nameMatches,
+        ),
+      )->toEqual([true, true, true, false, false])
+    })
   })
 })