@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/generator/PlatformManifests.res.mjs

@@ -0,0 +1,212 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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";
+
+function nodeFileSystem_exists(prim) {
+  return Nodefs.existsSync(prim);
+}
+
+function nodeFileSystem_readJson(path) {
+  try {
+    return JSON.parse(Nodefs.readFileSync(path, "utf8"));
+  } catch (exn) {
+    return;
+  }
+}
+
+let nodeFileSystem = {
+  exists: nodeFileSystem_exists,
+  readJson: nodeFileSystem_readJson
+};
+
+function describeVia(via) {
+  if (typeof via !== "object") {
+    return "its own src/";
+  } else if (via.TAG === "Generated") {
+    return `its \`generate\` script's ` + via._0;
+  } else {
+    return `dependency ` + via._0;
+  }
+}
+
+function asObject(json) {
+  return Stdlib_JSON.Decode.object(json);
+}
+
+function packageJsonAt(fs, dir) {
+  return Stdlib_Option.flatMap(fs.readJson(Nodepath.join(dir, "package.json")), asObject);
+}
+
+function scriptsOf(pkg) {
+  return Stdlib_Option.mapOr(Stdlib_Option.flatMap(pkg["scripts"], asObject), [], scripts => Stdlib_Array.filterMap(Object.values(scripts), Stdlib_JSON.Decode.string));
+}
+
+function generatedSrcDir(pkg) {
+  return Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(pkg["scripts"], asObject), scripts => scripts["generate"]), Stdlib_JSON.Decode.string), script => {
+    let tokens = script.split(" ").filter(t => t !== "");
+    if (tokens.length !== 4) {
+      return;
+    }
+    let match = tokens[0];
+    if (match !== "generate-plugin") {
+      return;
+    }
+    let match$1 = tokens[1];
+    if (match$1 === "--aws") {
+      return tokens[3];
+    }
+  });
+}
+
+function emitsCapabilities(pkg) {
+  return scriptsOf(pkg).some(script => script.includes("emit-capabilities"));
+}
+
+function dependencyNames(pkg) {
+  let seen = {};
+  return [
+    "dependencies",
+    "devDependencies"
+  ].flatMap(field => Stdlib_Option.mapOr(Stdlib_Option.flatMap(pkg[field], asObject), [], prim => Object.keys(prim))).filter(name => {
+    let match = seen[name];
+    if (match !== undefined) {
+      return false;
+    } else {
+      seen[name] = true;
+      return true;
+    }
+  });
+}
+
+function resolvePackageDir(fs, fromDir, name) {
+  let _dir = fromDir;
+  while (true) {
+    let dir = _dir;
+    let candidate = Nodepath.join(dir, "node_modules", name);
+    if (fs.exists(Nodepath.join(candidate, "package.json"))) {
+      return candidate;
+    }
+    let parent = Nodepath.dirname(dir);
+    if (parent === dir) {
+      return;
+    }
+    _dir = parent;
+    continue;
+  };
+}
+
+function fromDependencies(fs, pluginDir, pkg) {
+  let found = [];
+  let unbuilt = {
+    contents: undefined
+  };
+  dependencyNames(pkg).forEach(name => {
+    let packageDir = resolvePackageDir(fs, pluginDir, name);
+    if (packageDir === undefined) {
+      return;
+    }
+    let candidate = Nodepath.join(packageDir, "src", "capabilities.json");
+    if (fs.exists(candidate)) {
+      found.push({
+        path: candidate,
+        via: {
+          TAG: "Dependency",
+          _0: name
+        }
+      });
+      return;
+    }
+    if (!Stdlib_Option.mapOr(packageJsonAt(fs, packageDir), false, emitsCapabilities)) {
+      return;
+    }
+    let match = unbuilt.contents;
+    if (match !== undefined) {
+      return;
+    } else {
+      unbuilt.contents = {
+        evidence: `dependency ` + name + ` emits a capability manifest`,
+        expected: candidate
+      };
+      return;
+    }
+  });
+  let match = unbuilt.contents;
+  if (match !== undefined) {
+    return {
+      TAG: "Unbuilt",
+      _0: {
+        evidence: match.evidence,
+        expected: match.expected
+      }
+    };
+  } else if (found.length !== 0) {
+    return {
+      TAG: "Manifests",
+      _0: found
+    };
+  } else {
+    return "NotAPlugin";
+  }
+}
+
+function resolve(fsOpt, pluginDir) {
+  let fs = fsOpt !== undefined ? fsOpt : nodeFileSystem;
+  let direct = Nodepath.join(pluginDir, "src", "capabilities.json");
+  if (fs.exists(direct)) {
+    return {
+      TAG: "Manifests",
+      _0: [{
+          path: direct,
+          via: "Composition"
+        }]
+    };
+  }
+  let pkg = packageJsonAt(fs, pluginDir);
+  if (pkg === undefined) {
+    return "NotAPlugin";
+  }
+  let srcDir = generatedSrcDir(pkg);
+  if (srcDir === undefined) {
+    return fromDependencies(fs, pluginDir, pkg);
+  }
+  let expected = Nodepath.resolve(pluginDir, srcDir, "capabilities.json");
+  if (fs.exists(expected)) {
+    return {
+      TAG: "Manifests",
+      _0: [{
+          path: expected,
+          via: {
+            TAG: "Generated",
+            _0: srcDir
+          }
+        }]
+    };
+  } else {
+    return {
+      TAG: "Unbuilt",
+      _0: {
+        evidence: `its \`generate\` script composes ` + srcDir,
+        expected: expected
+      }
+    };
+  }
+}
+
+export {
+  nodeFileSystem,
+  describeVia,
+  asObject,
+  packageJsonAt,
+  scriptsOf,
+  generatedSrcDir,
+  emitsCapabilities,
+  dependencyNames,
+  resolvePackageDir,
+  fromDependencies,
+  resolve,
+}
+/* node:fs Not a pure module */

package/src/generator/PluginGenerator.res

@@ -0,0 +1,57 @@
+// Entry point for the plugin generator.
+// Usage: generate-plugin <srcDir>
+//        generate-plugin --aws <Namespace> <srcDir>
+
+
+let () = {
+  let argv2 = NodeProcess.argv->Array.get(2)->Option.getOr("")
+  let argv3 = NodeProcess.argv->Array.get(3)->Option.getOr("")
+  let argv4 = NodeProcess.argv->Array.get(4)->Option.getOr("")
+
+  let (variant, srcDirArg) = if argv2 === "--aws" {
+    if argv3 !== "" && argv4 !== "" {
+      (Config.Aws({compositionNamespace: argv3}), argv4)
+    } else {
+      Console.error("Usage: generate-plugin --aws <Namespace> <srcDir>")
+      (Config.Composition, "")
+    }
+  } else {
+    (Config.Composition, argv2)
+  }
+
+  if srcDirArg === "" {
+    if argv2 !== "--aws" {
+      Console.error("Usage: generate-plugin <srcDir>")
+      Console.error("       generate-plugin --aws <Namespace> <srcDir>")
+    }
+    // Exit non-zero on a usage error so `prebuild` (and CI) actually fail
+    // instead of continuing green with no Plugin.res generated.
+    NodeProcess.exit(1)
+  } else {
+    // Resolve to absolute path (handles relative paths and trailing slashes)
+    let srcDir = NodePath.resolve([srcDirArg])
+
+    let config = {...Config.read(~srcDir), variant}
+    let discovered = Discovery.scan(~srcDir, ~exclude=config.exclude)
+    let resolved = Pairing.resolve(discovered, ~srcDir)
+    let source = Codegen.render(~config, ~resolved, ~discovered)
+
+    let outputDir = switch variant {
+    | Config.Composition => srcDir
+    | Config.Aws(_) => NodePath.join([NodeProcess.cwd(), "src"])
+    }
+
+    let pluginPath = NodePath.join([outputDir, "Plugin.res"])
+    NodeFs.writeFileSync(pluginPath, source)
+    Console.log("Generated: " ++ pluginPath)
+
+    switch variant {
+    | Config.Composition => ()
+    | Config.Aws(_) =>
+      let mainSource = Codegen.renderMain(~config)
+      let mainPath = NodePath.join([outputDir, "Main.res"])
+      NodeFs.writeFileSync(mainPath, mainSource)
+      Console.log("Generated: " ++ mainPath)
+    }
+  }
+}

package/src/generator/PluginGenerator.res.mjs

@@ -0,0 +1,73 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Config$Reventless from "./Config.res.mjs";
+import * as Codegen$Reventless from "./Codegen.res.mjs";
+import * as Pairing$Reventless from "./Pairing.res.mjs";
+import * as Discovery$Reventless from "./Discovery.res.mjs";
+
+let argv2 = Stdlib_Option.getOr(process.argv[2], "");
+
+let argv3 = Stdlib_Option.getOr(process.argv[3], "");
+
+let argv4 = Stdlib_Option.getOr(process.argv[4], "");
+
+let match = argv2 === "--aws" ? (
+    argv3 !== "" && argv4 !== "" ? [
+        {
+          TAG: "Aws",
+          compositionNamespace: argv3
+        },
+        argv4
+      ] : (console.error("Usage: generate-plugin --aws <Namespace> <srcDir>"), [
+        "Composition",
+        ""
+      ])
+  ) : [
+    "Composition",
+    argv2
+  ];
+
+let srcDirArg = match[1];
+
+let variant = match[0];
+
+if (srcDirArg === "") {
+  if (argv2 !== "--aws") {
+    console.error("Usage: generate-plugin <srcDir>");
+    console.error("       generate-plugin --aws <Namespace> <srcDir>");
+  }
+  process.exit(1);
+} else {
+  let srcDir = Nodepath.resolve(srcDirArg);
+  let init = Config$Reventless.read(srcDir);
+  let config_name = init.name;
+  let config_heartbeatInterval = init.heartbeatInterval;
+  let config_exclude = init.exclude;
+  let config_componentRuntime = init.componentRuntime;
+  let config = {
+    name: config_name,
+    heartbeatInterval: config_heartbeatInterval,
+    exclude: config_exclude,
+    componentRuntime: config_componentRuntime,
+    variant: variant
+  };
+  let discovered = Discovery$Reventless.scan(srcDir, config_exclude);
+  let resolved = Pairing$Reventless.resolve(discovered, srcDir);
+  let source = Codegen$Reventless.render(config, resolved, discovered);
+  let outputDir;
+  outputDir = typeof variant !== "object" ? srcDir : Nodepath.join(process.cwd(), "src");
+  let pluginPath = Nodepath.join(outputDir, "Plugin.res");
+  Nodefs.writeFileSync(pluginPath, source, "utf8");
+  console.log("Generated: " + pluginPath);
+  if (typeof variant === "object") {
+    let mainSource = Codegen$Reventless.renderMain(config);
+    let mainPath = Nodepath.join(outputDir, "Main.res");
+    Nodefs.writeFileSync(mainPath, mainSource, "utf8");
+    console.log("Generated: " + mainPath);
+  }
+}
+
+/* argv2 Not a pure module */

package/src/semantic/Bytes.res

@@ -0,0 +1,54 @@
+/**
+Marks a numeric field as a count of bytes.
+
+## Why `float` and not `int`
+
+A byte count is a whole number and cannot be negative, so `int` is the type it
+wants to be. It is the wrong one here anyway: ReScript's `int` is int32, and
+sury enforces that, so an `int` byte count silently caps at 2,147,483,647 — just
+under 2 GiB. A type whose stated job is file sizes cannot stop at 2 GB.
+
+`float` is a JS number, exact for every integer up to 2^53 — nine petabytes,
+which is enough. The discreteness `int` would have given for free is recovered
+by checking it: the grammar below rejects a fractional byte count, so the type
+still means what `int` meant, minus the ceiling.
+
+The wire is unaffected either way — both are JSON numbers — so this is a source
+choice, not a format one. A field genuinely bounded below 2 GiB can still be
+declared `int` and left unmarked; this type is for the ones that are not.
+
+## The grammar
+
+A finite, whole number, zero or greater. Zero is a real byte count — an empty
+object — so it is accepted.
+
+@example
+```rescript
+@schema type state = {
+  documentId: string,
+  size: @s.matches(Reventless.Bytes.schema) float,
+}
+```
+*/
+
+/** The count's representation. Transparent `float`; see the note above on why
+    it is not `int`. */
+type t = float
+
+external unsafe: float => t = "%identity"
+external toFloat: t => float = "%identity"
+
+/** Validate a number as a byte count, saying why when it is not one. */
+let fromFloat = (raw: float): result<t, string> =>
+  if !Float.isFinite(raw) {
+    Error(`a byte count must be a finite number, got ${Float.toString(raw)}`)
+  } else if raw < 0.0 {
+    Error(`a byte count cannot be negative, got ${Float.toString(raw)}`)
+  } else if Math.floor(raw) !== raw {
+    Error(`a byte count is a whole number of bytes, got ${Float.toString(raw)}`)
+  } else {
+    Ok(raw)
+  }
+
+/** The sury schema for a byte-count field. Use with `@s.matches(Reventless.Bytes.schema)`. */
+let schema: S.t<t> = S.float->Semantic.refined(~id=Semantic.Id.bytes, ~check=fromFloat)

package/src/semantic/Bytes.res.mjs

@@ -0,0 +1,38 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+function fromFloat(raw) {
+  if (isFinite(raw)) {
+    if (raw < 0.0) {
+      return {
+        TAG: "Error",
+        _0: `a byte count cannot be negative, got ` + raw.toString()
+      };
+    } else if (Math.floor(raw) !== raw) {
+      return {
+        TAG: "Error",
+        _0: `a byte count is a whole number of bytes, got ` + raw.toString()
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: raw
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: `a byte count must be a finite number, got ` + raw.toString()
+    };
+  }
+}
+
+let schema = Semantic$Reventless.refined(S.float, Semantic$Reventless.Id.bytes, fromFloat);
+
+export {
+  fromFloat,
+  schema,
+}
+/* schema Not a pure module */

package/src/semantic/Capabilities.res

@@ -0,0 +1,43 @@
+/**
+The platform capabilities a slice's `translate` is handed.
+
+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.
+
+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
+evaluate imports before the importing module's body, so "the entry point runs
+first" is an assumption a bundling change can quietly break. A missing argument
+does not compile; an unfilled slot fails on the first real address, in
+production.
+
+**A record, not a widening argument list.** Adding a capability later changes
+this type, which breaks the handful of places that *construct* it — the
+platforms, which is exactly where a new capability has to be wired anyway — and
+leaves every `translate` reading `capabilities.geocode` untouched.
+*/
+type t = {
+  /** Turn an address into ranked candidates. See `Geocoding.search`. */
+  geocode: Geocoding.search,
+}
+
+/**
+The capability set of a platform that provisions nothing.
+
+Every capability here answers `Unavailable`, which is a *modelled* outcome:
+`translate` maps it to `Error`, the item is retried and the sweep surfaces it.
+That is the behaviour wanted for a deployment that simply has no geocoder — the
+work stays queued and visible rather than being written off as a verdict on the
+address, which is what `NoMatch` would mean.
+
+Named so that a platform passing it is making a statement rather than filling in
+a blank.
+*/
+let none: t = {
+  geocode: async (~text as _) => Error(Unavailable("no geocoder is configured for this platform")),
+}

package/src/semantic/Capabilities.res.mjs

@@ -0,0 +1,17 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let none = {
+  geocode: async param => ({
+    TAG: "Error",
+    _0: {
+      TAG: "Unavailable",
+      _0: "no geocoder is configured for this platform"
+    }
+  })
+};
+
+export {
+  none,
+}
+/* No side effect */

package/src/semantic/Color.res

@@ -0,0 +1,51 @@
+/**
+Marks a `string` field as a colour, written as a hex triplet.
+
+## Why hex only
+
+A field carrying this semantic is rendered as a swatch by setting the value as a
+CSS `background`. CSS accepts far more than a colour there — `url(…)`, gradients,
+`var(…)` — so "any CSS colour" would make a colour field a way to write arbitrary
+CSS into a log that cannot be edited afterwards. Hex is the form that is a
+colour and nothing else, and it is what a colour picker emits anyway.
+
+Named colours (`rebeccapurple`) and functional forms (`rgb(…)`, `oklch(…)`) are
+rejected for the same reason, not because they are worse notation.
+
+## The grammar
+
+`#` then 3, 4, 6 or 8 hex digits — the shorthand, the shorthand with alpha, the
+full triplet, and the triplet with alpha. Case is not significant.
+
+@example
+```rescript
+@schema type command =
+  | SetLabelColour({
+      labelId: @s.matches(DcbTag.string) string,
+      colour: @s.matches(Reventless.Color.schema) string,
+    })
+```
+*/
+
+/** The colour's representation. Transparent `string`; see `Email.t`. */
+type t = string
+
+external unsafe: string => t = "%identity"
+external toString: t => string = "%identity"
+
+let hex = /^#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/
+
+/** Validate a raw string as a hex colour, saying why when it is not one. */
+let fromString = (raw: string): result<t, string> =>
+  if hex->RegExp.test(raw) {
+    Ok(raw)
+  } else {
+    Error(
+      `expected a hex colour such as "#1e90ff" or "#1e90ffcc", got ${Semantic.showString(
+          raw,
+        )}. Named colours and rgb()/oklch() forms are not accepted.`,
+    )
+  }
+
+/** The sury schema for a colour field. Use with `@s.matches(Reventless.Color.schema)`. */
+let schema: S.t<t> = S.string->Semantic.refined(~id=Semantic.Id.color, ~check=fromString)

package/src/semantic/Color.res.mjs

@@ -0,0 +1,29 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+let hex = /^#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+function fromString(raw) {
+  if (hex.test(raw)) {
+    return {
+      TAG: "Ok",
+      _0: raw
+    };
+  } else {
+    return {
+      TAG: "Error",
+      _0: `expected a hex colour such as "#1e90ff" or "#1e90ffcc", got ` + Semantic$Reventless.showString(raw) + `. Named colours and rgb()/oklch() forms are not accepted.`
+    };
+  }
+}
+
+let schema = Semantic$Reventless.refined(S.string, Semantic$Reventless.Id.color, fromString);
+
+export {
+  hex,
+  fromString,
+  schema,
+}
+/* schema Not a pure module */