@reventlessdev/reventless-spec 3.0.0-alpha.143 → 3.0.0-alpha.144

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.144 (2026-09-23)
+
+* feat(node)!: every command-line tool reads its arguments through parseArgs ([2e41979](https://github.com/ReventlessDev/reventless-core/commit/2e41979b73646c46356e197e17eb4a3da0154c73))
+
+### BREAKING CHANGES
+
+* NodeProcess.onSignal takes the new NodeProcess.signal
+variant (SIGINT | SIGTERM | SIGHUP) instead of a polymorphic variant:
+write onSignal(SIGINT, …) for onSignal(#SIGINT, …). Node receives the
+same string.
+
+
+
 # 3.0.0-alpha.143 (2026-09-23)
 
 **Note:** Version bump only for package @reventlessdev/reventless-spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.143",
+  "version": "3.0.0-alpha.144",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -26,7 +26,7 @@
     "sury": "11.0.0",
     "sury-ppx": "11.0.0",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.14"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.15"
   },
   "devDependencies": {
     "rescript": "12.3.1",

package/run-certify-trait.mjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-import "./src/generator/CertifyTrait.res.mjs"
+import { main } from "./src/generator/CertifyTrait.res.mjs"
+await main()

package/run-generator.mjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-import "./src/generator/PluginGenerator.res.mjs"
+import { main } from "./src/generator/PluginGenerator.res.mjs"
+await main()

package/run-graft-trait.mjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-import "./src/generator/GraftTrait.res.mjs"
+import { main } from "./src/generator/GraftTrait.res.mjs"
+await main()

package/run-platform-generator.mjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-import "./src/generator/PlatformGenerator.res.mjs"
+import { main } from "./src/generator/PlatformGenerator.res.mjs"
+await main()

package/run-trait-manifest.mjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-import "./src/generator/TraitManifestCli.res.mjs"
+import { main } from "./src/generator/TraitManifestCli.res.mjs"
+await main()

package/src/CliArgs.res

@@ -0,0 +1,209 @@
+/***
+How every command-line tool in this repository reads `process.argv`: through
+Node's `parseArgs`, with mistakes worded the way these tools word them, and one
+behaviour on `--help`, on a usage mistake and on a bare invocation (see [run]).
+Non-strict with tokens rather than strict mode, because strict mode names the
+offending argument only inside English prose.
+*/
+
+/** An undeclared `--key` under `~pairs=true`: with a value, or on its own. */
+type value =
+  | Text(string)
+  | Present
+
+type t = {
+  values: NodeUtil.values,
+  positionals: array<string>,
+  pairs: array<(string, value)>,
+}
+
+/** A usage mistake. A tool that ran and failed exits 1, so a caller can tell a
+    misinvocation from a run whose answer was no. */
+let usageMistakeExit = 2
+
+let unknown = (arg: string) => `unknown argument "${arg}"`
+
+/** A positional the tool has no place for, worded like any other unknown argument. */
+let extra = (arg: string): result<'a, string> => Error(unknown(arg))
+
+/** `-` alone is a value (stdin, by convention); anything else starting with a
+    dash is the next flag, which a string option must not swallow. */
+let flagShaped = (value: string) => value->String.startsWith("-") && value != "-"
+
+/** Package managers can forward a bare `--` ahead of a script's own arguments.
+    Anywhere else it ends the options, as POSIX says. */
+let withoutLeadingTerminator = (argv: array<string>) =>
+  argv->Array.get(0) == Some("--") ? argv->Array.slice(~start=1, ~end=Array.length(argv)) : argv
+
+/** Parse against the declared options. `-h`/`--help` is declared for every
+    tool. The first mistake in argv order is the one reported. Under
+    `~pairs=true` an undeclared long option is kept as a `(key, value)` pair
+    instead of refused, taking the argument after it as its value when that
+    argument is not itself an option. */
+let parse = (
+  ~strings: array<string>=[],
+  ~bools: array<string>=[],
+  ~lists: array<string>=[],
+  ~pairs: bool=false,
+  argv: array<string>,
+): result<t, string> => {
+  let args = withoutLeadingTerminator(argv)
+  let options: dict<NodeUtil.optionConfig> = Dict.make()
+  options->Dict.set("help", {type_: Boolean, short: "h"})
+  bools->Array.forEach(name => options->Dict.set(name, {type_: Boolean}))
+  strings->Array.forEach(name => options->Dict.set(name, {type_: String}))
+  lists->Array.forEach(name => options->Dict.set(name, {type_: String, multiple: true}))
+
+  let parsed = NodeUtil.parseArgs({
+    args,
+    options,
+    strict: false,
+    allowPositionals: true,
+    tokens: true,
+  })
+  let tokens = parsed.tokens->Option.getOr([])
+  let positionals = []
+  let found = []
+
+  // Non-strict `parseArgs` types an undeclared option as a boolean and emits
+  // the argument after it as the next positional token, so a pair's value is
+  // read back from token order.
+  let rec walk = i =>
+    switch tokens->Array.get(i) {
+    | None => Ok()
+    | Some(token) =>
+      switch token.kind {
+      | Terminator => walk(i + 1)
+      | Positional =>
+        positionals->Array.push(token.value->Option.getOr(""))
+        walk(i + 1)
+      | Flag =>
+        let name = token.name->Option.getOr("")
+        let rawName = token.rawName->Option.getOr(name)
+        let inline = token.inlineValue->Option.getOr(false)
+        switch (options->Dict.get(name), token.value) {
+        | (Some({type_: String}), None) => Error(`${rawName} needs a value`)
+        | (Some({type_: String}), Some(v)) if !inline && flagShaped(v) =>
+          Error(`${rawName} needs a value`)
+        | (Some({type_: Boolean}), Some(_)) => Error(`${rawName} takes no value`)
+        | (Some(_), _) => walk(i + 1)
+        | (None, _) if !pairs || !(rawName->String.startsWith("--")) => Error(unknown(rawName))
+        | (None, Some(v)) =>
+          found->Array.push((name, Text(v)))
+          walk(i + 1)
+        | (None, None) =>
+          switch tokens->Array.get(i + 1) {
+          | Some({kind: Positional, index, value: ?Some(v)}) if index == token.index + 1 =>
+            found->Array.push((name, Text(v)))
+            walk(i + 2)
+          | _ =>
+            found->Array.push((name, Present))
+            walk(i + 1)
+          }
+        }
+      }
+    }
+
+  walk(0)->Result.map(() => {values: parsed.values, positionals, pairs: found})
+}
+
+let string = (t: t, name: string): option<string> => t.values->NodeUtil.string(name)
+let bool = (t: t, name: string): bool => t.values->NodeUtil.bool(name)->Option.getOr(false)
+let strings = (t: t, name: string): array<string> =>
+  t.values->NodeUtil.strings(name)->Option.getOr([])
+let positionals = (t: t): array<string> => t.positionals
+let pairs = (t: t): array<(string, value)> => t.pairs
+let help = (t: t): bool => t->bool("help")
+
+/** For a tool that takes at most `max` positionals: the first beyond them is
+    refused as [extra]. */
+let atMost = (t: t, max: int): result<t, string> =>
+  switch t.positionals->Array.get(max) {
+  | None => Ok(t)
+  | Some(arg) => extra(arg)
+  }
+
+let noPositionals = (t: t): result<t, string> => t->atMost(0)
+
+/** Whether `-h` or `--help` appears before any `--` that ends the options.
+    Read off argv rather than a parse, so it answers even when the other
+    arguments are wrong. */
+let asksForHelp = (argv: array<string>): bool => {
+  let argv = withoutLeadingTerminator(argv)
+  let options = switch argv->Array.indexOf("--") {
+  | -1 => argv
+  | end => argv->Array.slice(~start=0, ~end)
+  }
+  options->Array.some(arg => arg == "-h" || arg == "--help")
+}
+
+/** A tool's command line: its name, its usage (first line `Usage: <bin> …`),
+    and how it turns argv into its arguments. */
+type cli<'args> = {
+  bin: string,
+  usage: string,
+  parse: array<string> => result<'args, string>,
+}
+
+/** Where [run] writes and how it ends the process, so a test can watch it. */
+type io = {
+  out: string => unit,
+  err: string => unit,
+  exit: int => unit,
+}
+
+let processIo = {
+  out: text => Console.log(text),
+  err: text => Console.error(text),
+  exit: NodeProcess.exit,
+}
+
+/** Help anywhere prints the usage to stdout and exits 0, whatever else is
+    wrong. A usage mistake prints `<bin>: <message>`, a blank line and the usage
+    to stderr and exits 2. Otherwise `main` gets the arguments, and its own
+    failures keep their exit 1. */
+let run = async (
+  cli: cli<'args>,
+  ~argv: option<array<string>>=?,
+  ~io: io=processIo,
+  main: 'args => promise<unit>,
+): unit => {
+  let argv =
+    argv->Option.getOr(NodeProcess.argv->Array.slice(~start=2, ~end=NodeProcess.argv->Array.length))
+  let usage = cli.usage->String.trim
+  if asksForHelp(argv) {
+    io.out(usage)
+    io.exit(0)
+  } else {
+    switch cli.parse(argv) {
+    | Error(message) =>
+      io.err(`${cli.bin}: ${message}\n\n${usage}`)
+      io.exit(usageMistakeExit)
+    | Ok(args) => await main(args)
+    }
+  }
+}
+
+/** What [run] did with one argv, for a tool's own tests. */
+type observed = {
+  stdout: array<string>,
+  stderr: array<string>,
+  exitCode: option<int>,
+  reachedMain: bool,
+}
+
+/** Run a tool's command line without a process: nothing is printed, nothing
+    exits, and `main` is not called — only whether it would have been. */
+let observe = async (cli: cli<'args>, argv: array<string>): observed => {
+  let stdout = []
+  let stderr = []
+  let exitCode = ref(None)
+  let reachedMain = ref(false)
+  let io = {
+    out: text => stdout->Array.push(text),
+    err: text => stderr->Array.push(text),
+    exit: code => exitCode := Some(code),
+  }
+  await run(cli, ~argv, ~io, async _ => reachedMain := true)
+  {stdout, stderr, exitCode: exitCode.contents, reachedMain: reachedMain.contents}
+}

package/src/CliArgs.res.mjs

@@ -0,0 +1,325 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodeutil from "node:util";
+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 Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+
+function unknown(arg) {
+  return `unknown argument "` + arg + `"`;
+}
+
+function extra(arg) {
+  return {
+    TAG: "Error",
+    _0: unknown(arg)
+  };
+}
+
+function flagShaped(value) {
+  if (value.startsWith("-")) {
+    return value !== "-";
+  } else {
+    return false;
+  }
+}
+
+function withoutLeadingTerminator(argv) {
+  if (Primitive_object.equal(argv[0], "--")) {
+    return argv.slice(1, argv.length);
+  } else {
+    return argv;
+  }
+}
+
+function parse(stringsOpt, boolsOpt, listsOpt, pairsOpt, argv) {
+  let strings = stringsOpt !== undefined ? stringsOpt : [];
+  let bools = boolsOpt !== undefined ? boolsOpt : [];
+  let lists = listsOpt !== undefined ? listsOpt : [];
+  let pairs = pairsOpt !== undefined ? pairsOpt : false;
+  let args = withoutLeadingTerminator(argv);
+  let options = {};
+  options["help"] = {
+    type: "boolean",
+    short: "h"
+  };
+  bools.forEach(name => {
+    options[name] = {
+      type: "boolean"
+    };
+  });
+  strings.forEach(name => {
+    options[name] = {
+      type: "string"
+    };
+  });
+  lists.forEach(name => {
+    options[name] = {
+      type: "string",
+      multiple: true
+    };
+  });
+  let parsed = Nodeutil.parseArgs({
+    args: args,
+    options: options,
+    strict: false,
+    allowPositionals: true,
+    tokens: true
+  });
+  let tokens = Stdlib_Option.getOr(parsed.tokens, []);
+  let positionals = [];
+  let found = [];
+  let walk = _i => {
+    while (true) {
+      let i = _i;
+      let token = tokens[i];
+      if (token === undefined) {
+        return {
+          TAG: "Ok",
+          _0: undefined
+        };
+      }
+      let match = token.kind;
+      switch (match) {
+        case "option" :
+          let name = Stdlib_Option.getOr(token.name, "");
+          let rawName = Stdlib_Option.getOr(token.rawName, name);
+          let inline = Stdlib_Option.getOr(token.inlineValue, false);
+          let match$1 = options[name];
+          let match$2 = token.value;
+          if (match$1 !== undefined) {
+            if (match$1.type === "string") {
+              if (match$2 === undefined) {
+                return {
+                  TAG: "Error",
+                  _0: rawName + ` needs a value`
+                };
+              }
+              if (!inline && flagShaped(match$2)) {
+                return {
+                  TAG: "Error",
+                  _0: rawName + ` needs a value`
+                };
+              }
+              _i = i + 1 | 0;
+              continue;
+            }
+            if (match$2 !== undefined) {
+              return {
+                TAG: "Error",
+                _0: rawName + ` takes no value`
+              };
+            }
+            _i = i + 1 | 0;
+            continue;
+          }
+          if (!pairs || !rawName.startsWith("--")) {
+            return {
+              TAG: "Error",
+              _0: unknown(rawName)
+            };
+          }
+          if (match$2 !== undefined) {
+            found.push([
+              name,
+              {
+                TAG: "Text",
+                _0: match$2
+              }
+            ]);
+            _i = i + 1 | 0;
+            continue;
+          }
+          let match$3 = tokens[i + 1 | 0];
+          if (match$3 !== undefined) {
+            switch (match$3.kind) {
+              case "positional" :
+                let v = match$3.value;
+                if (v !== undefined && match$3.index === (token.index + 1 | 0)) {
+                  found.push([
+                    name,
+                    {
+                      TAG: "Text",
+                      _0: v
+                    }
+                  ]);
+                  _i = i + 2 | 0;
+                  continue;
+                }
+                break;
+              case "option" :
+              case "option-terminator" :
+                break;
+            }
+          }
+          found.push([
+            name,
+            "Present"
+          ]);
+          _i = i + 1 | 0;
+          continue;
+          break;
+        case "positional" :
+          positionals.push(Stdlib_Option.getOr(token.value, ""));
+          _i = i + 1 | 0;
+          continue;
+        case "option-terminator" :
+          _i = i + 1 | 0;
+          continue;
+      }
+    };
+  };
+  return Stdlib_Result.map(walk(0), () => ({
+    values: parsed.values,
+    positionals: positionals,
+    pairs: found
+  }));
+}
+
+function string(t, name) {
+  return t.values[name];
+}
+
+function bool(t, name) {
+  return Stdlib_Option.getOr(t.values[name], false);
+}
+
+function strings(t, name) {
+  return Stdlib_Option.getOr(t.values[name], []);
+}
+
+function positionals(t) {
+  return t.positionals;
+}
+
+function pairs(t) {
+  return t.pairs;
+}
+
+function help(t) {
+  return bool(t, "help");
+}
+
+function atMost(t, max) {
+  let arg = t.positionals[max];
+  if (arg !== undefined) {
+    return {
+      TAG: "Error",
+      _0: unknown(arg)
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: t
+    };
+  }
+}
+
+function noPositionals(t) {
+  return atMost(t, 0);
+}
+
+function asksForHelp(argv) {
+  let argv$1 = withoutLeadingTerminator(argv);
+  let end = argv$1.indexOf("--");
+  let options = end !== -1 ? argv$1.slice(0, end) : argv$1;
+  return options.some(arg => {
+    if (arg === "-h") {
+      return true;
+    } else {
+      return arg === "--help";
+    }
+  });
+}
+
+function processIo_out(text) {
+  console.log(text);
+}
+
+function processIo_err(text) {
+  console.error(text);
+}
+
+function processIo_exit(prim) {
+  process.exit(prim);
+}
+
+let processIo = {
+  out: processIo_out,
+  err: processIo_err,
+  exit: processIo_exit
+};
+
+async function run(cli, argv, ioOpt, main) {
+  let io = ioOpt !== undefined ? ioOpt : processIo;
+  let argv$1 = Stdlib_Option.getOr(argv, process.argv.slice(2, process.argv.length));
+  let usage = cli.usage.trim();
+  if (asksForHelp(argv$1)) {
+    io.out(usage);
+    return io.exit(0);
+  }
+  let message = cli.parse(argv$1);
+  if (message.TAG === "Ok") {
+    return await main(message._0);
+  }
+  io.err(cli.bin + `: ` + message._0 + `\n\n` + usage);
+  return io.exit(2);
+}
+
+async function observe(cli, argv) {
+  let stdout = [];
+  let stderr = [];
+  let exitCode = {
+    contents: undefined
+  };
+  let reachedMain = {
+    contents: false
+  };
+  let io_out = text => {
+    stdout.push(text);
+  };
+  let io_err = text => {
+    stderr.push(text);
+  };
+  let io_exit = code => {
+    exitCode.contents = code;
+  };
+  let io = {
+    out: io_out,
+    err: io_err,
+    exit: io_exit
+  };
+  await run(cli, argv, io, async param => {
+    reachedMain.contents = true;
+  });
+  return {
+    stdout: stdout,
+    stderr: stderr,
+    exitCode: exitCode.contents,
+    reachedMain: reachedMain.contents
+  };
+}
+
+let usageMistakeExit = 2;
+
+export {
+  usageMistakeExit,
+  unknown,
+  extra,
+  flagShaped,
+  withoutLeadingTerminator,
+  parse,
+  string,
+  bool,
+  strings,
+  positionals,
+  pairs,
+  help,
+  atMost,
+  noPositionals,
+  asksForHelp,
+  processIo,
+  run,
+  observe,
+}
+/* node:util Not a pure module */