@intentius/chant 0.124.51 → 0.124.52

package/src/pr-loop.ts

@@ -88,6 +88,9 @@ export const PR_REPORT_BEFORE_MERGE_FLOOR = "0.124.42";
 /** The first chant whose plan report can carry `migrations` (#4407). */
 export const PR_REPORT_MIGRATIONS_FLOOR = "0.124.49";
 
+/** The first chant whose report can carry a member's `reads`, known at plan or not. */
+export const PR_REPORT_READS_FLOOR = "0.124.52";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -155,6 +158,16 @@ export type PrMemberStatus =
    */
   | "waiting";
 
+/** One upstream a member reads outputs of (`PrMember.reads`). */
+export interface PrMemberRead {
+  /** The component (or stack) whose outputs it reads. */
+  upstream: string;
+  /** The output names it reads, sorted. `publish.<field>` for a published artifact. */
+  outputs: string[];
+  /** The ones its plan had no value for, sorted: known only after the upstream applies. Absent when every one was known. */
+  unknown?: string[];
+}
+
 export interface PrMember {
   /** The member's name in the change set: a root, for a terraform-family step. */
   member: string;
@@ -175,8 +188,10 @@ export interface PrMember {
   /**
    * The upstream outputs its plan read that the change's plans could not
    * say (#3999), as `<component>.<output>`, sorted: known only after that
-   * upstream applies. The approval does not cover what this member does
-   * with them; the apply plans it again once they are known.
+   * upstream applies. The apply plans the member again once they are known;
+   * the first approval covers that round when it does only what the preview
+   * showed with only these inputs filled in, and anything else waits for an
+   * approval of its own (`PrRound.covered`, `PrRound.notCovered`).
    */
   unknownInputs?: string[];
   /**
@@ -187,6 +202,15 @@ export interface PrMember {
    * applies without a later round.
    */
   buildInputs?: string[];
+  /**
+   * Every other component's output its steps read, one entry per upstream,
+   * by upstream: the output names, sorted, and under `unknown` the ones its
+   * plan had no value for. A read whose value the plan knew is here too, so
+   * a reader of the report sees each read between components from the plan
+   * on, not only the ones `unknownInputs` names. Added within contract 1 by
+   * chant {@link PR_REPORT_READS_FLOOR}.
+   */
+  reads?: PrMemberRead[];
   /** Apply stage (#3999): the round whose plan it applied or waits on, when not the first. */
   round?: number;
   /** Apply stage (#3999): why the first round's plan did not apply. */
@@ -210,6 +234,15 @@ export interface PrRound {
   status: "applied" | "failed" | "waiting" | "plan-failed";
   /** With `waiting`: why an approval that stands does not count (`--require-review`). */
   message?: string;
+  /**
+   * The first approval covered this round's plan (#4419): no gate of its own was
+   * decided. `digest` is the first approval's, which the coverage is bound
+   * to; `filledInputs` are the inputs it previewed as unknown and this plan
+   * had a value for, as `<component>.<output>`.
+   */
+  covered?: { digest: string; filledInputs: string[] };
+  /** Why the first approval did not cover this round, so it asked for its own (#4419). */
+  notCovered?: string;
   /** The change-set document the round planned. */
   changeSet: ChangeSetDocument;
 }
@@ -719,8 +752,8 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   if (unknown.length > 0) {
     out.push(
       "",
-      `Known only after apply: ${unknown.join("; ")}. This approval does not cover what those members do with them. ` +
-        "The apply plans them again once their upstream applied and asks for an approval of that plan.",
+      `Known only after apply: ${unknown.join("; ")}. ` +
+        "The apply plans those members again once their upstream applied. When that plan does only what this one shows, with only those inputs filled in, this approval covers it; anything else asks for an approval of its own.",
     );
   }
   const fromBuild = [...new Set(report.members.flatMap((m) => (m.buildInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
@@ -733,6 +766,12 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   }
   for (const r of report.rounds ?? []) {
     const what = `Round ${r.round} planned ${r.components.map(code).join(", ")} again after their upstream applied, digest ${code(r.digest)}`;
+    if (r.covered) {
+      const filled = r.covered.filledInputs.length > 0 ? `, with ${r.covered.filledInputs.map(code).join(", ")} filled in` : "";
+      out.push("", `${what}: covered by the approval of ${code(r.covered.digest)}${filled}, so it ${r.status === "applied" ? "applied" : "did not apply"} without a new approval${r.status === "failed" ? " (the apply failed)" : ""}.`);
+      continue;
+    }
+    if (r.notCovered) out.push("", `Round ${r.round}'s plan is not covered by the approval of ${code(report.digest)}: ${r.notCovered}.`);
     if (r.status === "waiting") {
       if (r.message) out.push("", `> ${r.message}`);
       out.push("", `${what}. Not approved yet. Approve it, then run the apply again with the same \`--resume\` record:`, "", "```", prApproveCommand({ op: report.op, gate: r.gate, digest: r.digest }, options.approver ?? "<you>"), "```");

package/src/workspace/pr-report.schema.json

@@ -153,6 +153,16 @@
           },
           "status": { "enum": ["applied", "failed", "waiting", "plan-failed"] },
           "message": { "type": "string", "description": "With waiting: why an approval that stands does not count under --require-review." },
+          "covered": {
+            "type": "object",
+            "required": ["digest", "filledInputs"],
+            "description": "Added within contract version 1 by #4419. The first approval covered this round's plan, so no gate of its own was decided and approval is the first one. The plan touched only components and logical ids the first plan previewed, with the same actions, and only inputs the first plan marked unknown differed.",
+            "properties": {
+              "digest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The digest of the first approval, which the coverage is bound to: the report's digest." },
+              "filledInputs": { "type": "array", "items": { "type": "string" }, "description": "The inputs the first plan marked unknown that this plan had a value for, as <component>.<output>, sorted." }
+            }
+          },
+          "notCovered": { "type": "string", "description": "Added within contract version 1 by #4419. Why an approval that stands for the first plan did not cover this round, so the round asked for its own." },
           "changeSet": { "type": "object", "description": "The change-set document the round planned. Its digest equals digest." }
         }
       }
@@ -208,13 +218,27 @@
           "unknownInputs": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "#3999: the upstream outputs its plan read that the change's plans could not say, as <component>.<output>, sorted. Known only after that upstream applies; the approval does not cover what this member does with them."
+            "description": "#3999: the upstream outputs its plan read that the change's plans could not say, as <component>.<output>, sorted. Known only after that upstream applies. The first approval covers the round that plans the member again when that plan does only what the preview showed, with only these inputs filled in; anything else waits for an approval of its own."
           },
           "buildInputs": {
             "type": "array",
             "items": { "type": "string" },
             "description": "#3999: the published artifact identities its plan read from a build in the same change, as <component>.publish.<field>, sorted. Known only after the build runs and never approved again: the build's provenance binds them, so the member applies without a later round."
           },
+          "reads": {
+            "type": "array",
+            "description": "Added within contract version 1, written by chant 0.124.52 and newer. Every other component's output its steps read, one entry per upstream: the output names, sorted, and under unknown the ones its plan had no value for. A read whose value the plan knew is listed too. Absent when it reads none.",
+            "items": {
+              "type": "object",
+              "required": ["upstream", "outputs"],
+              "additionalProperties": false,
+              "properties": {
+                "upstream": { "type": "string", "description": "The component (or stack) whose outputs it reads." },
+                "outputs": { "type": "array", "items": { "type": "string" }, "description": "The output names it reads, sorted. publish.<field> for a published artifact." },
+                "unknown": { "type": "array", "items": { "type": "string" }, "description": "The ones its plan had no value for, sorted: known only after the upstream applies. Absent when every one was known." }
+              }
+            }
+          },
           "round": { "type": "integer", "minimum": 2, "description": "Apply stage (#3999): the round whose plan it applied or waits on, when not the first. planDigest and counts are that round's." },
           "held": { "type": "string", "description": "Apply stage (#3999): why the first round's plan did not apply." }
         }