@intentius/chant 0.124.93 → 0.124.95

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 (85) hide show
  1. package/dist/ci-comment-commands.d.ts +12 -1
  2. package/dist/ci-comment-commands.d.ts.map +1 -1
  3. package/dist/ci-comment-commands.js +29 -0
  4. package/dist/ci-note-commands.d.ts +1 -1
  5. package/dist/ci-note-commands.d.ts.map +1 -1
  6. package/dist/ci-note-commands.js +11 -1
  7. package/dist/ci-product.d.ts +19 -1
  8. package/dist/ci-product.d.ts.map +1 -1
  9. package/dist/ci-product.js +25 -8
  10. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  11. package/dist/cli/handlers/pr-comment.js +11 -4
  12. package/dist/cli/handlers/run-wave.js +17 -3
  13. package/dist/cli/main.d.ts.map +1 -1
  14. package/dist/cli/main.js +4 -1
  15. package/dist/components/product-pipeline.d.ts.map +1 -1
  16. package/dist/components/product-pipeline.js +4 -2
  17. package/dist/components/product-plan.d.ts +6 -0
  18. package/dist/components/product-plan.d.ts.map +1 -1
  19. package/dist/components/product-plan.js +9 -1
  20. package/dist/floor-table.data.d.ts.map +1 -1
  21. package/dist/floor-table.data.js +15 -6
  22. package/dist/gate-resume-run.d.ts +7 -0
  23. package/dist/gate-resume-run.d.ts.map +1 -1
  24. package/dist/gate-resume-run.js +42 -3
  25. package/dist/lexicon.d.ts +47 -1
  26. package/dist/lexicon.d.ts.map +1 -1
  27. package/dist/lifecycle/gate-applied.d.ts +18 -0
  28. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  29. package/dist/op/before-merge-decide.d.ts +39 -2
  30. package/dist/op/before-merge-decide.d.ts.map +1 -1
  31. package/dist/op/before-merge-decide.js +59 -0
  32. package/dist/op/gate-run-locator.d.ts +17 -0
  33. package/dist/op/gate-run-locator.d.ts.map +1 -1
  34. package/dist/op/index.d.ts +3 -1
  35. package/dist/op/index.d.ts.map +1 -1
  36. package/dist/op/index.js +2 -1
  37. package/dist/op/op-waves-names.d.ts +40 -0
  38. package/dist/op/op-waves-names.d.ts.map +1 -1
  39. package/dist/op/op-waves-names.js +79 -0
  40. package/dist/op/op-waves-remainder.d.ts +110 -0
  41. package/dist/op/op-waves-remainder.d.ts.map +1 -0
  42. package/dist/op/op-waves-remainder.js +120 -0
  43. package/dist/op/op-waves-render-spec.d.ts +63 -5
  44. package/dist/op/op-waves-render-spec.d.ts.map +1 -1
  45. package/dist/op/op-waves-render-spec.js +68 -10
  46. package/dist/op/op-waves-run.d.ts +27 -1
  47. package/dist/op/op-waves-run.d.ts.map +1 -1
  48. package/dist/op/op-waves-run.js +192 -4
  49. package/dist/op/op-waves-split-resume.d.ts +57 -0
  50. package/dist/op/op-waves-split-resume.d.ts.map +1 -0
  51. package/dist/op/op-waves-split-resume.js +94 -0
  52. package/dist/op/op-waves.d.ts +26 -1
  53. package/dist/op/op-waves.d.ts.map +1 -1
  54. package/dist/op/op-waves.js +11 -2
  55. package/dist/release-floors.d.ts +13 -1
  56. package/dist/release-floors.d.ts.map +1 -1
  57. package/dist/release-floors.js +13 -1
  58. package/dist/wave-runtime.mjs +360 -360
  59. package/package.json +1 -1
  60. package/src/ci-comment-commands.test.ts +147 -0
  61. package/src/ci-comment-commands.ts +29 -1
  62. package/src/ci-note-commands.ts +12 -2
  63. package/src/ci-product.ts +28 -8
  64. package/src/cli/handlers/pr-comment.ts +10 -4
  65. package/src/cli/handlers/run-wave.ts +16 -3
  66. package/src/cli/main.ts +4 -1
  67. package/src/components/product-pipeline.ts +4 -2
  68. package/src/components/product-plan.ts +9 -2
  69. package/src/floor-table.data.ts +15 -6
  70. package/src/gate-resume-run.ts +38 -3
  71. package/src/lexicon.ts +47 -1
  72. package/src/lifecycle/gate-applied.ts +16 -0
  73. package/src/op/before-merge-decide.ts +74 -2
  74. package/src/op/gate-run-locator.ts +14 -0
  75. package/src/op/index.ts +5 -0
  76. package/src/op/op-waves-names.ts +80 -0
  77. package/src/op/op-waves-remainder.test.ts +341 -0
  78. package/src/op/op-waves-remainder.ts +146 -0
  79. package/src/op/op-waves-render-spec.test.ts +106 -0
  80. package/src/op/op-waves-render-spec.ts +81 -10
  81. package/src/op/op-waves-run.ts +200 -5
  82. package/src/op/op-waves-split-resume.test.ts +148 -0
  83. package/src/op/op-waves-split-resume.ts +109 -0
  84. package/src/op/op-waves.ts +33 -2
  85. package/src/release-floors.ts +19 -1
@@ -0,0 +1,109 @@
1
+ /**
2
+ * How `chant run resume` starts a killed split apply again (#5052), on the
3
+ * forges whose gate job's run locator alone does not do it.
4
+ *
5
+ * Under `approvals.remainder` (#5047) a split wave's gate job writes the
6
+ * applied line, and its applying job is the one that may be killed. On
7
+ * GitHub the line names the gate job's run, and a re-run of its failed jobs
8
+ * runs the applying and record jobs again. GitLab retries one job by its id,
9
+ * and the gate job knows only the names of the jobs after it; Forgejo has no
10
+ * re-run and dispatches the workflow on the branch, which before merge is
11
+ * not the decided head. So the generator tells the gate job, in
12
+ * {@link OP_WAVES_RESUME_ENV}, what a resume needs:
13
+ *
14
+ * - GitLab: the names of the wave's applying jobs and its record job. The
15
+ * line's locator carries them as `retry`, and the resume retries the
16
+ * newest try of each applying job that failed or was cancelled, then the
17
+ * record job.
18
+ * - Forgejo: the product's names of the dispatch inputs. The line's locator
19
+ * carries the run's own inputs (the decided head of a before-merge run,
20
+ * the wave and commit of a follow-on) as `inputs`, and the resume
21
+ * dispatches with them, so the new run plans the same commit and its gate
22
+ * job applies the rest under the same approval.
23
+ *
24
+ * Without the variable, the gate job's line names no run on those forges,
25
+ * as before.
26
+ */
27
+
28
+ import { BEFORE_MERGE_DIGEST_ENV, BEFORE_MERGE_HEAD_ENV, BEFORE_MERGE_PR_ENV } from "./before-merge";
29
+ import { OP_WAVES_COMMIT_ENV, OP_WAVES_WAVE_ENV } from "./follow-on-run";
30
+ import type { GateRunLocator } from "./gate-run-locator";
31
+ import type { OpWaveSplitJob } from "./op-waves-split";
32
+
33
+ export { OP_WAVES_SPLIT_RESUME_FLOOR } from "../release-floors";
34
+
35
+ /** The variable a split wave's gate job reads what a resume needs from, as JSON. */
36
+ export const OP_WAVES_RESUME_ENV = "CHANT_WAVES_RESUME";
37
+
38
+ /** The dispatch inputs a Forgejo resume fills, by chant's names. */
39
+ export type OpWaveResumeInput = "pr" | "head" | "digest" | "wave" | "commit";
40
+
41
+ /** What {@link OP_WAVES_RESUME_ENV} holds: GitLab's job names, or Forgejo's input names (each chant's own when left out). */
42
+ export interface OpWaveSplitResume {
43
+ apply?: string[];
44
+ record?: string;
45
+ inputs?: Partial<Record<OpWaveResumeInput, string>>;
46
+ }
47
+
48
+ /**
49
+ * The variable a split wave's gate job carries (#5052): on GitLab the names
50
+ * of wave `gate.wave`'s applying jobs and its record job, on Forgejo the
51
+ * product's dispatch input names. Empty on GitHub, whose re-run needs none,
52
+ * and for a job that is no gate job.
53
+ */
54
+ export function opWaveSplitResumeEnv(
55
+ split: readonly Pick<OpWaveSplitJob, "jobName" | "phase" | "wave">[],
56
+ gate: Pick<OpWaveSplitJob, "phase" | "wave">,
57
+ forge: "github" | "forgejo" | "gitlab",
58
+ inputs?: Partial<Record<OpWaveResumeInput, string>>,
59
+ ): Record<string, string> {
60
+ if (gate.phase !== "gate" || forge === "github") return {};
61
+ if (forge === "forgejo") return { [OP_WAVES_RESUME_ENV]: JSON.stringify(inputs && Object.keys(inputs).length > 0 ? { inputs } : {}) };
62
+ const apply = split.filter((j) => j.wave === gate.wave && j.phase === "apply").map((j) => j.jobName);
63
+ const record = split.find((j) => j.wave === gate.wave && j.phase === "record")?.jobName;
64
+ return { [OP_WAVES_RESUME_ENV]: JSON.stringify({ apply, ...(record ? { record } : {}) }) };
65
+ }
66
+
67
+ const NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
68
+
69
+ /** Read {@link OP_WAVES_RESUME_ENV}; undefined when unset or not one. */
70
+ export function parseOpWaveSplitResume(raw: string | undefined): OpWaveSplitResume | undefined {
71
+ if (raw === undefined || raw.trim() === "") return undefined;
72
+ let v: unknown;
73
+ try {
74
+ v = JSON.parse(raw);
75
+ } catch {
76
+ return undefined;
77
+ }
78
+ if (!v || typeof v !== "object" || Array.isArray(v)) return undefined;
79
+ const o = v as Record<string, unknown>;
80
+ const apply = Array.isArray(o.apply) && o.apply.every((n) => typeof n === "string" && n.trim() !== "") ? (o.apply as string[]) : undefined;
81
+ const record = typeof o.record === "string" && o.record.trim() !== "" ? o.record : undefined;
82
+ const inputs =
83
+ o.inputs && typeof o.inputs === "object" && !Array.isArray(o.inputs) && Object.entries(o.inputs).every(([k, n]) => ["pr", "head", "digest", "wave", "commit"].includes(k) && typeof n === "string" && NAME.test(n))
84
+ ? (o.inputs as Partial<Record<OpWaveResumeInput, string>>)
85
+ : undefined;
86
+ return { ...(apply ? { apply } : {}), ...(record ? { record } : {}), ...(inputs ? { inputs } : {}) };
87
+ }
88
+
89
+ /**
90
+ * The run locator a split wave's gate job writes on its applied line
91
+ * (#5052), from its own locator and what {@link OP_WAVES_RESUME_ENV} says:
92
+ * GitHub's as it is; GitLab's with `retry`, when the variable names applying
93
+ * jobs; Forgejo's with the run's own dispatch inputs, when the variable is
94
+ * set. Undefined where a resume could not start the applying jobs again.
95
+ */
96
+ export function opWaveSplitResumeLocator(locator: GateRunLocator | undefined, env: Record<string, string | undefined> = process.env): GateRunLocator | undefined {
97
+ if (!locator) return undefined;
98
+ if (locator.forge === "github") return locator;
99
+ const told = parseOpWaveSplitResume(env[OP_WAVES_RESUME_ENV]);
100
+ if (!told) return undefined;
101
+ if (locator.forge === "gitlab") return told.apply && told.apply.length > 0 ? { ...locator, retry: { apply: told.apply, ...(told.record ? { record: told.record } : {}) } } : undefined;
102
+ const of: Record<OpWaveResumeInput, string> = { pr: BEFORE_MERGE_PR_ENV, head: BEFORE_MERGE_HEAD_ENV, digest: BEFORE_MERGE_DIGEST_ENV, wave: OP_WAVES_WAVE_ENV, commit: OP_WAVES_COMMIT_ENV };
103
+ const inputs: Record<string, string> = {};
104
+ for (const [input, variable] of Object.entries(of) as Array<[OpWaveResumeInput, string]>) {
105
+ const value = env[variable]?.trim();
106
+ if (value) inputs[told.inputs?.[input] ?? input] = value;
107
+ }
108
+ return { ...locator, inputs };
109
+ }
@@ -764,6 +764,30 @@ export interface OpWavesApprovals {
764
764
  * approval of a digest passes that digest as often as it is planned.
765
765
  */
766
766
  spend?: boolean;
767
+ /**
768
+ * An apply that stopped applies the rest under its approval (#5047). With
769
+ * `spend`, read at the base commit. The applied line a wave writes before
770
+ * it applies under an approval carries each change its plans make (a run's
771
+ * resource and its digest), the commit and the run, when every run that
772
+ * changes something plans through the step on the `resource` lock grain
773
+ * (an engine that records each resource as it applies it). The job that
774
+ * applies the whole wave, or a split wave's record job, writes how the
775
+ * apply ended. A wave run again at the same commit whose plans make only
776
+ * changes of the newest such apply that did not finish (no finished line,
777
+ * or a failed one), with the same digests, applies them under that
778
+ * approval: the changes it no longer makes are done. A split wave's
779
+ * applying job applies a run whose plan moved the same way. A wave whose
780
+ * plans change nothing closes an apply that stopped as applied. Default
781
+ * false. See `./op-waves-remainder.ts`.
782
+ */
783
+ remainder?: boolean;
784
+ /**
785
+ * With `spend` (#5047), read at the base commit: a wave its gate lets
786
+ * through (`not-required`) spends an approval of its digest that stands,
787
+ * so it does not stand for the next plans. Default false: only a wave that
788
+ * applies under an approval spends it.
789
+ */
790
+ spendStanding?: boolean;
767
791
  /**
768
792
  * Approval rules (#4290): a wave takes each rule whose `targets` glob
769
793
  * matches one of its runs' targets (a rule with no `targets` covers every
@@ -1064,7 +1088,13 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
1064
1088
  if (typeof value !== "boolean") throw new Error(`${where}: approvals.preview must be true or false.`);
1065
1089
  continue;
1066
1090
  }
1067
- if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the ones there are approvals.spend, approvals.preview, approvals.quorum, approvals.reviewLedger, approvals.involved and approvals.pullRequest.`);
1091
+ if (key === "remainder" || key === "spendStanding") {
1092
+ // #5047: a stopped apply's rest, and an approval left standing, both under the spend rule.
1093
+ if (typeof value !== "boolean") throw new Error(`${where}: approvals.${key} must be true or false.`);
1094
+ if (value && (a as OpWavesApprovals).spend !== true) throw new Error(`${where}: approvals.${key} works on the lines approvals.spend writes, so it needs approvals.spend: true.`);
1095
+ continue;
1096
+ }
1097
+ if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the ones there are approvals.spend, approvals.remainder, approvals.spendStanding, approvals.preview, approvals.quorum, approvals.reviewLedger, approvals.involved and approvals.pullRequest.`);
1068
1098
  if (typeof value !== "boolean") throw new Error(`${where}: approvals.spend must be true or false.`);
1069
1099
  }
1070
1100
  if ((a as OpWavesApprovals).quorum?.length && (spec.point !== undefined || spec.waves.some((w) => w.point !== undefined))) {
@@ -1490,7 +1520,8 @@ export function opWaveShare<T extends { target: string }>(runs: readonly T[], sh
1490
1520
  * product's command in place of `chant` (#4607, {@link opWaveBinArgv}).
1491
1521
  * With `renderSpec` (#4982) every command passes `--render-spec`: the job
1492
1522
  * renders the spec at base through the product's command
1493
- * (`./op-waves-render-spec.ts`), and `spec` is the pipeline's shape.
1523
+ * (`./op-waves-render-spec.ts`; with `runsAtHead` the runs at the applied
1524
+ * commit, #5046), and `spec` is the pipeline's shape.
1494
1525
  * With `beforeMerge` (#4984) every command reads its base from
1495
1526
  * `CHANT_WAVES_BASE` when the run checked out a pull request's decided
1496
1527
  * head, else from the spec's `base` (or `HEAD^1`), as a push run does.
@@ -19,7 +19,7 @@
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.93";
22
+ export const NEXT_RELEASE = "0.124.95";
23
23
 
24
24
  /** The first chant with `chant dev local` and `chant dev bundle-check`, `@intentius/chant/local-chant` and `@intentius/chant/bundle-check` (`chantRuntimeTarget`, `chantExternalPlugin`, `checkBundle`): a product built against a chant checkout, and its bundle checked, without its own scripts (#4787). */
25
25
  export const LOCAL_CHANT_FLOOR = "0.124.86";
@@ -234,6 +234,24 @@ export const TARGET_SIGNED_CHECKS_FLOOR = "0.124.89";
234
234
  /** The first chant whose Op waves generators take `renderSpec` (the wave jobs run `chant run wave --render-spec`, and `CHANT_WAVES_SPEC_COMMAND` names the product command that prints the spec at the commit in `CHANT_WAVES_SPEC_AT`), so a product whose spec is built from its config at base renders its wave jobs, policy step, evidence job and cloud trade through chant (#4982). */
235
235
  export const RUNTIME_WAVES_SPEC_FLOOR = "0.124.89";
236
236
 
237
+ /** The first chant whose Op waves `renderSpec` takes `runsAtHead` (the jobs carry `CHANT_WAVES_SPEC_RUNS=head`): the job's own spec is rendered at the applied commit, with `CHANT_WAVES_SPEC_BASE` set to the base commit beside `CHANT_WAVES_SPEC_AT`, so the runs a change adds apply at its merge, while the gate policy, holds, hooks and evidence rules still come from the render at base (#5046). */
238
+ export const RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR = "0.124.94";
239
+
240
+ /** The first chant whose Op waves keep the record of an apply under an approval themselves (#5047): with `approvals.spend`, `approvals.remainder` writes each change the approved plans make, the commit and the run on the applied line (a split wave's gate job writes it), the job that applies the whole wave or the record job writes how the apply ended, and a wave run again at that commit applies the rest under the same approval when its plans make only changes the stopped apply did not finish; a wave that plans no change closes a stopped apply, and `approvals.spendStanding` spends an approval of the digest a wave its gate let through applies. */
241
+ export const OP_WAVES_REMAINDER_FLOOR = "0.124.94";
242
+
243
+ /** The first chant whose `chant run resume` starts a killed split apply again on GitLab and Forgejo (#5052): under `approvals.remainder` the gate job's applied line names its run there too, GitLab's with the wave's applying and record jobs by name (`retry`), which the resume retries, and Forgejo's with the run's dispatch inputs (`inputs`), which the resume dispatches with, so the new run applies the rest at the same decided head or commit. */
244
+ export const OP_WAVES_SPLIT_RESUME_FLOOR = "0.124.94";
245
+
246
+ /** The first chant whose `approvals.remainder` resumes the waves terragucci's own records resume (#5056): the terraform step gives a live choudoufu root's plan (`live-plan-set`) its `resourceDigests`, so its applied line names the changes, and the cover leaves out the cost member `(monthly cost)`, whose digest follows from the plans, on both sides. */
247
+ export const OP_WAVES_REMAINDER_PARITY_FLOOR = "0.124.94";
248
+
249
+ /** The first chant whose Op waves generators, in a product's workflow (`runIf`) with `beforeMerge` and a spec `control`, run the control job on the default branch's push, outside the product's `runIf` and after its `firstWaveNeeds` jobs, and tell the control repo the waves applied at the pushed commit without adding up outcomes, on GitHub, Forgejo and GitLab (#5060). */
250
+ export const OP_WAVES_CONTROL_BEFORE_MERGE_FLOOR = NEXT_RELEASE;
251
+
252
+ /** The first chant whose waves before merge lock and unlock on a comment by the product plan's reach line (#5061): with `wavesBeforeMerge` and `productPlan.reach`, and no `locks: "plan"`, the comment job (GitHub, Forgejo) and the note poll (GitLab, `chantNoteRuns`) answer `/<product> lock` on an open pull request by taking the locks of what the reach line prints at stage `apply` in `_locks/<reach.gate>.json` without applying (`decideLocksBeforeMerge`), refused with the holder named, and `/<product> unlock` by releasing the pull request's locks; and the product plan takes `reach` without `locks: "plan"` under `wavesBeforeMerge`, writing no reach lock job. */
253
+ export const WAVES_BEFORE_MERGE_LOCKS_FLOOR = NEXT_RELEASE;
254
+
237
255
  /** The first chant whose `chant run resume` (`resumeGateRun`) on GitLab retries a wave job's `<wave job>-evidence` with the wave job when the evidence job already ran, and whose `ci evidence sign --from-job` waits for a job it reads to finish, so a resumed wave's evidence job signs from the new try (#4978). */
238
256
  export const GITLAB_WAVE_EVIDENCE_RETRY_FLOOR = "0.124.89";
239
257