@intentius/chant 0.124.59 → 0.124.61

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/dist/cli/main.d.ts.map +1 -1
  2. package/dist/cli/main.js +16 -2
  3. package/dist/cli/parse-args.d.ts.map +1 -1
  4. package/dist/cli/parse-args.js +12 -0
  5. package/dist/cli/registry.d.ts +6 -0
  6. package/dist/cli/registry.d.ts.map +1 -1
  7. package/dist/components/capability.d.ts +11 -0
  8. package/dist/components/capability.d.ts.map +1 -1
  9. package/dist/lifecycle/wave-plans.d.ts +19 -0
  10. package/dist/lifecycle/wave-plans.d.ts.map +1 -1
  11. package/dist/lifecycle/wave-plans.js +25 -1
  12. package/dist/notify.d.ts +24 -2
  13. package/dist/notify.d.ts.map +1 -1
  14. package/dist/notify.js +16 -2
  15. package/dist/notify.schema.json +17 -1
  16. package/dist/op/gate-review.d.ts +1 -1
  17. package/dist/op/gate-review.d.ts.map +1 -1
  18. package/dist/op/index.d.ts +1 -0
  19. package/dist/op/index.d.ts.map +1 -1
  20. package/dist/op/index.js +1 -0
  21. package/dist/op/op-waves-capability.d.ts +2 -0
  22. package/dist/op/op-waves-capability.d.ts.map +1 -1
  23. package/dist/op/op-waves-capability.js +1 -0
  24. package/dist/op/op-waves-preview.d.ts +45 -0
  25. package/dist/op/op-waves-preview.d.ts.map +1 -0
  26. package/dist/op/op-waves-preview.js +37 -0
  27. package/dist/op/op-waves-run.d.ts +18 -0
  28. package/dist/op/op-waves-run.d.ts.map +1 -1
  29. package/dist/op/op-waves-run.js +40 -8
  30. package/dist/release-floors.d.ts +1 -1
  31. package/dist/release-floors.js +1 -1
  32. package/dist/wave-runtime.mjs +311 -310
  33. package/dist/workspace/ci-builds.d.ts +16 -4
  34. package/dist/workspace/ci-builds.d.ts.map +1 -1
  35. package/dist/workspace/ci-builds.js +10 -7
  36. package/dist/workspace/ci-green-cli.d.ts +12 -0
  37. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  38. package/dist/workspace/ci-green-cli.js +80 -6
  39. package/dist/workspace/ci-green-workflow.d.ts +11 -0
  40. package/dist/workspace/ci-green-workflow.d.ts.map +1 -1
  41. package/dist/workspace/ci-green-workflow.js +63 -1
  42. package/dist/workspace/ci-green.d.ts +130 -6
  43. package/dist/workspace/ci-green.d.ts.map +1 -1
  44. package/dist/workspace/ci-green.js +251 -24
  45. package/dist/workspace/declaration.d.ts +37 -0
  46. package/dist/workspace/declaration.d.ts.map +1 -1
  47. package/dist/workspace/declaration.js +29 -1
  48. package/dist/workspace/declaration.schema.json +44 -0
  49. package/dist/workspace/trust/ci-tag-statement.d.ts +1 -0
  50. package/dist/workspace/trust/ci-tag-statement.d.ts.map +1 -1
  51. package/dist/workspace/trust/ci-tag-statement.js +5 -1
  52. package/package.json +1 -1
  53. package/src/cli/main.ts +16 -2
  54. package/src/cli/parse-args.ts +9 -0
  55. package/src/cli/registry.ts +6 -0
  56. package/src/components/capability.ts +11 -0
  57. package/src/lifecycle/ledger-readers.test.ts +10 -0
  58. package/src/lifecycle/wave-plans.ts +41 -1
  59. package/src/notify.schema.json +17 -1
  60. package/src/notify.ts +30 -2
  61. package/src/op/gate-review.test.ts +1 -1
  62. package/src/op/gate-review.ts +1 -1
  63. package/src/op/index.ts +1 -0
  64. package/src/op/op-waves-capability.ts +3 -0
  65. package/src/op/op-waves-preview.test.ts +122 -5
  66. package/src/op/op-waves-preview.ts +70 -0
  67. package/src/op/op-waves-run.ts +58 -8
  68. package/src/op/op-waves.test.ts +11 -1
  69. package/src/release-floors.ts +1 -1
  70. package/src/workspace/ci-builds.ts +16 -7
  71. package/src/workspace/ci-green-builds.test.ts +83 -1
  72. package/src/workspace/ci-green-cli.ts +80 -6
  73. package/src/workspace/ci-green-lanes.test.ts +121 -0
  74. package/src/workspace/ci-green-merge-queue.test.ts +66 -0
  75. package/src/workspace/ci-green-notify.test.ts +166 -0
  76. package/src/workspace/ci-green-signed.test.ts +20 -0
  77. package/src/workspace/ci-green-workflow.test.ts +47 -1
  78. package/src/workspace/ci-green-workflow.ts +62 -1
  79. package/src/workspace/ci-green.ts +290 -26
  80. package/src/workspace/declaration.schema.json +44 -0
  81. package/src/workspace/declaration.ts +64 -2
  82. package/src/workspace/trust/ci-tag-statement.ts +5 -2
@@ -5,9 +5,9 @@ import { tmpdir } from "node:os";
5
5
  import { assertOpWavesSpec, opWavesPostsApprovalStatus, type OpWavesSpec } from "./op-waves";
6
6
  import { OP_WAVES_PREVIEW_FLOOR, readOpWavePolicy, runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
7
7
  import { memoryGateLedgerPort } from "./gate";
8
- import { NEXT_RELEASE } from "../release-floors";
9
8
  import { waveSetDigest } from "../gated-waves";
10
- import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
9
+ import type { HeadPlanMember, HeadPlans, MergedReview, ReviewSource } from "./gate-review";
10
+ import { movedSincePreview, shortAddress } from "./op-waves-preview";
11
11
 
12
12
  const spec: OpWavesSpec = {
13
13
  name: "records",
@@ -25,12 +25,21 @@ const reviews = (m: MergedReview | null): ReviewSource => ({ kind: "github", mer
25
25
  const recorded = (wave: number, set: string | undefined): ((name: string, head: string) => Promise<HeadPlans | null>) => async (name, head) =>
26
26
  set === undefined ? null : { version: 1, name, head, timestamp: "2026-10-30T00:00:00Z", waves: [{ wave, name: "dev", digest: set }] };
27
27
 
28
+ /** A record as chant after 0.124.59 writes it: the set digest, and each run's resources. */
29
+ const recordedRuns = (wave: number, members: HeadPlanMember[]): ((name: string, head: string) => Promise<HeadPlans | null>) => async (name, head) => ({
30
+ version: 1,
31
+ name,
32
+ head,
33
+ timestamp: "2026-10-30T00:00:00Z",
34
+ waves: [{ wave, name: "dev", digest: waveSetDigest(members.map((m) => ({ member: m.member, planDigest: m.planDigest }))), members }],
35
+ });
36
+
28
37
  const dirs: string[] = [];
29
38
  afterEach(() => {
30
39
  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
31
40
  });
32
41
 
33
- function harness(plan: { planDigest: string; destructive?: boolean }, atBase: OpWavesSpec = spec) {
42
+ function harness(plan: { planDigest: string; destructive?: boolean; resources?: Record<string, string> }, atBase: OpWavesSpec = spec) {
34
43
  const cwd = mkdtempSync(join(tmpdir(), "op-waves-preview-"));
35
44
  dirs.push(cwd);
36
45
  const calls: string[] = [];
@@ -152,8 +161,8 @@ describe("a wave applies the plans its pull request previewed (approvals.preview
152
161
  });
153
162
 
154
163
  describe("the setting", () => {
155
- test("its floor is the next release", () => {
156
- expect(OP_WAVES_PREVIEW_FLOOR).toBe(NEXT_RELEASE);
164
+ test("its floor is the release that shipped it", () => {
165
+ expect(OP_WAVES_PREVIEW_FLOOR).toBe("0.124.59");
157
166
  });
158
167
 
159
168
  test("is a boolean, is read at base, and makes the head record its plans", () => {
@@ -165,3 +174,111 @@ describe("the setting", () => {
165
174
  expect(opWavesPostsApprovalStatus({ ...spec, approvals: {} })).toBe(false);
166
175
  });
167
176
  });
177
+
178
+ describe("a wave compares the resources its pull request's plan changed (plywood#55)", () => {
179
+ // shop/dev holds an events queue and a set of worker queues. One pull request changes the events queue (EV), another adds a worker (WK).
180
+ const stack = "zone";
181
+ const EV = "urn:pulumi:dev::shop::aws:sqs/queue:Queue::events";
182
+ const WK = "urn:pulumi:dev::shop::aws:sqs/queue:Queue::worker-3";
183
+ const eventsPr: MergedReview = { pr: 3, head: "e".repeat(40), author: "github:dev", approvers: ["github:rev"], refused: [] };
184
+ const workersPr: MergedReview = { pr: 4, head: "w".repeat(40), author: "github:dev", approvers: ["github:rev"], refused: [] };
185
+ // What each pull request previewed against main before either merged.
186
+ const previewedEvents: HeadPlanMember[] = [{ member: stack, planDigest: digest("1"), resources: { [EV]: digest("e") } }];
187
+ const previewedWorkers: HeadPlanMember[] = [{ member: stack, planDigest: digest("2"), resources: { [WK]: digest("w") } }];
188
+
189
+ test("two pull requests that touch different resources both apply when merged in sequence", async () => {
190
+ // The first merge plans the events change alone.
191
+ const first = harness({ planDigest: digest("3"), resources: { [EV]: digest("e") } });
192
+ const one = await run(first, { reviews: reviews(eventsPr), headPlans: recordedRuns(1, previewedEvents) });
193
+ expect(one).toMatchObject({ exitCode: 0, applied: [stack], decision: { status: "not-required", preview: { status: "matched", pr: 3, compared: "resources" } } });
194
+ expect(first.applied()).toBe(true);
195
+ // The second merge plans while the first one's step is still in its plan: its set digest is neither pull request's.
196
+ const second = harness({ planDigest: digest("4"), resources: { [EV]: digest("e"), [WK]: digest("w") } });
197
+ const two = await run(second, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
198
+ expect(two).toMatchObject({ exitCode: 0, applied: [stack], decision: { status: "not-required", preview: { status: "matched", pr: 4, compared: "resources" } } });
199
+ expect(two.decision?.digest).not.toBe(two.decision?.preview?.recorded);
200
+ expect(second.applied()).toBe(true);
201
+ });
202
+
203
+ test("the second merge applies too when the first one has applied before it plans", async () => {
204
+ // The events queue is unchanged now but its recorded inputs are the new ones, so the stack's plan digest moved.
205
+ const second = harness({ planDigest: digest("5"), resources: { [WK]: digest("w") } });
206
+ const result = await run(second, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
207
+ expect(result).toMatchObject({ exitCode: 0, applied: [stack], decision: { preview: { status: "matched", compared: "resources" } } });
208
+ expect(second.applied()).toBe(true);
209
+ });
210
+
211
+ test("a pull request whose touched resource moved after another merge still returns 4", async () => {
212
+ // The other merge changed the worker queue the second pull request planned a change to.
213
+ const h = harness({ planDigest: digest("6"), resources: { [EV]: digest("e"), [WK]: digest("x") } });
214
+ const logs: string[] = [];
215
+ const result = await run(h, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers), log: (l) => logs.push(l) });
216
+ expect(result.exitCode).toBe(4);
217
+ expect(result.moved).toEqual([stack]);
218
+ expect(result.decision).toMatchObject({ status: "refused", refused: { reason: "moved" }, preview: { status: "moved", compared: "resources", moved: [`${stack}: aws:sqs/queue:Queue::worker-3 is planned differently`] } });
219
+ expect(result.decision?.refused?.message).toMatch(/worker-3 is planned differently/);
220
+ expect(h.applied()).toBe(false);
221
+ });
222
+
223
+ test("a resource the pull request changed that the merge no longer changes returns 4", async () => {
224
+ const h = harness({ planDigest: digest("7"), resources: { [EV]: digest("e") } });
225
+ const result = await run(h, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
226
+ expect(result).toMatchObject({ exitCode: 4, decision: { preview: { status: "moved", moved: [`${stack}: aws:sqs/queue:Queue::worker-3 is no longer changed by the plans`] } } });
227
+ expect(h.applied()).toBe(false);
228
+ });
229
+
230
+ test("a run the pull request changed that the wave no longer plans returns 4", () => {
231
+ expect(movedSincePreview(previewedWorkers, [])).toEqual([`${stack} is no longer in the wave`]);
232
+ });
233
+
234
+ test("a destructive change another merge added still waits for its approval", async () => {
235
+ const h = harness({ planDigest: digest("8"), destructive: true, resources: { [EV]: digest("d"), [WK]: digest("w") } });
236
+ const result = await run(h, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
237
+ expect(result).toMatchObject({ exitCode: 3, decision: { status: "waiting", preview: { status: "matched" } } });
238
+ expect(h.applied()).toBe(false);
239
+ const approved = memoryGateLedgerPort({
240
+ resolutions: [{ version: 1, op: "records", gate: "records-wave-1", resolvedBy: "alice", timestamp: "2026-10-30T00:30:00Z", planDigest: result.decision!.digest }],
241
+ });
242
+ expect(await run(h, { gates: approved, reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) })).toMatchObject({ exitCode: 0, applied: [stack], decision: { status: "approved" } });
243
+ });
244
+
245
+ test("an approval of the digest planned now lets a moved resource through", async () => {
246
+ const h = harness({ planDigest: digest("6"), resources: { [WK]: digest("x") } });
247
+ const refused = await run(h, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
248
+ expect(refused.exitCode).toBe(4);
249
+ const approved = memoryGateLedgerPort({
250
+ resolutions: [{ version: 1, op: "records", gate: "records-wave-1", resolvedBy: "alice", timestamp: "2026-10-30T00:30:00Z", planDigest: refused.decision!.digest }],
251
+ });
252
+ const result = await run(h, { gates: approved, reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
253
+ expect(result).toMatchObject({ exitCode: 0, applied: [stack], decision: { status: "approved", preview: { status: "moved", approvedAnyway: true } } });
254
+ });
255
+
256
+ test("a run recorded with no resources is compared whole, and one that changed nothing is not compared", async () => {
257
+ const whole: HeadPlanMember[] = [{ member: stack, planDigest: digest("a") }];
258
+ const moved = harness({ planDigest: digest("b") });
259
+ expect(await run(moved, { reviews: reviews(merged), headPlans: recordedRuns(1, whole) })).toMatchObject({ exitCode: 4, decision: { preview: { compared: "resources", moved: [`${stack}: its plan is another digest`] } } });
260
+ const same = harness({ planDigest: digest("a") });
261
+ expect(await run(same, { reviews: reviews(merged), headPlans: recordedRuns(1, whole) })).toMatchObject({ exitCode: 0, applied: [stack] });
262
+ const nothing = harness({ planDigest: digest("c"), resources: { [EV]: digest("e") } });
263
+ expect(await run(nothing, { reviews: reviews(merged), headPlans: recordedRuns(1, [{ member: stack, planDigest: digest("a"), empty: true }]) })).toMatchObject({ exitCode: 0, applied: [stack] });
264
+ });
265
+
266
+ test("a record written by 0.124.59 holds the set digest only, and is compared whole with a message saying so", async () => {
267
+ const h = harness({ planDigest: digest("b"), resources: { [WK]: digest("w") } });
268
+ const result = await run(h, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
269
+ expect(result).toMatchObject({ exitCode: 4, decision: { preview: { status: "moved", compared: "wave", recorded: setOf("a") } } });
270
+ expect(result.decision?.refused?.message).toMatch(/written by chant 0\.124\.59, which keeps the wave's digest only/);
271
+ const same = harness({ planDigest: digest("a"), resources: { [WK]: digest("w") } });
272
+ expect(await run(same, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) })).toMatchObject({ exitCode: 0, applied: [stack], decision: { preview: { status: "matched", compared: "wave" } } });
273
+ });
274
+
275
+ test("the plan file's resources are checked", async () => {
276
+ const h = harness({ planDigest: digest("a"), resources: { [WK]: 5 as unknown as string } });
277
+ await expect(run(h, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) })).rejects.toThrow(/map of a resource's address to its digest/);
278
+ });
279
+
280
+ test("an address reads short", () => {
281
+ expect(shortAddress(EV)).toBe("aws:sqs/queue:Queue::events");
282
+ expect(shortAddress("aws_s3_bucket.logs")).toBe("aws_s3_bucket.logs");
283
+ });
284
+ });
@@ -0,0 +1,70 @@
1
+ /**
2
+ * What `approvals.preview` compares (plywood#55): the resources a pull
3
+ * request's plan changed, and only those.
4
+ *
5
+ * A wave's set digest covers every run's whole plan. Two pull requests that
6
+ * change different resources of one stack, merged one after the other, never
7
+ * share a set digest: the second merge plans with the first one's change in
8
+ * it, either still waiting to apply (the plan holds that step) or applied
9
+ * (the plan holds that resource's new inputs where the pull request saw the
10
+ * old ones). Comparing the set refused the second merge's wave although
11
+ * nothing it previewed had moved.
12
+ *
13
+ * The record a pull request's head keeps (`HeadPlanWave.members`) holds, for
14
+ * each run, the digest of each resource its plan changes. The merged wave
15
+ * compares those resources with the ones it plans now:
16
+ *
17
+ * - a resource the pull request changed that the merge plans with another
18
+ * digest, or no longer changes, has moved;
19
+ * - a resource the merge changes that the pull request did not is another
20
+ * change's, which that change's own preview and gate answer for, and is not
21
+ * compared;
22
+ * - a run recorded with no resource digests (its plan command gave none) is
23
+ * compared whole, by its plan digest, unless its plan changed nothing;
24
+ * - a run the pull request's plan changed that the wave no longer plans has
25
+ * moved.
26
+ *
27
+ * The wave's gate still reads the plans the merge made, so a destructive
28
+ * change the merge adds waits for its approval whoever previewed it.
29
+ */
30
+ import type { HeadPlanMember } from "../lifecycle/wave-plans";
31
+ import { samePlanDigest } from "../lifecycle/plan-digest";
32
+
33
+ /** What the wave plans now for one run, as far as the comparison reads it. */
34
+ export interface PlannedRunDigests {
35
+ member: string;
36
+ planDigest: string;
37
+ resources?: Record<string, string>;
38
+ }
39
+
40
+ /** A resource address as a person reads it: a Pulumi URN is its type and name. */
41
+ export function shortAddress(address: string): string {
42
+ if (!address.startsWith("urn:pulumi:")) return address;
43
+ const parts = address.split("::");
44
+ return parts.length >= 3 ? parts.slice(-2).join("::") : address;
45
+ }
46
+
47
+ /**
48
+ * The runs and resources of the pull request's plan that the wave's plans now
49
+ * disagree with, as sentences naming each. Empty: nothing the pull request
50
+ * previewed has moved.
51
+ */
52
+ export function movedSincePreview(recorded: readonly HeadPlanMember[], now: readonly PlannedRunDigests[]): string[] {
53
+ const byMember = new Map(now.map((m) => [m.member, m]));
54
+ const moved: string[] = [];
55
+ for (const before of recorded) {
56
+ const fresh = byMember.get(before.member);
57
+ if (before.resources && fresh?.resources) {
58
+ for (const [address, digest] of Object.entries(before.resources)) {
59
+ const found = fresh.resources[address];
60
+ if (found === undefined) moved.push(`${before.member}: ${shortAddress(address)} is no longer changed by the plans`);
61
+ else if (!samePlanDigest(found, digest)) moved.push(`${before.member}: ${shortAddress(address)} is planned differently`);
62
+ }
63
+ continue;
64
+ }
65
+ if (before.empty === true) continue;
66
+ if (!fresh) moved.push(`${before.member} is no longer in the wave`);
67
+ else if (!samePlanDigest(before.planDigest, fresh.planDigest)) moved.push(`${before.member}: its plan is another digest`);
68
+ }
69
+ return moved;
70
+ }
@@ -82,7 +82,7 @@ import type { GatePointAsker } from "../point-decision";
82
82
  import type { WaitingPoint } from "./steward-points";
83
83
  import { isApprovalSpent, type AppliedGateRecord, type FinishedGateRecord } from "../lifecycle/gate-applied";
84
84
  import { samePlanDigest } from "../lifecycle/plan-digest";
85
- import { NEXT_RELEASE } from "../release-floors";
85
+ import { movedSincePreview } from "./op-waves-preview";
86
86
  import { isLifecycleLocalNote } from "../lifecycle/local-note";
87
87
  import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
88
88
  import type { TrustPolicy } from "../workspace/trust/policy";
@@ -187,6 +187,14 @@ export type { OpWaveAsyncExec, OpWaveExec, OpWaveHoldFinished, OpWaveHoldRequest
187
187
  /** What a run's plan command writes to `{plan}`. */
188
188
  export interface OpWavePlanFile {
189
189
  planDigest: string;
190
+ /**
191
+ * The digest of each resource this plan changes, by the resource's address
192
+ * (plywood#55). A merged wave under `approvals.preview` compares the ones
193
+ * its pull request recorded with the ones it plans now, resource by
194
+ * resource, and leaves a resource the pull request's plan did not change
195
+ * out. Absent: the run is compared as a whole, by `planDigest`.
196
+ */
197
+ resources?: Record<string, string>;
190
198
  /** The plan destroys, rewrites or otherwise needs a person under `on-destructive`. */
191
199
  destructive?: boolean;
192
200
  /** The plan changes nothing. */
@@ -260,6 +268,8 @@ export interface OpWaveRunsFile {
260
268
  /** One run's plan, as the decision records it. */
261
269
  export interface OpWaveMember extends WaveMember {
262
270
  op: string;
271
+ /** The digest of each resource the plan changes (plywood#55), when the plan gave them. */
272
+ resources?: Record<string, string>;
263
273
  destructive?: boolean;
264
274
  empty?: boolean;
265
275
  /** The product's policy denied the plan (#3821). */
@@ -412,6 +422,14 @@ export interface OpWavePreview {
412
422
  recorded?: string;
413
423
  /** Why the plans do not match, for `moved` and `unrecorded`. */
414
424
  reason?: string;
425
+ /**
426
+ * What was compared: `resources`, the resources the pull request's plan
427
+ * changed (plywood#55), or `wave`, the wave's whole set digest, which is
428
+ * all a record from chant 0.124.59 holds.
429
+ */
430
+ compared?: "resources" | "wave";
431
+ /** For `moved` under `resources`: each run or resource of the pull request's plan that is not as it was previewed. */
432
+ moved?: string[];
415
433
  /** Set when an approval of the digest planned now let a wave that did not match apply. */
416
434
  approvedAnyway?: true;
417
435
  }
@@ -708,7 +726,7 @@ function pointAtBase(spec: OpWavesSpec, name: string, where: string): Pick<OpWav
708
726
  }
709
727
 
710
728
  /** The first chant whose Op waves spec takes `approvals.preview`: a merged wave applies the plans its pull request previewed, or exits 4. */
711
- export const OP_WAVES_PREVIEW_FLOOR = NEXT_RELEASE;
729
+ export const OP_WAVES_PREVIEW_FLOOR = "0.124.59";
712
730
 
713
731
  /** The first chant whose op entry exports {@link opWavePlanPath} (terragucci#1304). */
714
732
  export const OP_WAVE_PLAN_PATH_FLOOR = "0.124.56";
@@ -950,6 +968,15 @@ function planRun(opts: { spec: OpWavesSpec; wave: number; cwd: string; exec: OpW
950
968
  return member(run.target, op, file);
951
969
  }
952
970
 
971
+ /** A plan file's `resources`: a map of address to digest, or nothing. Anything else is a mistake the wave names. */
972
+ function resourcesOf(value: unknown, target: string): Record<string, string> | undefined {
973
+ if (value === undefined) return undefined;
974
+ if (value === null || typeof value !== "object" || Array.isArray(value) || !Object.values(value).every((d) => typeof d === "string" && d !== "")) {
975
+ throw new Error(`the plan of ${target} has resources ${JSON.stringify(value)}; it is a map of a resource's address to its digest`);
976
+ }
977
+ return Object.fromEntries(Object.entries(value as Record<string, string>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
978
+ }
979
+
953
980
  function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember {
954
981
  for (const key of ["denied", "held"] as const) {
955
982
  const value = file[key] as unknown;
@@ -963,6 +990,7 @@ function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember
963
990
  member: target,
964
991
  planDigest: file.planDigest,
965
992
  op,
993
+ ...(resourcesOf(file.resources, target) ? { resources: resourcesOf(file.resources, target)! } : {}),
966
994
  ...(file.destructive === true ? { destructive: true } : {}),
967
995
  ...(file.empty === true ? { empty: true } : {}),
968
996
  ...(file.denied ? { denied: { rules: file.denied.rules, ...(file.denied.reason ? { reason: file.denied.reason } : {}) } } : {}),
@@ -1113,6 +1141,7 @@ async function planWaveRuns(
1113
1141
  const members = plans.map((p) => ({
1114
1142
  member: p.target,
1115
1143
  planDigest: p.planDigest,
1144
+ ...(p.resources ? { resources: p.resources } : {}),
1116
1145
  op: runs.find((r) => r.target === p.target)?.op ?? spec.op,
1117
1146
  ...(p.destructive ? { destructive: true } : {}),
1118
1147
  ...(p.empty ? { empty: true } : {}),
@@ -2593,11 +2622,11 @@ async function decideOpWave(
2593
2622
  // `approvals.preview` at base: the merged wave applies what the pull request previewed. Planned again to a digest this job already let through, it has been judged.
2594
2623
  let unseen = false;
2595
2624
  if (planned.rules.preview && !kept && decision.status !== "refused") {
2596
- const seen = await previewOf(options, ctx, digest);
2625
+ const seen = await previewOf(options, ctx, digest, members);
2597
2626
  if ("error" in seen) return { end: failed(ctx, `wave ${k} (${wave.name}): ${seen.error}, so it cannot be compared with what the pull request previewed and nothing in it was applied`) };
2598
2627
  decision.preview = seen.preview;
2599
2628
  unseen = seen.preview.status !== "matched";
2600
- if (!unseen) log(`wave ${k} (${wave.name}): the plans are the ones pull request #${seen.preview.pr} previewed at ${seen.preview.head?.slice(0, 12)} (${digest})`);
2629
+ if (!unseen) log(`wave ${k} (${wave.name}): the plans are the ones pull request #${seen.preview.pr} previewed at ${seen.preview.head?.slice(0, 12)} (${seen.preview.compared === "resources" ? `${seen.preview.recorded}, compared resource by resource; the wave now plans ${digest}` : digest})`);
2601
2630
  else log(`wave ${k} (${wave.name}): ${seen.preview.reason}`);
2602
2631
  }
2603
2632
  if (kept && was.status === "approved" && decision.status !== "refused") {
@@ -2634,7 +2663,7 @@ async function decideOpWave(
2634
2663
  * `error` only when the forge or the ledger cannot be read, which fails the
2635
2664
  * wave: a missing answer never stands in for a match.
2636
2665
  */
2637
- async function previewOf(options: RunOpWaveOptions, ctx: WaveContext, digest: string): Promise<{ preview: OpWavePreview } | { error: string }> {
2666
+ async function previewOf(options: RunOpWaveOptions, ctx: WaveContext, digest: string, members: readonly OpWaveMember[]): Promise<{ preview: OpWavePreview } | { error: string }> {
2638
2667
  const { spec, k, cwd } = ctx;
2639
2668
  const review = await import("./gate-review");
2640
2669
  const head = options.head ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim();
@@ -2652,21 +2681,40 @@ async function previewOf(options: RunOpWaveOptions, ctx: WaveContext, digest: st
2652
2681
  return { error: `the plans recorded for #${merged.pr} could not be read (${err instanceof Error ? err.message : String(err)})` };
2653
2682
  }
2654
2683
  const seen = { pr: merged.pr, head: merged.head };
2655
- const recorded = plans?.waves.find((w) => w.wave === k)?.digest;
2684
+ const recordedWave = plans?.waves.find((w) => w.wave === k);
2685
+ const recorded = recordedWave?.digest;
2656
2686
  if (recorded === undefined) {
2657
2687
  return { preview: { status: "unrecorded", ...seen, reason: `no plans are recorded for wave ${k} at the head ${merged.head.slice(0, 12)} of #${merged.pr} (its pipeline runs \`chant run wave --record-plans\`), so nothing was previewed` } };
2658
2688
  }
2689
+ // plywood#55: a record that holds each run's resources is compared resource by resource, over the ones the pull request's plan changed.
2690
+ if (recordedWave!.members) {
2691
+ const moved = movedSincePreview(recordedWave!.members, members);
2692
+ if (moved.length > 0) {
2693
+ return {
2694
+ preview: {
2695
+ status: "moved",
2696
+ ...seen,
2697
+ recorded,
2698
+ compared: "resources",
2699
+ moved,
2700
+ reason: `the plans moved since #${merged.pr} previewed them: ${moved.join("; ")} (the head ${merged.head.slice(0, 12)} planned ${recorded}, and the merge plans ${digest})`,
2701
+ },
2702
+ };
2703
+ }
2704
+ return { preview: { status: "matched", ...seen, recorded, compared: "resources" } };
2705
+ }
2659
2706
  if (!samePlanDigest(recorded, digest)) {
2660
2707
  return {
2661
2708
  preview: {
2662
2709
  status: "moved",
2663
2710
  ...seen,
2664
2711
  recorded,
2665
- reason: `the plans moved since #${merged.pr} previewed them: the head ${merged.head.slice(0, 12)} planned ${recorded}, and the merge plans ${digest}`,
2712
+ compared: "wave",
2713
+ reason: `the plans moved since #${merged.pr} previewed them: the head ${merged.head.slice(0, 12)} planned ${recorded}, and the merge plans ${digest}. The record was written by chant 0.124.59, which keeps the wave's digest only, so the whole wave was compared; a later chant records each resource and compares those`,
2666
2714
  },
2667
2715
  };
2668
2716
  }
2669
- return { preview: { status: "matched", ...seen, recorded } };
2717
+ return { preview: { status: "matched", ...seen, recorded, compared: "wave" } };
2670
2718
  }
2671
2719
 
2672
2720
  /**
@@ -3944,6 +3992,8 @@ export async function recordOpWaveHeadPlans(options: RecordHeadPlansOptions): Pr
3944
3992
  digest: opWaveSetDigest(spec, members, extras),
3945
3993
  changes: !members.every((m) => m.empty === true),
3946
3994
  destructive: members.some((m) => m.destructive === true),
3995
+ // plywood#55: each run's resources, which a merged wave under `approvals.preview` compares with its own.
3996
+ members: members.map((m) => ({ member: m.member, planDigest: m.planDigest, ...(m.resources ? { resources: m.resources } : {}), ...(m.empty ? { empty: true as const } : {}) })),
3947
3997
  // #4630: a pull-request wave's change set, which the pull request's own approval must cover.
3948
3998
  ...(changeSet ? { changeSet: changeSet.digest } : {}),
3949
3999
  });
@@ -140,7 +140,7 @@ describe("runOpWave with wave-level commands (#3762)", () => {
140
140
  { name: "apps", runs: [{ target: "a1" }, { target: "a2" }, { target: "a3" }], gate: "never", shares: 2 },
141
141
  ],
142
142
  };
143
- function harness(plans: Record<string, { planDigest: string; destructive?: boolean; empty?: boolean }>, atBase: OpWavesSpec | null = waveSpec) {
143
+ function harness(plans: Record<string, { planDigest: string; destructive?: boolean; empty?: boolean; resources?: Record<string, string> }>, atBase: OpWavesSpec | null = waveSpec) {
144
144
  const cwd = mkdtempSync(join(tmpdir(), "op-waves-wave-"));
145
145
  const calls: string[] = [];
146
146
  const applied: OpWaveRunsFile[] = [];
@@ -211,6 +211,16 @@ describe("runOpWave with wave-level commands (#3762)", () => {
211
211
  expect(h.calls.filter((c) => c.startsWith("tg plan"))).toHaveLength(2);
212
212
  h.done();
213
213
  });
214
+
215
+ test("--record-plans keeps each run's plan and resources for the merged wave to compare (plywood#55)", async () => {
216
+ const h = harness({ vpc: { planDigest: digest("1"), resources: { "aws_vpc.main": digest("a") } }, dns: { planDigest: digest("2"), empty: true }, a1: { planDigest: digest("1") }, a2: { planDigest: digest("2") }, a3: { planDigest: digest("3") } });
217
+ const plans = await recordOpWaveHeadPlans({ spec: waveSpec, cwd: h.cwd, exec: h.exec, head: "c".repeat(40), now: "t", write: async () => {} });
218
+ expect(plans.waves[0]!.members).toEqual([
219
+ { member: "vpc", planDigest: digest("1"), resources: { "aws_vpc.main": digest("a") } },
220
+ { member: "dns", planDigest: digest("2"), empty: true },
221
+ ]);
222
+ h.done();
223
+ });
214
224
  });
215
225
 
216
226
  describe("runOpWave hooks (#3762)", () => {
@@ -19,4 +19,4 @@
19
19
  * this constant to the next patch (#4501). The check fails while a floor
20
20
  * still names this constant after its version shipped.
21
21
  */
22
- export const NEXT_RELEASE = "0.124.59";
22
+ export const NEXT_RELEASE = "0.124.61";
@@ -48,6 +48,8 @@ export const CI_BUILD_TAG_PREFIX = "ci/build/";
48
48
  /** The directory on `chant/lifecycle` holding one record per commit. */
49
49
  export const CI_RECORDS_DIR = "_ci";
50
50
  const LEDGER_REF = "refs/heads/chant/lifecycle";
51
+ /** The local branch the records are read from, for readers that fall back to its remote-tracking branch. */
52
+ export const CI_LEDGER_REF = LEDGER_REF;
51
53
 
52
54
  /** How long a build request may wait for a runner before its phases count as unbuilt. */
53
55
  export const BUILD_REQUEST_TTL_MS = 6 * 3_600_000;
@@ -92,6 +94,12 @@ export interface CiRecord {
92
94
  request?: { tag: string; reason: BuildRequestReason; phases: string[]; at: string; dispatched?: true };
93
95
  /** The `every` phases a `missing` request asked for, and when (#4216). A commit is asked for once. */
94
96
  missing?: { phases: string[]; at: string };
97
+ /**
98
+ * What the tick told people about this commit through `ci.green.notify`
99
+ * (#4645), so it tells them once: when it sent `ci.red`, the culprit it
100
+ * sent `ci.culprit` for, and the green commit whose `ci.green` answered it.
101
+ */
102
+ notified?: { red?: string; culprit?: string; green?: string };
95
103
  }
96
104
 
97
105
  export interface CiRecordRun {
@@ -290,6 +298,7 @@ export function recordOf(input: { green: CiGreen; commit: TickCommit; previous?:
290
298
  const missing = req?.reason === "missing" ? { phases: req.phases, at: req.at } : previous?.missing;
291
299
  const extras = {
292
300
  ...(Object.keys(retried).length > 0 ? { retried } : {}),
301
+ ...(previous?.notified ? { notified: previous.notified } : {}),
293
302
  ...(req ? { request: { tag: req.tag, reason: req.reason, phases: req.phases, at: req.at } } : {}),
294
303
  ...(missing ? { missing } : {}),
295
304
  };
@@ -358,20 +367,20 @@ function parseRecord(text: string | null): CiRecord | undefined {
358
367
  }
359
368
  }
360
369
 
361
- /** One commit's record, from the local `chant/lifecycle`. */
362
- export function readCiRecord(top: string, sha: string): CiRecord | undefined {
363
- return parseRecord(tryGit(top, ["show", `${LEDGER_REF}:${recordPath(sha)}`]));
370
+ /** One commit's record, from the local `chant/lifecycle` (or `ref`, such as its remote-tracking branch). */
371
+ export function readCiRecord(top: string, sha: string, ref: string = LEDGER_REF): CiRecord | undefined {
372
+ return parseRecord(tryGit(top, ["show", `${ref}:${recordPath(sha)}`]));
364
373
  }
365
374
 
366
- /** Every record on the local `chant/lifecycle`, by commit. Empty when the branch or the directory is missing. */
367
- export function readCiRecords(top: string): Map<string, CiRecord> {
375
+ /** Every record on the local `chant/lifecycle` (or `ref`), by commit. Empty when the branch or the directory is missing. */
376
+ export function readCiRecords(top: string, ref: string = LEDGER_REF): Map<string, CiRecord> {
368
377
  const out = new Map<string, CiRecord>();
369
- const names = tryGit(top, ["ls-tree", "--name-only", `${LEDGER_REF}:${CI_RECORDS_DIR}`]);
378
+ const names = tryGit(top, ["ls-tree", "--name-only", `${ref}:${CI_RECORDS_DIR}`]);
370
379
  if (!names) return out;
371
380
  for (const name of names.split("\n")) {
372
381
  const m = /^([0-9a-f]{40,64})\.json$/.exec(name);
373
382
  if (!m) continue;
374
- const r = readCiRecord(top, m[1]);
383
+ const r = readCiRecord(top, m[1], ref);
375
384
  if (r) out.set(m[1], r);
376
385
  }
377
386
  return out;
@@ -8,7 +8,7 @@
8
8
  import { execFileSync } from "node:child_process";
9
9
  import { afterAll, describe, expect, test } from "vitest";
10
10
  import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
11
- import { ciList, ciTick, lastGreen, requestBuild } from "./ci-green";
11
+ import { ciBase, ciList, ciTick, lastGreen, requestBuild } from "./ci-green";
12
12
  import type { CheckRun, CiForge } from "./ci-green-forge";
13
13
  import { readBuildRequests, readCiRecord } from "./ci-builds";
14
14
 
@@ -204,3 +204,85 @@ describe("chant ci run --at (#4169)", () => {
204
204
  expect(readCiRecord(root, a)).toMatchObject({ state: "pending", request: { reason: "requested", dispatched: true } });
205
205
  });
206
206
  });
207
+
208
+ describe("chant ci base (#4643)", () => {
209
+ const baseOf = (cwd: string, from: string, phase?: string) => {
210
+ const doc = ciBase({ cwd, from, ...(phase ? { phase } : {}) });
211
+ if ("error" in doc) throw new Error(doc.error.message);
212
+ return doc.commit && { sha: doc.commit.sha, via: doc.commit.via };
213
+ };
214
+
215
+ test("a docs-only tip over a superseded commit diffs against the last commit the phase built, not its parent", async () => {
216
+ const { root } = workspace();
217
+ const base = commitAt(root, 4, "app/a.txt");
218
+ git(root, "push", "-q", "origin", "main");
219
+ // a changes the code and is superseded before its suites run; c changes only docs.
220
+ const a = commitAt(root, 3, "app/a.txt");
221
+ const c = commitAt(root, 2, "docs/readme.md");
222
+ git(root, "push", "-q", "origin", "main");
223
+ const runs = new Map([
224
+ [base, [run("check", "success"), run("suites", "success")]],
225
+ [a, [run("check", "success"), run("suites", "cancelled")]],
226
+ [c, [run("check", "success"), run("suites", null, "in_progress")]],
227
+ ]);
228
+ await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
229
+
230
+ // c's filter, run while c builds: its base is base, so a's change to app/ is in the diff.
231
+ expect(baseOf(root, c, "suites")).toEqual({ sha: base, via: "record" });
232
+ expect(baseOf(root, c)).toEqual({ sha: base, via: "record" });
233
+
234
+ // Once c's suites pass, a commit above c diffs against c, and a stays passed over.
235
+ runs.set(c, [run("check", "success"), run("suites", "success")]);
236
+ await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
237
+ const d = commitAt(root, 1, "docs/more.md");
238
+ expect(baseOf(root, d, "suites")).toEqual({ sha: c, via: "record" });
239
+ });
240
+
241
+ test("passes over a commit whose phase failed, so a change on top of the failure still runs it", async () => {
242
+ const { root } = workspace();
243
+ const base = commitAt(root, 4, "app/a.txt");
244
+ const red = commitAt(root, 3, "app/a.txt");
245
+ git(root, "push", "-q", "origin", "main");
246
+ const runs = new Map([
247
+ [base, [run("check", "success"), run("suites", "success")]],
248
+ [red, [run("check", "success"), run("suites", "failure"), run("suites", "failure")]],
249
+ ]);
250
+ await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
251
+ const docs = commitAt(root, 2, "docs/readme.md");
252
+ expect(baseOf(root, docs, "suites")).toEqual({ sha: base, via: "record" });
253
+ // A phase that passed on the red commit has it as its base.
254
+ expect(baseOf(root, docs, "check")).toEqual({ sha: red, via: "record" });
255
+ });
256
+
257
+ test("a commit with no record counts by its green tag, and none at all is a null commit", () => {
258
+ const { root } = workspace();
259
+ const tagged = commitAt(root, 3, "app/a.txt");
260
+ const above = commitAt(root, 2, "app/a.txt");
261
+ expect(baseOf(root, above, "suites")).toBeNull();
262
+ git(root, "tag", `ci/green/${tagged}`, tagged);
263
+ expect(baseOf(root, above, "suites")).toEqual({ sha: tagged, via: "tag" });
264
+ // The commit asked about is never its own base.
265
+ expect(baseOf(root, tagged)).toBeNull();
266
+ });
267
+
268
+ test("reads origin/chant/lifecycle when there is no local branch, as in a CI checkout", async () => {
269
+ const { root, origin } = workspace();
270
+ const base = commitAt(root, 3, "app/a.txt");
271
+ git(root, "push", "-q", "origin", "main");
272
+ await ciTick({ cwd: root, forge: fakeForge(new Map([[base, [run("check", "success"), run("suites", "success")]]])), now: NOW });
273
+ const clone = scratchDir("chant-base-clone-");
274
+ git(clone, "clone", "-q", "-b", "main", origin, ".");
275
+ git(clone, "fetch", "-q", "origin", "--tags", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle");
276
+ expect(git(clone, "branch", "--list", "chant/lifecycle")).toBe("");
277
+ writeFiles(clone, { "docs/readme.md": "docs\n" });
278
+ git(clone, "add", "-A");
279
+ git(clone, "-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "-m", "docs");
280
+ expect(baseOf(clone, "HEAD", "suites")).toEqual({ sha: base, via: "record" });
281
+ });
282
+
283
+ test("refuses a phase the declaration doesn't name", () => {
284
+ const { root } = workspace();
285
+ commitAt(root, 2, "app/a.txt");
286
+ expect(() => ciBase({ cwd: root, phase: "lint" })).toThrow(/declares no phase "lint"; it declares check, suites/);
287
+ });
288
+ });