@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/generator/PlatformCodegen.res.mjs

@@ -0,0 +1,154 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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 Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
+import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+
+function union(manifests) {
+  let byKey = {};
+  manifests.forEach(param => {
+    let pluginName = param.pluginName;
+    param.manifest.capabilities.forEach(entry => {
+      let sites = entry.declaredBy.map(site => ({
+        pluginName: pluginName,
+        component: site.component,
+        field: site.field,
+        annotation: site.annotation
+      }));
+      let existing = byKey[entry.key];
+      if (existing !== undefined) {
+        byKey[entry.key] = {
+          kind: existing.kind,
+          key: existing.key,
+          declaredBy: existing.declaredBy.concat(sites)
+        };
+      } else {
+        byKey[entry.key] = {
+          kind: entry.kind,
+          key: entry.key,
+          declaredBy: sites
+        };
+      }
+    });
+  });
+  return Object.values(byKey).toSorted((a, b) => Primitive_string.compare(a.key, b.key));
+}
+
+function quote(s) {
+  return JSON.stringify(s);
+}
+
+function splitKey(key) {
+  return Stdlib_Option.map(Stdlib_String.indexOfOpt(key, "."), i => [
+    key.slice(0, i),
+    key.slice(i + 1 | 0)
+  ]);
+}
+
+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;
+    let annotation = site.annotation;
+    if (annotation !== undefined) {
+      return site_ + ` @storageRef(` + JSON.stringify(annotation) + `)`;
+    } else {
+      return site_;
+    }
+  });
+  let line = `  ObjectStore({plugin: ` + JSON.stringify(match[0]) + `, store: ` + JSON.stringify(match[1]) + `}),`;
+  return {
+    TAG: "Ok",
+    _0: comments.concat([line])
+  };
+}
+
+function duplicatePluginOwners(entries) {
+  let owners = {};
+  entries.forEach(entry => {
+    let match = splitKey(entry.key);
+    if (match === undefined) {
+      return;
+    }
+    let plugin = match[0];
+    entry.declaredBy.forEach(site => {
+      let annotation = site.annotation;
+      if (annotation === undefined) {
+        return;
+      }
+      if (annotation.includes(".")) {
+        return;
+      }
+      let claimants = Stdlib_Option.getOr(owners[plugin], []);
+      if (!claimants.includes(site.pluginName)) {
+        owners[plugin] = claimants.concat([site.pluginName]);
+        return;
+      }
+    });
+  });
+  return Object.entries(owners).filter(param => param[1].length > 1).toSorted((param, param$1) => Primitive_string.compare(param[0], param$1[0]));
+}
+
+function duplicatePluginMessage(param) {
+  return `Plugin name "` + param[0] + `" is registered by more than one deployable: ` + param[1].join(", ") + `.\n  A platform keys its plugin registry by name, so the second registration is read as a new VERSION of the first and supersedes it.\n  Give each deployable's plugin a distinct name (plugin.json), or — if these were meant to be one plugin — deploy only one of them.`;
+}
+
+let header = [
+  "// AUTO-GENERATED — do not edit. Run `pnpm run generate:platform` to update.",
+  "//",
+  "// 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.",
+  ""
+];
+
+function render(manifests) {
+  let entries = union(manifests);
+  let rendered = entries.map(renderEntry);
+  let match = duplicatePluginOwners(entries);
+  let match$1 = Stdlib_Array.findMap(rendered, r => {
+    if (r.TAG === "Ok") {
+      return;
+    } else {
+      return r._0;
+    }
+  });
+  if (match.length !== 0) {
+    return {
+      TAG: "Error",
+      _0: match.map(duplicatePluginMessage).join("\n\n")
+    };
+  }
+  if (match$1 !== undefined) {
+    return {
+      TAG: "Error",
+      _0: match$1
+    };
+  }
+  let body = entries.length === 0 ? ["let capabilities: array<ReventlessInfra.Platform.capability> = []"] : ["let capabilities: array<ReventlessInfra.Platform.capability> = ["].concat(rendered.flatMap(r => Stdlib_Result.getOr(r, []))).concat(["]"]);
+  return {
+    TAG: "Ok",
+    _0: header.concat(body).join("\n") + "\n"
+  };
+}
+
+export {
+  union,
+  quote,
+  splitKey,
+  renderEntry,
+  duplicatePluginOwners,
+  duplicatePluginMessage,
+  header,
+  render,
+}
+/* No side effect */

package/src/generator/PlatformGenerator.res

@@ -0,0 +1,126 @@
+// Entry point for the platform generator.
+// Usage: generate-platform <deploy-manifest.yaml>
+//
+// Reads the deploy manifest for the plugin list, unions the plugins' committed
+// `capabilities.json` manifests, and writes the platform's committed
+// `PlatformCapabilities.res` (see PlatformCodegen). The platform root stays
+// hand-written and reads `PlatformCapabilities.capabilities`.
+//
+// A deploy manifest enumerates *deployables*, not plugins, and a plugin's
+// manifest can sit in any of three places. `PlatformManifests` owns both facts —
+// its head comment states the resolution order and why each arm exists; add a
+// fourth arm there, not here.
+
+@module("yaml") external parseYaml: string => JSON.t = "parse"
+
+let fail = (message: string) => {
+  Console.error("generate-platform: " ++ message)
+  NodeProcess.exit(1)
+}
+
+let asObject = (json: JSON.t): option<dict<JSON.t>> => json->JSON.Decode.object
+let stringAt = (obj: dict<JSON.t>, field: string): option<string> =>
+  obj->Dict.get(field)->Option.flatMap(JSON.Decode.string)
+
+let () = {
+  let manifestArg = NodeProcess.argv->Array.get(2)->Option.getOr("")
+  if manifestArg == "" {
+    Console.error("Usage: generate-platform <deploy-manifest.yaml>")
+    NodeProcess.exit(1)
+  } else {
+    let manifestPath = NodePath.resolve([manifestArg])
+    if !NodeFs.existsSync(manifestPath) {
+      fail(`${manifestPath} not found`)
+    }
+    let manifestDir = NodePath.dirname(manifestPath)
+    let deployManifest = try NodeFs.readFileSync(manifestPath)->parseYaml catch {
+    | _ => {
+        fail(`could not parse ${manifestPath} as YAML`)
+        JSON.Null
+      }
+    }
+
+    let platformPath =
+      deployManifest
+      ->asObject
+      ->Option.flatMap(m => m->Dict.get("platform"))
+      ->Option.flatMap(asObject)
+      ->Option.flatMap(p => p->stringAt("path"))
+    let plugins =
+      deployManifest
+      ->asObject
+      ->Option.flatMap(m => m->Dict.get("plugins"))
+      ->Option.flatMap(JSON.Decode.array)
+      ->Option.map(entries =>
+        entries->Array.filterMap(entry => {
+          let obj = entry->asObject
+          switch (
+            obj->Option.flatMap(o => o->stringAt("name")),
+            obj->Option.flatMap(o => o->stringAt("path")),
+          ) {
+          | (Some(name), Some(path)) => Some((name, path))
+          | _ => None
+          }
+        })
+      )
+
+    switch (platformPath, plugins) {
+    | (Some(platformPath), Some(plugins)) => {
+        let pluginManifests = plugins->Array.flatMap(((pluginName, pluginPath)) => {
+          let pluginDir = NodePath.resolve([manifestDir, pluginPath])
+          if !NodeFs.existsSync(pluginDir) {
+            fail(`plugin "${pluginName}" points at ${pluginDir}, which does not exist`)
+          }
+          switch PlatformManifests.resolve(~pluginDir) {
+          // A stack whose package graph holds no plugin composition — an
+          // SdkService, an SPA, a standalone Lambda — has no capabilities to
+          // contribute, which is not an error. Said out loud so a plugin
+          // skipped by mistake is visible in the generator's output.
+          | NotAPlugin => {
+              Console.log(`Skipped: ${pluginName} (${pluginDir}) — no plugin composition`)
+              []
+            }
+          | Unbuilt({evidence, expected}) => {
+              fail(
+                `no capabilities.json found for plugin "${pluginName}" (${pluginDir}) — ` ++
+                `build the plugin first; its build emits src/capabilities.json beside Plugin.res ` ++
+                `(${evidence}; expected ${expected})`,
+              )
+              []
+            }
+          | Manifests(manifests) =>
+            manifests->Array.map(({path, via}) => {
+              Console.log(
+                `Read: ${pluginName} — ${path} (via ${PlatformManifests.describeVia(via)})`,
+              )
+              let manifest = try NodeFs.readFileSync(path)
+              ->JSON.parseOrThrow
+              ->S.parseOrThrow(CapabilityManifest.schema) catch {
+              | _ => {
+                  fail(`could not parse ${path} as a capability manifest`)
+                  ({capabilities: []}: CapabilityManifest.t)
+                }
+              }
+              ({pluginName, manifest}: PlatformCodegen.pluginManifest)
+            })
+          }
+        })
+
+        switch PlatformCodegen.render(pluginManifests) {
+        | Error(message) => fail(message)
+        | Ok(source) => {
+            let outputPath = NodePath.resolve([
+              manifestDir,
+              platformPath,
+              "src",
+              "PlatformCapabilities.res",
+            ])
+            NodeFs.writeFileSync(outputPath, source)
+            Console.log("Generated: " ++ outputPath)
+          }
+        }
+      }
+    | _ => fail(`${manifestPath} needs a \`platform.path\` and a \`plugins\` list with name + path`)
+    }
+  }
+}

package/src/generator/PlatformGenerator.res.mjs

@@ -0,0 +1,114 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Yaml from "yaml";
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+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 PlatformCodegen$Reventless from "./PlatformCodegen.res.mjs";
+import * as PlatformManifests$Reventless from "./PlatformManifests.res.mjs";
+import * as CapabilityManifest$Reventless from "../components/CapabilityManifest.res.mjs";
+
+function fail(message) {
+  console.error("generate-platform: " + message);
+  process.exit(1);
+}
+
+function asObject(json) {
+  return Stdlib_JSON.Decode.object(json);
+}
+
+function stringAt(obj, field) {
+  return Stdlib_Option.flatMap(obj[field], Stdlib_JSON.Decode.string);
+}
+
+let manifestArg = Stdlib_Option.getOr(process.argv[2], "");
+
+if (manifestArg === "") {
+  console.error("Usage: generate-platform <deploy-manifest.yaml>");
+  process.exit(1);
+} else {
+  let manifestPath = Nodepath.resolve(manifestArg);
+  if (!Nodefs.existsSync(manifestPath)) {
+    fail(manifestPath + ` not found`);
+  }
+  let manifestDir = Nodepath.dirname(manifestPath);
+  let deployManifest;
+  try {
+    deployManifest = Yaml.parse(Nodefs.readFileSync(manifestPath, "utf8"));
+  } catch (exn) {
+    fail(`could not parse ` + manifestPath + ` as YAML`);
+    deployManifest = null;
+  }
+  let platformPath = Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(deployManifest), m => m["platform"]), asObject), p => stringAt(p, "path"));
+  let plugins = Stdlib_Option.map(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(deployManifest), m => m["plugins"]), Stdlib_JSON.Decode.array), entries => Stdlib_Array.filterMap(entries, entry => {
+    let obj = Stdlib_JSON.Decode.object(entry);
+    let match = Stdlib_Option.flatMap(obj, o => stringAt(o, "name"));
+    let match$1 = Stdlib_Option.flatMap(obj, o => stringAt(o, "path"));
+    if (match !== undefined && match$1 !== undefined) {
+      return [
+        match,
+        match$1
+      ];
+    }
+  }));
+  if (platformPath !== undefined) {
+    if (plugins !== undefined) {
+      let pluginManifests = plugins.flatMap(param => {
+        let pluginName = param[0];
+        let pluginDir = Nodepath.resolve(manifestDir, param[1]);
+        if (!Nodefs.existsSync(pluginDir)) {
+          fail(`plugin "` + pluginName + `" points at ` + pluginDir + `, which does not exist`);
+        }
+        let manifests = PlatformManifests$Reventless.resolve(undefined, pluginDir);
+        if (typeof manifests !== "object") {
+          console.log(`Skipped: ` + pluginName + ` (` + pluginDir + `) — no plugin composition`);
+          return [];
+        }
+        if (manifests.TAG === "Manifests") {
+          return manifests._0.map(param => {
+            let path = param.path;
+            console.log(`Read: ` + pluginName + ` — ` + path + ` (via ` + PlatformManifests$Reventless.describeVia(param.via) + `)`);
+            let manifest;
+            try {
+              manifest = S.parseOrThrow(JSON.parse(Nodefs.readFileSync(path, "utf8")), CapabilityManifest$Reventless.schema);
+            } catch (exn) {
+              fail(`could not parse ` + path + ` as a capability manifest`);
+              manifest = {
+                capabilities: []
+              };
+            }
+            return {
+              pluginName: pluginName,
+              manifest: manifest
+            };
+          });
+        }
+        let match = manifests._0;
+        fail(`no capabilities.json found for plugin "` + pluginName + `" (` + pluginDir + `) — build the plugin first; its build emits src/capabilities.json beside Plugin.res ` + (`(` + match.evidence + `; expected ` + match.expected + `)`));
+        return [];
+      });
+      let message = PlatformCodegen$Reventless.render(pluginManifests);
+      if (message.TAG === "Ok") {
+        let outputPath = Nodepath.resolve(manifestDir, platformPath, "src", "PlatformCapabilities.res");
+        Nodefs.writeFileSync(outputPath, message._0, "utf8");
+        console.log("Generated: " + outputPath);
+      } else {
+        fail(message._0);
+      }
+    } else {
+      fail(manifestPath + ` needs a \`platform.path\` and a \`plugins\` list with name + path`);
+    }
+  } else {
+    fail(manifestPath + ` needs a \`platform.path\` and a \`plugins\` list with name + path`);
+  }
+}
+
+export {
+  fail,
+  asObject,
+  stringAt,
+}
+/* manifestArg Not a pure module */

package/src/generator/PlatformManifests.res

@@ -0,0 +1,203 @@
+// Where a deploy-manifest entry's capability manifests live — and, when it
+// contributes none, whether that is because the entry is not a plugin at all.
+//
+// A deploy manifest enumerates *deployables*, not plugins. An SdkService stack,
+// a static SPA, a standalone ingester Lambda are all legitimate entries with no
+// `pluginStructure` to derive capabilities from; contributing nothing is the
+// right answer for those. A plugin whose manifest is merely unbuilt is the
+// opposite case, and silently skipping it would deprovision the stores it
+// declared. The two are told apart by evidence — something in the package graph
+// that emits a capability manifest — never by falling through the arms below.
+//
+// Resolution order, first arm that yields manifests wins:
+//
+//   1. `<dir>/src/capabilities.json` — the entry is itself a composition
+//      package, so its manifest sits beside its composition root.
+//   2. `<dir>`'s own `generate: generate-plugin --aws <Namespace> <srcDir>`
+//      script — an `-aws` root generated from a composition `src/` elsewhere in
+//      the same repo. The script is the single existing record of that
+//      delegation, so no second hand-typed spelling of the path is introduced.
+//   3. `<dir>`'s dependencies — an `-aws` root that *installs* a published
+//      composition package, which is the shape the framework recommends and the
+//      one arms 1 and 2 both miss. Every plugin dependency contributes: a root
+//      deploying two plugins legitimately needs both manifests.
+//   4. Nothing in the package graph emits a manifest — not a plugin stack.
+//
+// I/O goes through `fileSystem` so the arms are testable without a fixture
+// tree; `nodeFileSystem` is what the generator passes.
+
+/** How a manifest was found — reported so the resolving arm never has to be
+    reconstructed from the output. */
+type via =
+  | Composition
+  | Generated(string)
+  | Dependency(string)
+
+type manifest = {path: string, via: via}
+
+/** Why the entry counted as a plugin, and where its manifest was looked for. */
+type unbuilt = {evidence: string, expected: string}
+
+type t =
+  | Manifests(array<manifest>)
+  /** Something here emits a capability manifest, but the manifest is not on
+      disk: a plugin that has not been built. */
+  | Unbuilt(unbuilt)
+  /** No plugin composition anywhere in the entry's package graph. */
+  | NotAPlugin
+
+type fileSystem = {
+  exists: string => bool,
+  readJson: string => option<JSON.t>,
+}
+
+let nodeFileSystem: fileSystem = {
+  exists: NodeFs.existsSync,
+  readJson: path =>
+    try Some(NodeFs.readFileSync(path)->JSON.parseOrThrow) catch {
+    | _ => None
+    },
+}
+
+let describeVia = (via: via): string =>
+  switch via {
+  | Composition => "its own src/"
+  | Generated(srcDir) => `its \`generate\` script's ${srcDir}`
+  | Dependency(name) => `dependency ${name}`
+  }
+
+let asObject = (json: JSON.t): option<dict<JSON.t>> => json->JSON.Decode.object
+
+let packageJsonAt = (~fs: fileSystem, ~dir: string): option<dict<JSON.t>> =>
+  fs.readJson(NodePath.join([dir, "package.json"]))->Option.flatMap(asObject)
+
+let scriptsOf = (pkg: dict<JSON.t>): array<string> =>
+  pkg
+  ->Dict.get("scripts")
+  ->Option.flatMap(asObject)
+  ->Option.mapOr([], scripts =>
+    scripts->Dict.valuesToArray->Array.filterMap(JSON.Decode.string)
+  )
+
+// The composition `src/` an `-aws` root is generated from, read off the script
+// that performs the generation.
+let generatedSrcDir = (pkg: dict<JSON.t>): option<string> =>
+  pkg
+  ->Dict.get("scripts")
+  ->Option.flatMap(asObject)
+  ->Option.flatMap(scripts => scripts->Dict.get("generate"))
+  ->Option.flatMap(JSON.Decode.string)
+  ->Option.flatMap(script => {
+    let tokens = script->String.split(" ")->Array.filter(t => t != "")
+    switch tokens {
+    | ["generate-plugin", "--aws", _namespace, srcDir] => Some(srcDir)
+    | _ => None
+    }
+  })
+
+// A package that runs `emit-capabilities` as part of its build is a plugin
+// composition package, whether or not it has been built yet. That is the whole
+// signal G1 needs: it is stated once, by the package that owns the fact, and it
+// is already there in every plugin package — unlike a `kind:` on the deploy
+// manifest, which would restate it a second time.
+//
+// `reventless-local` *provides* the bin under `bin`, and so is correctly not
+// matched here.
+let emitsCapabilities = (pkg: dict<JSON.t>): bool =>
+  pkg->scriptsOf->Array.some(script => script->String.includes("emit-capabilities"))
+
+let dependencyNames = (pkg: dict<JSON.t>): array<string> => {
+  let seen = Dict.make()
+  ["dependencies", "devDependencies"]
+  ->Array.flatMap(field =>
+    pkg->Dict.get(field)->Option.flatMap(asObject)->Option.mapOr([], Dict.keysToArray)
+  )
+  ->Array.filter(name =>
+    switch seen->Dict.get(name) {
+    | Some(_) => false
+    | None => {
+        seen->Dict.set(name, true)
+        true
+      }
+    }
+  )
+}
+
+/** Node's directory resolution: `<dir>/node_modules/<name>`, then each parent's,
+    up to the filesystem root. Walking it rather than binding `require.resolve`
+    keeps the lookup on the package directory itself — a package's entry point
+    may be anywhere, and it is `src/capabilities.json` that is wanted. */
+let resolvePackageDir = (~fs: fileSystem, ~fromDir: string, ~name: string): option<string> => {
+  let rec search = dir => {
+    let candidate = NodePath.join([dir, "node_modules", name])
+    if fs.exists(NodePath.join([candidate, "package.json"])) {
+      Some(candidate)
+    } else {
+      let parent = NodePath.dirname(dir)
+      parent == dir ? None : search(parent)
+    }
+  }
+  search(fromDir)
+}
+
+// Arm 3. Unbuilt wins over what was found: a root deploying two plugins needs
+// both manifests, so one of them missing is a failure even though the other
+// resolved.
+let fromDependencies = (~fs: fileSystem, ~pluginDir: string, ~pkg: dict<JSON.t>): t => {
+  let found = []
+  let unbuilt = ref(None)
+  pkg
+  ->dependencyNames
+  ->Array.forEach(name =>
+    switch resolvePackageDir(~fs, ~fromDir=pluginDir, ~name) {
+    | None => ()
+    | Some(packageDir) => {
+        let candidate = NodePath.join([packageDir, "src", "capabilities.json"])
+        if fs.exists(candidate) {
+          found->Array.push({path: candidate, via: Dependency(name)})
+        } else if packageJsonAt(~fs, ~dir=packageDir)->Option.mapOr(false, emitsCapabilities) {
+          switch unbuilt.contents {
+          | Some(_) => ()
+          | None =>
+            unbuilt :=
+              Some({
+                evidence: `dependency ${name} emits a capability manifest`,
+                expected: candidate,
+              })
+          }
+        }
+      }
+    }
+  )
+  switch (unbuilt.contents, found) {
+  | (Some({evidence, expected}), _) => Unbuilt({evidence, expected})
+  | (None, []) => NotAPlugin
+  | (None, manifests) => Manifests(manifests)
+  }
+}
+
+let resolve = (~fs: fileSystem=nodeFileSystem, ~pluginDir: string): t => {
+  let direct = NodePath.join([pluginDir, "src", "capabilities.json"])
+  if fs.exists(direct) {
+    Manifests([{path: direct, via: Composition}])
+  } else {
+    switch packageJsonAt(~fs, ~dir=pluginDir) {
+    | None => NotAPlugin
+    | Some(pkg) =>
+      switch generatedSrcDir(pkg) {
+      | Some(srcDir) => {
+          let expected = NodePath.resolve([pluginDir, srcDir, "capabilities.json"])
+          if fs.exists(expected) {
+            Manifests([{path: expected, via: Generated(srcDir)}])
+          } else {
+            Unbuilt({
+              evidence: `its \`generate\` script composes ${srcDir}`,
+              expected,
+            })
+          }
+        }
+      | None => fromDependencies(~fs, ~pluginDir, ~pkg)
+      }
+    }
+  }
+}