@reventlessdev/reventless-spec 3.0.0-alpha.85 → 3.0.0-alpha.87

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)

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

package/src/semantic/Duration.res

@@ -0,0 +1,53 @@
+/**
+Marks an `int` field as a length of time, in **seconds**.
+
+## Why a scalar, and why seconds are part of the type
+
+The obvious richer design is `{value, unit}`. It is not available here, and the
+reason is the reason this whole set of types is safe to add: a record is an
+*object* on the wire, so adopting it would turn every field that used it into a
+decode failure against events already written. These types are additive
+precisely because they stay scalars. A duration that carries its unit is a
+different type for a different plan, not a later version of this one — widening
+this one would retroactively hand an upcaster obligation to every field that had
+already adopted it.
+
+Seconds, because that is what the renderer reads: it formats `3660` as
+`"1h 1m"`. Milliseconds would be off by a factor of a thousand and would
+render as weeks, which is the same class of silent wrongness `Percent` avoids by
+matching its gauge.
+
+`int` is right here where it was wrong for `Bytes`: int32 seconds is 68 years,
+which no duration field needs to exceed.
+
+## The grammar
+
+A whole number of seconds, zero or greater. Zero is a real duration — an instant
+timeout, a zero-length window.
+
+@example
+```rescript
+@schema type state = {
+  jobId: string,
+  runtimeSeconds: @s.matches(Reventless.Duration.schema) int,
+}
+```
+*/
+
+/** The duration's representation, in seconds. Transparent `int`. */
+type t = int
+
+external unsafe: int => t = "%identity"
+external toInt: t => int = "%identity"
+
+/** Validate a number of seconds as a duration, saying why when it is not one. */
+let fromInt = (raw: int): result<t, string> =>
+  if raw < 0 {
+    Error(`a duration cannot be negative, got ${Int.toString(raw)} seconds`)
+  } else {
+    Ok(raw)
+  }
+
+/** The sury schema for a duration field, in seconds.
+    Use with `@s.matches(Reventless.Duration.schema)`. */
+let schema: S.t<t> = S.int->Semantic.refined(~id=Semantic.Id.duration, ~check=fromInt)

package/src/semantic/Duration.res.mjs

@@ -0,0 +1,26 @@
+// 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 fromInt(raw) {
+  if (raw < 0) {
+    return {
+      TAG: "Error",
+      _0: `a duration cannot be negative, got ` + raw.toString() + ` seconds`
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: raw
+    };
+  }
+}
+
+let schema = Semantic$Reventless.refined(S.int, Semantic$Reventless.Id.duration, fromInt);
+
+export {
+  fromInt,
+  schema,
+}
+/* schema Not a pure module */

package/src/semantic/Email.res

@@ -0,0 +1,51 @@
+/**
+Marks a `string` field as an email address.
+
+## Why a type rather than a name
+
+An `email` field already renders as a mailto link today, because the UI guesses
+from the field's *name*. The guess is the whole problem: `contact`, `owner` and
+`notifyTo` hold addresses and are not guessed, `emailTemplate` is guessed and is
+not an address, and nothing anywhere checks that what was written is one. A type
+says it, and the check comes with it.
+
+## The grammar
+
+Sury's `S.email`, and nothing added. This is a case where the framework has no
+opinion worth having: address syntax is somebody else's specification, and a
+second regex here would only be a way to disagree with it.
+
+Note that a syntactically valid address is not a deliverable one — nothing here
+sends a probe. This rejects what is not an address, which is the part a boundary
+check can honestly do.
+
+@example
+```rescript
+@schema type command =
+  | InviteMember({
+      teamId: @s.matches(DcbTag.string) string,
+      email: @s.matches(Reventless.Email.schema) string,
+    })
+```
+*/
+
+/** The address's representation. Transparent `string`: the marker refines an
+    existing field rather than replacing it, so nothing stored changes. */
+type t = string
+
+external unsafe: string => t = "%identity"
+external toString: t => string = "%identity"
+
+// Sury's check, held once. `fromString` runs it rather than restating it, and
+// `schema` is built from `fromString`, so there is exactly one grammar here.
+let grammar: S.t<string> = S.string->S.email
+
+/** Validate a raw string as an email address, saying why when it is not one. */
+let fromString = (raw: string): result<t, string> =>
+  switch raw->S.parseOrThrow(grammar) {
+  | value => Ok(value)
+  | exception _ => Error(`expected an email address, got ${Semantic.showString(raw)}`)
+  }
+
+/** The sury schema for an email field. Use with `@s.matches(Reventless.Email.schema)`. */
+let schema: S.t<t> = S.string->Semantic.refined(~id=Semantic.Id.email, ~check=fromString)

package/src/semantic/Email.res.mjs

@@ -0,0 +1,31 @@
+// 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 grammar = S.email(S.string, undefined);
+
+function fromString(raw) {
+  let value;
+  try {
+    value = S.parseOrThrow(raw, grammar);
+  } catch (exn) {
+    return {
+      TAG: "Error",
+      _0: `expected an email address, got ` + Semantic$Reventless.showString(raw)
+    };
+  }
+  return {
+    TAG: "Ok",
+    _0: value
+  };
+}
+
+let schema = Semantic$Reventless.refined(S.string, Semantic$Reventless.Id.email, fromString);
+
+export {
+  grammar,
+  fromString,
+  schema,
+}
+/* grammar Not a pure module */

package/src/semantic/Percent.res

@@ -0,0 +1,53 @@
+/**
+Marks a `float` field as a percentage, expressed **0–100**.
+
+## Why 0–100 and not 0–1
+
+Both conventions are defensible in the abstract, so the tie is broken by the
+consumer that already exists: the dashboard gauges a field with this semantic
+against fixed bounds of 0 and 100, and formats `42.0` as `"42%"`. Under a 0–1
+convention every value would render as a rounding error near zero — a gauge
+pinned at empty and a label reading `"0.42%"`.
+
+That failure is quiet, and it is quiet in the worst way: the numbers are
+*present* and *wrong*, and the layer at fault is not the one showing the symptom.
+Agreeing with the renderer costs nothing; disagreeing costs an afternoon.
+
+A fraction is still perfectly good arithmetic — it just multiplies by 100 before
+it becomes this type.
+
+## The grammar
+
+A finite number in `[0, 100]`. Fractions are allowed: `99.95` is a percentage.
+
+@example
+```rescript
+@schema type state = {
+  productId: string,
+  taxRate: @s.matches(Reventless.Percent.schema) float,
+}
+```
+*/
+
+/** The percentage's representation. Transparent `float`: the marker refines an
+    existing numeric field rather than replacing it, so nothing stored changes. */
+type t = float
+
+external unsafe: float => t = "%identity"
+external toFloat: t => float = "%identity"
+
+/** Validate a number as a percentage, saying why when it is not one. */
+let fromFloat = (raw: float): result<t, string> =>
+  if !Float.isFinite(raw) {
+    Error(`a percentage must be a finite number, got ${Float.toString(raw)}`)
+  } else if raw < 0.0 || raw > 100.0 {
+    Error(
+      `a percentage runs from 0 to 100, got ${Float.toString(raw)}. ` ++
+      `This scale is 0–100, not 0–1 — a fraction multiplies by 100 first.`,
+    )
+  } else {
+    Ok(raw)
+  }
+
+/** The sury schema for a percentage field. Use with `@s.matches(Reventless.Percent.schema)`. */
+let schema: S.t<t> = S.float->Semantic.refined(~id=Semantic.Id.percent, ~check=fromFloat)

package/src/semantic/Percent.res.mjs

@@ -0,0 +1,33 @@
+// 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 || raw > 100.0) {
+      return {
+        TAG: "Error",
+        _0: `a percentage runs from 0 to 100, got ` + raw.toString() + `. This scale is 0–100, not 0–1 — a fraction multiplies by 100 first.`
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: raw
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: `a percentage must be a finite number, got ` + raw.toString()
+    };
+  }
+}
+
+let schema = Semantic$Reventless.refined(S.float, Semantic$Reventless.Id.percent, fromFloat);
+
+export {
+  fromFloat,
+  schema,
+}
+/* schema Not a pure module */

package/src/semantic/Phone.res

@@ -0,0 +1,55 @@
+/**
+Marks a `string` field as a phone number in E.164 form.
+
+## Why E.164, and only E.164
+
+A phone number written the way a person says it out loud — `(030) 12 34 56`,
+`+49 30 123456`, `0049-30-123456` — is three different strings for one number,
+so a log full of them cannot be searched, deduplicated or dialled reliably. E.164
+is the one form that is unambiguous internationally, and it is the form the
+`tel:` link this field renders as actually wants.
+
+That makes this the one branded scalar that is likely to *reject* input a form
+would otherwise have accepted, and it should: the alternative is storing an
+un-dialable string permanently. Normalising a local number into E.164 needs a
+default country the framework does not know, so that belongs to the caller,
+before the command.
+
+## The grammar
+
+`+`, then a country digit 1–9, then up to 14 more digits — at most 15 in total,
+which is the E.164 limit. No spaces, no punctuation, no leading zero after the
+`+`.
+
+@example
+```rescript
+@schema type command =
+  | SetContactPhone({
+      customerId: @s.matches(DcbTag.string) string,
+      phone: @s.matches(Reventless.Phone.schema) string,
+    })
+```
+*/
+
+/** The number's representation. Transparent `string`; see `Email.t`. */
+type t = string
+
+external unsafe: string => t = "%identity"
+external toString: t => string = "%identity"
+
+let e164 = /^\+[1-9]\d{0,14}$/
+
+/** Validate a raw string as an E.164 number, saying why when it is not one. */
+let fromString = (raw: string): result<t, string> =>
+  if e164->RegExp.test(raw) {
+    Ok(raw)
+  } else {
+    Error(
+      `expected a phone number in E.164 form — "+" then up to 15 digits, as in "+4930123456" — got ${Semantic.showString(
+          raw,
+        )}. Spaces, dashes and brackets are not part of the stored form.`,
+    )
+  }
+
+/** The sury schema for a phone field. Use with `@s.matches(Reventless.Phone.schema)`. */
+let schema: S.t<t> = S.string->Semantic.refined(~id=Semantic.Id.phone, ~check=fromString)