@reventlessdev/reventless-spec 3.0.0-alpha.124 → 3.0.0-alpha.126

package/src/generator/GraftTrait.res

@@ -0,0 +1,230 @@
+// Graft a domain trait into a plugin: write the spec surface it can own, print
+// the arms it cannot.
+//
+// Usage: graft-trait <trait-package> --into <srcDir> --tests <testsDir> [--key value …]
+//
+// The trait is resolved **by the name it is given** and its scaffold module is
+// dynamically imported. That is what keeps this file honest: `reventless-spec`
+// ships the CLI and never depends on a trait, so the rule that framework
+// packages never import one survives a generator that runs their code.
+//
+// Every remaining `--key value` becomes a config field, handed to the trait's
+// own sury-validated schema. A misspelled key is a decode error naming the key,
+// here, rather than a placeholder that survives into a file and fails at
+// compile — which is the whole difference between this and a text template.
+
+@val external dynImport: string => promise<'a> = "import"
+
+// ── The dynamic-import boundary ──────────────────────────────────────────────
+//
+// Typed at the boundary: a trait's scaffold module exports exactly these two,
+// and everything downstream is ordinary typed ReScript. Same shape as
+// `EmitCapabilities`, which reaches a composition root the same way.
+
+type file = {path: string, contents: string}
+type patch = {into: string, at: string, contents: string}
+type output = {files: array<file>, patches: array<patch>}
+type scaffoldExports = {
+  configSchema: S.t<unknown>,
+  emit: (~config: unknown, ~into: string, ~tests: string) => output,
+}
+
+let fail = (message: string) => {
+  Console.error("graft-trait: " ++ message)
+  NodeProcess.exit(1)
+}
+
+let usage = `Usage: graft-trait <trait-package> --into <srcDir> --tests <testsDir> [--key value …]
+
+  <trait-package>  the installed trait, e.g. @reventlessdev/trait-attachments
+  --into           where the graft's own components are written
+  --tests          where its conformance binding is written
+  --dry-run        print what would be written, write nothing
+
+  Every other --key value is a field of the trait's config. The trait validates
+  them, so run it once to be told what it wants.`
+
+// ── Arguments ────────────────────────────────────────────────────────────────
+
+/** `--key value` pairs, in order, with the leading positional taken off first.
+    A flag with no value (`--dry-run`) reads as `true`, so the config schema can
+    take it as a boolean without the CLI knowing which keys are flags. */
+let parseFlags = (args: array<string>): dict<JSON.t> => {
+  let out = Dict.make()
+  let rec go = i =>
+    switch args->Array.get(i) {
+    | None => ()
+    | Some(arg) if arg->String.startsWith("--") =>
+      let key = arg->String.sliceToEnd(~start=2)
+      switch args->Array.get(i + 1) {
+      | Some(value) if !(value->String.startsWith("--")) =>
+        out->Dict.set(key, JSON.Encode.string(value))
+        go(i + 2)
+      | _ =>
+        out->Dict.set(key, JSON.Encode.bool(true))
+        go(i + 1)
+      }
+    | Some(_) => go(i + 1)
+    }
+  go(0)
+  out
+}
+
+/** A comma-separated value becomes an array. Applied only to keys the trait's
+    schema declares as arrays, so a name that happens to contain a comma is not
+    split behind the author's back. */
+let splitList = (value: string): JSON.t =>
+  value
+  ->String.split(",")
+  ->Array.map(part => part->String.trim)
+  ->Array.filter(part => part != "")
+  ->Array.map(JSON.Encode.string)
+  ->JSON.Encode.array
+
+let arrayFieldNames = (schema: S.t<unknown>): array<string> =>
+  switch schema {
+  | Object({properties}) =>
+    properties
+    ->Dict.toArray
+    ->Array.filterMap(((name, field)) =>
+      switch field {
+      | Array(_) => Some(name)
+      | AnyOf({anyOf}) =>
+        anyOf->Array.some(m =>
+          switch m {
+          | Array(_) => true
+          | _ => false
+          }
+        )
+          ? Some(name)
+          : None
+      | _ => None
+      }
+    )
+  | _ => []
+  }
+
+// ── Entry point ──────────────────────────────────────────────────────────────
+
+let main = async () => {
+  let argv = NodeProcess.argv->Array.sliceToEnd(~start=2)
+  switch argv->Array.get(0) {
+  | None | Some("") | Some("--help") | Some("-h") => {
+      Console.log(usage)
+      NodeProcess.exit(argv->Array.length == 0 ? 1 : 0)
+    }
+  | Some(traitPackage) => {
+      let flags = parseFlags(argv->Array.sliceToEnd(~start=1))
+      let stringFlag = key => flags->Dict.get(key)->Option.flatMap(JSON.Decode.string)
+      let into = stringFlag("into")
+      let tests = stringFlag("tests")
+      let dryRun = flags->Dict.get("dry-run")->Option.isSome
+
+      switch (into, tests) {
+      | (None, _) | (_, None) => fail("--into and --tests are both required.\n\n" ++ usage)
+      | (Some(into), Some(tests)) => {
+          // Resolved by name, from the consumer's own `node_modules`. A trait
+          // that ships no scaffold fails here, saying so, rather than half-way
+          // through writing files.
+          // `@scope/trait-attachments` → `Attachments_Scaffold`;
+          // `@scope/trait-address-geocoding` → `AddressGeocoding_Scaffold`.
+          let scaffoldModule =
+            traitPackage
+            ->String.split("/")
+            ->Array.last
+            ->Option.getOr("")
+            ->String.replace("trait-", "")
+            ->String.split("-")
+            ->Array.map(part =>
+              part->String.charAt(0)->String.toUpperCase ++ part->String.sliceToEnd(~start=1)
+            )
+            ->Array.join("") ++ "_Scaffold"
+          let specifier = `${traitPackage}/src/${scaffoldModule}.res.mjs`
+          // Resolved from the **caller's** directory, not this file's. The trait
+          // is a dependency of the plugin being grafted, and deliberately not one
+          // of this package — a bare `import()` here would look in
+          // `reventless-spec`'s own tree and never find it. Same reason
+          // `HostShellDist` reaches for the host shell this way.
+          let modulePath = try NodeModule.createRequire(
+            NodeProcess.cwd() ++ "/index.js",
+          )->NodeModule.requireResolve(specifier) catch {
+          | _ => specifier
+          }
+          let scaffold: scaffoldExports = try await dynImport(
+            NodeUrl.pathToFileURL(modulePath)["href"],
+          ) catch {
+          | _ =>
+            fail(
+              `${traitPackage} ships no scaffold (looked for ${specifier}).\n` ++
+              `  Not every trait has one — a trait whose graft is all patches has nothing to write.\n` ++
+              `  Write the graft by hand instead; its README says what the host must declare.`,
+            )
+            %raw(`undefined`)
+          }
+
+          // The trait validates its own config, so the CLI never learns a
+          // trait's vocabulary — and a misspelled key is named here.
+          let listFields = arrayFieldNames(scaffold.configSchema)
+          let raw = Dict.make()
+          flags
+          ->Dict.toArray
+          ->Array.forEach(((key, value)) =>
+            switch (listFields->Array.includes(key), value->JSON.Decode.string) {
+            | (true, Some(text)) => raw->Dict.set(key, splitList(text))
+            | _ => raw->Dict.set(key, value)
+            }
+          )
+          ["into", "tests", "dry-run"]->Array.forEach(k => raw->Dict.delete(k))
+
+          let config = try raw->JSON.Encode.object->Util_Sury.fromJson(scaffold.configSchema) catch {
+          | exn => {
+              fail(
+                `${traitPackage} refused this config: ${Util_Sury.exnMessage(exn)}\n` ++
+                `  Every --key is a field of the trait's own config; it decides what it needs.`,
+              )
+              %raw(`undefined`)
+            }
+          }
+
+          let {files, patches} = scaffold.emit(~config, ~into, ~tests)
+
+          files->Array.forEach(({path, contents}) =>
+            if dryRun {
+              Console.log(`Would write: ${path} (${contents->String.split("\n")->Array.length->Int.toString} lines)`)
+            } else if NodeFs.existsSync(path) {
+              // Never overwrite. From the moment a graft lands it is the host's
+              // source, edited with the policy the trait deliberately does not
+              // write — silently replacing it would delete exactly the part no
+              // generator can reproduce.
+              Console.log(`Skipped (exists): ${path}`)
+            } else {
+              NodeFs.mkdirSync(NodePath.dirname(path), {recursive: true})
+              NodeFs.writeFileSync(path, contents)
+              Console.log(`Wrote: ${path}`)
+            }
+          )
+
+          if patches->Array.length > 0 {
+            Console.log("")
+            Console.log("── Paste these; they go into files you already own ──────────────")
+            patches->Array.forEach(({into, at, contents}) => {
+              Console.log("")
+              Console.log(`# ${into} — ${at}`)
+              Console.log(contents)
+            })
+            Console.log("")
+            Console.log(
+              "Printed rather than written: placing an arm in an existing ordered `switch`\n" ++
+              "is an AST operation, and a text splice into the wrong arm is a bug the\n" ++
+              "compiler cannot see.",
+            )
+          }
+
+          NodeProcess.exit(0)
+        }
+      }
+    }
+  }
+}
+
+await main()

package/src/generator/GraftTrait.res.mjs

@@ -0,0 +1,193 @@
+// 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_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Nodemodule from "node:module";
+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 Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
+
+function fail(message) {
+  console.error("graft-trait: " + message);
+  process.exit(1);
+}
+
+let usage = `Usage: graft-trait <trait-package> --into <srcDir> --tests <testsDir> [--key value …]
+
+  <trait-package>  the installed trait, e.g. @reventlessdev/trait-attachments
+  --into           where the graft's own components are written
+  --tests          where its conformance binding is written
+  --dry-run        print what would be written, write nothing
+
+  Every other --key value is a field of the trait's config. The trait validates
+  them, so run it once to be told what it wants.`;
+
+function parseFlags(args) {
+  let out = {};
+  let go = _i => {
+    while (true) {
+      let i = _i;
+      let arg = args[i];
+      if (arg === undefined) {
+        return;
+      }
+      if (arg.startsWith("--")) {
+        let key = arg.slice(2);
+        let value = args[i + 1 | 0];
+        if (value !== undefined && !value.startsWith("--")) {
+          out[key] = value;
+          _i = i + 2 | 0;
+          continue;
+        }
+        out[key] = true;
+        _i = i + 1 | 0;
+        continue;
+      }
+      _i = i + 1 | 0;
+      continue;
+    };
+  };
+  go(0);
+  return out;
+}
+
+function splitList(value) {
+  return value.split(",").map(part => part.trim()).filter(part => part !== "").map(prim => prim);
+}
+
+function arrayFieldNames(schema) {
+  if (schema.type === "object") {
+    return Stdlib_Array.filterMap(Object.entries(schema.properties), param => {
+      let field = param[1];
+      let name = param[0];
+      switch (field.type) {
+        case "array" :
+          return name;
+        case "anyOf" :
+          if (field.anyOf.some(m => m.type === "array")) {
+            return name;
+          } else {
+            return;
+          }
+        default:
+          return;
+      }
+    });
+  } else {
+    return [];
+  }
+}
+
+async function main() {
+  let argv = process.argv.slice(2);
+  let traitPackage = argv[0];
+  if (traitPackage !== undefined) {
+    switch (traitPackage) {
+      case "" :
+      case "--help" :
+      case "-h" :
+        break;
+      default:
+        let flags = parseFlags(argv.slice(1));
+        let stringFlag = key => Stdlib_Option.flatMap(flags[key], Stdlib_JSON.Decode.string);
+        let into = stringFlag("into");
+        let tests = stringFlag("tests");
+        let dryRun = Stdlib_Option.isSome(flags["dry-run"]);
+        if (into === undefined) {
+          return fail("--into and --tests are both required.\n\n" + usage);
+        }
+        if (tests === undefined) {
+          return fail("--into and --tests are both required.\n\n" + usage);
+        }
+        let scaffoldModule = Stdlib_Option.getOr(Stdlib_Array.last(traitPackage.split("/")), "").replace("trait-", "").split("-").map(part => part.charAt(0).toUpperCase() + part.slice(1)).join("") + "_Scaffold";
+        let specifier = traitPackage + `/src/` + scaffoldModule + `.res.mjs`;
+        let modulePath;
+        try {
+          modulePath = Nodemodule.createRequire(process.cwd() + "/index.js").resolve(specifier);
+        } catch (exn) {
+          modulePath = specifier;
+        }
+        let scaffold;
+        try {
+          scaffold = await import(Nodeurl.pathToFileURL(modulePath).href);
+        } catch (exn$1) {
+          fail(traitPackage + ` ships no scaffold (looked for ` + specifier + `).\n  Not every trait has one — a trait whose graft is all patches has nothing to write.\n  Write the graft by hand instead; its README says what the host must declare.`);
+          scaffold = undefined;
+        }
+        let listFields = arrayFieldNames(scaffold.configSchema);
+        let raw = {};
+        Object.entries(flags).forEach(param => {
+          let value = param[1];
+          let key = param[0];
+          let match = listFields.includes(key);
+          let match$1 = Stdlib_JSON.Decode.string(value);
+          if (match && match$1 !== undefined) {
+            raw[key] = splitList(match$1);
+          } else {
+            raw[key] = value;
+          }
+        });
+        [
+          "into",
+          "tests",
+          "dry-run"
+        ].forEach(k => Stdlib_Dict.$$delete(raw, k));
+        let config;
+        try {
+          config = Util_Sury$Reventless.fromJson(raw, scaffold.configSchema);
+        } catch (raw_exn) {
+          let exn$2 = Primitive_exceptions.internalToException(raw_exn);
+          fail(traitPackage + ` refused this config: ` + Util_Sury$Reventless.exnMessage(exn$2, undefined) + `\n  Every --key is a field of the trait's own config; it decides what it needs.`);
+          config = undefined;
+        }
+        let match = scaffold.emit(config, into, tests);
+        let patches = match.patches;
+        match.files.forEach(param => {
+          let contents = param.contents;
+          let path = param.path;
+          if (dryRun) {
+            console.log(`Would write: ` + path + ` (` + contents.split("\n").length.toString() + ` lines)`);
+          } else if (Nodefs.existsSync(path)) {
+            console.log(`Skipped (exists): ` + path);
+          } else {
+            Nodefs.mkdirSync(Nodepath.dirname(path), {
+              recursive: true
+            });
+            Nodefs.writeFileSync(path, contents, "utf8");
+            console.log(`Wrote: ` + path);
+          }
+        });
+        if (patches.length !== 0) {
+          console.log("");
+          console.log("── Paste these; they go into files you already own ──────────────");
+          patches.forEach(param => {
+            console.log("");
+            console.log(`# ` + param.into + ` — ` + param.at);
+            console.log(param.contents);
+          });
+          console.log("");
+          console.log("Printed rather than written: placing an arm in an existing ordered `switch`\nis an AST operation, and a text splice into the wrong arm is a bug the\ncompiler cannot see.");
+        }
+        process.exit(0);
+        return;
+    }
+  }
+  console.log(usage);
+  process.exit(argv.length === 0 ? 1 : 0);
+}
+
+await main();
+
+export {
+  fail,
+  usage,
+  parseFlags,
+  splitList,
+  arrayFieldNames,
+  main,
+}
+/*  Not a pure module */

package/src/generator/PlatformCodegen.res

@@ -17,17 +17,20 @@ type pluginManifest = {
   manifest: CapabilityManifest.t,
 }
 
-/** One declaring site, keeping which plugin's manifest carried it. */
+/** One declaring site, keeping which plugin's manifest carried it. `field` is
+    absent for a capability a slice declares — there is no field to name. */
 type provenance = {
   pluginName: string,
   component: string,
-  field: string,
+  field: option<string>,
   annotation: option<string>,
 }
 
-/** One capability the platform must provision: the qualified `{plugin}.{store}`
-    key with every declaring site across every plugin. Identity is the key —
-    many fields, in several plugins, legitimately name one store. */
+/** One capability the platform must provision: the key — a qualified
+    `{plugin}.{store}` for a store, the capability's own name otherwise — with
+    every declaring site across every plugin. Identity is the key: many fields,
+    in several plugins, legitimately name one store, and several slices
+    legitimately need one capability. */
 type unionEntry = {
   kind: CapabilityManifest.kind,
   key: string,
@@ -83,31 +86,42 @@ let splitKey = (key: string): option<(string, string)> =>
 //
 // A site with no recorded store predates the recording. It still names the
 // field, which is the comment's job; it just makes no claim it cannot support.
+let renderComments = (entry: unionEntry): array<string> =>
+  entry.declaredBy->Array.map(site => {
+    let site_ = switch site.field {
+    | Some(field) => `  // ${site.pluginName}: ${site.component}.${field}`
+    | None => `  // ${site.pluginName}: ${site.component}`
+    }
+    // `→ store` rather than `@storageRef("store")`: a field may name its
+    // store by annotation *or* by being named, and the manifest carries
+    // the store either way without saying which. Naming the annotation
+    // would send a reader looking for source text a derived field has not
+    // got.
+    switch site.annotation {
+    | Some(annotation) => `${site_} → ${annotation}`
+    | None => site_
+    }
+  })
+
 let renderEntry = (entry: unionEntry): result<array<string>, string> =>
-  switch splitKey(entry.key) {
-  | None =>
-    Error(
-      `malformed capability key ${quote(entry.key)} — expected "{plugin}.{store}" (is the plugin's capabilities.json hand-edited?)`,
-    )
-  | Some((plugin, store)) => {
-      let comments =
-        entry.declaredBy->Array.map(site => {
-          let site_ = `  // ${site.pluginName}: ${site.component}.${site.field}`
-          // `→ store` rather than `@storageRef("store")`: a field may name its
-          // store by annotation *or* by being named, and the manifest carries
-          // the store either way without saying which. Naming the annotation
-          // would send a reader looking for source text a derived field has not
-          // got.
-          switch site.annotation {
-          | Some(annotation) => `${site_} → ${annotation}`
-          | None => site_
-          }
-        })
-      let line = switch entry.kind {
-      | ObjectStore => `  ObjectStore({plugin: ${quote(plugin)}, store: ${quote(store)}}),`
-      }
-      Ok(comments->Array.concat([line]))
+  switch entry.kind {
+  | ObjectStore =>
+    switch splitKey(entry.key) {
+    | None =>
+      Error(
+        `malformed capability key ${quote(entry.key)} — expected "{plugin}.{store}" (is the plugin's capabilities.json hand-edited?)`,
+      )
+    | Some((plugin, store)) =>
+      Ok(
+        renderComments(entry)->Array.concat([
+          `  ObjectStore({plugin: ${quote(plugin)}, store: ${quote(store)}}),`,
+        ]),
+      )
     }
+  // A capability with no per-plugin identity: one arm however many slices
+  // declared it, with every declaring slice kept as provenance.
+  | Geocoding => Ok(renderComments(entry)->Array.concat(["  Geocoding,"]))
+  | Messaging => Ok(renderComments(entry)->Array.concat(["  Messaging,"]))
   }
 
 /**
@@ -170,8 +184,8 @@ let header = [
   "//",
   "// The platform's capability list, unioned from the committed",
   "// `capabilities.json` manifests of the plugins deploy-manifest.yaml names.",
-  "// Each entry keeps its declaring fields as provenance, so when a capability",
-  "// disappears from this list, the diff says which field's change removed it.",
+  "// Each entry keeps its declaring sites as provenance, so when a capability",
+  "// disappears from this list, the diff says which change removed it.",
   "",
 ]
 

package/src/generator/PlatformCodegen.res.mjs

@@ -47,16 +47,10 @@ function splitKey(key) {
   ]);
 }
 
-function renderEntry(entry) {
-  let match = splitKey(entry.key);
-  if (match === undefined) {
-    return {
-      TAG: "Error",
-      _0: `malformed capability key ` + JSON.stringify(entry.key) + ` — expected "{plugin}.{store}" (is the plugin's capabilities.json hand-edited?)`
-    };
-  }
-  let comments = entry.declaredBy.map(site => {
-    let site_ = `  // ` + site.pluginName + `: ` + site.component + `.` + site.field;
+function renderComments(entry) {
+  return entry.declaredBy.map(site => {
+    let field = site.field;
+    let site_ = field !== undefined ? `  // ` + site.pluginName + `: ` + site.component + `.` + field : `  // ` + site.pluginName + `: ` + site.component;
     let annotation = site.annotation;
     if (annotation !== undefined) {
       return site_ + ` → ` + annotation;
@@ -64,11 +58,35 @@ function renderEntry(entry) {
       return site_;
     }
   });
-  let line = `  ObjectStore({plugin: ` + JSON.stringify(match[0]) + `, store: ` + JSON.stringify(match[1]) + `}),`;
-  return {
-    TAG: "Ok",
-    _0: comments.concat([line])
-  };
+}
+
+function renderEntry(entry) {
+  let match = entry.kind;
+  switch (match) {
+    case "ObjectStore" :
+      let match$1 = splitKey(entry.key);
+      if (match$1 !== undefined) {
+        return {
+          TAG: "Ok",
+          _0: renderComments(entry).concat([`  ObjectStore({plugin: ` + JSON.stringify(match$1[0]) + `, store: ` + JSON.stringify(match$1[1]) + `}),`])
+        };
+      } else {
+        return {
+          TAG: "Error",
+          _0: `malformed capability key ` + JSON.stringify(entry.key) + ` — expected "{plugin}.{store}" (is the plugin's capabilities.json hand-edited?)`
+        };
+      }
+    case "Geocoding" :
+      return {
+        TAG: "Ok",
+        _0: renderComments(entry).concat(["  Geocoding,"])
+      };
+    case "Messaging" :
+      return {
+        TAG: "Ok",
+        _0: renderComments(entry).concat(["  Messaging,"])
+      };
+  }
 }
 
 function duplicatePluginOwners(entries) {
@@ -106,8 +124,8 @@ let header = [
   "//",
   "// The platform's capability list, unioned from the committed",
   "// `capabilities.json` manifests of the plugins deploy-manifest.yaml names.",
-  "// Each entry keeps its declaring fields as provenance, so when a capability",
-  "// disappears from this list, the diff says which field's change removed it.",
+  "// Each entry keeps its declaring sites as provenance, so when a capability",
+  "// disappears from this list, the diff says which change removed it.",
   ""
 ];
 
@@ -145,6 +163,7 @@ export {
   union,
   quote,
   splitKey,
+  renderComments,
   renderEntry,
   duplicatePluginOwners,
   duplicatePluginMessage,