@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/generator/Pairing.res.mjs

@@ -0,0 +1,415 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+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 Generator_Node$Reventless from "./Generator_Node.res.mjs";
+
+let implSuffixForStateChange = "_Behavior";
+
+let implSuffixForStateView = "_Projection";
+
+let implSuffixForAutomation = "_Automation";
+
+let implSuffixForTranslation = "_Translation";
+
+let mappingsSuffixForAutomation = "_Mappings";
+
+function isImplStem(stem) {
+  if (stem.endsWith(implSuffixForStateChange) || stem.endsWith(implSuffixForStateView) || stem.endsWith(implSuffixForAutomation) || stem.endsWith(implSuffixForTranslation)) {
+    return true;
+  } else {
+    return stem.endsWith(mappingsSuffixForAutomation);
+  }
+}
+
+function findEventMappings(srcDir) {
+  let dict = {};
+  let parentDirIsAggregate = relSegments => {
+    let n = relSegments.length;
+    if (n === 0) {
+      return false;
+    }
+    let parent = relSegments[n - 1 | 0];
+    if (parent === "Aggregate") {
+      return true;
+    } else {
+      return parent === "EventMappings";
+    }
+  };
+  let walk = (dir, segments) => {
+    Generator_Node$Reventless.readDir(dir).forEach(entry => {
+      let name = entry.name;
+      if (entry.isDirectory()) {
+        if (name !== "Plugin" && name !== "tests" && name !== "lib") {
+          return walk(Nodepath.join(dir, name), segments.concat([name]));
+        } else {
+          return;
+        }
+      }
+      if (!entry.isFile()) {
+        return;
+      }
+      if (name.endsWith("_Mappings.res") && parentDirIsAggregate(segments)) {
+        let stem = name.slice(0, name.length - 4 | 0);
+        let aggName = stem.slice(0, stem.length - 9 | 0);
+        dict[aggName] = stem;
+        return;
+      }
+      if (!name.endsWith("_EventMappings.res")) {
+        return;
+      }
+      let stem$1 = name.slice(0, name.length - 4 | 0);
+      let aggName$1 = stem$1.slice(0, stem$1.length - 14 | 0);
+      let match = dict[aggName$1];
+      if (match !== undefined) {
+        return;
+      } else {
+        dict[aggName$1] = stem$1;
+        return;
+      }
+    });
+  };
+  if (Nodefs.existsSync(srcDir)) {
+    walk(srcDir, []);
+  }
+  return dict;
+}
+
+function sortedStems(stems) {
+  return stems.toSorted((a, b) => {
+    if (a < b) {
+      return -1.0;
+    } else if (a > b) {
+      return 1.0;
+    } else {
+      return 0.0;
+    }
+  });
+}
+
+function extractTargetName(filePath) {
+  try {
+    let content = Nodefs.readFileSync(filePath, "utf8");
+    let result = {
+      contents: undefined
+    };
+    content.split("\n").forEach(line => {
+      let trimmed = line.trimStart();
+      if (!trimmed.startsWith("let targetName = ")) {
+        return;
+      }
+      let firstQuote = trimmed.indexOf("\"");
+      let lastQuote = trimmed.lastIndexOf("\"");
+      if (firstQuote >= 0 && lastQuote > firstQuote) {
+        result.contents = trimmed.slice(firstQuote + 1 | 0, lastQuote);
+        return;
+      }
+    });
+    return result.contents;
+  } catch (exn) {
+    return;
+  }
+}
+
+function hasFileAttribute(filePath, attr) {
+  try {
+    let content = Nodefs.readFileSync(filePath, "utf8");
+    let found = {
+      contents: false
+    };
+    content.split("\n").forEach(line => {
+      let trimmed = line.trimStart();
+      if (trimmed.startsWith(attr + " ") || trimmed.startsWith(attr + "(") || trimmed === attr) {
+        found.contents = true;
+        return;
+      }
+    });
+    return found.contents;
+  } catch (exn) {
+    return false;
+  }
+}
+
+function hasAsyncAttribute(filePath) {
+  return hasFileAttribute(filePath, "@@reventless.async");
+}
+
+function hasSystemCallableAttribute(filePath) {
+  return hasFileAttribute(filePath, "@@reventless.systemCallable");
+}
+
+function effectiveSpecName(filePath, stem) {
+  try {
+    let content = Nodefs.readFileSync(filePath, "utf8");
+    let name = {
+      contents: undefined
+    };
+    content.split("\n").forEach(line => {
+      let trimmed = line.trimStart();
+      if (!trimmed.startsWith("@@reventless.spec(")) {
+        return;
+      }
+      let firstQuote = trimmed.indexOf("\"");
+      let lastQuote = trimmed.lastIndexOf("\"");
+      if (firstQuote >= 0 && lastQuote > firstQuote) {
+        name.contents = trimmed.slice(firstQuote + 1 | 0, lastQuote);
+        return;
+      }
+    });
+    return Stdlib_Option.getOr(name.contents, stem);
+  } catch (exn) {
+    return stem;
+  }
+}
+
+function groupExtensionPoints(epFiles) {
+  let epByGroup = {};
+  let flatEpMappings = [];
+  epFiles.forEach(param => {
+    let epGroup = param.epGroup;
+    let stem = param.stem;
+    if (epGroup !== undefined) {
+      let arr = epByGroup[epGroup];
+      if (arr !== undefined) {
+        arr.push(stem);
+      } else {
+        epByGroup[epGroup] = [stem];
+      }
+      return;
+    }
+    flatEpMappings.push(stem);
+  });
+  let extensionPoints = [];
+  if (flatEpMappings.length !== 0) {
+    extensionPoints.push({
+      group: undefined,
+      mappings: sortedStems(flatEpMappings)
+    });
+  }
+  Object.entries(epByGroup).forEach(param => {
+    extensionPoints.push({
+      group: param[0],
+      mappings: sortedStems(param[1])
+    });
+  });
+  return extensionPoints;
+}
+
+function resolve(discovered, srcDir) {
+  let eventMappings = findEventMappings(srcDir);
+  let stateChangeSlices = [];
+  let stateViewSlices = [];
+  let stateViewSlicesStream = [];
+  let automationSlices = [];
+  let inboundTranslationSlices = [];
+  let outboundTranslationSlices = [];
+  let automationSliceRelPaths = {};
+  let inboundTranslationSliceRelPaths = {};
+  let outboundTranslationSliceRelPaths = {};
+  let aggregateSpecs = [];
+  let aggregateSpecRelPaths = {};
+  let stateChangeSliceRelPaths = {};
+  let stateViewSliceRelPaths = {};
+  let aggregateBehaviors = [];
+  let readModelStems = [];
+  let readModelStreamStems = [];
+  let projectionsByRelPath = {};
+  let tasks = [];
+  let epFiles = [];
+  let extensions = [];
+  discovered.forEach(param => {
+    let relPath = param.relPath;
+    let componentType = param.componentType;
+    let stem = param.stem;
+    switch (componentType) {
+      case "StateChangeSlice" :
+        if (!isImplStem(stem)) {
+          stateChangeSlices.push(stem);
+          stateChangeSliceRelPaths[stem] = relPath;
+          return;
+        } else {
+          return;
+        }
+      case "StateViewSlice" :
+        if (!isImplStem(stem)) {
+          stateViewSlices.push(stem);
+          stateViewSliceRelPaths[stem] = relPath;
+          return;
+        } else {
+          return;
+        }
+      case "StateViewSliceStream" :
+        if (!isImplStem(stem)) {
+          stateViewSlicesStream.push(stem);
+          stateViewSliceRelPaths[stem] = relPath;
+          return;
+        } else {
+          return;
+        }
+      case "AutomationSlice" :
+        if (!isImplStem(stem)) {
+          automationSlices.push(stem);
+          automationSliceRelPaths[stem] = relPath;
+          return;
+        } else {
+          return;
+        }
+      case "InboundTranslationSlice" :
+        if (!isImplStem(stem)) {
+          inboundTranslationSlices.push(stem);
+          inboundTranslationSliceRelPaths[stem] = relPath;
+          return;
+        } else {
+          return;
+        }
+      case "OutboundTranslationSlice" :
+        if (!isImplStem(stem)) {
+          outboundTranslationSlices.push(stem);
+          outboundTranslationSliceRelPaths[stem] = relPath;
+          return;
+        } else {
+          return;
+        }
+      case "Aggregate" :
+        if (stem.endsWith("Behavior")) {
+          aggregateBehaviors.push(stem);
+        } else {
+          aggregateSpecs.push(stem);
+          aggregateSpecRelPaths[stem] = relPath;
+        }
+        return;
+      case "ReadModel" :
+        if (stem.endsWith("Projections")) {
+          projectionsByRelPath[stem] = relPath;
+        } else {
+          readModelStems.push(stem);
+        }
+        return;
+      case "ReadModelStream" :
+        if (stem.endsWith("Projections")) {
+          projectionsByRelPath[stem] = relPath;
+        } else {
+          readModelStreamStems.push(stem);
+        }
+        return;
+      case "Task" :
+        tasks.push(stem);
+        return;
+      case "ExtensionPoint" :
+        epFiles.push({
+          stem: stem,
+          componentType: componentType,
+          epGroup: param.epGroup,
+          relPath: relPath
+        });
+        return;
+      case "Extension" :
+        extensions.push(stem);
+        return;
+    }
+  });
+  let aggregates = Stdlib_Array.filterMap(sortedStems(aggregateSpecs), spec => {
+    let underscored = spec + "_Behavior";
+    let bare = spec + "Behavior";
+    let behaviorStem = aggregateBehaviors.includes(underscored) ? underscored : (
+        aggregateBehaviors.includes(bare) ? bare : undefined
+      );
+    if (behaviorStem !== undefined) {
+      let relPath = aggregateSpecRelPaths[spec];
+      let isAsync = relPath !== undefined ? hasFileAttribute(Nodepath.join(srcDir, relPath), "@@reventless.async") : false;
+      return {
+        spec: spec,
+        behavior: behaviorStem,
+        eventMappings: eventMappings[spec],
+        isAsync: isAsync
+      };
+    }
+    console.warn("Generator: Aggregate spec `" + spec + "` has no matching `" + underscored + "` or `" + bare + "` — skipping");
+  });
+  let pairReadModel = (stream, rm) => {
+    let baseName = rm.endsWith("ReadModel") ? rm.slice(0, rm.length - 9 | 0) : rm;
+    let underscoredProj = baseName + "_Projections";
+    let match = projectionsByRelPath[underscoredProj];
+    if (match !== undefined) {
+      return {
+        readModel: rm,
+        projections: underscoredProj,
+        stream: stream
+      };
+    } else {
+      console.warn("Generator: ReadModel `" + rm + "` has no matching `" + underscoredProj + ".res` — skipping");
+      return;
+    }
+  };
+  let readModels = Stdlib_Array.filterMap(sortedStems(readModelStems), rm => pairReadModel(false, rm)).concat(Stdlib_Array.filterMap(sortedStems(readModelStreamStems), rm => pairReadModel(true, rm)));
+  let extensionPoints = groupExtensionPoints(epFiles);
+  let buildTargets = (stems, relPaths) => {
+    let dict = {};
+    stems.forEach(stem => {
+      let relPath = relPaths[stem];
+      let target = relPath !== undefined ? extractTargetName(Nodepath.join(srcDir, relPath)) : undefined;
+      dict[stem] = target;
+    });
+    return dict;
+  };
+  let d = {};
+  let names = [];
+  let collect = (stems, relPaths) => {
+    stems.forEach(stem => {
+      let relPath = relPaths[stem];
+      if (relPath === undefined) {
+        return;
+      }
+      let filePath = Nodepath.join(srcDir, relPath);
+      if (hasFileAttribute(filePath, "@@reventless.systemCallable")) {
+        names.push(effectiveSpecName(filePath, stem));
+        return;
+      }
+    });
+  };
+  return {
+    stateChangeSlices: sortedStems(stateChangeSlices),
+    stateViewSlices: sortedStems(stateViewSlices),
+    stateViewSlicesStream: sortedStems(stateViewSlicesStream),
+    automationSlices: sortedStems(automationSlices),
+    inboundTranslationSlices: sortedStems(inboundTranslationSlices),
+    outboundTranslationSlices: sortedStems(outboundTranslationSlices),
+    automationSliceTargets: buildTargets(automationSlices, automationSliceRelPaths),
+    inboundTranslationSliceTargets: buildTargets(inboundTranslationSlices, inboundTranslationSliceRelPaths),
+    outboundTranslationSliceTargets: buildTargets(outboundTranslationSlices, outboundTranslationSliceRelPaths),
+    asyncStateChangeSlices: (stateChangeSlices.forEach(stem => {
+      let relPath = stateChangeSliceRelPaths[stem];
+      if (relPath !== undefined && hasFileAttribute(Nodepath.join(srcDir, relPath), "@@reventless.async")) {
+        d[stem] = true;
+        return;
+      }
+    }), d),
+    systemCallableComponents: (collect(stateChangeSlices, stateChangeSliceRelPaths), collect(stateViewSlices, stateViewSliceRelPaths), collect(stateViewSlicesStream, stateViewSliceRelPaths), sortedStems(names)),
+    aggregates: aggregates,
+    readModels: readModels,
+    tasks: sortedStems(tasks),
+    extensionPoints: extensionPoints,
+    extensions: sortedStems(extensions)
+  };
+}
+
+export {
+  implSuffixForStateChange,
+  implSuffixForStateView,
+  implSuffixForAutomation,
+  implSuffixForTranslation,
+  mappingsSuffixForAutomation,
+  isImplStem,
+  findEventMappings,
+  sortedStems,
+  extractTargetName,
+  hasFileAttribute,
+  hasAsyncAttribute,
+  hasSystemCallableAttribute,
+  effectiveSpecName,
+  groupExtensionPoints,
+  resolve,
+}
+/* node:fs Not a pure module */

package/src/generator/PlatformCodegen.res

@@ -0,0 +1,207 @@
+// Pure rendering for the platform generator: union the plugins' capability
+// manifests and emit the committed `PlatformCapabilities.res`.
+//
+// Only the derived list is generated — the platform root stays hand-written
+// and reads `PlatformCapabilities.capabilities`. That keeps a requirement
+// change small and entirely about capabilities in review, and it keeps the
+// generator out of the business of expressing everything a real root does
+// (bootstrap calls, capability handles, stack references).
+//
+// I/O-free so the exact bytes are testable; `PlatformGenerator` owns the file
+// system.
+
+/** One plugin's manifest, tagged with the name `deploy-manifest.yaml` lists it
+    under — the name provenance comments cite. */
+type pluginManifest = {
+  pluginName: string,
+  manifest: CapabilityManifest.t,
+}
+
+/** One declaring site, keeping which plugin's manifest carried it. */
+type provenance = {
+  pluginName: string,
+  component: string,
+  field: 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. */
+type unionEntry = {
+  kind: CapabilityManifest.kind,
+  key: string,
+  declaredBy: array<provenance>,
+}
+
+/** Union the manifests: entries with one key collapse to one capability, their
+    provenance concatenated in manifest order. Sorted by key so the rendered
+    file is deterministic. */
+let union = (manifests: array<pluginManifest>): array<unionEntry> => {
+  let byKey: dict<unionEntry> = Dict.make()
+  manifests->Array.forEach(({pluginName, manifest}) =>
+    manifest.capabilities->Array.forEach(entry => {
+      let sites =
+        entry.declaredBy->Array.map(site => {
+          pluginName,
+          component: site.component,
+          field: site.field,
+          annotation: site.annotation,
+        })
+      switch byKey->Dict.get(entry.key) {
+      | Some(existing) =>
+        byKey->Dict.set(entry.key, {...existing, declaredBy: existing.declaredBy->Array.concat(sites)})
+      | None => byKey->Dict.set(entry.key, {kind: entry.kind, key: entry.key, declaredBy: sites})
+      }
+    })
+  )
+  byKey
+  ->Dict.valuesToArray
+  ->Array.toSorted((a, b) => String.compare(a.key, b.key))
+}
+
+let quote = (s: string): string => s->JSON.Encode.string->JSON.stringify
+
+// A key is `{plugin}.{store}` by construction (`Plugin_Structure` qualifies
+// every declaration). The split is at the first dot: the plugin's registered
+// name cannot contain one, the store name could in principle.
+let splitKey = (key: string): option<(string, string)> =>
+  key
+  ->String.indexOfOpt(".")
+  ->Option.map(i => (
+    key->String.slice(~start=0, ~end=i),
+    key->String.slice(~start=i + 1),
+  ))
+
+// The provenance comment quotes the annotation as its author wrote it — taken
+// from the manifest, which recorded it at the one place the owning plugin was
+// unambiguous. Inferring it here is what this replaced: the manifest carries a
+// deploy-manifest entry name and the key carries the registered name, and no
+// rule relates the two (`platform-inspector` against `PlatformInspector` is an
+// ordinary pairing), so any comparison here eventually quotes a string that is
+// in no source file.
+//
+// A site with no recorded annotation predates the recording. It still names the
+// field, which is the comment's job; it just makes no claim about the source
+// text it cannot see.
+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}`
+          switch site.annotation {
+          | Some(annotation) => `${site_} @storageRef(${quote(annotation)})`
+          | None => site_
+          }
+        })
+      let line = switch entry.kind {
+      | ObjectStore => `  ObjectStore({plugin: ${quote(plugin)}, store: ${quote(store)}}),`
+      }
+      Ok(comments->Array.concat([line]))
+    }
+  }
+
+/**
+Two deployables each claiming to own one plugin name.
+
+Nothing else in the toolchain catches this. The deploy manifest's keys are
+*deployable* names with no rule relating them to registered ones, and the Plugin
+aggregate is keyed by the registered name — so a second plugin registering an
+existing name is not rejected but read as a **new version of the first**, and
+silently supersedes it in the registry.
+
+Ownership is read from the annotation as authored, which is the one signal that
+separates a duplicate from legitimate sharing: an **unqualified**
+`@storageRef("productImages")` means "a store of my own plugin", so the
+deployable that wrote it is the plugin the key names. A **qualified**
+`@storageRef("Catalog.productImages")` points at someone else's store and says
+nothing about who owns it — that is the sanctioned cross-plugin form and must not
+trip this.
+
+Partial by construction: it can only see plugins that declare a store, because
+capability manifests are the only per-plugin input the generator reads. A
+duplicate between two store-less plugins is invisible here and stays uncaught.
+*/
+let duplicatePluginOwners = (entries: array<unionEntry>): array<(string, array<string>)> => {
+  let owners: dict<array<string>> = Dict.make()
+  entries->Array.forEach(entry =>
+    switch splitKey(entry.key) {
+    | None => ()
+    | Some((plugin, _)) =>
+      entry.declaredBy->Array.forEach(site =>
+        switch site.annotation {
+        // A site with no recorded annotation predates the recording, so it
+        // cannot be read either way and is skipped rather than guessed at.
+        | Some(annotation) if !(annotation->String.includes(".")) =>
+          let claimants = owners->Dict.get(plugin)->Option.getOr([])
+          if !(claimants->Array.includes(site.pluginName)) {
+            owners->Dict.set(plugin, Array.concat(claimants, [site.pluginName]))
+          }
+        | _ => ()
+        }
+      )
+    }
+  )
+  owners
+  ->Dict.toArray
+  ->Array.filter(((_, claimants)) => claimants->Array.length > 1)
+  ->Array.toSorted(((a, _), (b, _)) => String.compare(a, b))
+}
+
+let duplicatePluginMessage = ((plugin, claimants): (string, array<string>)): string =>
+  `Plugin name "${plugin}" is registered by more than one deployable: ${claimants->Array.join(
+      ", ",
+    )}.\n` ++
+  `  A platform keys its plugin registry by name, so the second registration is read as a new ` ++
+  `VERSION of the first and supersedes it.\n` ++
+  `  Give each deployable's plugin a distinct name (plugin.json), or — if these were meant to be ` ++
+  `one plugin — deploy only one of them.`
+
+let header = [
+  "// AUTO-GENERATED — do not edit. Run `pnpm run generate:platform` to update.",
+  "//",
+  "// 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.",
+  "",
+]
+
+/** Render the complete `PlatformCapabilities.res`. Deterministic and
+    newline-terminated: regenerating with no manifest change is byte-identical,
+    so the committed file never churns. */
+let render = (manifests: array<pluginManifest>): result<string, string> => {
+  let entries = union(manifests)
+  let rendered = entries->Array.map(renderEntry)
+  switch (
+    duplicatePluginOwners(entries),
+    rendered->Array.findMap(r =>
+      switch r {
+      | Error(e) => Some(e)
+      | Ok(_) => None
+      }
+    ),
+  ) {
+  // Generation is the earliest point a deployment's plugins are seen together,
+  // so a name two of them both claim is refused here rather than left to
+  // supersede one of them at runtime.
+  | (duplicates, _) if duplicates->Array.length > 0 =>
+    Error(duplicates->Array.map(duplicatePluginMessage)->Array.join("\n\n"))
+  | (_, Some(e)) => Error(e)
+  | (_, None) => {
+      let body = if entries->Array.length == 0 {
+        ["let capabilities: array<ReventlessInfra.Platform.capability> = []"]
+      } else {
+        ["let capabilities: array<ReventlessInfra.Platform.capability> = ["]
+        ->Array.concat(rendered->Array.flatMap(r => r->Result.getOr([])))
+        ->Array.concat(["]"])
+      }
+      Ok(header->Array.concat(body)->Array.join("\n") ++ "\n")
+    }
+  }
+}