@reventlessdev/reventless-spec 3.0.0-alpha.123 → 3.0.0-alpha.125

package/src/generator/PlatformCodegen.res.mjs

@@ -47,16 +47,10 @@ function splitKey(key) {
   ]);
 }
 
-function renderEntry(entry) {
-  let match = splitKey(entry.key);
-  if (match === undefined) {
-    return {
-      TAG: "Error",
-      _0: `malformed capability key ` + JSON.stringify(entry.key) + ` — expected "{plugin}.{store}" (is the plugin's capabilities.json hand-edited?)`
-    };
-  }
-  let comments = entry.declaredBy.map(site => {
-    let site_ = `  // ` + site.pluginName + `: ` + site.component + `.` + site.field;
+function renderComments(entry) {
+  return entry.declaredBy.map(site => {
+    let field = site.field;
+    let site_ = field !== undefined ? `  // ` + site.pluginName + `: ` + site.component + `.` + field : `  // ` + site.pluginName + `: ` + site.component;
     let annotation = site.annotation;
     if (annotation !== undefined) {
       return site_ + ` → ` + annotation;
@@ -64,11 +58,35 @@ function renderEntry(entry) {
       return site_;
     }
   });
-  let line = `  ObjectStore({plugin: ` + JSON.stringify(match[0]) + `, store: ` + JSON.stringify(match[1]) + `}),`;
-  return {
-    TAG: "Ok",
-    _0: comments.concat([line])
-  };
+}
+
+function renderEntry(entry) {
+  let match = entry.kind;
+  switch (match) {
+    case "ObjectStore" :
+      let match$1 = splitKey(entry.key);
+      if (match$1 !== undefined) {
+        return {
+          TAG: "Ok",
+          _0: renderComments(entry).concat([`  ObjectStore({plugin: ` + JSON.stringify(match$1[0]) + `, store: ` + JSON.stringify(match$1[1]) + `}),`])
+        };
+      } else {
+        return {
+          TAG: "Error",
+          _0: `malformed capability key ` + JSON.stringify(entry.key) + ` — expected "{plugin}.{store}" (is the plugin's capabilities.json hand-edited?)`
+        };
+      }
+    case "Geocoding" :
+      return {
+        TAG: "Ok",
+        _0: renderComments(entry).concat(["  Geocoding,"])
+      };
+    case "Messaging" :
+      return {
+        TAG: "Ok",
+        _0: renderComments(entry).concat(["  Messaging,"])
+      };
+  }
 }
 
 function duplicatePluginOwners(entries) {
@@ -106,8 +124,8 @@ let header = [
   "//",
   "// The platform's capability list, unioned from the committed",
   "// `capabilities.json` manifests of the plugins deploy-manifest.yaml names.",
-  "// Each entry keeps its declaring fields as provenance, so when a capability",
-  "// disappears from this list, the diff says which field's change removed it.",
+  "// Each entry keeps its declaring sites as provenance, so when a capability",
+  "// disappears from this list, the diff says which change removed it.",
   ""
 ];
 
@@ -145,6 +163,7 @@ export {
   union,
   quote,
   splitKey,
+  renderComments,
   renderEntry,
   duplicatePluginOwners,
   duplicatePluginMessage,

package/src/generator/TraitManifestCli.res

@@ -0,0 +1,138 @@
+// Derive a trait's listing metadata from the trait itself.
+//
+// Usage: trait-manifest <trait-package> --out <file>
+//
+// The old design had a hand-written `trait.yaml`. Everything in it is already a
+// fact somewhere typed, so this reads those facts instead: identity from the
+// package, needs from the value the trait exports, and the config surface from
+// the emitter's own sury schema.
+//
+// Nothing here knows a trait's vocabulary. Both modules are resolved by the name
+// the trait is given and dynamically imported, exactly as `graft-trait` reaches a
+// scaffold — so `reventless-spec` still depends on no trait.
+
+@val external dynImport: string => promise<'a> = "import"
+
+type scaffoldExports = {configSchema: S.t<unknown>}
+type traitExports = {capabilityNeeds: array<CapabilityNeed.t>}
+
+let fail = (message: string) => {
+  Console.error("trait-manifest: " ++ message)
+  NodeProcess.exit(1)
+}
+
+let usage = `Usage: trait-manifest <trait-package> --out <file>
+
+  <trait-package>  the installed trait, e.g. @reventlessdev/trait-attachments
+  --out            where to write the manifest
+
+  Everything is read from the trait: identity from its package.json, capability
+  needs from the value it exports, the config surface from its emitter's schema.
+  There is nothing to hand-write and nothing to keep in step.`
+
+/** `@scope/trait-address-geocoding` → `AddressGeocoding`. The same derivation
+    `graft-trait` and `certify-trait` do, for the same reason: a trait's module
+    names follow from its package name, so nothing has to be configured. */
+let moduleBase = (traitPackage: string) =>
+  traitPackage
+  ->String.split("/")
+  ->Array.last
+  ->Option.getOr("")
+  ->String.replace("trait-", "")
+  ->String.split("-")
+  ->Array.map(part =>
+    part->String.charAt(0)->String.toUpperCase ++
+      part->String.slice(~start=1, ~end=part->String.length)
+  )
+  ->Array.join("")
+
+let resolveFrom = (specifier: string) =>
+  try Some(
+    NodeModule.createRequire(NodeProcess.cwd() ++ "/index.js")->NodeModule.requireResolve(specifier),
+  ) catch {
+  | _ => None
+  }
+
+let readPackageField = (packageJson: JSON.t, field: string, fallback: string) =>
+  packageJson
+  ->JSON.Decode.object
+  ->Option.flatMap(o => o->Dict.get(field))
+  ->Option.flatMap(JSON.Decode.string)
+  ->Option.getOr(fallback)
+
+let main = async () => {
+  let argv = NodeProcess.argv->Array.slice(~start=2, ~end=NodeProcess.argv->Array.length)
+  let flag = key =>
+    switch argv->Array.indexOf("--" ++ key) {
+    | -1 => None
+    | i => argv->Array.get(i + 1)
+    }
+
+  switch (argv->Array.get(0), flag("out")) {
+  | (None, _) | (Some(""), _) | (Some("--help"), _) | (Some("-h"), _) => {
+      Console.log(usage)
+      NodeProcess.exit(argv->Array.length == 0 ? 1 : 0)
+    }
+  | (Some(_), None) => fail("--out is required.\n\n" ++ usage)
+  | (Some(traitPackage), Some(out)) => {
+      let base = moduleBase(traitPackage)
+
+      let packageJson = switch resolveFrom(`${traitPackage}/package.json`) {
+      | None =>
+        fail(
+          `${traitPackage} is not installed here. A manifest is derived from the trait, so ` ++
+          `the trait has to be resolvable.`,
+        )
+        JSON.Encode.null
+      | Some(path) => NodeFs.readFileSync(path)->JSON.parseOrThrow
+      }
+
+      // The trait's entry module, for what it needs. Absent is refused rather
+      // than defaulted to `[]`: "needs nothing" and "nobody said" are different
+      // claims, and a listing that could not tell them apart would quietly
+      // publish the second as the first.
+      let traitModule: traitExports = switch resolveFrom(`${traitPackage}/src/${base}.res.mjs`) {
+      | None =>
+        fail(
+          `${traitPackage} exports no ${base} module, so its capability needs cannot be read.\n` ++
+          `  A trait states them as a value — an empty array if it brokers nothing — because ` ++
+          `an unstated need fails silently at run time.`,
+        )
+        %raw(`undefined`)
+      | Some(path) => await dynImport(NodeUrl.pathToFileURL(path)["href"])
+      }
+
+      // The emitter is optional: a trait whose graft is all patches has nothing
+      // to write, and says so here rather than by failing when someone tries.
+      let scaffold: option<scaffoldExports> = switch resolveFrom(
+        `${traitPackage}/src/${base}_Scaffold.res.mjs`,
+      ) {
+      | None => None
+      | Some(path) => Some(await dynImport(NodeUrl.pathToFileURL(path)["href"]))
+      }
+
+      let manifest: TraitManifest.t = {
+        trait: readPackageField(packageJson, "name", traitPackage),
+        version: readPackageField(packageJson, "version", "0.0.0"),
+        description: readPackageField(packageJson, "description", ""),
+        license: readPackageField(packageJson, "license", ""),
+        capabilities: traitModule.capabilityNeeds->Array.map(CapabilityNeed.toString),
+        config: switch scaffold {
+        | Some({configSchema}) => TraitManifest.configFieldsOf(configSchema)
+        | None => []
+        },
+        scaffolded: scaffold->Option.isSome,
+      }
+
+      NodeFs.writeFileSync(out, manifest->TraitManifest.render)
+      Console.log(
+        `trait-manifest: ${manifest.trait}@${manifest.version} — ` ++
+        `${(manifest.capabilities->Array.length)->Int.toString} capabilit(ies), ` ++
+        `${(manifest.config->Array.length)->Int.toString} config field(s)`,
+      )
+      Console.log(`Wrote: ${out}`)
+    }
+  }
+}
+
+main()->Promise.ignore

package/src/generator/TraitManifestCli.res.mjs

@@ -0,0 +1,105 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodeurl from "node:url";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Nodemodule from "node:module";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as TraitManifest$Reventless from "../components/TraitManifest.res.mjs";
+import * as CapabilityNeed$Reventless from "../semantic/CapabilityNeed.res.mjs";
+
+function fail(message) {
+  console.error("trait-manifest: " + message);
+  process.exit(1);
+}
+
+let usage = `Usage: trait-manifest <trait-package> --out <file>
+
+  <trait-package>  the installed trait, e.g. @reventlessdev/trait-attachments
+  --out            where to write the manifest
+
+  Everything is read from the trait: identity from its package.json, capability
+  needs from the value it exports, the config surface from its emitter's schema.
+  There is nothing to hand-write and nothing to keep in step.`;
+
+function moduleBase(traitPackage) {
+  return Stdlib_Option.getOr(Stdlib_Array.last(traitPackage.split("/")), "").replace("trait-", "").split("-").map(part => part.charAt(0).toUpperCase() + part.slice(1, part.length)).join("");
+}
+
+function resolveFrom(specifier) {
+  try {
+    return Nodemodule.createRequire(process.cwd() + "/index.js").resolve(specifier);
+  } catch (exn) {
+    return;
+  }
+}
+
+function readPackageField(packageJson, field, fallback) {
+  return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(packageJson), o => o[field]), Stdlib_JSON.Decode.string), fallback);
+}
+
+async function main() {
+  let argv = process.argv.slice(2, process.argv.length);
+  let flag = key => {
+    let i = argv.indexOf("--" + key);
+    if (i !== -1) {
+      return argv[i + 1 | 0];
+    }
+  };
+  let match = argv[0];
+  let match$1 = flag("out");
+  if (match !== undefined) {
+    switch (match) {
+      case "" :
+      case "--help" :
+      case "-h" :
+        break;
+      default:
+        if (match$1 === undefined) {
+          return fail("--out is required.\n\n" + usage);
+        }
+        let base = moduleBase(match);
+        let path = resolveFrom(match + `/package.json`);
+        let packageJson = path !== undefined ? JSON.parse(Nodefs.readFileSync(path, "utf8")) : (fail(match + ` is not installed here. A manifest is derived from the trait, so the trait has to be resolvable.`), null);
+        let path$1 = resolveFrom(match + `/src/` + base + `.res.mjs`);
+        let traitModule = path$1 !== undefined ? await import(Nodeurl.pathToFileURL(path$1).href) : (fail(match + ` exports no ` + base + ` module, so its capability needs cannot be read.\n  A trait states them as a value — an empty array if it brokers nothing — because an unstated need fails silently at run time.`), undefined);
+        let path$2 = resolveFrom(match + `/src/` + base + `_Scaffold.res.mjs`);
+        let scaffold = path$2 !== undefined ? await import(Nodeurl.pathToFileURL(path$2).href) : undefined;
+        let manifest_trait = readPackageField(packageJson, "name", match);
+        let manifest_version = readPackageField(packageJson, "version", "0.0.0");
+        let manifest_description = readPackageField(packageJson, "description", "");
+        let manifest_license = readPackageField(packageJson, "license", "");
+        let manifest_capabilities = traitModule.capabilityNeeds.map(CapabilityNeed$Reventless.toString);
+        let manifest_config = scaffold !== undefined ? TraitManifest$Reventless.configFieldsOf(scaffold.configSchema) : [];
+        let manifest_scaffolded = Stdlib_Option.isSome(scaffold);
+        let manifest = {
+          trait: manifest_trait,
+          version: manifest_version,
+          description: manifest_description,
+          license: manifest_license,
+          capabilities: manifest_capabilities,
+          config: manifest_config,
+          scaffolded: manifest_scaffolded
+        };
+        Nodefs.writeFileSync(match$1, TraitManifest$Reventless.render(manifest), "utf8");
+        console.log(`trait-manifest: ` + manifest_trait + `@` + manifest_version + ` — ` + (manifest_capabilities.length.toString() + ` capabilit(ies), `) + (manifest_config.length.toString() + ` config field(s)`));
+        console.log(`Wrote: ` + match$1);
+        return;
+    }
+  }
+  console.log(usage);
+  process.exit(argv.length === 0 ? 1 : 0);
+}
+
+main();
+
+export {
+  fail,
+  usage,
+  moduleBase,
+  resolveFrom,
+  readPackageField,
+  main,
+}
+/*  Not a pure module */

package/src/semantic/Capabilities.res

@@ -5,9 +5,9 @@ A plugin is provider-agnostic: it depends on `reventless-spec`, never on
 `reventless-aws`, so it cannot name Amazon Location — and it should not want to.
 What it can do is receive a function that geocodes, and let whoever assembled the
 runtime decide what is on the other end. The same capability a client reaches
-through a GraphQL field, plugin code reaches through here; the object store
-already works this way, with `Upload_Presign` on one side and an injected
-`Offload.resolve(~fetch)` on the other.
+through a GraphQL field, plugin code reaches through here. (The object store has
+only the client half so far — `Upload_Presign`; `Offload.resolve(~fetch)` has no
+injected caller yet, and the accessor for it belongs in this record.)
 
 Injected rather than looked up, and required rather than optional, because the
 alternative is a slot filled at cold start that nothing enforces: ES modules
@@ -24,6 +24,9 @@ leaves every `translate` reading `capabilities.geocode` untouched.
 type t = {
   /** Turn an address into ranked candidates. See `Geocoding.search`. */
   geocode: Geocoding.search,
+  /** Send a message to a person, and say which channels this deployment can
+      attempt at all. See `Messaging.provider`. */
+  messaging: Messaging.provider,
 }
 
 /**
@@ -40,4 +43,17 @@ a blank.
 */
 let none: t = {
   geocode: async (~text as _) => Error(Unavailable("no geocoder is configured for this platform")),
+  // `channels: []` and a retryable `send` say two different true things, and both
+  // are needed. The empty list is what a deploy gate reads and what a preference
+  // centre renders — offering a channel nothing can deliver on would collect a
+  // subscription that never arrives. The send stays `Unavailable` rather than
+  // `UnsupportedChannel` because a caller that got this far is looking at a
+  // deployment gap, not at a fact about the recipient, and abandoning the message
+  // would record the second.
+  messaging: {
+    channels: [],
+    send: async (~recipient as _, ~message as _) => Error(
+      Unavailable("no messaging provider is configured for this platform"),
+    ),
+  },
 }

package/src/semantic/Capabilities.res.mjs

@@ -1,16 +1,32 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 
-let none = {
-  geocode: async param => ({
+async function none_geocode(param) {
+  return {
     TAG: "Error",
     _0: {
       TAG: "Unavailable",
       _0: "no geocoder is configured for this platform"
     }
+  };
+}
+
+let none_messaging = {
+  channels: [],
+  send: async (param, param$1) => ({
+    TAG: "Error",
+    _0: {
+      TAG: "Unavailable",
+      _0: "no messaging provider is configured for this platform"
+    }
   })
 };
 
+let none = {
+  geocode: none_geocode,
+  messaging: none_messaging
+};
+
 export {
   none,
 }

package/src/semantic/CapabilityNeed.res

@@ -0,0 +1,81 @@
+/**
+A platform capability a component declares it needs, in the plugin's own
+vocabulary.
+
+`Capabilities.t` is what a slice is *handed*; this is what it says it will
+reach for. The two are separate because they are read at different times: the
+record is injected at run time, the declaration is read at build time by
+`emit-capabilities` and at deploy time by the coverage gate, neither of which
+can run a `translate`.
+
+**Object stores are not here.** A store need is already declared by the field
+that carries `@storageRef`, travels as `pluginStructure.requiredStores`, and is
+identified by `(plugin, store)` rather than by a capability alone. This type
+carries the needs that no field can express.
+
+A real variant, so a trait exports its need as a value the compiler checks
+rather than a string a README repeats.
+*/
+type t =
+  | Geocoding
+  | /** Sending a message to a person, reached through `Capabilities.messaging`.
+        One need however many channels the platform provisions — which channels
+        those are is a runtime answer the provider publishes, not a second
+        declaration, because a plugin that named `Sms` would fail a deploy it
+        could have run on email. */
+  Messaging
+
+/** The spelling carried in `pluginStructure` and in `capabilities.json`.
+    Persisted structures hold strings, not enum members, so a plugin built
+    against a newer framework still decodes in an older reader. */
+let toString = (need: t): string =>
+  switch need {
+  | Geocoding => "Geocoding"
+  | Messaging => "Messaging"
+  }
+
+/** The inverse, for readers of a persisted structure or a committed manifest.
+    `None` for a capability this build does not know — a newer plugin's need is
+    reported as unrecognised, never silently dropped into a known arm. */
+let fromString = (name: string): option<t> =>
+  switch name {
+  | "Geocoding" => Some(Geocoding)
+  | "Messaging" => Some(Messaging)
+  | _ => None
+  }
+
+/** One declared need the deployment does not provision, with the component that
+    declared it — a deploy refusal has to name what to go and look at. */
+type unmet = {need: t, component: string}
+
+/**
+Declared capability needs a platform does not provision.
+
+`declared` is `pluginStructure.requiredCapabilities` as persisted: `(capability,
+component)` pairs whose capability is a string, because a structure is replayed
+from an event log. A name this build does not recognise is **skipped** — it
+belongs to a newer framework, and refusing a deploy over a capability this code
+cannot evaluate would be a guess dressed as a check.
+
+Only what was declared. A plugin that declares nothing is unaffected: an
+unprovisioned capability it never named degrades exactly as it always has, which
+is the modelled outcome for a deployment that simply does not have one.
+*/
+let unmet = (~declared: array<(string, string)>, ~provisioned: array<t>): array<unmet> =>
+  declared->Array.filterMap((((capability, component))) =>
+    switch fromString(capability) {
+    | Some(need) if !(provisioned->Array.includes(need)) => Some({need, component})
+    | _ => None
+    }
+  )
+
+/** The refusal text: what is missing, who asked for it, and what silently happens
+    if it is not provisioned — the symptom is a wrong verdict, never an error. */
+let unmetMessage = (unmet: array<unmet>): string =>
+  `Plugin declares capabilit(ies) the platform does not provision: ` ++
+  `${unmet
+    ->Array.map(u => `${toString(u.need)} (${u.component})`)
+    ->Array.join(", ")}.\n` ++
+  `  Provision them in the platform stack and redeploy the platform first.\n` ++
+  `  Without it every call answers Unavailable, the slice exhausts its retries, and a ` ++
+  `permanent verdict is recorded against data that is fine — no error anywhere.`

package/src/semantic/CapabilityNeed.res.mjs

@@ -0,0 +1,46 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+
+function toString(need) {
+  if (need === "Geocoding") {
+    return "Geocoding";
+  } else {
+    return "Messaging";
+  }
+}
+
+function fromString(name) {
+  switch (name) {
+    case "Geocoding" :
+      return "Geocoding";
+    case "Messaging" :
+      return "Messaging";
+    default:
+      return;
+  }
+}
+
+function unmet(declared, provisioned) {
+  return Stdlib_Array.filterMap(declared, param => {
+    let need = fromString(param[0]);
+    if (need !== undefined && !provisioned.includes(need)) {
+      return {
+        need: need,
+        component: param[1]
+      };
+    }
+  });
+}
+
+function unmetMessage(unmet) {
+  return `Plugin declares capabilit(ies) the platform does not provision: ` + (unmet.map(u => toString(u.need) + ` (` + u.component + `)`).join(", ") + `.\n`) + `  Provision them in the platform stack and redeploy the platform first.\n  Without it every call answers Unavailable, the slice exhausts its retries, and a permanent verdict is recorded against data that is fine — no error anywhere.`;
+}
+
+export {
+  toString,
+  fromString,
+  unmet,
+  unmetMessage,
+}
+/* No side effect */