@intentius/chant 0.61.0 → 0.63.0

package/src/op/builders.ts

@@ -107,16 +107,22 @@ export function activity(
  * that reaches this step with no resolution newer than its pending fact
  * records the pending fact and ends `gated`. `chant approve <op> <gate>`
  * writes the resolution, and the next run walks through carrying the approver.
+ *
+ * Pass `plan` to bind the approval to a specific plan (#2300) — normally the
+ * Plan phase's own digest, `plan.out.planDigest`. Then a resolution counts
+ * only for that plan, and a run whose fresh plan differs is refused by name
+ * instead of applying a change nobody approved. See {@link GateStep.plan}.
  */
 export function gate(
   name: string,
-  opts?: { timeout?: string; description?: string },
+  opts?: { timeout?: string; description?: string; plan?: GateStep["plan"] },
 ): GateStep {
   return {
     kind: "gate",
     gate: name,
     ...(opts?.timeout ? { timeout: opts.timeout } : {}),
     ...(opts?.description ? { description: opts.description } : {}),
+    ...(opts?.plan !== undefined ? { plan: opts.plan } : {}),
   };
 }
 

package/src/op/composites/apply-op.ts

@@ -19,6 +19,12 @@
  * approve <op> <gate>` line to run. Approve, run again, and the same Op
  * converges — no durable workflow engine is involved.
  *
+ * The gate binds the plan (#2300). The Plan phase's `lifecycleDiff` publishes
+ * a digest of its change set, the gate step references it, and a resolution
+ * counts only for that digest. Approve, change the declared source, re-run,
+ * and the run stops again with both digests named rather than applying a
+ * change set the approver never saw.
+ *
  * @example
  * ```typescript
  * // additive, local executor
@@ -38,6 +44,7 @@
  */
 
 import { Op, phase, activity, gate } from "../builders";
+import { stepOutput } from "../step-output-ref";
 import { gateName } from "../gate-name";
 import type { OpResource } from "../resource";
 import { defaultOutput, hasNativeRollback, type ApplyTarget, type DeleteMode } from "../activities/apply";
@@ -129,6 +136,10 @@ export function ApplyOp(config: ApplyOpConfig): ApplyOpResources {
     phase("Plan", [
       {
         kind: "activity" as const,
+        // #2300: the gate below references this step's digest, and a
+        // reference needs an id. `plan` rather than `diff`, because what the
+        // Approve phase binds to is the plan this step produced.
+        id: "plan",
         fn: "lifecycleDiff",
         args: { env: config.env, live: true },
         outcomeAttribute: { name: "Drift", from: "drifted" },
@@ -141,6 +152,11 @@ export function ApplyOp(config: ApplyOpConfig): ApplyOpResources {
       phase("Approve", [
         gate(gateName(config.gate ?? {}) || `approve-${config.name}`, {
           ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
+          // #2300: the approval is for the change set the Plan phase just
+          // produced. Edit the source between approving and re-running and
+          // the gate refuses, naming the approved digest and the planned one,
+          // instead of applying what nobody read.
+          plan: stepOutput("plan", "planDigest"),
           description:
             config.gate?.description ??
             `Approve apply to ${config.env} (delete mode: ${deleteMode}` +

package/src/op/composites/composites.test.ts

@@ -12,6 +12,7 @@ import { ReconcileOp } from "./reconcile-op";
 import { ApplyOp } from "./apply-op";
 import { DECLARABLE_MARKER } from "../../declarable";
 import { EffectReceipt, receiptExpectation } from "../../effect-receipt";
+import { isStepOutputRef } from "../step-output-ref";
 
 function getProps(entity: unknown): Record<string, unknown> {
   return (entity as { props: Record<string, unknown> }).props;
@@ -115,14 +116,14 @@ describe("ReconcileOp: configuration", () => {
     expect(phases.map((p) => p.name)).toEqual(["Snapshot", "Plan", "Reconcile"]);
     const reconcileStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
     expect(reconcileStep.fn).toBe("reconcilePr");
-    expect(reconcileStep.args).toEqual({ env: "prod", mode: "pull-request", owned: false });
+    expect(reconcileStep.args).toEqual({ env: "prod", op: "p", mode: "pull-request", owned: false });
   });
 
   test("scope.owned + onDrift flow into the reconcilePr step", () => {
     const { op } = ReconcileOp({ name: "p", env: "prod", onDrift: "issue", scope: { owned: true } });
     const phases = getProps(op).phases as Array<Record<string, unknown>>;
     const reconcileStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
-    expect(reconcileStep.args).toEqual({ env: "prod", mode: "issue", owned: true });
+    expect(reconcileStep.args).toEqual({ env: "prod", op: "p", mode: "issue", owned: true });
   });
 
   test("labels include Reconcile + Env", () => {
@@ -204,6 +205,18 @@ describe("ApplyOp: gating + deletes", () => {
     const { op } = ApplyOp({ name: "p", env: "prod" });
     expect(getProps(op).labels).toEqual({ Apply: "true", Env: "prod" });
   });
+
+  // #2300 — the gate approves the change set the Plan phase produced, not the
+  // next run of the Op. The Plan step carries the id the reference needs.
+  test("the gate binds the Plan phase's own change-set digest", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", delete: "gated" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const planStep = (phases[1].steps as Array<Record<string, unknown>>)[0];
+    expect(planStep.id).toBe("plan");
+    const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(isStepOutputRef(gateStep.plan)).toBe(true);
+    expect(gateStep.plan).toMatchObject({ step: "plan", path: "planDigest" });
+  });
 });
 
 describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {

package/src/op/composites/reconcile-op.test.ts

@@ -34,6 +34,24 @@ describe("ReconcileOp composite — PR/issue URL outcome (#8)", () => {
   });
 });
 
+describe("ReconcileOp composite — the finding step names its Op (#2319)", () => {
+  test("passes the Op's own name as `op`, which is what keeps the issue marker unique", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod", onDrift: "issue" });
+    expect((reconcileStep(op).args as { op: string }).op).toBe("prod-reconcile");
+  });
+
+  test("two Ops over one env carry two identities", () => {
+    // The collision #2319 reports: `env` alone is shared here by construction,
+    // and a `TerraformWatchOp` over a root named "prod" would share it too.
+    const a = ReconcileOp({ name: "prod-reconcile", env: "prod", onDrift: "issue" });
+    const b = ReconcileOp({ name: "prod-reconcile-owned", env: "prod", onDrift: "issue" });
+    const argsA = reconcileStep(a.op).args as { op: string; env: string };
+    const argsB = reconcileStep(b.op).args as { op: string; env: string };
+    expect(argsA.env).toBe(argsB.env);
+    expect(argsA.op).not.toBe(argsB.op);
+  });
+});
+
 describe("ReconcileOp composite — cadence on the op (#2120)", () => {
   function opProps(op: unknown): Record<string, unknown> {
     return (op as { props: Record<string, unknown> }).props;

package/src/op/composites/reconcile-op.ts

@@ -96,10 +96,16 @@ export function ReconcileOp(config: ReconcileOpConfig): ReconcileOpResources {
         // regenerates via `chant import --from`, and opens a PR. Surface the
         // opened PR/issue URL as an outcome so `chant run` prints it — the
         // reconcile's result is the link.
+        //
+        // `op` names this Op in the marker `issue` mode's sticky issue is
+        // found by (#2319). The env alone is not unique across Ops: it shares
+        // a marker namespace with `TerraformWatchOp`, which passes a terraform
+        // *root* as its `env`, so a chant environment and a root that happen
+        // to share a name resolved to one marker and overwrote each other.
         {
           kind: "activity" as const,
           fn: "reconcilePr",
-          args: { env: config.env, mode: onDrift, owned },
+          args: { env: config.env, op: config.name, mode: onDrift, owned },
           ...(reconcileOutcome ? { outcomeAttribute: reconcileOutcome } : {}),
         },
       ]),

package/src/op/gate-summary.test.ts

@@ -28,6 +28,39 @@ describe("gatedRunSummaryMarkdown (#2243)", () => {
     expect(md).toContain("chant approve app-apply approve-app-apply --approver <you>");
     expect(md).toContain("_gates/app-apply.jsonl");
   });
+
+  // #2310: `recordGateApproval`'s push was already reported (#2309); the
+  // gate's own `appendPending` push was not. The GitHub/Forgejo/Gitea step
+  // summary is exactly the surface an operator working from a different
+  // checkout would open, so it is where the gap mattered most.
+  test("says so when this run's own append never reached the remote", () => {
+    const md = gatedRunSummaryMarkdown({
+      ...summary,
+      pushed: false,
+      pushWarning: "chant/lifecycle remote branch has moved since this run started",
+    });
+    expect(md).toContain("was not pushed to the remote");
+    expect(md).toContain("chant/lifecycle remote branch has moved since this run started");
+    expect(md).toContain("cannot see it to approve it");
+  });
+
+  test("says nothing extra when the push landed or nothing was pushed this run", () => {
+    const md = gatedRunSummaryMarkdown(summary);
+    expect(md).not.toContain("was not pushed");
+  });
+
+  // #2300 — the block is where a CI approver reads what they are approving,
+  // so it names the plan and says the approval does not carry to the next one.
+  test("names the plan the approval binds to, when the gate binds one", () => {
+    const digest = `sha256:${"d".repeat(64)}`;
+    const md = gatedRunSummaryMarkdown({ ...summary, planDigest: digest });
+    expect(md).toContain(digest);
+    expect(md).toContain("and not the next run");
+  });
+
+  test("a gate that binds no plan says nothing about one", () => {
+    expect(gatedRunSummaryMarkdown(summary)).not.toContain("and not the next run");
+  });
 });
 
 describe("writeGatedRunSummary surfaces (#2243, #2256)", () => {

package/src/op/gate-summary.ts

@@ -34,6 +34,22 @@ export interface GatedRunSummary {
   expiresAt?: string;
   /** The approval surface the run resolved, when it knew one. */
   url?: string;
+  /**
+   * False when this run's own append reached only the local chant/lifecycle
+   * branch, not the remote (#2310) — the reason lives in `pushWarning`.
+   * Absent when this run left an already-standing pending fact alone, or when
+   * the push landed.
+   */
+  pushed?: boolean;
+  /** Set when `pushed` is false. */
+  pushWarning?: string;
+  /**
+   * The plan the pending fact was recorded against (#2300), when the gate
+   * binds one. Shown because it is what the `chant approve` line below
+   * approves — and because a reader who comes back to a stale summary needs
+   * to see that the digest has moved on.
+   */
+  planDigest?: string;
 }
 
 /**
@@ -51,6 +67,13 @@ export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
   if (summary.description) {
     lines.push(summary.description, "");
   }
+  if (summary.planDigest) {
+    lines.push(
+      `This approves one plan, \`${summary.planDigest}\`, and not the next run (#2300). ` +
+        "Change the configuration after approving and the next run refuses rather than applying.",
+      "",
+    );
+  }
   lines.push(
     "Approve it, then re-run this workflow:",
     "",
@@ -62,6 +85,14 @@ export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
   );
   if (summary.expiresAt) lines.push(`Expires: ${summary.expiresAt}`);
   if (summary.url) lines.push(`Approve at: ${summary.url}`);
+  if (summary.pushed === false) {
+    lines.push(
+      "",
+      `**This pending fact was not pushed to the remote** (${summary.pushWarning ?? "no reason given"}). ` +
+        "It exists only in this job's checkout. An operator working from a clone of the remote cannot " +
+        "see it to approve it until it reaches \`chant/lifecycle\` there.",
+    );
+  }
   lines.push("");
   return lines.join("\n");
 }