@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,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What each stage of a folded pipeline becomes (#5324).
|
|
3
|
+
*
|
|
4
|
+
* A stage is an op-waves spec: the pipeline's shared settings, the stage's
|
|
5
|
+
* waves, its gate on every wave, its hooks after the pipeline's, `labels.Env`
|
|
6
|
+
* naming the stage so run and release records go on its environment's
|
|
7
|
+
* ledger. `chant run wave` runs it, and the gate is read from the folded
|
|
8
|
+
* pipeline at the base commit like any op-waves spec's.
|
|
9
|
+
*
|
|
10
|
+
* The merge path: a merge applies the first stage, as products do now, and
|
|
11
|
+
* once its last wave applied cuts a release from the applied commit (an
|
|
12
|
+
* after-apply hook on that wave, read at base with the others). The control
|
|
13
|
+
* repo dispatch (`<product>-applied`) goes after the first stage. Each later
|
|
14
|
+
* stage takes that release through `chant components promote --to <stage>
|
|
15
|
+
* --release <label>` behind its gate. A member with no components takes it
|
|
16
|
+
* by the stage's op waves, which the promote runs once that gate passed
|
|
17
|
+
* (#5427, `./stage-waves.ts`).
|
|
18
|
+
*
|
|
19
|
+
* The stage order is the promotion order: `promotionOrderOf` gives it in the
|
|
20
|
+
* shape `environments` in `chant.config.ts` gives it, so `components
|
|
21
|
+
* promote`, `release cut`, `workspace status` and `workspace train promote`
|
|
22
|
+
* read the same order from either.
|
|
23
|
+
*/
|
|
24
|
+
import { type OpWaveHook, type OpWavesSpec } from "../op/op-waves.js";
|
|
25
|
+
import type { PromotionStep } from "../workspace/promotion-order.js";
|
|
26
|
+
import type { PipelineSpec, PipelineStage } from "./spec.js";
|
|
27
|
+
/** The op-waves spec name a stage runs under: `<pipeline>-<stage>`, so each stage's wave gates are its own. */
|
|
28
|
+
export declare function stageWavesName(spec: Pick<PipelineSpec, "name">, stage: string): string;
|
|
29
|
+
/** The stage named `name`, or undefined. */
|
|
30
|
+
export declare function pipelineStage(spec: Pick<PipelineSpec, "stages">, name: string): PipelineStage | undefined;
|
|
31
|
+
/** The stages in promotion order, as `promotionOrder` reads `environments`. */
|
|
32
|
+
export declare function promotionOrderOf(spec: Pick<PipelineSpec, "stages">): PromotionStep[];
|
|
33
|
+
/** The hook a merge's first stage cuts its release with. */
|
|
34
|
+
export declare function releaseCutHook(spec: Pick<PipelineSpec, "release">): OpWaveHook | undefined;
|
|
35
|
+
/**
|
|
36
|
+
* The hook a stage publishes its release artifacts with (#5356), run after
|
|
37
|
+
* the release cut on the first stage's last wave: `chant pipeline artifacts
|
|
38
|
+
* publish --stage <stage>`, through the cut's bin. Undefined when the stage
|
|
39
|
+
* publishes nothing or the merge cuts no release.
|
|
40
|
+
*/
|
|
41
|
+
export declare function artifactsPublishHook(spec: Pick<PipelineSpec, "release" | "stages">, stage: string): OpWaveHook | undefined;
|
|
42
|
+
/**
|
|
43
|
+
* The op-waves spec stage `name` runs: its waves under its gate. The first
|
|
44
|
+
* stage also carries the release cut and the control dispatch, since it is
|
|
45
|
+
* the stage a merge applies. A canary wave with no soak of its own takes
|
|
46
|
+
* the stage's (#5327). A stage whose step's targets name environments
|
|
47
|
+
* records its releases under the pipeline's component (#5427). Throws on a
|
|
48
|
+
* stage the pipeline lacks, or a spec no job could run.
|
|
49
|
+
*/
|
|
50
|
+
export declare function stageWavesSpec(spec: PipelineSpec, name: string): OpWavesSpec;
|
|
51
|
+
/** Why a stage refuses promotion now, and until when. */
|
|
52
|
+
export interface StageHeld {
|
|
53
|
+
stage: string;
|
|
54
|
+
kind: "hold" | "freeze";
|
|
55
|
+
/** When it lifts by itself, or null when only a change to the pipeline lifts it. */
|
|
56
|
+
until: string | null;
|
|
57
|
+
reason?: string;
|
|
58
|
+
/** What the person who lifts the hold reads first (#5354). */
|
|
59
|
+
description?: string;
|
|
60
|
+
}
|
|
61
|
+
/** The hold or freeze window on `stage` at `now`, or undefined when promotion is open. A hold wins over a window. */
|
|
62
|
+
export declare function stageHeldAt(stage: Pick<PipelineStage, "name" | "hold" | "freeze">, now: Date): StageHeld | undefined;
|
|
63
|
+
/** The line a held stage's refusal prints: what holds it, and until when. */
|
|
64
|
+
export declare function stageHeldLine(held: StageHeld): string;
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What each stage of a folded pipeline becomes (#5324).
|
|
3
|
+
*
|
|
4
|
+
* A stage is an op-waves spec: the pipeline's shared settings, the stage's
|
|
5
|
+
* waves, its gate on every wave, its hooks after the pipeline's, `labels.Env`
|
|
6
|
+
* naming the stage so run and release records go on its environment's
|
|
7
|
+
* ledger. `chant run wave` runs it, and the gate is read from the folded
|
|
8
|
+
* pipeline at the base commit like any op-waves spec's.
|
|
9
|
+
*
|
|
10
|
+
* The merge path: a merge applies the first stage, as products do now, and
|
|
11
|
+
* once its last wave applied cuts a release from the applied commit (an
|
|
12
|
+
* after-apply hook on that wave, read at base with the others). The control
|
|
13
|
+
* repo dispatch (`<product>-applied`) goes after the first stage. Each later
|
|
14
|
+
* stage takes that release through `chant components promote --to <stage>
|
|
15
|
+
* --release <label>` behind its gate. A member with no components takes it
|
|
16
|
+
* by the stage's op waves, which the promote runs once that gate passed
|
|
17
|
+
* (#5427, `./stage-waves.ts`).
|
|
18
|
+
*
|
|
19
|
+
* The stage order is the promotion order: `promotionOrderOf` gives it in the
|
|
20
|
+
* shape `environments` in `chant.config.ts` gives it, so `components
|
|
21
|
+
* promote`, `release cut`, `workspace status` and `workspace train promote`
|
|
22
|
+
* read the same order from either.
|
|
23
|
+
*/
|
|
24
|
+
import { assertOpWavesSpec } from "../op/op-waves.js";
|
|
25
|
+
/** The op-waves spec name a stage runs under: `<pipeline>-<stage>`, so each stage's wave gates are its own. */
|
|
26
|
+
export function stageWavesName(spec, stage) {
|
|
27
|
+
return `${spec.name}-${stage}`;
|
|
28
|
+
}
|
|
29
|
+
/** The stage named `name`, or undefined. */
|
|
30
|
+
export function pipelineStage(spec, name) {
|
|
31
|
+
return spec.stages.find((s) => s.name === name);
|
|
32
|
+
}
|
|
33
|
+
/** The stages in promotion order, as `promotionOrder` reads `environments`. */
|
|
34
|
+
export function promotionOrderOf(spec) {
|
|
35
|
+
return spec.stages.map((s) => ({ name: s.name, canary: s.canary === true }));
|
|
36
|
+
}
|
|
37
|
+
/** The hook a merge's first stage cuts its release with. */
|
|
38
|
+
export function releaseCutHook(spec) {
|
|
39
|
+
if (spec.release?.cut === false)
|
|
40
|
+
return undefined;
|
|
41
|
+
const bin = spec.release?.bin ?? ["chant"];
|
|
42
|
+
return { name: "release-cut", command: [...bin, "release", "cut", spec.release?.label ?? "auto", "--yes"] };
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* The hook a stage publishes its release artifacts with (#5356), run after
|
|
46
|
+
* the release cut on the first stage's last wave: `chant pipeline artifacts
|
|
47
|
+
* publish --stage <stage>`, through the cut's bin. Undefined when the stage
|
|
48
|
+
* publishes nothing or the merge cuts no release.
|
|
49
|
+
*/
|
|
50
|
+
export function artifactsPublishHook(spec, stage) {
|
|
51
|
+
if (spec.release?.cut === false)
|
|
52
|
+
return undefined;
|
|
53
|
+
const declared = spec.stages.find((s) => s.name === stage)?.publish;
|
|
54
|
+
if (!declared || Object.keys(declared).length === 0)
|
|
55
|
+
return undefined;
|
|
56
|
+
const bin = spec.release?.bin ?? ["chant"];
|
|
57
|
+
return { name: "artifacts-publish", command: [...bin, "pipeline", "artifacts", "publish", "--stage", stage] };
|
|
58
|
+
}
|
|
59
|
+
function joinHooks(first, then) {
|
|
60
|
+
if (!first)
|
|
61
|
+
return then;
|
|
62
|
+
if (!then)
|
|
63
|
+
return first;
|
|
64
|
+
const both = (k) => {
|
|
65
|
+
const a = (first[k] ?? {});
|
|
66
|
+
const b = (then[k] ?? {});
|
|
67
|
+
const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])];
|
|
68
|
+
return keys.length === 0 ? undefined : Object.fromEntries(keys.map((m) => [m, [...(a[m] ?? []), ...(b[m] ?? [])]]));
|
|
69
|
+
};
|
|
70
|
+
const before = both("before");
|
|
71
|
+
const after = both("after");
|
|
72
|
+
const apply = then.apply ?? first.apply;
|
|
73
|
+
return { ...(before ? { before } : {}), ...(after ? { after } : {}), ...(apply ? { apply } : {}) };
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* The release names a stage's step records under (#5427), when the pipeline
|
|
77
|
+
* fixes them: a stage with a `step` whose every run target is missing from
|
|
78
|
+
* some other stage names an environment, not a component (a yodel project's
|
|
79
|
+
* `dev` and `staging`), so its records take `release.component` of the
|
|
80
|
+
* defaults, else the pipeline's name, and each stage's records name the same
|
|
81
|
+
* component. Undefined when the defaults name a component or turn the
|
|
82
|
+
* records off, when the stage has no step, or when a target is run by every
|
|
83
|
+
* stage (a root or a stack, which names its own records).
|
|
84
|
+
*/
|
|
85
|
+
function stageReleaseNames(spec, stage) {
|
|
86
|
+
const own = spec.defaults?.release;
|
|
87
|
+
if (!spec.defaults?.step || own === false || own?.component !== undefined)
|
|
88
|
+
return undefined;
|
|
89
|
+
const targets = stage.waves.flatMap((w) => (w.runs ?? []).map((r) => r.target));
|
|
90
|
+
if (targets.length === 0 || spec.stages.length < 2)
|
|
91
|
+
return undefined;
|
|
92
|
+
const everywhere = (target) => spec.stages.every((s) => s.waves.some((w) => (w.runs ?? []).some((r) => r.target === target)));
|
|
93
|
+
if (targets.some(everywhere))
|
|
94
|
+
return undefined;
|
|
95
|
+
return { ...(own ?? {}), component: spec.name };
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* The op-waves spec stage `name` runs: its waves under its gate. The first
|
|
99
|
+
* stage also carries the release cut and the control dispatch, since it is
|
|
100
|
+
* the stage a merge applies. A canary wave with no soak of its own takes
|
|
101
|
+
* the stage's (#5327). A stage whose step's targets name environments
|
|
102
|
+
* records its releases under the pipeline's component (#5427). Throws on a
|
|
103
|
+
* stage the pipeline lacks, or a spec no job could run.
|
|
104
|
+
*/
|
|
105
|
+
export function stageWavesSpec(spec, name) {
|
|
106
|
+
const index = spec.stages.findIndex((s) => s.name === name);
|
|
107
|
+
if (index < 0)
|
|
108
|
+
throw new Error(`the pipeline "${spec.name}" has no stage "${name}"; its stages are ${spec.stages.map((s) => s.name).join(", ")}`);
|
|
109
|
+
const stage = spec.stages[index];
|
|
110
|
+
const first = index === 0;
|
|
111
|
+
const defaults = spec.defaults ?? {};
|
|
112
|
+
const gate = stage.gate ?? {};
|
|
113
|
+
const waves = stage.waves.map((w, k) => {
|
|
114
|
+
const tolerance = w.failureTolerance ?? stage.failureTolerance;
|
|
115
|
+
const { failureTolerance: _own, ...rest } = w;
|
|
116
|
+
const wave = {
|
|
117
|
+
...rest,
|
|
118
|
+
gate: w.gate ?? gate.policy ?? "always",
|
|
119
|
+
...(w.approval ?? gate.approval ? { approval: w.approval ?? gate.approval } : {}),
|
|
120
|
+
...(w.environment ?? stage.forgeEnvironment ? { environment: w.environment ?? stage.forgeEnvironment } : {}),
|
|
121
|
+
...(tolerance !== undefined && tolerance !== 0 ? { failureTolerance: tolerance } : {}),
|
|
122
|
+
// #5327: a canary wave that declares no soak takes the stage's, so a product's waves.canary needs no key of its own.
|
|
123
|
+
...(w.canary && w.soak === undefined && stage.soak !== undefined ? { soak: structuredClone(stage.soak) } : {}),
|
|
124
|
+
};
|
|
125
|
+
const cut = first && k === stage.waves.length - 1 ? releaseCutHook(spec) : undefined;
|
|
126
|
+
const publish = cut ? artifactsPublishHook(spec, stage.name) : undefined;
|
|
127
|
+
if (cut)
|
|
128
|
+
wave.hooks = joinHooks(wave.hooks, { after: { apply: publish ? [cut, publish] : [cut] } });
|
|
129
|
+
return wave;
|
|
130
|
+
});
|
|
131
|
+
const approvals = gate.quorum !== undefined ? { ...defaults.approvals, quorum: gate.quorum } : defaults.approvals;
|
|
132
|
+
const release = stageReleaseNames(spec, stage);
|
|
133
|
+
const hooks = joinHooks(defaults.hooks, stage.hooks);
|
|
134
|
+
const holds = gate.holds ?? defaults.holds;
|
|
135
|
+
const point = gate.point ?? defaults.point;
|
|
136
|
+
const out = {
|
|
137
|
+
...defaults,
|
|
138
|
+
name: stageWavesName(spec, stage.name),
|
|
139
|
+
op: defaults.op ?? spec.name,
|
|
140
|
+
labels: { ...defaults.labels, Env: stage.name },
|
|
141
|
+
...(approvals ? { approvals } : {}),
|
|
142
|
+
...(release ? { release } : {}),
|
|
143
|
+
...(hooks ? { hooks } : {}),
|
|
144
|
+
...(holds ? { holds } : {}),
|
|
145
|
+
...(point ? { point } : {}),
|
|
146
|
+
...(first && spec.control ? { control: spec.control } : {}),
|
|
147
|
+
...(stage.replanDependents ? { replanDependents: [...stage.replanDependents] } : {}),
|
|
148
|
+
waves,
|
|
149
|
+
};
|
|
150
|
+
assertOpWavesSpec(out);
|
|
151
|
+
return out;
|
|
152
|
+
}
|
|
153
|
+
/** The hold or freeze window on `stage` at `now`, or undefined when promotion is open. A hold wins over a window. */
|
|
154
|
+
export function stageHeldAt(stage, now) {
|
|
155
|
+
const hold = stage.hold;
|
|
156
|
+
if (hold === true)
|
|
157
|
+
return { stage: stage.name, kind: "hold", until: null };
|
|
158
|
+
if (hold !== undefined && (hold.until === undefined || Date.parse(hold.until) > now.getTime())) {
|
|
159
|
+
return { stage: stage.name, kind: "hold", until: hold.until ?? null, ...(hold.reason ? { reason: hold.reason } : {}), ...(hold.description ? { description: hold.description } : {}) };
|
|
160
|
+
}
|
|
161
|
+
const windows = (stage.freeze ?? []).filter((w) => Date.parse(w.from) <= now.getTime() && now.getTime() < Date.parse(w.until));
|
|
162
|
+
if (windows.length === 0)
|
|
163
|
+
return undefined;
|
|
164
|
+
// Overlapping windows: the one that ends last says until when.
|
|
165
|
+
const last = windows.reduce((a, b) => (Date.parse(b.until) > Date.parse(a.until) ? b : a));
|
|
166
|
+
return { stage: stage.name, kind: "freeze", until: last.until, ...(last.reason ? { reason: last.reason } : {}) };
|
|
167
|
+
}
|
|
168
|
+
/** The line a held stage's refusal prints: what holds it, and until when. */
|
|
169
|
+
export function stageHeldLine(held) {
|
|
170
|
+
const what = held.kind === "hold" ? `stage "${held.stage}" is held` : `stage "${held.stage}" is in a freeze window`;
|
|
171
|
+
const until = held.until ? ` until ${held.until}` : " until a change to the pipeline lifts the hold";
|
|
172
|
+
const read = held.description ? `. Before it goes on: ${held.description}` : "";
|
|
173
|
+
return `${what}${until}${held.reason ? ` (${held.reason})` : ""}, so nothing is promoted into it${read}`;
|
|
174
|
+
}
|
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A rollback a stage requests when its verify or its soak fails (#5328).
|
|
3
|
+
*
|
|
4
|
+
* A stage sets `onVerifyFail: "rollback"` in `.chant/pipeline.ts` to opt in.
|
|
5
|
+
* The default, `"hold"`, is what every stage did before: the stage stays as
|
|
6
|
+
* applied, or mixed, and `workspace status` prints the rollback line for a
|
|
7
|
+
* person to run.
|
|
8
|
+
*
|
|
9
|
+
* Two failures count:
|
|
10
|
+
*
|
|
11
|
+
* - verify: a promote into the stage failed at a verify step, as
|
|
12
|
+
* `isVerifyStep` (`../components/verify-step.ts`) names one: a step in a
|
|
13
|
+
* phase named `Verify`, or of a wait-and-verify kind. The agent trigger of
|
|
14
|
+
* #5339 reads a failed verify by the same function. A failed apply is not
|
|
15
|
+
* one, so the stage holds as before;
|
|
16
|
+
* - soak: a check of the stage's soak failed while a promote out of it read
|
|
17
|
+
* the soak (`./soak-gate.ts`).
|
|
18
|
+
*
|
|
19
|
+
* On either, {@link requestStageRollback} writes three things on the stage's
|
|
20
|
+
* ledger (`./stage-ledger.ts`): a `failed` line, with each member's state
|
|
21
|
+
* ({@link memberStateOf}); then a `rollback-requested` line bound to the
|
|
22
|
+
* stage's previous release, naming the members the rollback restores and
|
|
23
|
+
* linking the failure; and the pending fact of gate `<stage>-rollback`
|
|
24
|
+
* under the pipeline's op, bound to that release's digest. It sends a
|
|
25
|
+
* `rollback-requested` notify event, and the command exits 3.
|
|
26
|
+
*
|
|
27
|
+
* The request applies nothing. `chant components rollback <stage>
|
|
28
|
+
* --requested` reads it, passes it through {@link requestedRollbackGate}
|
|
29
|
+
* and only then runs `components rollback --release` for the members it
|
|
30
|
+
* names. That gate always waits for a person: a stage gate policy of `never`
|
|
31
|
+
* lets a promote through, and never a requested rollback. It counts the
|
|
32
|
+
* stage gate's approval rules and approval mode, only approvals given since
|
|
33
|
+
* the request, and the run spends the approval it used. The `rolled-back`
|
|
34
|
+
* line links the rollback to its request and its failure.
|
|
35
|
+
*
|
|
36
|
+
* No rollback is requested, and the line `rollback-held` says why, when the
|
|
37
|
+
* stage ran no earlier release, when the newest earlier one is revoked or
|
|
38
|
+
* no longer kept, or when no member left applied ran that release.
|
|
39
|
+
*
|
|
40
|
+
* The `failed` line names no rollback, so a separate reader of failures, such
|
|
41
|
+
* as an agent trigger, reads it on its own; whatever that reader opens, the
|
|
42
|
+
* request stays on the ledger until the rollback runs.
|
|
43
|
+
*/
|
|
44
|
+
import type { DriverComponentResult } from "../components/driver.js";
|
|
45
|
+
import type { ReleaseRecord } from "../lifecycle/release-ledger.js";
|
|
46
|
+
import type { GateResolutionRecord } from "../lifecycle/gate-ledger.js";
|
|
47
|
+
import { type GateLedgerPort } from "../op/gate.js";
|
|
48
|
+
import { type NotifyConfig, type NotifyEvent } from "../notify.js";
|
|
49
|
+
import type { PipelineGateProof } from "./promote.js";
|
|
50
|
+
import type { PipelineOnVerifyFail, PipelineSpec, PipelineStage } from "./spec.js";
|
|
51
|
+
import type { StageLedgerPort, StageMemberState, StageMemberStateName, StagePauseLine, StageRelease } from "./stage-ledger.js";
|
|
52
|
+
/** How long a rollback request's pending fact stands. The request itself stays on the stage's ledger until the rollback runs. */
|
|
53
|
+
export declare const ROLLBACK_REQUEST_EXPIRY = "30d";
|
|
54
|
+
/** What a stage does when its verify or soak fails: its `onVerifyFail`, else `"hold"`. */
|
|
55
|
+
export declare function stageOnVerifyFail(stage: Pick<PipelineStage, "onVerifyFail"> | undefined): PipelineOnVerifyFail;
|
|
56
|
+
/** The gate a stage's requested rollback passes, under the pipeline's op. */
|
|
57
|
+
export declare function stageRollbackGate(stage: string): string;
|
|
58
|
+
/** The command that carries out a stage's requested rollback once its gate passes. */
|
|
59
|
+
export declare function requestedRollbackCommand(stage: string): string;
|
|
60
|
+
/**
|
|
61
|
+
* The state a run left one member in, from its result: `applied` when it
|
|
62
|
+
* deployed; for a failed or gated one, `left-applied` when a step's change
|
|
63
|
+
* stays (a `rollback-opted-out` record, an undo that failed, or a step that
|
|
64
|
+
* ran before a gate stopped it), `rolled-back` when each step that ran was
|
|
65
|
+
* undone, and `not-applied` when nothing of it ran.
|
|
66
|
+
*/
|
|
67
|
+
export declare function memberStateOf(result: Pick<DriverComponentResult, "status" | "records"> | undefined): StageMemberStateName;
|
|
68
|
+
/** Each planned member's state after a run, in plan order. */
|
|
69
|
+
export declare function memberStatesOf(members: readonly string[], results: readonly Pick<DriverComponentResult, "component" | "status" | "records">[]): StageMemberState[];
|
|
70
|
+
/**
|
|
71
|
+
* The stage a held promotion's soak failure rolls back, and its members, or
|
|
72
|
+
* undefined when the soak held for its clock or for a check that could not
|
|
73
|
+
* be read (#5328). The stage is the one whose soak held (`heldBy`), which on
|
|
74
|
+
* a later promote can be a canary upstream rather than the stage promoted
|
|
75
|
+
* from or into.
|
|
76
|
+
*/
|
|
77
|
+
export declare function soakFailureOf(outcome: {
|
|
78
|
+
passed: boolean;
|
|
79
|
+
decision: {
|
|
80
|
+
holds: readonly {
|
|
81
|
+
reason: string;
|
|
82
|
+
status?: string;
|
|
83
|
+
}[];
|
|
84
|
+
};
|
|
85
|
+
heldBy?: {
|
|
86
|
+
stage: string;
|
|
87
|
+
members: string[];
|
|
88
|
+
};
|
|
89
|
+
}): {
|
|
90
|
+
stage: string;
|
|
91
|
+
members: string[];
|
|
92
|
+
} | undefined;
|
|
93
|
+
/** The lines a failed run's records give, one per failed step: `<member> <phase>/<kind>: <error>`. */
|
|
94
|
+
export declare function failureDetail(results: readonly Pick<DriverComponentResult, "component" | "status" | "records">[]): string[];
|
|
95
|
+
/** What a release check says: whether the release is kept, and the revocation's reason when its commit is revoked. */
|
|
96
|
+
export interface ReleaseCheck {
|
|
97
|
+
kept: boolean;
|
|
98
|
+
revoked: string | null;
|
|
99
|
+
}
|
|
100
|
+
/** The stage's previous release, or why there is none to go back to. */
|
|
101
|
+
export type PreviousRelease = {
|
|
102
|
+
status: "found";
|
|
103
|
+
release: StageRelease;
|
|
104
|
+
} | {
|
|
105
|
+
status: "none";
|
|
106
|
+
} | {
|
|
107
|
+
status: "revoked";
|
|
108
|
+
release: StageRelease;
|
|
109
|
+
reason: string;
|
|
110
|
+
} | {
|
|
111
|
+
status: "not-kept";
|
|
112
|
+
release: StageRelease;
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* The release the stage ran before the one that failed: the newest release
|
|
116
|
+
* its ledger names outside `exclude`. Unlike `rollbackTarget`, a revoked or
|
|
117
|
+
* no longer kept release is not passed over for an older one; it is the
|
|
118
|
+
* answer, so the hold can say which release it is.
|
|
119
|
+
*/
|
|
120
|
+
export declare function previousRelease(input: {
|
|
121
|
+
records: readonly ReleaseRecord[];
|
|
122
|
+
exclude: ReadonlySet<string>;
|
|
123
|
+
check: (releaseDigest: string) => Promise<ReleaseCheck>;
|
|
124
|
+
label?: (releaseDigest: string) => string | null;
|
|
125
|
+
}): Promise<PreviousRelease>;
|
|
126
|
+
/** Why no rollback is requested, as the `rollback-held` line and the promote say it. */
|
|
127
|
+
export declare function heldReason(stage: string, previous: Exclude<PreviousRelease, {
|
|
128
|
+
status: "found";
|
|
129
|
+
}>): string;
|
|
130
|
+
/**
|
|
131
|
+
* Which members a rollback to `to` restores: each member left `applied` or
|
|
132
|
+
* `left-applied` that ran release `to` in the stage. Every other member is
|
|
133
|
+
* listed with why it is not restored.
|
|
134
|
+
*/
|
|
135
|
+
export declare function rollbackMembers(states: readonly StageMemberState[], records: readonly ReleaseRecord[], to: StageRelease): StageMemberState[];
|
|
136
|
+
/** The `failed` lines of a stage's ledger, oldest first: what a separate trigger reads. */
|
|
137
|
+
export declare function stageFailures(lines: readonly StagePauseLine[]): StagePauseLine[];
|
|
138
|
+
/**
|
|
139
|
+
* The newest rollback request no `rolled-back` line has answered, or
|
|
140
|
+
* undefined. With `failed`, only a request for that failed release counts.
|
|
141
|
+
*/
|
|
142
|
+
export declare function standingRollbackRequest(lines: readonly StagePauseLine[], failed?: string): StagePauseLine | undefined;
|
|
143
|
+
/** One line in the words a person reads: each member and what the rollback does with it. */
|
|
144
|
+
export declare function memberLines(members: readonly StageMemberState[]): string[];
|
|
145
|
+
export interface StageRollbackInput {
|
|
146
|
+
spec: Pick<PipelineSpec, "name" | "stages">;
|
|
147
|
+
stage: string;
|
|
148
|
+
failure: "verify" | "soak";
|
|
149
|
+
/** The release that failed in the stage, or the promotion's digest when it named none. */
|
|
150
|
+
failed: StageRelease;
|
|
151
|
+
/** Each member's state. */
|
|
152
|
+
members: readonly StageMemberState[];
|
|
153
|
+
/** What the failure said, one line each. */
|
|
154
|
+
detail: readonly string[];
|
|
155
|
+
/** The stage's release ledger. */
|
|
156
|
+
records: readonly ReleaseRecord[];
|
|
157
|
+
/** Releases that are not earlier ones: the one that failed. */
|
|
158
|
+
exclude: ReadonlySet<string>;
|
|
159
|
+
check: (releaseDigest: string) => Promise<ReleaseCheck>;
|
|
160
|
+
label?: (releaseDigest: string) => string | null;
|
|
161
|
+
stages: StageLedgerPort;
|
|
162
|
+
gates: GateLedgerPort;
|
|
163
|
+
/** Who the lines name: the promote's actor. */
|
|
164
|
+
by: string;
|
|
165
|
+
now: Date;
|
|
166
|
+
gitSha?: string;
|
|
167
|
+
/** Where the request's notice goes. Absent: none is sent. */
|
|
168
|
+
notify?: {
|
|
169
|
+
config: NotifyConfig | undefined;
|
|
170
|
+
source: string;
|
|
171
|
+
send?: (config: NotifyConfig | undefined, event: NotifyEvent) => Promise<unknown>;
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
/** What {@link requestStageRollback} did. */
|
|
175
|
+
export type StageRollbackOutcome =
|
|
176
|
+
/** The stage holds, as it always did: its `onVerifyFail` is `hold`. Nothing was written. */
|
|
177
|
+
{
|
|
178
|
+
status: "hold";
|
|
179
|
+
}
|
|
180
|
+
/** A request for this failed release stands already; nothing new was written. */
|
|
181
|
+
| {
|
|
182
|
+
status: "standing";
|
|
183
|
+
request: StagePauseLine;
|
|
184
|
+
exitCode: 3;
|
|
185
|
+
lines: string[];
|
|
186
|
+
hint: string;
|
|
187
|
+
} | {
|
|
188
|
+
status: "requested";
|
|
189
|
+
request: StagePauseLine;
|
|
190
|
+
failure: StagePauseLine;
|
|
191
|
+
exitCode: 3;
|
|
192
|
+
lines: string[];
|
|
193
|
+
hint: string;
|
|
194
|
+
}
|
|
195
|
+
/** No rollback could be requested; the stage holds, and `reason` says why. */
|
|
196
|
+
| {
|
|
197
|
+
status: "held";
|
|
198
|
+
failure: StagePauseLine;
|
|
199
|
+
reason: string;
|
|
200
|
+
lines: string[];
|
|
201
|
+
};
|
|
202
|
+
/** Write a stage's failure and its rollback request. See the module comment. */
|
|
203
|
+
export declare function requestStageRollback(input: StageRollbackInput): Promise<StageRollbackOutcome>;
|
|
204
|
+
/** What {@link requestedRollbackGate} decided. */
|
|
205
|
+
export type RequestedRollbackGate = {
|
|
206
|
+
passed: true;
|
|
207
|
+
approval: GateResolutionRecord;
|
|
208
|
+
lines: string[];
|
|
209
|
+
} | {
|
|
210
|
+
passed: false;
|
|
211
|
+
exitCode: 3;
|
|
212
|
+
code: "pipeline-rollback-waiting";
|
|
213
|
+
message: string;
|
|
214
|
+
hint: string;
|
|
215
|
+
};
|
|
216
|
+
/**
|
|
217
|
+
* The gate a requested rollback passes before it applies: gate
|
|
218
|
+
* `<stage>-rollback` under the pipeline's op, bound to the release it goes
|
|
219
|
+
* back to, with the stage gate's approval rules and mode. It always waits
|
|
220
|
+
* for a person, whatever the stage's gate policy, and counts only an
|
|
221
|
+
* approval given since the request and not spent by an earlier rollback.
|
|
222
|
+
*/
|
|
223
|
+
export declare function requestedRollbackGate(input: {
|
|
224
|
+
spec: Pick<PipelineSpec, "name" | "stages">;
|
|
225
|
+
stage: string;
|
|
226
|
+
request: StagePauseLine;
|
|
227
|
+
port: GateLedgerPort;
|
|
228
|
+
proof?: PipelineGateProof;
|
|
229
|
+
now: Date;
|
|
230
|
+
gitSha?: string;
|
|
231
|
+
}): Promise<RequestedRollbackGate>;
|
|
232
|
+
/** A step a stage applies, as the build check reads it: the member's component and phase, or the pipeline's `defaults.step`. */
|
|
233
|
+
export interface RollbackStepView {
|
|
234
|
+
/** Where the step sits: `component "api" step deploy/terraform-apply`, or `defaults.step`. */
|
|
235
|
+
where: string;
|
|
236
|
+
kind: string;
|
|
237
|
+
}
|
|
238
|
+
/** What the build check reads of a step's capability. */
|
|
239
|
+
export interface RollbackCapabilityView {
|
|
240
|
+
/** Whether the capability answers `releaseInputs`, so a release records the files the step applies. */
|
|
241
|
+
releaseInputs: boolean;
|
|
242
|
+
/** Its `rollbackPolicy`, else `native` when it has a `rollback` and `none-by-design` when not, as COMP003 derives it. */
|
|
243
|
+
rollbackPolicy: "native" | "none-by-design" | "needs-opt-out";
|
|
244
|
+
}
|
|
245
|
+
/** The step kind whose change no earlier release takes back. */
|
|
246
|
+
export declare const MIGRATION_STEP_KIND = "sql-migrate";
|
|
247
|
+
/**
|
|
248
|
+
* Why `chant build` refuses `onVerifyFail: "rollback"` on a stage (#5328),
|
|
249
|
+
* one line per step; empty when nothing refuses. A requested rollback is
|
|
250
|
+
* `components rollback --release`, which applies the files an earlier
|
|
251
|
+
* release recorded, so each step the stage applies has to be one that
|
|
252
|
+
* applying an earlier release restores:
|
|
253
|
+
*
|
|
254
|
+
* - a `sql-migrate` step is refused: a migration that ran stays run;
|
|
255
|
+
* - a step whose kind no registered capability has is refused, since
|
|
256
|
+
* nothing says what it does;
|
|
257
|
+
* - a step whose capability changes nothing (`none-by-design`) passes;
|
|
258
|
+
* - any other step passes only when its capability answers `releaseInputs`,
|
|
259
|
+
* as `terraform-apply` and `pulumi-up` do. Without it, the release records
|
|
260
|
+
* none of its files and the rollback has nothing of it to apply.
|
|
261
|
+
*
|
|
262
|
+
* A step's `noRollback` decides nothing here: it says the capability does not
|
|
263
|
+
* undo a failed apply, and the rollback is a forward apply of the earlier
|
|
264
|
+
* release, not an undo.
|
|
265
|
+
*/
|
|
266
|
+
export declare function verifyRollbackProblems(input: {
|
|
267
|
+
spec: Pick<PipelineSpec, "stages">;
|
|
268
|
+
steps: readonly RollbackStepView[];
|
|
269
|
+
capability: (kind: string) => RollbackCapabilityView | undefined;
|
|
270
|
+
}): string[];
|
|
271
|
+
/** The line a requested rollback that ran writes: the members it restored, linked to its request and failure. */
|
|
272
|
+
export declare function rolledBackLine(input: {
|
|
273
|
+
request: StagePauseLine;
|
|
274
|
+
by: string;
|
|
275
|
+
approval: GateResolutionRecord;
|
|
276
|
+
now: Date;
|
|
277
|
+
}): StagePauseLine;
|