@reventlessdev/reventless-spec 3.0.0-alpha.135 → 3.0.0-alpha.136

package/src/components/DcbTag.res.mjs

@@ -10,6 +10,7 @@ import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
+import * as ComponentKind$Reventless from "./ComponentKind.res.mjs";
 import * as DcbScopeInference$Reventless from "./DcbScopeInference.res.mjs";
 
 let tagSchema = Sury.$schema(s => ({
@@ -68,6 +69,10 @@ let derivedPartitionTagSchema = Sury.union([
   Sury.$schema(s => ({
     TAG: "Composite",
     _0: s.m(compositePartitionSpecSchema)
+  })),
+  Sury.$schema(s => ({
+    TAG: "ByEventType",
+    _0: s.m(Sury.dict(Sury.string))
   }))
 ]);
 
@@ -789,7 +794,23 @@ function extractPartitionTagFields(schema) {
   }
 }
 
-function sliceShapeFromSchemas(name, commandSchema, consumedEventSchema, eventSchema) {
+function chapterOfModuleUrl(moduleUrl) {
+  let parts = moduleUrl.split("/src/");
+  let len = parts.length;
+  if (len === 1) {
+    return;
+  }
+  if (len === 0) {
+    return;
+  }
+  let segments = parts[parts.length - 1 | 0].split("/");
+  let first = segments[0];
+  if (first !== undefined && segments.length > 1 && !ComponentKind$Reventless.isKindFolder(first)) {
+    return first;
+  }
+}
+
+function sliceShapeFromSchemas(name, commandSchema, consumedEventSchema, eventSchema, moduleUrl) {
   let match = extractPartitionTagFields(eventSchema);
   let partitionHint = match.length !== 1 ? undefined : match[0];
   return {
@@ -797,10 +818,15 @@ function sliceShapeFromSchemas(name, commandSchema, consumedEventSchema, eventSc
     command: eventShapesOfSchema(commandSchema).flatMap(e => e.idFields),
     consumed: eventShapesOfSchema(consumedEventSchema),
     produced: eventShapesOfSchema(eventSchema),
-    partitionHint: partitionHint
+    partitionHint: partitionHint,
+    chapter: Stdlib_Option.flatMap(moduleUrl, chapterOfModuleUrl)
   };
 }
 
+function sliceShape(s) {
+  return sliceShapeFromSchemas(s.name, s.commandSchema, s.consumedEventSchema, s.eventSchema, s.moduleUrl);
+}
+
 function deriveEffectiveScope(slices) {
   let producedSchemas = slices.map(s => s.eventSchema);
   let seen = new Set();
@@ -813,8 +839,7 @@ function deriveEffectiveScope(slices) {
     }
   });
   let annotatedTagKeys = mergeTagKeysByEventType(producedSchemas.map(extractTagKeysByEventType));
-  let shapes = slices.map(s => sliceShapeFromSchemas(s.name, s.commandSchema, s.consumedEventSchema, s.eventSchema));
-  let inferred = DcbScopeInference$Reventless.infer(shapes);
+  let inferred = DcbScopeInference$Reventless.infer(slices.map(sliceShape));
   let useInferred = inferred.ambiguities.length === 0;
   return {
     crossPartitionTagKeys: useInferred ? inferred.crossPartitionTagKeys : annotatedCross,
@@ -824,46 +849,6 @@ function deriveEffectiveScope(slices) {
   };
 }
 
-function hasMultiTagVariant(schema) {
-  switch (schema.type) {
-    case "object" :
-      let tagCount = Object.entries(schema.properties).filter(param => Stdlib_Option.isSome(Sury.$Metadata_get(param[1], dcbTagId))).length;
-      return tagCount > 1;
-    case "anyOf" :
-      return schema.anyOf.some(variantSchema => {
-        if (variantSchema.type !== "object") {
-          return false;
-        }
-        let tagCount = Object.entries(variantSchema.properties).filter(param => Stdlib_Option.isSome(Sury.$Metadata_get(param[1], dcbTagId))).length;
-        return tagCount > 1;
-      });
-    default:
-      return false;
-  }
-}
-
-function findMultiTagVariantNames(schema) {
-  let variantName = variantSchema => {
-    if (variantSchema.type !== "object") {
-      return;
-    }
-    let properties = variantSchema.properties;
-    let tagCount = Object.entries(properties).filter(param => Stdlib_Option.isSome(Sury.$Metadata_get(param[1], dcbTagId))).length;
-    if (tagCount > 1) {
-      return Stdlib_Option.getOr(variantTagName(properties), "(unknown)");
-    }
-  };
-  if (schema.type === "anyOf") {
-    return Stdlib_Array.filterMap(schema.anyOf, variantName);
-  }
-  let name = variantName(schema);
-  if (name !== undefined) {
-    return [name];
-  } else {
-    return [];
-  }
-}
-
 function extractCompositePartitionFieldsFromProperties(properties) {
   return Stdlib_Array.filterMap(Object.entries(properties), param => {
     let meta = Sury.$Metadata_get(param[1], dcbCompositePartitionMemberId);
@@ -918,98 +903,118 @@ function getCompositePartitionKeyValue(tags, spec) {
   }).join("");
 }
 
-function derivePartitionTag(namedSchemas) {
-  let schemas = namedSchemas.map(param => param[2]);
-  let seen = new Set();
-  let allCompositeFields = schemas.flatMap(extractCompositePartitionFields).filter(info => {
-    if (seen.has(info.name)) {
-      return false;
-    } else {
-      seen.add(info.name);
-      return true;
-    }
-  });
-  let hasComposite = allCompositeFields.length !== 0;
-  let seen$1 = new Set();
-  let allPartitionFields = schemas.flatMap(extractPartitionTagFields).filter(f => {
-    if (seen$1.has(f)) {
-      return false;
-    } else {
-      seen$1.add(f);
-      return true;
-    }
-  });
-  if (hasComposite && allPartitionFields.length !== 0) {
-    Stdlib_JsError.throwWithMessage(`DCB spec mixes @compositePartitionTag and @partitionTag — use one strategy per schema`);
+function compositePartitionOf(schemas) {
+  let dedupe = (items, keyOf) => {
+    let seen = new Set();
+    return items.filter(item => {
+      let k = keyOf(item);
+      if (seen.has(k)) {
+        return false;
+      } else {
+        seen.add(k);
+        return true;
+      }
+    });
+  };
+  let compositeFields = dedupe(schemas.flatMap(extractCompositePartitionFields), info => info.name);
+  let partitionFields = dedupe(schemas.flatMap(extractPartitionTagFields), f => f);
+  if (compositeFields.length === 0) {
+    return;
   }
-  if (hasComposite) {
-    if (allCompositeFields.length < 2) {
-      Stdlib_JsError.throwWithMessage(`@compositePartitionTag requires at least 2 annotated fields — only ` + allCompositeFields.length.toString() + ` found`);
-    }
-    let sorted = allCompositeFields.toSorted((a, b) => Primitive_int.compare(a.position, b.position));
-    let keys = sorted.map(info => info.name);
-    let seps = sorted.slice(0, sorted.length - 1 | 0).map(info => info.sep);
+  if (partitionFields.length !== 0) {
+    return Stdlib_JsError.throwWithMessage(`DCB spec mixes @compositePartitionTag and @partitionTag — use one strategy per schema`);
+  }
+  if (compositeFields.length === 1) {
+    return Stdlib_JsError.throwWithMessage(`@compositePartitionTag requires at least 2 annotated fields — only 1 found`);
+  }
+  let sorted = compositeFields.toSorted((a, b) => Primitive_int.compare(a.position, b.position));
+  return {
+    keys: sorted.map(info => info.name),
+    seps: sorted.slice(0, sorted.length - 1 | 0).map(info => info.sep)
+  };
+}
+
+function deriveBoundaryPartition(slices) {
+  let spec = compositePartitionOf(slices.map(s => s.eventSchema));
+  if (spec !== undefined) {
     return {
-      TAG: "Composite",
-      _0: {
-        keys: keys,
-        seps: seps
+      partitionBySlice: {},
+      partitionTag: {
+        TAG: "Composite",
+        _0: spec
       }
     };
   }
-  let seen$2 = new Set();
-  let allTaggedFields = schemas.flatMap(extractTaggedFields).filter(f => {
-    if (seen$2.has(f)) {
-      return false;
-    } else {
-      seen$2.add(f);
-      return true;
-    }
+  let resolution = DcbScopeInference$Reventless.resolvePartitions(slices.map(sliceShape));
+  if (resolution.ambiguities.length !== 0) {
+    Stdlib_JsError.throwWithMessage(`DCB partition key cannot be inferred — ` + resolution.ambiguities.map(param => param[0] + `: ` + param[1]).join(" | "));
+  }
+  let byEventType = {};
+  slices.forEach(s => {
+    let key = resolution.partitionBySlice[s.name];
+    Object.entries(extractTagKeysByEventType(s.eventSchema)).forEach(param => {
+      let tagKeys = param[1];
+      let eventType = param[0];
+      if (tagKeys.length !== 0 && !tagKeys.includes(key)) {
+        Stdlib_JsError.throwWithMessage(`DCB slice ` + s.name + ` is partitioned by ` + key + `, but its event ` + eventType + ` carries no ` + key + ` tag (it carries ` + tagKeys.join(", ") + `) — add ` + key + ` to the event, or declare the partition with @partitionTag`);
+      }
+      let other = byEventType[eventType];
+      if (other !== undefined && other !== key) {
+        return Stdlib_JsError.throwWithMessage(`DCB event ` + eventType + ` is written under two partition keys (` + other + `, ` + key + `) — every slice writing it must be partitioned by the same key`);
+      } else {
+        byEventType[eventType] = key;
+        return;
+      }
+    });
   });
-  let len = allTaggedFields.length;
-  if (len !== 1) {
-    if (len === 0) {
-      return Stdlib_JsError.throwWithMessage("DCB spec has no tagged fields — cannot derive partition tag");
+  return {
+    partitionBySlice: resolution.partitionBySlice,
+    partitionTag: {
+      TAG: "ByEventType",
+      _0: byEventType
     }
-    let needsExplicitPartition = schemas.some(hasMultiTagVariant);
-    if (needsExplicitPartition) {
-      let context = Stdlib_Array.filterMap(namedSchemas, param => {
-        let variantNames = findMultiTagVariantNames(param[2]);
-        if (variantNames.length !== 0) {
-          return param[0] + ` (` + variantNames.join(", ") + `) @ ` + param[1];
-        }
-      }).join(", ");
-      let len$1 = allPartitionFields.length;
-      if (len$1 !== 1) {
-        if (len$1 !== 0) {
-          return Stdlib_JsError.throwWithMessage(`DCB spec has multiple fields annotated with @partitionTag (` + allPartitionFields.join(", ") + `) — only one is allowed — affected: ` + context);
-        } else {
-          return Stdlib_JsError.throwWithMessage(`DCB spec has variants with multiple tagged fields (` + allTaggedFields.join(", ") + `) but none is annotated with @partitionTag — affected: ` + context + ` — mark one field as the partition key`);
-        }
-      }
-      let singlePartition = allPartitionFields[0];
-      return {
+  };
+}
+
+function slicePartitionTag(bp, sliceName) {
+  let other = bp.partitionTag;
+  switch (other.TAG) {
+    case "Simple" :
+    case "Composite" :
+      return other;
+    case "ByEventType" :
+      return Stdlib_Option.map(bp.partitionBySlice[sliceName], key => ({
         TAG: "Simple",
         _0: {
-          key: singlePartition
+          key: key
         }
-      };
-    }
-    let sorted$1 = allTaggedFields.toSorted(Primitive_string.compare);
-    return {
-      TAG: "Simple",
-      _0: {
-        key: sorted$1[0]
-      }
-    };
+      }));
+  }
+}
+
+function deriveSlicePartition(slice) {
+  let tag = slicePartitionTag(deriveBoundaryPartition([slice]), slice.name);
+  if (tag !== undefined) {
+    return tag;
+  } else {
+    return Stdlib_JsError.throwWithMessage(`DCB slice ` + slice.name + ` has no partition key`);
+  }
+}
+
+function partitionValueOfTags(tags, pt) {
+  switch (pt.TAG) {
+    case "Simple" :
+      let key = pt._0.key;
+      return Stdlib_Option.getOr(Stdlib_Array.findMap(tags, t => {
+        if (t.key === key) {
+          return t.value;
+        }
+      }), "");
+    case "Composite" :
+      return getCompositePartitionKeyValue(tags, pt._0);
+    case "ByEventType" :
+      return "";
   }
-  let singleField = allTaggedFields[0];
-  return {
-    TAG: "Simple",
-    _0: {
-      key: singleField
-    }
-  };
 }
 
 function getPartitionTagValue(query, pt) {
@@ -1081,14 +1086,18 @@ export {
   idFieldsOfProperties,
   eventShapesOfSchema,
   extractPartitionTagFields,
+  chapterOfModuleUrl,
   sliceShapeFromSchemas,
+  sliceShape,
   deriveEffectiveScope,
-  hasMultiTagVariant,
-  findMultiTagVariantNames,
   extractCompositePartitionFieldsFromProperties,
   extractCompositePartitionFields,
   getCompositePartitionKeyValue,
-  derivePartitionTag,
+  compositePartitionOf,
+  deriveBoundaryPartition,
+  slicePartitionTag,
+  deriveSlicePartition,
+  partitionValueOfTags,
   getPartitionTagValue,
 }
 /* tagSchema Not a pure module */

package/src/components/DcbValidation.res

@@ -481,3 +481,53 @@ let validateScopeVsInference = (
   )
   {contradictions, redundancies}
 }
+
+/**
+Checks each `@partitionTag` against what inference derives with that hint removed.
+
+- **Contradiction** — inference resolves the slice to a different key, or the
+  hint names a key the slice only reads as a reference to another entity. Storage,
+  fence and read scope would all follow the wrong key.
+- **Redundant** — inference reaches the same key unaided; the annotation can go.
+
+A hint that names a key the slice's events do not carry is not checked here:
+inference ignores it, and the boundary derivation reports the slice instead.
+*/
+let validatePartitionHintsVsInference = (
+  ~shapes: array<DcbScopeInference.sliceShape>,
+): scopeInferenceIssues => {
+  let contradictions: array<validationError> = []
+  let redundancies: array<validationError> = []
+  shapes->Array.forEach(s =>
+    switch s.partitionHint {
+    | Some(hint) if DcbScopeInference.producedKeys(s)->Array.includes(hint) =>
+      let unaided = DcbScopeInference.resolvePartitions(
+        shapes->Array.map(o => o.sliceName == s.sliceName ? {...o, partitionHint: None} : o),
+      )
+      switch unaided.partitionBySlice->Dict.get(s.sliceName) {
+      | Some(inferred) if inferred == hint =>
+        redundancies->Array.push({
+          sliceName: s.sliceName,
+          message: `@partitionTag ${hint} is what inference derives without it — the annotation is redundant and can be removed.`,
+        })
+      | Some(inferred) =>
+        contradictions->Array.push({
+          sliceName: s.sliceName,
+          message: `@partitionTag names ${hint}, but inference derives ${inferred} from the slice graph — ${hint} is read from another entity. Remove the annotation, or move it to ${inferred}.`,
+        })
+      | None =>
+        let candidates = unaided.candidatesBySlice->Dict.get(s.sliceName)->Option.getOr([])
+        if !(candidates->Array.includes(hint)) {
+          contradictions->Array.push({
+            sliceName: s.sliceName,
+            message: `@partitionTag names ${hint}, which this slice only reads as a reference to another entity (candidates: ${candidates->Array.join(
+                ", ",
+              )}). Move the annotation to the slice's own key.`,
+          })
+        }
+      }
+    | _ => ()
+    }
+  )
+  {contradictions, redundancies}
+}

package/src/components/DcbValidation.res.mjs

@@ -5,6 +5,7 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as DcbTag$Reventless from "./DcbTag.res.mjs";
+import * as DcbScopeInference$Reventless from "./DcbScopeInference.res.mjs";
 
 function extractVariantInfo(variantSchema) {
   switch (variantSchema.type) {
@@ -425,6 +426,55 @@ function validateScopeVsInference(annotations, inferred) {
   };
 }
 
+function validatePartitionHintsVsInference(shapes) {
+  let contradictions = [];
+  let redundancies = [];
+  shapes.forEach(s => {
+    let hint = s.partitionHint;
+    if (hint === undefined) {
+      return;
+    }
+    if (!DcbScopeInference$Reventless.producedKeys(s).includes(hint)) {
+      return;
+    }
+    let unaided = DcbScopeInference$Reventless.resolvePartitions(shapes.map(o => {
+      if (o.sliceName !== s.sliceName) {
+        return o;
+      }
+      let newrecord = {...o};
+      newrecord.partitionHint = undefined;
+      return newrecord;
+    }));
+    let inferred = unaided.partitionBySlice[s.sliceName];
+    if (inferred !== undefined) {
+      if (inferred === hint) {
+        redundancies.push({
+          sliceName: s.sliceName,
+          message: `@partitionTag ` + hint + ` is what inference derives without it — the annotation is redundant and can be removed.`
+        });
+      } else {
+        contradictions.push({
+          sliceName: s.sliceName,
+          message: `@partitionTag names ` + hint + `, but inference derives ` + inferred + ` from the slice graph — ` + hint + ` is read from another entity. Remove the annotation, or move it to ` + inferred + `.`
+        });
+      }
+      return;
+    }
+    let candidates = Stdlib_Option.getOr(unaided.candidatesBySlice[s.sliceName], []);
+    if (!candidates.includes(hint)) {
+      contradictions.push({
+        sliceName: s.sliceName,
+        message: `@partitionTag names ` + hint + `, which this slice only reads as a reference to another entity (candidates: ` + candidates.join(", ") + `). Move the annotation to the slice's own key.`
+      });
+      return;
+    }
+  });
+  return {
+    contradictions: contradictions,
+    redundancies: redundancies
+  };
+}
+
 export {
   extractVariantInfo,
   extractAllVariants,
@@ -438,5 +488,6 @@ export {
   validateProducedAndConsumed,
   validateCrossPartitionScope,
   validateScopeVsInference,
+  validatePartitionHintsVsInference,
 }
 /* DcbTag-Reventless Not a pure module */

package/src/generator/Codegen.res

@@ -638,7 +638,8 @@ let renderComposition = (
         `name: ${stem}.name, ` ++
         `commandSchema: ${stem}.commandSchema->S.castToUnknown, ` ++
         `consumedEventSchema: ${stem}.consumedEventSchema->S.castToUnknown, ` ++
-        `eventSchema: ${stem}.eventSchema->S.castToUnknown` ++ "},",
+        `eventSchema: ${stem}.eventSchema->S.castToUnknown, ` ++
+        `moduleUrl: ${stem}.moduleUrl` ++ "},",
       )
     )
     lines->Array.push("]")

package/src/generator/Codegen.res.mjs

@@ -406,7 +406,7 @@ function renderComposition(config, resolved, componentChapters, hasLifecycleMode
     lines.push("");
     lines.push("let dcbSliceSchemas: array<Reventless.DcbTag.sliceSchemas> = [");
     resolved.stateChangeSlices.forEach(stem => {
-      lines.push("  {" + (`name: ` + stem + `.name, `) + (`commandSchema: ` + stem + `.commandSchema->S.castToUnknown, `) + (`consumedEventSchema: ` + stem + `.consumedEventSchema->S.castToUnknown, `) + (`eventSchema: ` + stem + `.eventSchema->S.castToUnknown`) + "},");
+      lines.push("  {" + (`name: ` + stem + `.name, `) + (`commandSchema: ` + stem + `.commandSchema->S.castToUnknown, `) + (`consumedEventSchema: ` + stem + `.consumedEventSchema->S.castToUnknown, `) + (`eventSchema: ` + stem + `.eventSchema->S.castToUnknown, `) + (`moduleUrl: ` + stem + `.moduleUrl`) + "},");
     });
     lines.push("]");
   }

package/src/lifecycle/CheckLifecycleModel.res

@@ -681,6 +681,90 @@ let deriveCommands = (
   })
 }
 
+// ── What each command yields ────────────────────────────────────────────────
+
+/** Which command yields which event or error, as its scenarios show it — what a
+    consumer draws a command's outcome arrows from, read off the corpus rather
+    than guessed from names. It needs no lifecycle labelling, so every corpus a
+    plugin has is read, though only its command scenarios count.
+
+    An empty `then` is skipped rather than read as "accepted, nothing happened".
+    The PPX currently writes `then: []` for `thenNoEvent`, so an empty `then` is
+    indistinguishable from one the sidecar could not read, and an outcome shown
+    here has to be one a scenario actually states. */
+type shownOutcome = {
+  kind: string, // "event" | "error" | "noEvent"
+  /** The whole `then`, in order: `thenEvents([A, B])` is one outcome of two
+      events — both, not either. Empty for `noEvent`. */
+  names: array<string>,
+  /** The title of every scenario showing this outcome, in corpus order. */
+  scenarios: array<string>,
+}
+
+type commandOutcomes = {
+  plugin: string,
+  component: string,
+  command: string,
+  /** One per distinct outcome, in order of first appearance. */
+  outcomes: array<shownOutcome>,
+}
+
+let shownOutcomeOf = (s: scenario): option<(string, array<string>)> =>
+  switch s.thenKind {
+  | "event" | "error" => Some((s.thenKind, s.thenElements->Array.map(e => e.name)))
+  | "noEvent" => Some(("noEvent", []))
+  // The empty `then` above, and a `then` that is not about this command's
+  // result — a side effect, a published command.
+  | _ => None
+  }
+
+let byPluginComponentCommand = (xs: array<commandOutcomes>): array<commandOutcomes> =>
+  xs->Array.toSorted((a, b) =>
+    switch String.compare(a.plugin, b.plugin) {
+    | 0. =>
+      switch String.compare(a.component, b.component) {
+      | 0. => String.compare(a.command, b.command)
+      | c => c
+      }
+    | c => c
+    }
+  )
+
+/** A command with no readable outcome is left out: an entry must say something. */
+let commandOutcomes = (~plugin: string, ~corpora: array<corpus>): array<commandOutcomes> => {
+  let entries: array<commandOutcomes> = []
+  corpora->Array.forEach(c =>
+    c.scenarios->Array.forEach(s =>
+      switch (s.whenKind, s.whenElements->Array.get(0), shownOutcomeOf(s)) {
+      | ("command", Some(command), Some((kind, names))) =>
+        let entry = switch entries->Array.find(
+          e => e.component == c.component && e.command == command.name,
+        ) {
+        | Some(e) => e
+        | None =>
+          let e: commandOutcomes = {
+            plugin,
+            component: c.component,
+            command: command.name,
+            outcomes: [],
+          }
+          entries->Array.push(e)
+          e
+        }
+        switch entry.outcomes->Array.find(o => o.kind == kind && o.names == names) {
+        | Some(o) =>
+          if !(o.scenarios->Array.includes(s.title)) {
+            o.scenarios->Array.push(s.title)
+          }
+        | None => entry.outcomes->Array.push({kind, names, scenarios: [s.title]})
+        }
+      | _ => ()
+      }
+    )
+  )
+  entries->byPluginComponentCommand
+}
+
 // ── The three verdicts ──────────────────────────────────────────────────────
 
 type finding = {
@@ -953,6 +1037,7 @@ let runPlugin = async (
   ~pluginDir: string,
   ~findings: array<finding>,
   ~opaque: array<opaque>,
+  ~outcomes: array<commandOutcomes>,
 ): result<array<derivedCommand>, string> =>
   switch await readDeclared(~pluginDir) {
   | Error(msg) => Error(msg)
@@ -962,6 +1047,8 @@ let runPlugin = async (
         readCorpus,
       )
 
+    outcomes->Array.pushMany(commandOutcomes(~plugin, ~corpora))
+
     // Every corpus, not only the ones the walk goes on to use: the kinds that
     // are unreadable in full — extension points, automation and translation
     // slices — are exactly the ones that sit outside the view/writable folders
@@ -1131,13 +1218,16 @@ let goldenPath = (~root: appRoot) => NodePath.join([root.dir, "schema", "lifecyc
       ever exercised, which is a sharper "missing scenario" than a verdict.
     - `opaque` — the corpora the walk cannot read, so a consumer can say "not
       analysed" where it would otherwise say "not covered".
+    - `outcomes` — which command yields which event or error, and the scenarios
+      that show it, sorted by plugin, component and command.
 
-    `str` is the schema's own version, bumped when a consumer would have to
-    change. */
+    `version` is the schema's own version, bumped when a consumer would have to
+    change. An added section is not such a change. */
 let reportJson = (
   ~findings: array<finding>,
   ~opaque: array<opaque>,
   ~derived: array<(string, derivedCommand)>,
+  ~outcomes: array<commandOutcomes>,
   ~failures: array<string>,
 ): string => {
   let strs = xs => JSON.Encode.array(xs->Array.map(JSON.Encode.string))
@@ -1174,11 +1264,30 @@ let reportJson = (
       ("unreadable", JSON.Encode.int(o.unreadable)),
     ])
 
+  let shownOutcomeJson = (o: shownOutcome) =>
+    obj([
+      ("kind", JSON.Encode.string(o.kind)),
+      ("names", strs(o.names)),
+      ("scenarios", strs(o.scenarios)),
+    ])
+
+  let commandOutcomesJson = (e: commandOutcomes) =>
+    obj([
+      ("plugin", JSON.Encode.string(e.plugin)),
+      ("component", JSON.Encode.string(e.component)),
+      ("command", JSON.Encode.string(e.command)),
+      ("outcomes", JSON.Encode.array(e.outcomes->Array.map(shownOutcomeJson))),
+    ])
+
   JSON.stringify(
     obj([
       ("version", JSON.Encode.int(1)),
       ("findings", JSON.Encode.array(findings->Array.map(findingJson))),
       ("commands", JSON.Encode.array(derived->Array.map(commandJson))),
+      (
+        "outcomes",
+        JSON.Encode.array(outcomes->byPluginComponentCommand->Array.map(commandOutcomesJson)),
+      ),
       ("opaque", JSON.Encode.array(opaque->Array.map(opaqueJson))),
       ("unreadable", strs(failures)),
     ]),
@@ -1270,6 +1379,7 @@ let writeOrCompare = (~path: string, ~actual: string, ~label: string, ~drifted:
 let main = async () => {
   let findings = []
   let opaque = []
+  let outcomes = []
   let failures = []
   let drifted = []
   let allDerived = []
@@ -1327,7 +1437,7 @@ let main = async () => {
         | Some(pluginDir) =>
           let plugin = NodePath.basename(pluginDir)
           let qualified = `${example}/${plugin}`
-          switch await runPlugin(~plugin=qualified, ~pluginDir, ~findings, ~opaque) {
+          switch await runPlugin(~plugin=qualified, ~pluginDir, ~findings, ~opaque, ~outcomes) {
           | Ok(commands) =>
             commands->Array.forEach(c => {
               derived->Array.push(c)
@@ -1370,7 +1480,7 @@ let main = async () => {
   let contradicted = of_("contradicted")
 
   if json {
-    Console.log(reportJson(~findings, ~opaque, ~derived=allDerived, ~failures))
+    Console.log(reportJson(~findings, ~opaque, ~derived=allDerived, ~outcomes, ~failures))
   } else {
     ["contradicted", "unverified", "undeclared", "level", "ambiguous"]->Array.forEach(severity => {
       let group = of_(severity)