@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/AnsiStyle.res

@@ -0,0 +1,40 @@
+/** ANSI terminal style primitives + sink detection for log output.
+    Kept in reventless-spec so both reventless-core (Logger / LogFormat) and
+    reventless-infra (compLog in ExtensionMapping/ExtensionPointMapping)
+    can share the same styling helpers AND the same sink decision.
+
+    This is the lowest layer in the logging stack — LogPrefix and Logger
+    depend on it, so the sink decision lives here as the single source of
+    truth. `useAnsi()` ⇒ TTY text mode (colour/bold); `isJsonSink()` ⇒
+    structured JSON for any non-TTY collector (CloudWatch, Datadog, …). */
+
+@val external _isTty: option<bool> = "process.stdout.isTTY"
+@val external _logFormat: option<string> = "process.env.REVENTLESS_LOG_FORMAT"
+
+// "json" | "text". Explicit REVENTLESS_LOG_FORMAT override always wins; otherwise
+// a TTY stdout ⇒ human-readable text, everything else (Lambda, Fargate, ECS,
+// Azure, GCP, Docker, CI runners, piped stdout) ⇒ structured JSON.
+let _resolveFormat = (): string =>
+  switch (_logFormat, _isTty) {
+  | (Some("json"), _) => "json"
+  | (Some("text"), _) => "text"
+  | (_, Some(true)) => "text"
+  | _ => "json"
+  }
+
+// Resolved once at module init; recomputable via `reload()` (test-only — after a
+// test mutates process.env / process.stdout.isTTY). Not a hot path, but caching
+// keeps every log call off `process.env`.
+let _format = ref(_resolveFormat())
+
+/** Test-only: re-evaluate REVENTLESS_LOG_FORMAT / process.stdout.isTTY. */
+let reload = () => _format := _resolveFormat()
+
+/** True when output should be structured JSON (non-TTY sink). */
+let isJsonSink = () => _format.contents == "json"
+
+/** True when output should carry ANSI colour/bold (TTY text mode). */
+let useAnsi = () => _format.contents == "text"
+
+/** Wrap a string in ANSI bold escape codes — no-op in a JSON sink. */
+let bold = s => useAnsi() ? `\x1b[1m${s}\x1b[0m` : s

package/src/AnsiStyle.res.mjs

@@ -0,0 +1,54 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function _resolveFormat() {
+  let match = process.env.REVENTLESS_LOG_FORMAT;
+  let match$1 = process.stdout.isTTY;
+  if (match !== undefined) {
+    switch (match) {
+      case "json" :
+        return "json";
+      case "text" :
+        return "text";
+    }
+  }
+  if (match$1 !== undefined && match$1) {
+    return "text";
+  } else {
+    return "json";
+  }
+}
+
+let _format = {
+  contents: _resolveFormat()
+};
+
+function reload() {
+  _format.contents = _resolveFormat();
+}
+
+function isJsonSink() {
+  return _format.contents === "json";
+}
+
+function useAnsi() {
+  return _format.contents === "text";
+}
+
+function bold(s) {
+  if (_format.contents === "text") {
+    return `\x1b[1m` + s + `\x1b[0m`;
+  } else {
+    return s;
+  }
+}
+
+export {
+  _resolveFormat,
+  _format,
+  reload,
+  isJsonSink,
+  useAnsi,
+  bold,
+}
+/* _format Not a pure module */

package/src/LogPrefix.res

@@ -0,0 +1,192 @@
+/** Plugin-name resolution for log prefixes.
+
+Shared between `ReventlessCore.Logger` (terminal/CloudWatch emit) and
+`ReventlessInfra.{ExtensionPoint,Extension}Mapping.compLog` so logs from
+either layer carry the same `[PluginName][Comp]` prefix.
+
+Resolution priority for a comp string like `"Kind(Name)"`:
+1. The inner name (e.g. `"AddProduct"`) looked up in `componentPluginRegistry`.
+2. The ambient `currentPluginName` ref (set by `Plugin_Builder.construct`).
+3. Transformations of the inner name, each tried against the registry:
+   - strip `@version` suffix (handles `Plugin(Foo@1.2.3)`)
+   - strip trailing `Plugin` (handles `CommandTopic(FooPlugin)`)
+   - last dot segment (handles `Extension(Catalog.Products.Ordering)`)
+   - first dot segment (handles `ExtensionPoint(Catalog.Products)`)
+4. Longest registered component name that prefixes the inner name (handles
+   kind-suffixed resource names like `EventCollector(CustomersReadModel)`).
+
+`Plugin_Builder` registers every component (and the plugin's self-name) when
+constructing a plugin, so all transformation candidates resolve to a
+real plugin name. */
+
+// Ambient plugin name. Set inside `Plugin_Builder.Make.construct` so
+// synchronous logs during construction carry a `[Name]` prefix.
+let currentPluginName: ref<option<string>> = ref(None)
+
+// Registry: component name → owning plugin name. Populated at construct time.
+let componentPluginRegistry: ref<dict<string>> = ref(Dict.make())
+
+let registerComponentPlugin = (~componentName: string, ~pluginName: string) =>
+  componentPluginRegistry.contents->Dict.set(componentName, pluginName)
+
+// Stable hash for picking a color from the palette.
+let hashStr = (s: string): int => {
+  let h = ref(0)
+  for i in 0 to s->String.length - 1 {
+    let code = s->String.charCodeAt(i)->Option.getOr(0)
+    h := h.contents + code * (i + 1)
+  }
+  h.contents
+}
+
+// Foreground colors that don't collide with level indicators (cyan / yellow / red).
+let pluginColors = [
+  "\x1b[32m", // green
+  "\x1b[34m", // blue
+  "\x1b[35m", // magenta
+  "\x1b[92m", // bright green
+  "\x1b[94m", // bright blue
+  "\x1b[95m", // bright magenta
+]
+
+let pluginColor = (name: string): string =>
+  pluginColors->Array.getUnsafe(mod(hashStr(name), pluginColors->Array.length))
+
+// Extract the inner argument from a comp like `"Kind(Name)"`.
+let extractInnerName = (comp: string): option<string> => {
+  let openIdx = comp->String.indexOf("(")
+  let closeIdx = comp->String.lastIndexOf(")")
+  if openIdx > 0 && closeIdx > openIdx + 1 {
+    Some(comp->String.slice(~start=openIdx + 1, ~end=closeIdx))
+  } else {
+    None
+  }
+}
+
+let stripAtVersion = (s: string): option<string> => {
+  let idx = s->String.indexOf("@")
+  if idx > 0 {
+    Some(s->String.slice(~start=0, ~end=idx))
+  } else {
+    None
+  }
+}
+
+let stripPluginSuffix = (s: string): option<string> => {
+  let suffix = "Plugin"
+  if s->String.endsWith(suffix) && s->String.length > suffix->String.length {
+    Some(s->String.slice(~start=0, ~end=s->String.length - suffix->String.length))
+  } else {
+    None
+  }
+}
+
+let firstDotSegment = (s: string): option<string> => {
+  let idx = s->String.indexOf(".")
+  if idx > 0 {
+    Some(s->String.slice(~start=0, ~end=idx))
+  } else {
+    None
+  }
+}
+
+let lastDotSegment = (s: string): option<string> => {
+  let idx = s->String.lastIndexOf(".")
+  if idx > 0 && idx + 1 < s->String.length {
+    Some(s->String.slice(~start=idx + 1, ~end=s->String.length))
+  } else {
+    None
+  }
+}
+
+let lookup = (name: string): option<string> =>
+  componentPluginRegistry.contents->Dict.get(name)
+
+// Last-resort candidate: the inner name is a registered component name carrying a
+// component-kind suffix (`Customers` + `ReadModel` → `CustomersReadModel`), which is
+// how event-collector resources are named. Longest prefix wins so `OrdersReadModel`
+// resolves via `Orders` rather than a shorter `Order` registered by another plugin.
+// LogPrefix sits below `ComponentType`, so this stays suffix-table-free.
+let longestRegisteredPrefix = (name: string): option<string> =>
+  componentPluginRegistry.contents
+  ->Dict.keysToArray
+  ->Array.reduce(None, (acc, key) =>
+    if key->String.length < name->String.length && name->String.startsWith(key) {
+      switch acc {
+      | Some(best) if best->String.length >= key->String.length => acc
+      | _ => Some(key)
+      }
+    } else {
+      acc
+    }
+  )
+  ->Option.flatMap(lookup)
+
+let resolvePlugin = (~comp=?, ()) =>
+  switch comp {
+  | Some(c) =>
+    switch extractInnerName(c) {
+    | Some(inner) =>
+      switch lookup(inner) {
+      | Some(p) => Some(p)
+      | None =>
+        switch currentPluginName.contents {
+        | Some(p) => Some(p)
+        | None =>
+          // Try transformations in declaration order; first hit wins.
+          let candidates = [
+            stripAtVersion(inner),
+            stripPluginSuffix(inner),
+            lastDotSegment(inner),
+            firstDotSegment(inner),
+          ]
+          candidates
+          ->Array.reduce(None, (acc, candidate) =>
+            switch acc {
+            | Some(_) => acc
+            | None => candidate->Option.flatMap(lookup)
+            }
+          )
+          ->Option.orElse(longestRegisteredPrefix(inner))
+        }
+      }
+    | None => currentPluginName.contents
+    }
+  | None => currentPluginName.contents
+  }
+
+// Plain (no ANSI) prefix used for Lambda/CloudWatch output.
+let fmtPlainPrefix = (~comp=?, ()) => {
+  let plugin = switch resolvePlugin(~comp?, ()) {
+  | Some(p) => `[${p}]`
+  | None => ""
+  }
+  let c = switch comp {
+  | Some(c) => `[${c}] `
+  | None => ""
+  }
+  plugin ++ c
+}
+
+// Bold-bracketed prefix used for terminal output.
+// Plugin bracket is colored (foreground) by a stable hash of the plugin name;
+// no trailing space between `[Plugin]` and `[Comp]`.
+//
+// Sink-aware: in a non-TTY/JSON sink it falls back to `fmtPlainPrefix` so no
+// ANSI colour or bold leaks into structured logs. This makes every caller that
+// pre-formats a prefix before reaching `Logger.emit` (EffectLogger.withComp,
+// the infra-layer `compLog`s) correct without per-call-site changes.
+let fmtComp = (~comp=?, ()) =>
+  if !AnsiStyle.useAnsi() {
+    fmtPlainPrefix(~comp?, ())
+  } else {
+    let plugin = switch resolvePlugin(~comp?, ()) {
+    | Some(p) => `${pluginColor(p)}${AnsiStyle.bold(`[${p}]`)}`
+    | None => ""
+    }
+    let c = switch comp {
+    | Some(c) => `${AnsiStyle.bold(`[${c}]`)} `
+    | None => ""
+    }
+    plugin ++ c
+  }

package/src/LogPrefix.res.mjs

@@ -0,0 +1,159 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
+import * as AnsiStyle$Reventless from "./AnsiStyle.res.mjs";
+
+let currentPluginName = {
+  contents: undefined
+};
+
+let componentPluginRegistry = {
+  contents: {}
+};
+
+function registerComponentPlugin(componentName, pluginName) {
+  componentPluginRegistry.contents[componentName] = pluginName;
+}
+
+function hashStr(s) {
+  let h = 0;
+  for (let i = 0, i_finish = s.length; i < i_finish; ++i) {
+    let code = Stdlib_Option.getOr(Stdlib_String.charCodeAt(s, i), 0);
+    h = h + (code * (i + 1 | 0) | 0) | 0;
+  }
+  return h;
+}
+
+let pluginColors = [
+  "\x1b[32m",
+  "\x1b[34m",
+  "\x1b[35m",
+  "\x1b[92m",
+  "\x1b[94m",
+  "\x1b[95m"
+];
+
+function pluginColor(name) {
+  return pluginColors[Primitive_int.mod_(hashStr(name), pluginColors.length)];
+}
+
+function extractInnerName(comp) {
+  let openIdx = comp.indexOf("(");
+  let closeIdx = comp.lastIndexOf(")");
+  if (openIdx > 0 && closeIdx > (openIdx + 1 | 0)) {
+    return comp.slice(openIdx + 1 | 0, closeIdx);
+  }
+}
+
+function stripAtVersion(s) {
+  let idx = s.indexOf("@");
+  if (idx > 0) {
+    return s.slice(0, idx);
+  }
+}
+
+function stripPluginSuffix(s) {
+  let suffix = "Plugin";
+  if (s.endsWith(suffix) && s.length > suffix.length) {
+    return s.slice(0, s.length - suffix.length | 0);
+  }
+}
+
+function firstDotSegment(s) {
+  let idx = s.indexOf(".");
+  if (idx > 0) {
+    return s.slice(0, idx);
+  }
+}
+
+function lastDotSegment(s) {
+  let idx = s.lastIndexOf(".");
+  if (idx > 0 && (idx + 1 | 0) < s.length) {
+    return s.slice(idx + 1 | 0, s.length);
+  }
+}
+
+function lookup(name) {
+  return componentPluginRegistry.contents[name];
+}
+
+function longestRegisteredPrefix(name) {
+  return Stdlib_Option.flatMap(Stdlib_Array.reduce(Object.keys(componentPluginRegistry.contents), undefined, (acc, key) => {
+    if (key.length < name.length && name.startsWith(key) && !(acc !== undefined && acc.length >= key.length)) {
+      return key;
+    } else {
+      return acc;
+    }
+  }), lookup);
+}
+
+function resolvePlugin(comp, param) {
+  if (comp === undefined) {
+    return currentPluginName.contents;
+  }
+  let inner = extractInnerName(comp);
+  if (inner === undefined) {
+    return currentPluginName.contents;
+  }
+  let p = componentPluginRegistry.contents[inner];
+  if (p !== undefined) {
+    return p;
+  }
+  let p$1 = currentPluginName.contents;
+  if (p$1 !== undefined) {
+    return p$1;
+  }
+  let candidates = [
+    stripAtVersion(inner),
+    stripPluginSuffix(inner),
+    lastDotSegment(inner),
+    firstDotSegment(inner)
+  ];
+  return Stdlib_Option.orElse(Stdlib_Array.reduce(candidates, undefined, (acc, candidate) => {
+    if (acc !== undefined) {
+      return acc;
+    } else {
+      return Stdlib_Option.flatMap(candidate, lookup);
+    }
+  }), longestRegisteredPrefix(inner));
+}
+
+function fmtPlainPrefix(comp, param) {
+  let p = resolvePlugin(comp, undefined);
+  let plugin = p !== undefined ? `[` + p + `]` : "";
+  let c = comp !== undefined ? `[` + comp + `] ` : "";
+  return plugin + c;
+}
+
+function fmtComp(comp, param) {
+  if (!AnsiStyle$Reventless.useAnsi()) {
+    return fmtPlainPrefix(comp, undefined);
+  }
+  let p = resolvePlugin(comp, undefined);
+  let plugin = p !== undefined ? pluginColor(p) + AnsiStyle$Reventless.bold(`[` + p + `]`) : "";
+  let c = comp !== undefined ? AnsiStyle$Reventless.bold(`[` + comp + `]`) + ` ` : "";
+  return plugin + c;
+}
+
+export {
+  currentPluginName,
+  componentPluginRegistry,
+  registerComponentPlugin,
+  hashStr,
+  pluginColors,
+  pluginColor,
+  extractInnerName,
+  stripAtVersion,
+  stripPluginSuffix,
+  firstDotSegment,
+  lastDotSegment,
+  lookup,
+  longestRegisteredPrefix,
+  resolvePlugin,
+  fmtPlainPrefix,
+  fmtComp,
+}
+/* AnsiStyle-Reventless Not a pure module */

package/src/PackageVersion.res

@@ -0,0 +1,67 @@
+let readVersion = (path: string) =>
+  NodeFs.readFileSync(path)
+  ->JSON.parseOrThrow
+  ->JSON.Decode.object
+  ->Option.flatMap(o => o->Dict.get("version"))
+  ->Option.flatMap(JSON.Decode.string)
+  ->Option.getOr("0.0.0")
+
+let fromCwd = () => readVersion("./package.json")
+
+let findVersion = dir => {
+  let rec find = dir => {
+    let candidate = NodePath.join([dir, "package.json"])
+    if NodeFs.existsSync(candidate) {
+      readVersion(candidate)
+    } else {
+      let parent = NodePath.dirname(dir)
+      if parent == dir {
+        "0.0.0"
+      } else {
+        find(parent)
+      }
+    }
+  }
+  find(dir)
+}
+
+let fromModuleUrl = (url: string) => findVersion(url->NodeUrl.fileURLToPath->NodePath.dirname)
+
+/** Detect the caller's file via V8 Structured Stack Trace API and read the
+    version from the nearest package.json. Skips frames from framework packages
+    (reventless-spec, reventless-core, reventless-infra, reventless-local,
+    reventless-aws, reventless-interop). Falls back to CWD's package.json. */
+let callerFile: unit => option<string> = %raw(`
+  function() {
+    var frameworkMarkers = [
+      '/reventless/',
+      '/@reventlessdev/reventless-',
+    ];
+    var oldPrepare = Error.prepareStackTrace;
+    Error.prepareStackTrace = function(_, stack) { return stack; };
+    var err = new Error();
+    var stack = err.stack;
+    Error.prepareStackTrace = oldPrepare;
+    for (var i = 0; i < stack.length; i++) {
+      var file = stack[i].getFileName();
+      if (!file) continue;
+      var isFramework = false;
+      for (var j = 0; j < frameworkMarkers.length; j++) {
+        if (file.indexOf(frameworkMarkers[j]) !== -1) { isFramework = true; break; }
+      }
+      if (!isFramework) return file;
+    }
+    return undefined;
+  }
+`)
+
+let fromCaller = () =>
+  switch callerFile() {
+  | Some(file) =>
+    if file->String.startsWith("file://") {
+      findVersion(file->NodeUrl.fileURLToPath->NodePath.dirname)
+    } else {
+      findVersion(file->NodePath.dirname)
+    }
+  | None => fromCwd()
+  }

package/src/PackageVersion.res.mjs

@@ -0,0 +1,81 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodeurl from "node:url";
+import * as Nodepath from "node:path";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function readVersion(path) {
+  return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(JSON.parse(Nodefs.readFileSync(path, "utf8"))), o => o["version"]), Stdlib_JSON.Decode.string), "0.0.0");
+}
+
+function fromCwd() {
+  return readVersion("./package.json");
+}
+
+function findVersion(dir) {
+  let _dir = dir;
+  while (true) {
+    let dir$1 = _dir;
+    let candidate = Nodepath.join(dir$1, "package.json");
+    if (Nodefs.existsSync(candidate)) {
+      return readVersion(candidate);
+    }
+    let parent = Nodepath.dirname(dir$1);
+    if (parent === dir$1) {
+      return "0.0.0";
+    }
+    _dir = parent;
+    continue;
+  };
+}
+
+function fromModuleUrl(url) {
+  return findVersion(Nodepath.dirname(Nodeurl.fileURLToPath(url)));
+}
+
+let callerFile = (function() {
+    var frameworkMarkers = [
+      '/reventless/',
+      '/@reventlessdev/reventless-',
+    ];
+    var oldPrepare = Error.prepareStackTrace;
+    Error.prepareStackTrace = function(_, stack) { return stack; };
+    var err = new Error();
+    var stack = err.stack;
+    Error.prepareStackTrace = oldPrepare;
+    for (var i = 0; i < stack.length; i++) {
+      var file = stack[i].getFileName();
+      if (!file) continue;
+      var isFramework = false;
+      for (var j = 0; j < frameworkMarkers.length; j++) {
+        if (file.indexOf(frameworkMarkers[j]) !== -1) { isFramework = true; break; }
+      }
+      if (!isFramework) return file;
+    }
+    return undefined;
+  });
+
+function fromCaller() {
+  let file = callerFile();
+  if (file !== undefined) {
+    if (file.startsWith("file://")) {
+      return findVersion(Nodepath.dirname(Nodeurl.fileURLToPath(file)));
+    } else {
+      return findVersion(Nodepath.dirname(file));
+    }
+  } else {
+    return readVersion("./package.json");
+  }
+}
+
+export {
+  readVersion,
+  fromCwd,
+  findVersion,
+  fromModuleUrl,
+  callerFile,
+  fromCaller,
+}
+/* node:fs Not a pure module */

package/src/components/Aggregate.res

@@ -0,0 +1,64 @@
+/**
+Module type for an aggregate's identity and schema specification.
+
+Every aggregate defines a `Spec` module satisfying this type. The `Spec` is
+used by `Platform.Aggregate.Make` and by `Behavior.T` to fix the aggregate's
+command, event, and error types.
+
+@example
+```rescript
+// Category.res
+module Id = Id.String
+let name = "Category"
+
+@schema
+type command =
+  | AddCategory({categoryId: string, name: string})
+  | RenameCategory({categoryId: string, name: string})
+  | ArchiveCategory({categoryId: string})
+
+@schema
+type event =
+  | CategoryAdded({categoryId: string, name: string})
+  | CategoryRenamed({categoryId: string, name: string})
+  | CategoryArchived({categoryId: string})
+
+@schema
+type error =
+  | CategoryAlreadyExists
+  | CategoryNotFound
+  | CategoryAlreadyArchived
+```
+*/
+module type Spec = {
+  module Id: Id.T
+
+  /** Logical aggregate name used as a prefix for infrastructure resource names. */
+  let name: string
+
+  /** Commands this aggregate accepts. Must carry `@schema`. */
+  @schema
+  type command
+
+  /** Events this aggregate emits. Must carry `@schema`. */
+  @schema
+  type event
+
+  /** Business rule violation errors. Must carry `@schema`. */
+  @schema
+  type error
+
+  /** Sury schema for the command type — generated automatically by `@schema`. */
+  let commandSchema: S.t<command>
+
+  /** File URL of this module (`import.meta.url`). Used by AWS builders to derive
+      the npm specifier for runtime dynamic imports. */
+  let moduleUrl: string
+
+  /** Authorization rule evaluated at the GraphQL resolver entry before any
+      command is dispatched. Auto-injected by `@@reventless.spec` and on
+      structurally-detected inline spec modules — defaults to
+      `AllowAuthenticated`; override at the file/module level with
+      `@@reventless.authorize(<rule>)`. */
+  let commandAuthorization: command => Authorization.permission
+}

package/src/components/Aggregate.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */