@intentius/chant 0.124.108 → 0.124.110
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.
- package/dist/__golden__/wave-loop/fan-out-applied.json +12 -6
- package/dist/__golden__/wave-loop/fan-out-apply-fails.json +8 -4
- package/dist/__golden__/wave-loop/fan-out-gated.json +4 -2
- package/dist/__golden__/wave-loop/fan-out-no-members.json +16 -8
- package/dist/__golden__/wave-loop/fan-out-plan-fails.json +8 -4
- package/dist/__golden__/wave-loop/fan-out-same-root.json +4 -2
- package/dist/agent-facts.d.ts +130 -0
- package/dist/agent-facts.js +196 -0
- package/dist/change-risk.d.ts +216 -0
- package/dist/change-risk.js +304 -0
- package/dist/change-set.d.ts +8 -0
- package/dist/ci-agent-alert.d.ts +139 -0
- package/dist/ci-agent-alert.js +342 -0
- package/dist/ci-agent-triggers.d.ts +152 -0
- package/dist/ci-agent-triggers.js +232 -0
- package/dist/ci-agent-verify-failed.d.ts +149 -0
- package/dist/ci-agent-verify-failed.js +191 -0
- package/dist/ci-agent.d.ts +136 -8
- package/dist/ci-agent.js +353 -26
- package/dist/ci-comment-commands.d.ts +8 -0
- package/dist/ci-comment-commands.js +17 -1
- package/dist/ci-comment-reject.d.ts +70 -0
- package/dist/ci-comment-reject.js +135 -0
- package/dist/ci-comment-replies.d.ts +3 -1
- package/dist/ci-comment-replies.js +6 -0
- package/dist/ci-estate/delivery.d.ts +25 -3
- package/dist/ci-estate/delivery.js +28 -9
- package/dist/ci-estate/page.d.ts +7 -3
- package/dist/ci-estate/page.js +19 -4
- package/dist/ci-estate/rows.d.ts +14 -2
- package/dist/ci-estate/rows.js +9 -1
- package/dist/ci-estate.d.ts +5 -2
- package/dist/ci-estate.js +3 -2
- package/dist/ci-handover.d.ts +2 -7
- package/dist/ci-handover.js +3 -20
- package/dist/ci-jobs.d.ts +6 -0
- package/dist/ci-jobs.js +17 -0
- package/dist/ci-note-commands.d.ts +2 -0
- package/dist/ci-note-commands.js +12 -1
- package/dist/ci-product-words.d.ts +151 -1
- package/dist/ci-product-words.js +1390 -3
- package/dist/ci-product.d.ts +100 -4
- package/dist/ci-product.js +99 -3
- package/dist/ci-respond-run.d.ts +9 -0
- package/dist/ci-respond-run.js +35 -4
- package/dist/ci-respond-summary-env.d.ts +56 -0
- package/dist/ci-respond-summary-env.js +81 -0
- package/dist/ci-respond-summary.d.ts +103 -0
- package/dist/ci-respond-summary.js +243 -0
- package/dist/ci-respond.d.ts +4 -2
- package/dist/ci-respond.js +4 -2
- package/dist/cli/command-group.js +1 -1
- package/dist/cli/commands/lint.js +21 -3
- package/dist/cli/handlers/agent.js +49 -4
- package/dist/cli/handlers/approve.js +3 -1
- package/dist/cli/handlers/build.d.ts +97 -1
- package/dist/cli/handlers/build.js +251 -3
- package/dist/cli/handlers/fan-out.js +55 -0
- package/dist/cli/handlers/graph.d.ts +14 -0
- package/dist/cli/handlers/graph.js +58 -3
- package/dist/cli/handlers/lifecycle-health.d.ts +7 -0
- package/dist/cli/handlers/lifecycle-health.js +47 -9
- package/dist/cli/handlers/lifecycle.js +4 -1
- package/dist/cli/handlers/notify-relay.d.ts +2 -2
- package/dist/cli/handlers/notify-relay.js +67 -7
- package/dist/cli/handlers/pipeline-agent.d.ts +30 -0
- package/dist/cli/handlers/pipeline-agent.js +255 -0
- package/dist/cli/handlers/pipeline-artifacts.d.ts +39 -0
- package/dist/cli/handlers/pipeline-artifacts.js +203 -0
- package/dist/cli/handlers/pipeline.d.ts +16 -0
- package/dist/cli/handlers/pipeline.js +112 -0
- package/dist/cli/handlers/pr-comment.js +4 -0
- package/dist/cli/handlers/pr-notes.js +4 -1
- package/dist/cli/handlers/pr.d.ts +20 -0
- package/dist/cli/handlers/pr.js +114 -11
- package/dist/cli/handlers/promote.js +792 -47
- package/dist/cli/handlers/reject.d.ts +84 -0
- package/dist/cli/handlers/reject.js +216 -0
- package/dist/cli/handlers/release.js +4 -2
- package/dist/cli/handlers/replan.d.ts +54 -0
- package/dist/cli/handlers/replan.js +177 -0
- package/dist/cli/handlers/run-generate.d.ts +5 -0
- package/dist/cli/handlers/run-generate.js +31 -4
- package/dist/cli/handlers/run-wave.js +15 -2
- package/dist/cli/handlers/run.js +4 -2
- package/dist/cli/handlers/stage.d.ts +35 -0
- package/dist/cli/handlers/stage.js +90 -0
- package/dist/cli/lsp/server.js +4 -0
- package/dist/cli/main.js +88 -8
- package/dist/cli/parse-args.js +35 -2
- package/dist/cli/registry.d.ts +12 -0
- package/dist/components/auto-release.d.ts +2 -0
- package/dist/components/auto-release.js +1 -0
- package/dist/components/capability.d.ts +40 -0
- package/dist/components/cli-support.d.ts +21 -1
- package/dist/components/cli-support.js +28 -6
- package/dist/components/component.d.ts +23 -4
- package/dist/components/component.schema.json +28 -0
- package/dist/components/declared-reads.d.ts +44 -4
- package/dist/components/declared-reads.js +80 -3
- package/dist/components/discover.d.ts +8 -0
- package/dist/components/discover.js +1 -1
- package/dist/components/driver.d.ts +13 -0
- package/dist/components/driver.js +23 -2
- package/dist/components/environment-sets.d.ts +229 -0
- package/dist/components/environment-sets.js +338 -0
- package/dist/components/fan-out-canary.d.ts +47 -0
- package/dist/components/fan-out-canary.js +58 -0
- package/dist/components/fan-out-run.d.ts +17 -0
- package/dist/components/fan-out-run.js +14 -1
- package/dist/components/fan-out-support.d.ts +7 -0
- package/dist/components/fan-out-support.js +1 -1
- package/dist/components/groups.d.ts +8 -1
- package/dist/components/groups.js +19 -1
- package/dist/components/index.d.ts +5 -2
- package/dist/components/index.js +4 -1
- package/dist/components/pr-cost.d.ts +28 -0
- package/dist/components/pr-cost.js +53 -0
- package/dist/components/pr-pipeline.d.ts +33 -0
- package/dist/components/pr-pipeline.js +32 -5
- package/dist/components/pr-policy.d.ts +33 -2
- package/dist/components/pr-policy.js +5 -2
- package/dist/components/pr-risk.d.ts +42 -0
- package/dist/components/pr-risk.js +74 -0
- package/dist/components/product-pipeline.d.ts +43 -0
- package/dist/components/product-pipeline.js +67 -1
- package/dist/components/promote.d.ts +6 -0
- package/dist/components/promote.js +13 -0
- package/dist/components/release-compile.js +3 -1
- package/dist/components/release-gate.d.ts +6 -1
- package/dist/components/release-gate.js +10 -2
- package/dist/components/step-environments.d.ts +236 -0
- package/dist/components/step-environments.js +392 -0
- package/dist/components/upstream-replan.d.ts +201 -0
- package/dist/components/upstream-replan.js +249 -0
- package/dist/components/verify-step.d.ts +30 -0
- package/dist/components/verify-step.js +27 -0
- package/dist/components/wave-plan.js +6 -2
- package/dist/config-environments.d.ts +4 -2
- package/dist/control/dispatch.d.ts +15 -0
- package/dist/control/dispatch.js +28 -4
- package/dist/cost-estimate.d.ts +188 -0
- package/dist/cost-estimate.js +363 -0
- package/dist/drift-record.d.ts +36 -0
- package/dist/drift-record.js +44 -0
- package/dist/engine-facts.d.ts +105 -0
- package/dist/engine-facts.js +111 -0
- package/dist/exit-codes.d.ts +4 -3
- package/dist/exit-codes.js +4 -3
- package/dist/flag-params.d.ts +2 -2
- package/dist/flag-params.js +9 -4
- package/dist/floor-table.data.js +53 -0
- package/dist/forge-token-vars.d.ts +12 -0
- package/dist/forge-token-vars.js +25 -0
- package/dist/gate-decision.d.ts +3 -1
- package/dist/gate-decision.js +3 -1
- package/dist/gated-waves.d.ts +2 -0
- package/dist/gated-waves.js +1 -0
- package/dist/graph-ir.d.ts +30 -0
- package/dist/graph-ir.js +33 -1
- package/dist/graph-refs.d.ts +26 -0
- package/dist/graph-refs.js +34 -3
- package/dist/graph-schema/graph.schema.json +136 -0
- package/dist/health.d.ts +65 -0
- package/dist/health.js +62 -0
- package/dist/lexicon.d.ts +188 -1
- package/dist/lifecycle/disruption.d.ts +14 -1
- package/dist/lifecycle/disruption.js +5 -1
- package/dist/lifecycle/gate-change-set.d.ts +8 -0
- package/dist/lifecycle/gate-change-set.js +2 -1
- package/dist/lifecycle/gate-ledger.d.ts +26 -0
- package/dist/lifecycle/gate-rejection.d.ts +82 -0
- package/dist/lifecycle/gate-rejection.js +93 -0
- package/dist/lifecycle/gate-seal.d.ts +3 -3
- package/dist/lifecycle/gate-seal.js +5 -5
- package/dist/lifecycle/observe.d.ts +17 -0
- package/dist/lifecycle/observe.js +10 -1
- package/dist/lifecycle/release-cut.js +4 -0
- package/dist/lifecycle/release-ledger.d.ts +8 -0
- package/dist/lifecycle/release-risk.d.ts +137 -0
- package/dist/lifecycle/release-risk.js +214 -0
- package/dist/lifecycle/release-store.d.ts +9 -0
- package/dist/lifecycle/release-store.js +4 -0
- package/dist/lifecycle/stage-log.d.ts +85 -0
- package/dist/lifecycle/stage-log.js +141 -0
- package/dist/lint/canary-checks.d.ts +31 -0
- package/dist/lint/canary-checks.js +45 -0
- package/dist/lint/rule.d.ts +1 -0
- package/dist/lint/rules/evl012-pipeline-fold.d.ts +14 -0
- package/dist/lint/rules/evl012-pipeline-fold.js +30 -0
- package/dist/lint/rules/index.d.ts +1 -0
- package/dist/lint/rules/index.js +3 -0
- package/dist/notify-relay-repo.d.ts +54 -0
- package/dist/notify-relay-repo.js +84 -0
- package/dist/notify-relay.d.ts +53 -3
- package/dist/notify-relay.js +96 -3
- package/dist/notify.d.ts +57 -1
- package/dist/notify.js +7 -1
- package/dist/notify.schema.json +61 -3
- package/dist/observation.d.ts +34 -0
- package/dist/observation.js +14 -1
- package/dist/op/activities/review-agent.d.ts +39 -2
- package/dist/op/activities/review-agent.js +88 -5
- package/dist/op/agent-permit.d.ts +88 -0
- package/dist/op/agent-permit.js +97 -0
- package/dist/op/gate-approval-base.d.ts +8 -0
- package/dist/op/gate-approval-base.js +9 -0
- package/dist/op/gate-approval.d.ts +30 -1
- package/dist/op/gate-approval.js +23 -2
- package/dist/op/gate-quorum.d.ts +114 -8
- package/dist/op/gate-quorum.js +198 -21
- package/dist/op/gate-reject.d.ts +79 -0
- package/dist/op/gate-reject.js +96 -0
- package/dist/op/gate-summary.js +1 -1
- package/dist/op/gate.d.ts +28 -3
- package/dist/op/gate.js +55 -13
- package/dist/op/generate-pipeline.d.ts +15 -1
- package/dist/op/generate-pipeline.js +32 -5
- package/dist/op/index.d.ts +11 -6
- package/dist/op/index.js +10 -5
- package/dist/op/local-executor.d.ts +2 -0
- package/dist/op/local-executor.js +23 -4
- package/dist/op/op-waves-after-plan.d.ts +23 -0
- package/dist/op/op-waves-after-plan.js +12 -1
- package/dist/op/op-waves-capability-spec.d.ts +14 -0
- package/dist/op/op-waves-capability-spec.js +46 -6
- package/dist/op/op-waves-capability.d.ts +21 -13
- package/dist/op/op-waves-capability.js +22 -59
- package/dist/op/op-waves-environment-sets.d.ts +41 -0
- package/dist/op/op-waves-environment-sets.js +82 -0
- package/dist/op/op-waves-quorum-warnings.d.ts +53 -0
- package/dist/op/op-waves-quorum-warnings.js +90 -0
- package/dist/op/op-waves-release-port.d.ts +7 -0
- package/dist/op/op-waves-release-port.js +15 -3
- package/dist/op/op-waves-release.d.ts +15 -0
- package/dist/op/op-waves-release.js +15 -0
- package/dist/op/op-waves-run.d.ts +37 -3
- package/dist/op/op-waves-run.js +141 -18
- package/dist/op/op-waves-soak.d.ts +57 -0
- package/dist/op/op-waves-soak.js +111 -0
- package/dist/op/op-waves-split.d.ts +4 -0
- package/dist/op/op-waves-split.js +4 -0
- package/dist/op/op-waves.d.ts +67 -4
- package/dist/op/op-waves.js +71 -3
- package/dist/pipeline/agent-ajv.d.ts +4 -0
- package/dist/pipeline/agent-ajv.js +14 -0
- package/dist/pipeline/agent-steps.d.ts +329 -0
- package/dist/pipeline/agent-steps.js +602 -0
- package/dist/pipeline/artifacts.d.ts +264 -0
- package/dist/pipeline/artifacts.js +425 -0
- package/dist/pipeline/diff.d.ts +45 -0
- package/dist/pipeline/diff.js +177 -0
- package/dist/pipeline/fold.d.ts +43 -0
- package/dist/pipeline/fold.js +140 -0
- package/dist/pipeline/generate.d.ts +52 -0
- package/dist/pipeline/generate.js +120 -0
- package/dist/pipeline/product.d.ts +225 -0
- package/dist/pipeline/product.js +257 -0
- package/dist/pipeline/promote.d.ts +404 -0
- package/dist/pipeline/promote.js +694 -0
- package/dist/pipeline/read.d.ts +37 -0
- package/dist/pipeline/read.js +58 -0
- package/dist/pipeline/rendered.d.ts +25 -0
- package/dist/pipeline/rendered.js +53 -0
- package/dist/pipeline/soak-checks.d.ts +80 -0
- package/dist/pipeline/soak-checks.js +254 -0
- package/dist/pipeline/soak-gate.d.ts +97 -0
- package/dist/pipeline/soak-gate.js +176 -0
- package/dist/pipeline/soak-sources.d.ts +17 -0
- package/dist/pipeline/soak-sources.js +42 -0
- package/dist/pipeline/soak.d.ts +260 -0
- package/dist/pipeline/soak.js +378 -0
- package/dist/pipeline/spec.d.ts +724 -0
- package/dist/pipeline/spec.js +567 -0
- package/dist/pipeline/stage-ledger.d.ts +187 -0
- package/dist/pipeline/stage-ledger.js +185 -0
- package/dist/pipeline/stage-waves.d.ts +114 -0
- package/dist/pipeline/stage-waves.js +161 -0
- package/dist/pipeline/stages.d.ts +64 -0
- package/dist/pipeline/stages.js +174 -0
- package/dist/pipeline/verify-rollback.d.ts +277 -0
- package/dist/pipeline/verify-rollback.js +393 -0
- package/dist/pipeline.d.ts +142 -0
- package/dist/pipeline.js +143 -0
- package/dist/pr-loop.d.ts +22 -0
- package/dist/pr-loop.js +8 -0
- package/dist/pr-plan-note.d.ts +15 -1
- package/dist/pr-plan-note.js +8 -0
- package/dist/pr-post.d.ts +31 -0
- package/dist/pr-post.js +89 -0
- package/dist/release-floors.d.ts +1 -1
- package/dist/release-floors.js +1 -1
- package/dist/report-store/audit.schema.json +50 -0
- package/dist/report-store/dora.schema.json +331 -0
- package/dist/report-store/estate.schema.json +96 -0
- package/dist/report-store/run.schema.json +14 -0
- package/dist/report-store.d.ts +151 -0
- package/dist/report-store.js +344 -0
- package/dist/run-event.d.ts +7 -2
- package/dist/wave-runtime.mjs +458 -404
- package/dist/workspace/catalog-edges.js +3 -3
- package/dist/workspace/change-set.schema.json +4 -0
- package/dist/workspace/ci-cloud-identity.d.ts +4 -0
- package/dist/workspace/ci-cloud-identity.js +30 -0
- package/dist/workspace/ci-run.js +17 -2
- package/dist/workspace/ci-secrets.d.ts +3 -1
- package/dist/workspace/ci-secrets.js +7 -1
- package/dist/workspace/compose-graph.d.ts +1 -1
- package/dist/workspace/compose-graph.js +3 -1
- package/dist/workspace/declaration.d.ts +27 -0
- package/dist/workspace/declaration.js +35 -0
- package/dist/workspace/declaration.schema.json +56 -0
- package/dist/workspace/graph-cli.js +26 -0
- package/dist/workspace/graph.schema.json +5 -1
- package/dist/workspace/identity-gate-rule.d.ts +4 -0
- package/dist/workspace/identity-gate-rule.js +2 -2
- package/dist/workspace/identity-reject-rule.d.ts +14 -0
- package/dist/workspace/identity-reject-rule.js +24 -0
- package/dist/workspace/identity.d.ts +3 -0
- package/dist/workspace/identity.js +2 -1
- package/dist/workspace/nested-graph.js +2 -0
- package/dist/workspace/pr-report.schema.json +65 -0
- package/dist/workspace/promotion-order.d.ts +19 -4
- package/dist/workspace/promotion-order.js +26 -4
- package/dist/workspace/release-train.d.ts +14 -0
- package/dist/workspace/release-train.js +32 -0
- package/dist/workspace/run-event.schema.json +2 -2
- package/dist/workspace/stack-read-edges.d.ts +19 -0
- package/dist/workspace/stack-read-edges.js +54 -0
- package/dist/workspace/status-gates.d.ts +51 -1
- package/dist/workspace/status-gates.js +60 -0
- package/dist/workspace/status-stages.d.ts +223 -0
- package/dist/workspace/status-stages.js +279 -0
- package/dist/workspace/status.d.ts +45 -1
- package/dist/workspace/status.js +109 -5
- package/dist/workspace/status.schema.json +283 -2
- package/dist/workspace/train-cut.js +5 -2
- package/dist/workspace/train-shell.d.ts +18 -0
- package/dist/workspace/train-shell.js +43 -0
- package/dist/workspace/trust/seal.d.ts +7 -0
- package/dist/workspace/trust/seal.js +9 -0
- package/package.json +5 -1
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A stage's own ledger (#5355): pauses, resumes, the releases that waited
|
|
3
|
+
* while the stage was paused, and each promote that passed on the urgent
|
|
4
|
+
* rule.
|
|
5
|
+
*
|
|
6
|
+
* The lines sit in `<stage>/stage.jsonl` on `chant/lifecycle`, beside the
|
|
7
|
+
* stage's `releases.jsonl`, in the member's part of the branch. Each names
|
|
8
|
+
* the pipeline, so two pipelines of one member keep their own state.
|
|
9
|
+
*
|
|
10
|
+
* - `pause`: `chant stage pause <stage>`, or a rollback of a stage that sets
|
|
11
|
+
* `pauseAfterRollback` (`cause: "rollback"`). A paused stage refuses
|
|
12
|
+
* promotion with exit 3. A promote already applying is not stopped; it
|
|
13
|
+
* finishes and records as usual.
|
|
14
|
+
* - `waiting`: a promote the pause refused, with the release it carried.
|
|
15
|
+
* - `resume`: `chant stage resume <stage>`. It names the newest release that
|
|
16
|
+
* waited (`admits`) and the older ones it replaces (`superseded`). A
|
|
17
|
+
* promote of a superseded release is refused from then on, so the newest
|
|
18
|
+
* waiting release is the one that enters.
|
|
19
|
+
* - `urgent`: a promote that passed the stage's gate on its urgent rule, with
|
|
20
|
+
* who approved it, who promoted it, and why.
|
|
21
|
+
* - `failed` (#5328): a verify after a promote, or a check of the stage's
|
|
22
|
+
* soak, failed, with each member's state. Written by a stage whose
|
|
23
|
+
* `onVerifyFail` is `rollback`; a separate reader (an agent trigger) can
|
|
24
|
+
* read it on its own, since nothing about it names the rollback.
|
|
25
|
+
* - `rollback-requested` (#5328): the rollback to the stage's previous
|
|
26
|
+
* release that a `failed` line asks for, and the members it restores. It
|
|
27
|
+
* waits at gate `<stage>-rollback` until a person approves it.
|
|
28
|
+
* - `rollback-held` (#5328): a `failed` line for which no rollback could be
|
|
29
|
+
* requested, and why: no earlier release, or one that is revoked.
|
|
30
|
+
* - `rolled-back` (#5328): the requested rollback ran, linked to its request
|
|
31
|
+
* and its failure, with who approved it.
|
|
32
|
+
*
|
|
33
|
+
* Every line records who wrote it (`by`) and, where one was given, why
|
|
34
|
+
* (`reason`).
|
|
35
|
+
*/
|
|
36
|
+
import type { ReleaseRecord } from "../lifecycle/release-ledger.js";
|
|
37
|
+
import type { DeployOutcome } from "../lifecycle/deploy-outcome.js";
|
|
38
|
+
/** The file a stage's lines are kept in, under the stage's directory on `chant/lifecycle`. */
|
|
39
|
+
export declare const STAGE_LEDGER_FILE = "stage.jsonl";
|
|
40
|
+
/** A release a line names: its digest and label. */
|
|
41
|
+
export interface StageRelease {
|
|
42
|
+
digest: string;
|
|
43
|
+
label: string | null;
|
|
44
|
+
}
|
|
45
|
+
/** The kinds of line a stage's ledger holds. */
|
|
46
|
+
export declare const STAGE_LINE_KINDS: readonly ["pause", "resume", "waiting", "urgent", "failed", "rollback-requested", "rollback-held", "rolled-back"];
|
|
47
|
+
export type StageLineKind = (typeof STAGE_LINE_KINDS)[number];
|
|
48
|
+
/**
|
|
49
|
+
* What a run left one member (a component) of a stage in (#5328):
|
|
50
|
+
*
|
|
51
|
+
* - `applied`: it deployed, and the release ledger records it;
|
|
52
|
+
* - `left-applied`: it failed after a step changed something that its
|
|
53
|
+
* capability does not undo (`rollback-opted-out`), so the change stays;
|
|
54
|
+
* - `rolled-back`: it failed, and each step that ran was undone;
|
|
55
|
+
* - `not-applied`: nothing of it ran, or it stopped at a gate.
|
|
56
|
+
*/
|
|
57
|
+
export type StageMemberStateName = "applied" | "left-applied" | "rolled-back" | "not-applied";
|
|
58
|
+
/** One member's state on a `failed` line, and on a rollback request whether it is rolled back. */
|
|
59
|
+
export interface StageMemberState {
|
|
60
|
+
member: string;
|
|
61
|
+
state: StageMemberStateName;
|
|
62
|
+
/** On a request: whether the rollback restores it, and why not when it does not. */
|
|
63
|
+
rollback?: "requested" | string;
|
|
64
|
+
}
|
|
65
|
+
/** One line of a stage's ledger. */
|
|
66
|
+
export interface StagePauseLine {
|
|
67
|
+
version: 1;
|
|
68
|
+
kind: StageLineKind;
|
|
69
|
+
pipeline: string;
|
|
70
|
+
stage: string;
|
|
71
|
+
/** Who wrote it: the person who paused or resumed, or the promote's actor. */
|
|
72
|
+
by: string;
|
|
73
|
+
/** Why, as the person gave it. */
|
|
74
|
+
reason?: string;
|
|
75
|
+
timestamp: string;
|
|
76
|
+
/** On a pause a rollback wrote. */
|
|
77
|
+
cause?: "rollback";
|
|
78
|
+
/** On `waiting` and `urgent`, the release promoted; on a pause after a rollback, the release rolled back to. */
|
|
79
|
+
release?: StageRelease;
|
|
80
|
+
/** On `resume`: the newest release that waited while the stage was paused. */
|
|
81
|
+
admits?: StageRelease;
|
|
82
|
+
/** On `resume`: the digests of the older releases that waited, which no longer enter. */
|
|
83
|
+
superseded?: string[];
|
|
84
|
+
/** On `urgent`: the approval the urgent rule passed on. On `rolled-back` (#5328): the approval of the rollback gate, with no role. */
|
|
85
|
+
approval?: {
|
|
86
|
+
by: string;
|
|
87
|
+
at: string;
|
|
88
|
+
role?: string;
|
|
89
|
+
note?: string;
|
|
90
|
+
};
|
|
91
|
+
/** On `failed` and `rollback-requested` (#5328): the line's own id, which later lines link to. */
|
|
92
|
+
id?: string;
|
|
93
|
+
/** On `failed` (#5328): what failed, a verify after a promote or a check of the stage's soak. */
|
|
94
|
+
failure?: "verify" | "soak";
|
|
95
|
+
/** On `failed` (#5328): the release that failed in the stage, or the promotion's digest when it named none. */
|
|
96
|
+
failed?: StageRelease;
|
|
97
|
+
/** On `failed`: each member's state. On `rollback-requested`: each member, and whether the rollback restores it. On `rolled-back`: the members restored. */
|
|
98
|
+
members?: StageMemberState[];
|
|
99
|
+
/** On `failed` (#5328): what the failure said, one line each. */
|
|
100
|
+
detail?: string[];
|
|
101
|
+
/** On `rollback-requested`, `rollback-held` and `rolled-back` (#5328): the id of the `failed` line it answers. */
|
|
102
|
+
failureId?: string;
|
|
103
|
+
/** On `rolled-back` (#5328): the id of the request it carried out. */
|
|
104
|
+
requestId?: string;
|
|
105
|
+
/** On `rollback-requested` and `rolled-back` (#5328): the gate the rollback passes, under the pipeline's op. */
|
|
106
|
+
gate?: string;
|
|
107
|
+
/** On `rollback-held` (#5328): why no rollback was requested. */
|
|
108
|
+
held?: string;
|
|
109
|
+
}
|
|
110
|
+
/** Reads and appends a stage's lines. */
|
|
111
|
+
export interface StageLedgerPort {
|
|
112
|
+
/** The stage's lines for `pipeline`, oldest first. */
|
|
113
|
+
read(pipeline: string, stage: string): Promise<StagePauseLine[]>;
|
|
114
|
+
append(line: StagePauseLine): Promise<{
|
|
115
|
+
pushed: boolean;
|
|
116
|
+
pushWarning?: string;
|
|
117
|
+
}>;
|
|
118
|
+
}
|
|
119
|
+
/** Parse a stage ledger's text: the lines that read, and how many did not. */
|
|
120
|
+
export declare function parseStagePauseLines(text: string | null): {
|
|
121
|
+
lines: StagePauseLine[];
|
|
122
|
+
malformed: number;
|
|
123
|
+
};
|
|
124
|
+
/** A ledger held in memory, for tests and for a caller that read the lines already. */
|
|
125
|
+
export declare function memoryStageLedgerPort(seed?: StagePauseLine[]): StageLedgerPort & {
|
|
126
|
+
lines: StagePauseLine[];
|
|
127
|
+
};
|
|
128
|
+
/** The real port: `<stage>/stage.jsonl` on `chant/lifecycle`, appended with the ledger's retry and pushed. */
|
|
129
|
+
export declare function gitStageLedgerPort(opts?: {
|
|
130
|
+
cwd?: string;
|
|
131
|
+
}): StageLedgerPort;
|
|
132
|
+
/** The pause standing on the stage, or undefined when it is not paused: the newest pause or resume line decides. */
|
|
133
|
+
export declare function stagePaused(lines: readonly StagePauseLine[]): StagePauseLine | undefined;
|
|
134
|
+
/** The line a paused stage's refusal prints. */
|
|
135
|
+
export declare function stagePausedLine(pause: StagePauseLine): string;
|
|
136
|
+
/** The releases that waited since the standing pause, oldest first, each once at its newest wait. */
|
|
137
|
+
export declare function waitingReleases(lines: readonly StagePauseLine[]): StageRelease[];
|
|
138
|
+
/** The pause line for `chant stage pause`, or a refusal when the stage is paused already. */
|
|
139
|
+
export declare function pauseLine(input: {
|
|
140
|
+
pipeline: string;
|
|
141
|
+
stage: string;
|
|
142
|
+
by: string;
|
|
143
|
+
reason?: string;
|
|
144
|
+
lines: readonly StagePauseLine[];
|
|
145
|
+
now: Date;
|
|
146
|
+
cause?: "rollback";
|
|
147
|
+
release?: StageRelease;
|
|
148
|
+
}): StagePauseLine | {
|
|
149
|
+
refused: string;
|
|
150
|
+
};
|
|
151
|
+
/** The resume line for `chant stage resume`: the newest waiting release enters, the older ones are superseded. A refusal when the stage is not paused. */
|
|
152
|
+
export declare function resumeLine(input: {
|
|
153
|
+
pipeline: string;
|
|
154
|
+
stage: string;
|
|
155
|
+
by: string;
|
|
156
|
+
reason?: string;
|
|
157
|
+
lines: readonly StagePauseLine[];
|
|
158
|
+
now: Date;
|
|
159
|
+
}): StagePauseLine | {
|
|
160
|
+
refused: string;
|
|
161
|
+
};
|
|
162
|
+
/** The line a promote the pause refused records. */
|
|
163
|
+
export declare function waitingLine(input: {
|
|
164
|
+
pipeline: string;
|
|
165
|
+
stage: string;
|
|
166
|
+
by: string;
|
|
167
|
+
release: StageRelease;
|
|
168
|
+
now: Date;
|
|
169
|
+
}): StagePauseLine;
|
|
170
|
+
/**
|
|
171
|
+
* The resume that superseded `digest`, when the stage's newest resume names
|
|
172
|
+
* it among the releases that waited behind a newer one; undefined otherwise.
|
|
173
|
+
*/
|
|
174
|
+
export declare function supersededBy(lines: readonly StagePauseLine[], digest: string): StagePauseLine | undefined;
|
|
175
|
+
/**
|
|
176
|
+
* The components of `components` that release `releaseDigest` (cut from
|
|
177
|
+
* `commit`) has not deployed in a stage, by its release ledger and deploy
|
|
178
|
+
* outcomes: each needs a record of the release (or of its commit), and no
|
|
179
|
+
* failed or gated run of it since. Empty when the release succeeded there.
|
|
180
|
+
*/
|
|
181
|
+
export declare function releaseMissingIn(input: {
|
|
182
|
+
records: readonly ReleaseRecord[];
|
|
183
|
+
outcomes: readonly DeployOutcome[];
|
|
184
|
+
releaseDigest: string;
|
|
185
|
+
commit?: string;
|
|
186
|
+
components: readonly string[];
|
|
187
|
+
}): string[];
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A stage's own ledger (#5355): pauses, resumes, the releases that waited
|
|
3
|
+
* while the stage was paused, and each promote that passed on the urgent
|
|
4
|
+
* rule.
|
|
5
|
+
*
|
|
6
|
+
* The lines sit in `<stage>/stage.jsonl` on `chant/lifecycle`, beside the
|
|
7
|
+
* stage's `releases.jsonl`, in the member's part of the branch. Each names
|
|
8
|
+
* the pipeline, so two pipelines of one member keep their own state.
|
|
9
|
+
*
|
|
10
|
+
* - `pause`: `chant stage pause <stage>`, or a rollback of a stage that sets
|
|
11
|
+
* `pauseAfterRollback` (`cause: "rollback"`). A paused stage refuses
|
|
12
|
+
* promotion with exit 3. A promote already applying is not stopped; it
|
|
13
|
+
* finishes and records as usual.
|
|
14
|
+
* - `waiting`: a promote the pause refused, with the release it carried.
|
|
15
|
+
* - `resume`: `chant stage resume <stage>`. It names the newest release that
|
|
16
|
+
* waited (`admits`) and the older ones it replaces (`superseded`). A
|
|
17
|
+
* promote of a superseded release is refused from then on, so the newest
|
|
18
|
+
* waiting release is the one that enters.
|
|
19
|
+
* - `urgent`: a promote that passed the stage's gate on its urgent rule, with
|
|
20
|
+
* who approved it, who promoted it, and why.
|
|
21
|
+
* - `failed` (#5328): a verify after a promote, or a check of the stage's
|
|
22
|
+
* soak, failed, with each member's state. Written by a stage whose
|
|
23
|
+
* `onVerifyFail` is `rollback`; a separate reader (an agent trigger) can
|
|
24
|
+
* read it on its own, since nothing about it names the rollback.
|
|
25
|
+
* - `rollback-requested` (#5328): the rollback to the stage's previous
|
|
26
|
+
* release that a `failed` line asks for, and the members it restores. It
|
|
27
|
+
* waits at gate `<stage>-rollback` until a person approves it.
|
|
28
|
+
* - `rollback-held` (#5328): a `failed` line for which no rollback could be
|
|
29
|
+
* requested, and why: no earlier release, or one that is revoked.
|
|
30
|
+
* - `rolled-back` (#5328): the requested rollback ran, linked to its request
|
|
31
|
+
* and its failure, with who approved it.
|
|
32
|
+
*
|
|
33
|
+
* Every line records who wrote it (`by`) and, where one was given, why
|
|
34
|
+
* (`reason`).
|
|
35
|
+
*/
|
|
36
|
+
import { unsettledComponents } from "../lifecycle/mixed-environment.js";
|
|
37
|
+
/** The file a stage's lines are kept in, under the stage's directory on `chant/lifecycle`. */
|
|
38
|
+
export const STAGE_LEDGER_FILE = "stage.jsonl";
|
|
39
|
+
/** The kinds of line a stage's ledger holds. */
|
|
40
|
+
export const STAGE_LINE_KINDS = ["pause", "resume", "waiting", "urgent", "failed", "rollback-requested", "rollback-held", "rolled-back"];
|
|
41
|
+
/** Parse a stage ledger's text: the lines that read, and how many did not. */
|
|
42
|
+
export function parseStagePauseLines(text) {
|
|
43
|
+
const lines = [];
|
|
44
|
+
let malformed = 0;
|
|
45
|
+
for (const raw of (text ?? "").split("\n")) {
|
|
46
|
+
if (raw.trim() === "")
|
|
47
|
+
continue;
|
|
48
|
+
try {
|
|
49
|
+
const v = JSON.parse(raw);
|
|
50
|
+
if (v && v.version === 1 && typeof v.pipeline === "string" && typeof v.stage === "string" && typeof v.by === "string" && typeof v.timestamp === "string" && STAGE_LINE_KINDS.includes(v.kind))
|
|
51
|
+
lines.push(v);
|
|
52
|
+
else
|
|
53
|
+
malformed++;
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
malformed++;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
return { lines, malformed };
|
|
60
|
+
}
|
|
61
|
+
/** A ledger held in memory, for tests and for a caller that read the lines already. */
|
|
62
|
+
export function memoryStageLedgerPort(seed = []) {
|
|
63
|
+
const lines = [...seed];
|
|
64
|
+
return {
|
|
65
|
+
lines,
|
|
66
|
+
async read(pipeline, stage) {
|
|
67
|
+
return lines.filter((l) => l.pipeline === pipeline && l.stage === stage);
|
|
68
|
+
},
|
|
69
|
+
async append(line) {
|
|
70
|
+
lines.push(line);
|
|
71
|
+
return { pushed: true };
|
|
72
|
+
},
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
/** The real port: `<stage>/stage.jsonl` on `chant/lifecycle`, appended with the ledger's retry and pushed. */
|
|
76
|
+
export function gitStageLedgerPort(opts) {
|
|
77
|
+
return {
|
|
78
|
+
async read(pipeline, stage) {
|
|
79
|
+
const { readBlobFromPath } = await import("../lifecycle/git.js");
|
|
80
|
+
return parseStagePauseLines(await readBlobFromPath(stage, STAGE_LEDGER_FILE, opts)).lines.filter((l) => l.pipeline === pipeline && l.stage === stage);
|
|
81
|
+
},
|
|
82
|
+
async append(line) {
|
|
83
|
+
const { appendLedgerLine, pushLifecycleRebasing, LifecyclePushLostError } = await import("../lifecycle/git.js");
|
|
84
|
+
const { sortedJsonReplacer } = await import("../utils.js");
|
|
85
|
+
await appendLedgerLine(line.stage, STAGE_LEDGER_FILE, JSON.stringify(line, sortedJsonReplacer), `Stage ${line.kind}: ${line.pipeline} ${line.stage}`, opts);
|
|
86
|
+
try {
|
|
87
|
+
return await pushLifecycleRebasing(opts);
|
|
88
|
+
}
|
|
89
|
+
catch (err) {
|
|
90
|
+
if (err instanceof LifecyclePushLostError)
|
|
91
|
+
return { pushed: false, pushWarning: err.message };
|
|
92
|
+
throw err;
|
|
93
|
+
}
|
|
94
|
+
},
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
/** The pause standing on the stage, or undefined when it is not paused: the newest pause or resume line decides. */
|
|
98
|
+
export function stagePaused(lines) {
|
|
99
|
+
const last = [...lines].reverse().find((l) => l.kind === "pause" || l.kind === "resume");
|
|
100
|
+
return last?.kind === "pause" ? last : undefined;
|
|
101
|
+
}
|
|
102
|
+
/** The line a paused stage's refusal prints. */
|
|
103
|
+
export function stagePausedLine(pause) {
|
|
104
|
+
const why = pause.cause === "rollback" ? `after a rollback${pause.release ? ` to ${pause.release.label ?? pause.release.digest}` : ""}` : "";
|
|
105
|
+
const parts = [why, pause.reason ? pause.reason : ""].filter(Boolean).join(": ");
|
|
106
|
+
return `stage "${pause.stage}" is paused since ${pause.timestamp} by ${pause.by}${parts ? ` (${parts})` : ""}, so nothing is promoted into it`;
|
|
107
|
+
}
|
|
108
|
+
/** The releases that waited since the standing pause, oldest first, each once at its newest wait. */
|
|
109
|
+
export function waitingReleases(lines) {
|
|
110
|
+
const pause = stagePaused(lines);
|
|
111
|
+
if (!pause)
|
|
112
|
+
return [];
|
|
113
|
+
const since = lines.lastIndexOf(pause);
|
|
114
|
+
const out = [];
|
|
115
|
+
for (const l of lines.slice(since + 1)) {
|
|
116
|
+
if (l.kind !== "waiting" || !l.release)
|
|
117
|
+
continue;
|
|
118
|
+
const at = out.findIndex((r) => r.digest === l.release.digest);
|
|
119
|
+
if (at >= 0)
|
|
120
|
+
out.splice(at, 1);
|
|
121
|
+
out.push(l.release);
|
|
122
|
+
}
|
|
123
|
+
return out;
|
|
124
|
+
}
|
|
125
|
+
/** The pause line for `chant stage pause`, or a refusal when the stage is paused already. */
|
|
126
|
+
export function pauseLine(input) {
|
|
127
|
+
const standing = stagePaused(input.lines);
|
|
128
|
+
if (standing)
|
|
129
|
+
return { refused: `${stagePausedLine(standing)}; it is paused already` };
|
|
130
|
+
return {
|
|
131
|
+
version: 1,
|
|
132
|
+
kind: "pause",
|
|
133
|
+
pipeline: input.pipeline,
|
|
134
|
+
stage: input.stage,
|
|
135
|
+
by: input.by,
|
|
136
|
+
...(input.reason ? { reason: input.reason } : {}),
|
|
137
|
+
timestamp: input.now.toISOString(),
|
|
138
|
+
...(input.cause ? { cause: input.cause } : {}),
|
|
139
|
+
...(input.release ? { release: input.release } : {}),
|
|
140
|
+
};
|
|
141
|
+
}
|
|
142
|
+
/** The resume line for `chant stage resume`: the newest waiting release enters, the older ones are superseded. A refusal when the stage is not paused. */
|
|
143
|
+
export function resumeLine(input) {
|
|
144
|
+
if (!stagePaused(input.lines))
|
|
145
|
+
return { refused: `stage "${input.stage}" is not paused` };
|
|
146
|
+
const waited = waitingReleases(input.lines);
|
|
147
|
+
const admits = waited[waited.length - 1];
|
|
148
|
+
const superseded = waited.slice(0, -1).map((r) => r.digest);
|
|
149
|
+
return {
|
|
150
|
+
version: 1,
|
|
151
|
+
kind: "resume",
|
|
152
|
+
pipeline: input.pipeline,
|
|
153
|
+
stage: input.stage,
|
|
154
|
+
by: input.by,
|
|
155
|
+
...(input.reason ? { reason: input.reason } : {}),
|
|
156
|
+
timestamp: input.now.toISOString(),
|
|
157
|
+
...(admits ? { admits } : {}),
|
|
158
|
+
...(superseded.length > 0 ? { superseded } : {}),
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
/** The line a promote the pause refused records. */
|
|
162
|
+
export function waitingLine(input) {
|
|
163
|
+
return { version: 1, kind: "waiting", pipeline: input.pipeline, stage: input.stage, by: input.by, timestamp: input.now.toISOString(), release: input.release };
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* The resume that superseded `digest`, when the stage's newest resume names
|
|
167
|
+
* it among the releases that waited behind a newer one; undefined otherwise.
|
|
168
|
+
*/
|
|
169
|
+
export function supersededBy(lines, digest) {
|
|
170
|
+
const last = [...lines].reverse().find((l) => l.kind === "pause" || l.kind === "resume");
|
|
171
|
+
return last?.kind === "resume" && last.superseded?.includes(digest) ? last : undefined;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* The components of `components` that release `releaseDigest` (cut from
|
|
175
|
+
* `commit`) has not deployed in a stage, by its release ledger and deploy
|
|
176
|
+
* outcomes: each needs a record of the release (or of its commit), and no
|
|
177
|
+
* failed or gated run of it since. Empty when the release succeeded there.
|
|
178
|
+
*/
|
|
179
|
+
export function releaseMissingIn(input) {
|
|
180
|
+
const unsettled = unsettledComponents(input.records, input.outcomes);
|
|
181
|
+
return input.components.filter((component) => {
|
|
182
|
+
const ran = input.records.filter((r) => r.component === component && (r.releaseDigest === input.releaseDigest || (input.commit !== undefined && r.gitSha === input.commit)));
|
|
183
|
+
return ran.length === 0 || unsettled.has(component);
|
|
184
|
+
});
|
|
185
|
+
}
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A stage's op waves, run by `chant components promote` (#5427).
|
|
3
|
+
*
|
|
4
|
+
* A member whose stages apply through a `step` and that declares no
|
|
5
|
+
* components (a yodel project's `sql-migrate`) has nothing for the
|
|
6
|
+
* component driver to deploy. Its promote runs the stage's op waves
|
|
7
|
+
* instead, once the stage's pause, rejections, soaks, agent steps and gate
|
|
8
|
+
* let the release in, as `chant run wave` runs them in a wave job:
|
|
9
|
+
*
|
|
10
|
+
* - The spec is the stage's, `stageWavesSpec` of the pipeline folded at the
|
|
11
|
+
* default branch, written over the stage's rendered spec file
|
|
12
|
+
* (`pipelineStageSpecFile`, the file a wave job of `chant pipeline
|
|
13
|
+
* generate` writes with `pipeline spec --stage`). A step input named
|
|
14
|
+
* `spec` names that file ({@link stageRunSpec}), so an engine that reads
|
|
15
|
+
* chant's decision by its spec file (`sql-migrate`) reads this stage's.
|
|
16
|
+
* - Each wave's gate, approval mode, holds and hooks are read at the
|
|
17
|
+
* default branch's commit from the same fold ({@link pipelineStageShow}),
|
|
18
|
+
* so the gate is the one the merged pipeline declares. A wave plans,
|
|
19
|
+
* decides its own gate on its plan digest and applies the plan it
|
|
20
|
+
* decided; one that waits stops the promote with exit 3, and the same
|
|
21
|
+
* promote carries on once it is approved.
|
|
22
|
+
* - The waves run in order in the one job, and the first that does not end
|
|
23
|
+
* with exit 0 ends the promote with its exit code.
|
|
24
|
+
* - The release records the step writes name the release promoted, with the
|
|
25
|
+
* step's plan digest, so later stages find the release applied here.
|
|
26
|
+
*
|
|
27
|
+
* The stand-down for a newer commit is off: a promote takes a release, not
|
|
28
|
+
* the branch's tip.
|
|
29
|
+
*/
|
|
30
|
+
import type { OpWavesSpec } from "../op/op-waves.js";
|
|
31
|
+
import type { OpWaveShowAtBase, RunOpWaveOptions, RunOpWaveResult } from "../op/op-waves-run.js";
|
|
32
|
+
import type { ReleaseRecord } from "../lifecycle/release-ledger.js";
|
|
33
|
+
import { type PipelineShow } from "./read.js";
|
|
34
|
+
import { type PipelineSpec } from "./spec.js";
|
|
35
|
+
/**
|
|
36
|
+
* The first chant whose `components promote` runs a stage's op waves for a
|
|
37
|
+
* member that declares no components (#5427): the stage's spec written to
|
|
38
|
+
* its rendered spec file with a step's `spec` input naming it, each wave's
|
|
39
|
+
* gate read from the pipeline at the default branch, release records under
|
|
40
|
+
* the release promoted, `pipelineStageShow` for an engine that reads a
|
|
41
|
+
* stage's gate at base, a stage's records under the pipeline's component
|
|
42
|
+
* when its targets name environments, and `idTokens` on a promote job
|
|
43
|
+
* (`PipelinePromoteStageInputs`). A product feature-detects the promote of
|
|
44
|
+
* its stages on this name.
|
|
45
|
+
*/
|
|
46
|
+
export declare const PROMOTE_STAGE_WAVES_FLOOR = "0.124.110";
|
|
47
|
+
/** Whether stage `stage` of the pipeline applies through a `step`, so a member with no components promotes into it by its op waves. */
|
|
48
|
+
export declare function stageRunsWaves(spec: PipelineSpec, stage: string): boolean;
|
|
49
|
+
/**
|
|
50
|
+
* The op-waves spec a promote runs for `stage`: `stageWavesSpec`, with a
|
|
51
|
+
* step input `spec` set to the stage's rendered spec file, the file the
|
|
52
|
+
* promote writes it to. A step without that input is left as it is.
|
|
53
|
+
*/
|
|
54
|
+
export declare function stageRunSpec(spec: PipelineSpec, stage: string): OpWavesSpec;
|
|
55
|
+
/**
|
|
56
|
+
* An `OpWaveShowAtBase` that reads a stage's rendered spec file
|
|
57
|
+
* (`.chant/op-waves/<pipeline>-<stage>.spec.json`) at a commit from the
|
|
58
|
+
* pipeline folded there: {@link stageRunSpec} of the stage whose file it
|
|
59
|
+
* is. A commit whose pipeline is absent, does not fold, or has no such stage
|
|
60
|
+
* reads as a spec absent at base, so every wave's gate is `always`. Every
|
|
61
|
+
* other file is read through `fallback`, which also resolves the commit.
|
|
62
|
+
*
|
|
63
|
+
* `readOpWavePolicy(specFile, wave, base, cwd, pipelineStageShow())` is how
|
|
64
|
+
* an engine that checks chant's decision again (`sql-migrate`) reads a
|
|
65
|
+
* stage's gate at base.
|
|
66
|
+
*/
|
|
67
|
+
export declare function pipelineStageShow(fallback?: OpWaveShowAtBase, show?: PipelineShow): OpWaveShowAtBase;
|
|
68
|
+
/**
|
|
69
|
+
* What stage `stage` applied of a release (#5427), for a soak's clock: the
|
|
70
|
+
* newest record of each component on its ledger that names the release, or
|
|
71
|
+
* that was applied at the commit the release was cut from (the first
|
|
72
|
+
* stage's apply, recorded before the cut).
|
|
73
|
+
*/
|
|
74
|
+
export declare function stageReleaseItems(records: readonly ReleaseRecord[], stage: string, release: {
|
|
75
|
+
releaseDigest: string;
|
|
76
|
+
commit: string;
|
|
77
|
+
}): Array<{
|
|
78
|
+
component: string;
|
|
79
|
+
digest: string;
|
|
80
|
+
source: ReleaseRecord;
|
|
81
|
+
}>;
|
|
82
|
+
/** One wave a promote ran (#5427). */
|
|
83
|
+
export interface StageWaveRan {
|
|
84
|
+
wave: number;
|
|
85
|
+
name: string;
|
|
86
|
+
result: RunOpWaveResult;
|
|
87
|
+
}
|
|
88
|
+
/** What {@link runStageWaves} did: the spec file it wrote, each wave it ran, and the exit code of the first that did not end with 0, else 0. */
|
|
89
|
+
export interface StageWavesRun {
|
|
90
|
+
specFile: string;
|
|
91
|
+
spec: OpWavesSpec;
|
|
92
|
+
waves: StageWaveRan[];
|
|
93
|
+
exitCode: number;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Run stage `stage`'s op waves for a release (#5427), in order, through
|
|
97
|
+
* `run` (`runOpWave`), as a wave job of the stage would. `spec` is the
|
|
98
|
+
* pipeline folded at `base`, the default branch's commit. Call it only once
|
|
99
|
+
* the stage's gate passed. `options` are the runner's seams (the gate
|
|
100
|
+
* ledger, the capabilities, the release port); `afterWave` is told how each
|
|
101
|
+
* wave ended, as `chant run wave` tells the spec's notify.
|
|
102
|
+
*/
|
|
103
|
+
export declare function runStageWaves(input: {
|
|
104
|
+
spec: PipelineSpec;
|
|
105
|
+
stage: string;
|
|
106
|
+
base: string;
|
|
107
|
+
cwd: string;
|
|
108
|
+
release: {
|
|
109
|
+
releaseDigest: string;
|
|
110
|
+
};
|
|
111
|
+
options?: Omit<Partial<RunOpWaveOptions>, "spec" | "specFile" | "wave" | "base" | "cwd">;
|
|
112
|
+
run?: (options: RunOpWaveOptions) => Promise<RunOpWaveResult>;
|
|
113
|
+
afterWave?: (ran: StageWaveRan, spec: OpWavesSpec) => Promise<void>;
|
|
114
|
+
}): Promise<StageWavesRun>;
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A stage's op waves, run by `chant components promote` (#5427).
|
|
3
|
+
*
|
|
4
|
+
* A member whose stages apply through a `step` and that declares no
|
|
5
|
+
* components (a yodel project's `sql-migrate`) has nothing for the
|
|
6
|
+
* component driver to deploy. Its promote runs the stage's op waves
|
|
7
|
+
* instead, once the stage's pause, rejections, soaks, agent steps and gate
|
|
8
|
+
* let the release in, as `chant run wave` runs them in a wave job:
|
|
9
|
+
*
|
|
10
|
+
* - The spec is the stage's, `stageWavesSpec` of the pipeline folded at the
|
|
11
|
+
* default branch, written over the stage's rendered spec file
|
|
12
|
+
* (`pipelineStageSpecFile`, the file a wave job of `chant pipeline
|
|
13
|
+
* generate` writes with `pipeline spec --stage`). A step input named
|
|
14
|
+
* `spec` names that file ({@link stageRunSpec}), so an engine that reads
|
|
15
|
+
* chant's decision by its spec file (`sql-migrate`) reads this stage's.
|
|
16
|
+
* - Each wave's gate, approval mode, holds and hooks are read at the
|
|
17
|
+
* default branch's commit from the same fold ({@link pipelineStageShow}),
|
|
18
|
+
* so the gate is the one the merged pipeline declares. A wave plans,
|
|
19
|
+
* decides its own gate on its plan digest and applies the plan it
|
|
20
|
+
* decided; one that waits stops the promote with exit 3, and the same
|
|
21
|
+
* promote carries on once it is approved.
|
|
22
|
+
* - The waves run in order in the one job, and the first that does not end
|
|
23
|
+
* with exit 0 ends the promote with its exit code.
|
|
24
|
+
* - The release records the step writes name the release promoted, with the
|
|
25
|
+
* step's plan digest, so later stages find the release applied here.
|
|
26
|
+
*
|
|
27
|
+
* The stand-down for a newer commit is off: a promote takes a release, not
|
|
28
|
+
* the branch's tip.
|
|
29
|
+
*/
|
|
30
|
+
import { execFileSync } from "node:child_process";
|
|
31
|
+
import { mkdirSync, writeFileSync } from "node:fs";
|
|
32
|
+
import { dirname, isAbsolute, join, posix } from "node:path";
|
|
33
|
+
import { pipelineStageSpecFile } from "./generate.js";
|
|
34
|
+
import { gitShowPipeline, readPipelineAt } from "./read.js";
|
|
35
|
+
import { PIPELINE_FILE } from "./spec.js";
|
|
36
|
+
import { pipelineStage, stageWavesSpec } from "./stages.js";
|
|
37
|
+
/**
|
|
38
|
+
* The first chant whose `components promote` runs a stage's op waves for a
|
|
39
|
+
* member that declares no components (#5427): the stage's spec written to
|
|
40
|
+
* its rendered spec file with a step's `spec` input naming it, each wave's
|
|
41
|
+
* gate read from the pipeline at the default branch, release records under
|
|
42
|
+
* the release promoted, `pipelineStageShow` for an engine that reads a
|
|
43
|
+
* stage's gate at base, a stage's records under the pipeline's component
|
|
44
|
+
* when its targets name environments, and `idTokens` on a promote job
|
|
45
|
+
* (`PipelinePromoteStageInputs`). A product feature-detects the promote of
|
|
46
|
+
* its stages on this name.
|
|
47
|
+
*/
|
|
48
|
+
export const PROMOTE_STAGE_WAVES_FLOOR = "0.124.110";
|
|
49
|
+
/** Whether stage `stage` of the pipeline applies through a `step`, so a member with no components promotes into it by its op waves. */
|
|
50
|
+
export function stageRunsWaves(spec, stage) {
|
|
51
|
+
return pipelineStage(spec, stage) !== undefined && spec.defaults?.step !== undefined;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The op-waves spec a promote runs for `stage`: `stageWavesSpec`, with a
|
|
55
|
+
* step input `spec` set to the stage's rendered spec file, the file the
|
|
56
|
+
* promote writes it to. A step without that input is left as it is.
|
|
57
|
+
*/
|
|
58
|
+
export function stageRunSpec(spec, stage) {
|
|
59
|
+
const out = stageWavesSpec(spec, stage);
|
|
60
|
+
if (!out.step || typeof out.step.spec !== "string")
|
|
61
|
+
return out;
|
|
62
|
+
return { ...out, step: { ...out.step, spec: pipelineStageSpecFile(spec, stage) } };
|
|
63
|
+
}
|
|
64
|
+
const STAGE_SPEC_FILE = /^\.chant\/op-waves\/[^/]+\.spec\.json$/;
|
|
65
|
+
const posixPath = (p) => p.replace(/^\.\//, "").split("\\").join(posix.sep);
|
|
66
|
+
/** `git show <base>:<path>` in `cwd`, with the commit resolved; text null when the commit has no such file. */
|
|
67
|
+
const gitShowFile = (base, path, cwd) => {
|
|
68
|
+
let sha;
|
|
69
|
+
try {
|
|
70
|
+
sha = execFileSync("git", ["rev-parse", "--verify", `${base}^{commit}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
|
|
71
|
+
}
|
|
72
|
+
catch {
|
|
73
|
+
throw new Error(`the gate policy is read at ${base}, which this checkout does not have. Check out the full history (fetch-depth: 0 on GitHub and Forgejo, GIT_DEPTH: "0" on GitLab).`);
|
|
74
|
+
}
|
|
75
|
+
try {
|
|
76
|
+
return { sha, text: execFileSync("git", ["show", `${sha}:./${path}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }) };
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
return { sha, text: null };
|
|
80
|
+
}
|
|
81
|
+
};
|
|
82
|
+
/**
|
|
83
|
+
* An `OpWaveShowAtBase` that reads a stage's rendered spec file
|
|
84
|
+
* (`.chant/op-waves/<pipeline>-<stage>.spec.json`) at a commit from the
|
|
85
|
+
* pipeline folded there: {@link stageRunSpec} of the stage whose file it
|
|
86
|
+
* is. A commit whose pipeline is absent, does not fold, or has no such stage
|
|
87
|
+
* reads as a spec absent at base, so every wave's gate is `always`. Every
|
|
88
|
+
* other file is read through `fallback`, which also resolves the commit.
|
|
89
|
+
*
|
|
90
|
+
* `readOpWavePolicy(specFile, wave, base, cwd, pipelineStageShow())` is how
|
|
91
|
+
* an engine that checks chant's decision again (`sql-migrate`) reads a
|
|
92
|
+
* stage's gate at base.
|
|
93
|
+
*/
|
|
94
|
+
export function pipelineStageShow(fallback = gitShowFile, show = gitShowPipeline) {
|
|
95
|
+
return (base, path, cwd) => {
|
|
96
|
+
const file = posixPath(path);
|
|
97
|
+
if (!STAGE_SPEC_FILE.test(file))
|
|
98
|
+
return fallback(base, path, cwd);
|
|
99
|
+
const { sha } = fallback(base, PIPELINE_FILE, cwd);
|
|
100
|
+
const read = readPipelineAt(sha, cwd, show);
|
|
101
|
+
if (read.status !== "folded")
|
|
102
|
+
return { sha, text: null };
|
|
103
|
+
const stage = read.spec.stages.find((s) => pipelineStageSpecFile(read.spec, s.name) === file);
|
|
104
|
+
return { sha, text: stage ? `${JSON.stringify(stageRunSpec(read.spec, stage.name), null, 2)}\n` : null };
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* What stage `stage` applied of a release (#5427), for a soak's clock: the
|
|
109
|
+
* newest record of each component on its ledger that names the release, or
|
|
110
|
+
* that was applied at the commit the release was cut from (the first
|
|
111
|
+
* stage's apply, recorded before the cut).
|
|
112
|
+
*/
|
|
113
|
+
export function stageReleaseItems(records, stage, release) {
|
|
114
|
+
const newest = new Map();
|
|
115
|
+
for (const r of records) {
|
|
116
|
+
if (r.env !== stage || (r.releaseDigest !== release.releaseDigest && r.gitSha !== release.commit))
|
|
117
|
+
continue;
|
|
118
|
+
const prior = newest.get(r.component);
|
|
119
|
+
if (!prior || Date.parse(r.timestamp) >= Date.parse(prior.timestamp))
|
|
120
|
+
newest.set(r.component, r);
|
|
121
|
+
}
|
|
122
|
+
return [...newest.values()].sort((a, b) => a.component.localeCompare(b.component)).map((source) => ({ component: source.component, digest: source.digest, source }));
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Run stage `stage`'s op waves for a release (#5427), in order, through
|
|
126
|
+
* `run` (`runOpWave`), as a wave job of the stage would. `spec` is the
|
|
127
|
+
* pipeline folded at `base`, the default branch's commit. Call it only once
|
|
128
|
+
* the stage's gate passed. `options` are the runner's seams (the gate
|
|
129
|
+
* ledger, the capabilities, the release port); `afterWave` is told how each
|
|
130
|
+
* wave ended, as `chant run wave` tells the spec's notify.
|
|
131
|
+
*/
|
|
132
|
+
export async function runStageWaves(input) {
|
|
133
|
+
const spec = stageRunSpec(input.spec, input.stage);
|
|
134
|
+
const specFile = pipelineStageSpecFile(input.spec, input.stage);
|
|
135
|
+
const path = isAbsolute(specFile) ? specFile : join(input.cwd, specFile);
|
|
136
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
137
|
+
writeFileSync(path, `${JSON.stringify(spec, null, 2)}\n`);
|
|
138
|
+
const run = input.run ?? (await import("../op/op-waves-run.js")).runOpWave;
|
|
139
|
+
const own = input.options ?? {};
|
|
140
|
+
const releases = own.releases ?? (await import("../op/op-waves-release-port.js")).gitOpWaveReleasePort({ cwd: input.cwd, release: input.release });
|
|
141
|
+
const waves = [];
|
|
142
|
+
for (const [i, wave] of spec.waves.entries()) {
|
|
143
|
+
const result = await run({
|
|
144
|
+
...own,
|
|
145
|
+
spec,
|
|
146
|
+
specFile,
|
|
147
|
+
wave: i + 1,
|
|
148
|
+
base: input.base,
|
|
149
|
+
cwd: input.cwd,
|
|
150
|
+
show: own.show ?? pipelineStageShow(),
|
|
151
|
+
standDown: false,
|
|
152
|
+
releases,
|
|
153
|
+
});
|
|
154
|
+
const ran = { wave: i + 1, name: wave.name, result };
|
|
155
|
+
waves.push(ran);
|
|
156
|
+
await input.afterWave?.(ran, spec);
|
|
157
|
+
if (result.exitCode !== 0)
|
|
158
|
+
return { specFile, spec, waves, exitCode: result.exitCode };
|
|
159
|
+
}
|
|
160
|
+
return { specFile, spec, waves, exitCode: 0 };
|
|
161
|
+
}
|