@reventlessdev/reventless-spec 3.0.0-alpha.84 → 3.0.0-alpha.86

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: Generator_Node.existsSync,
+  readJson: path =>
+    try Some(Generator_Node.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(Generator_Node.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 = Generator_Node.join([dir, "node_modules", name])
+    if fs.exists(Generator_Node.join([candidate, "package.json"])) {
+      Some(candidate)
+    } else {
+      let parent = Generator_Node.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 = Generator_Node.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 = Generator_Node.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 = Generator_Node.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)
+      }
+    }
+  }
+}

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/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/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)