@intentius/chant 0.124.109 → 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/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/trust/seal.d.ts +7 -0
- package/dist/workspace/trust/seal.js +9 -0
- package/package.json +5 -1
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The helpers a product writes `.chant/pipeline.ts` with (#5324).
|
|
3
|
+
*
|
|
4
|
+
* A committed TypeScript file cannot read `terragucci.yml`, `plywood.yml` or
|
|
5
|
+
* `yodel.config.ts` itself, so the product writes the file from its config,
|
|
6
|
+
* the way it renders its workflows: {@link pipelineFromConfig} maps the
|
|
7
|
+
* vocabulary's keys (`promotion`, `environments.<name>.gate`, `.hold`,
|
|
8
|
+
* `.freeze`, `.failure_tolerance`, `.risk`, `.replan_dependents`, `.publish`, `.reads`, `.after`, `.queue`,
|
|
9
|
+
* `.urgent`, `.pause_after_rollback`, `.hooks.<when>`, `.agent_steps`, `.on_verify_fail`,
|
|
10
|
+
* `approval_rules`, `release.cut`) onto a
|
|
11
|
+
* declaration, {@link pipelineSource} writes the file's text, and
|
|
12
|
+
* {@link checkPipelineFile} is what `<product> ci --check` runs: it fails
|
|
13
|
+
* when the committed file is not the one the config writes now.
|
|
14
|
+
*
|
|
15
|
+
* The file is generated output. Hand edits are overwritten the next time the
|
|
16
|
+
* product writes it, and fail the check until then.
|
|
17
|
+
*/
|
|
18
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
19
|
+
import { dirname, join } from "node:path";
|
|
20
|
+
import { OP_WAVE_HOOK_MOMENTS } from "../op/op-waves.js";
|
|
21
|
+
import { foldPipelineSource, pipelineFindingLine, PIPELINE_MODULE } from "./fold.js";
|
|
22
|
+
import { lineDiff } from "./diff.js";
|
|
23
|
+
import { asPipelineSpec, PIPELINE_FILE } from "./spec.js";
|
|
24
|
+
/**
|
|
25
|
+
* The first chant whose `pipelineFromConfig` maps a stage's hooks (#5421):
|
|
26
|
+
* `environments.<name>.hooks.<when>` in a product's config onto a stage's
|
|
27
|
+
* `hooks` in `.chant/pipeline.ts`, with `<when>` one of `before-observe`,
|
|
28
|
+
* `before-plan`, `after-plan`, `after-gate`, `before-apply` and
|
|
29
|
+
* `after-apply`. A product feature-detects the key on this name before it
|
|
30
|
+
* writes it.
|
|
31
|
+
*/
|
|
32
|
+
export const STAGE_HOOKS_KEY_FLOOR = "0.124.110";
|
|
33
|
+
/** A stage's `gate.holds.risk` from `environments.<name>.risk` (#5325). */
|
|
34
|
+
function riskOf(risk, stage) {
|
|
35
|
+
if (!risk)
|
|
36
|
+
return undefined;
|
|
37
|
+
const approveAbove = risk.approve_above ?? risk.approveAbove;
|
|
38
|
+
const rules = rulesOf(risk.approval_rules ?? risk.approvalRules);
|
|
39
|
+
if (rules?.some((n) => "all" in n || "any" in n))
|
|
40
|
+
throw new Error(`environments.${stage}.risk.approval_rules holds a group; a risk hold takes rules only`);
|
|
41
|
+
const out = {
|
|
42
|
+
...(approveAbove !== undefined ? { approveAbove } : {}),
|
|
43
|
+
...(rules && rules.length > 0 ? { quorum: rules } : {}),
|
|
44
|
+
};
|
|
45
|
+
return Object.keys(out).length > 0 ? out : undefined;
|
|
46
|
+
}
|
|
47
|
+
const SOAK_CHECK_WORDS = { on_fail: "onFail", timeout_seconds: "timeoutSeconds" };
|
|
48
|
+
function soakChecksOf(checks) {
|
|
49
|
+
return checks.map((c) => Object.fromEntries(Object.entries(c).map(([k, v]) => [SOAK_CHECK_WORDS[k] ?? k, structuredClone(v)])));
|
|
50
|
+
}
|
|
51
|
+
/** A stage's `soak` from `environments.<name>.soak` (#5326). */
|
|
52
|
+
function soakOf(soak) {
|
|
53
|
+
if (!soak)
|
|
54
|
+
return undefined;
|
|
55
|
+
return {
|
|
56
|
+
duration: soak.duration,
|
|
57
|
+
...(soak.checks ? { checks: soakChecksOf(soak.checks) } : {}),
|
|
58
|
+
...(soak.overrides ? { overrides: soak.overrides.map((o) => ({ members: [...o.members], ...(o.duration !== undefined ? { duration: o.duration } : {}), ...(o.checks ? { checks: soakChecksOf(o.checks) } : {}) })) } : {}),
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
/** A stage's `agentSteps` from `environments.<name>.agent_steps` (#5358). The schema is kept as written. */
|
|
62
|
+
function agentStepsOf(steps) {
|
|
63
|
+
if (!steps || Object.keys(steps).length === 0)
|
|
64
|
+
return undefined;
|
|
65
|
+
return Object.fromEntries(Object.entries(steps).map(([name, c]) => {
|
|
66
|
+
const keyEnv = c.key_secret ?? c.keySecret;
|
|
67
|
+
const maxRuns = c.max_runs ?? c.maxRuns;
|
|
68
|
+
const maxCostUsd = c.max_cost_usd ?? c.maxCostUsd;
|
|
69
|
+
return [
|
|
70
|
+
name,
|
|
71
|
+
{
|
|
72
|
+
prompt: c.prompt,
|
|
73
|
+
...(c.reads && Object.keys(c.reads).length > 0 ? { reads: Object.fromEntries(Object.entries(c.reads).map(([k, r]) => [k, "step" in r ? { step: r.step } : { stage: r.stage, artifact: r.artifact }])) } : {}),
|
|
74
|
+
schema: structuredClone(c.schema),
|
|
75
|
+
...(c.command ? { command: c.command } : {}),
|
|
76
|
+
...(keyEnv ? { keyEnv } : {}),
|
|
77
|
+
...(c.timeout !== undefined ? { timeout: c.timeout } : {}),
|
|
78
|
+
...(maxRuns !== undefined ? { maxRuns } : {}),
|
|
79
|
+
...(maxCostUsd !== undefined ? { maxCostUsd } : {}),
|
|
80
|
+
},
|
|
81
|
+
];
|
|
82
|
+
}));
|
|
83
|
+
}
|
|
84
|
+
function rulesOf(config) {
|
|
85
|
+
if (config === undefined)
|
|
86
|
+
return undefined;
|
|
87
|
+
const list = Array.isArray(config) ? config : Object.keys(config).sort().map((k) => config[k]);
|
|
88
|
+
return list.map((r) => {
|
|
89
|
+
// #5354: a rule or group is named by its own `name`. A map's key stays the config's own label, so a spec written before names stays the same.
|
|
90
|
+
const named = r.name !== undefined ? { name: r.name } : {};
|
|
91
|
+
if ("all" in r)
|
|
92
|
+
return { ...named, all: rulesOf(r.all) ?? [] };
|
|
93
|
+
if ("any" in r)
|
|
94
|
+
return { ...named, any: rulesOf(r.any) ?? [] };
|
|
95
|
+
const rule = {
|
|
96
|
+
...named,
|
|
97
|
+
count: r.count,
|
|
98
|
+
...(r.roles ? { roles: [...r.roles] } : {}),
|
|
99
|
+
...(r.not_author ?? r.notAuthor ? { notAuthor: true } : {}),
|
|
100
|
+
...(r.targets ? { targets: [...r.targets] } : {}),
|
|
101
|
+
...(r.proven ? { proven: true } : {}),
|
|
102
|
+
};
|
|
103
|
+
return rule;
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
const SECRET_WORDS = { forge_secret: "forgeSecret", aws_secrets_manager: "awsSecretsManager", gcp_secret_manager: "gcpSecretManager", azure_key_vault: "azureKeyVault", json_key: "jsonKey" };
|
|
107
|
+
/** A secret's place in camelCase, as a set's secret takes it (#5348): a product's snake_case keys renamed, a string kept. */
|
|
108
|
+
function secretRefOf(ref) {
|
|
109
|
+
if (ref === null || typeof ref !== "object" || Array.isArray(ref))
|
|
110
|
+
return ref;
|
|
111
|
+
return Object.fromEntries(Object.entries(ref).map(([k, v]) => [SECRET_WORDS[k] ?? k, v]));
|
|
112
|
+
}
|
|
113
|
+
/** A stage's `publish` from `environments.<name>.publish` (#5356). */
|
|
114
|
+
function publishOf(publish) {
|
|
115
|
+
if (!publish || Object.keys(publish).length === 0)
|
|
116
|
+
return undefined;
|
|
117
|
+
return Object.fromEntries(Object.entries(publish).map(([name, source]) => [name, (source && "secret" in source ? { secret: secretRefOf(source.secret) } : { member: source?.member, output: source?.output })]));
|
|
118
|
+
}
|
|
119
|
+
/** A stage's `hooks` from `environments.<name>.hooks.<when>` (#5421). Throws on a `<when>` that is not a moment. */
|
|
120
|
+
function hooksOf(hooks, stage) {
|
|
121
|
+
if (!hooks)
|
|
122
|
+
return undefined;
|
|
123
|
+
const out = {};
|
|
124
|
+
for (const [when, list] of Object.entries(hooks)) {
|
|
125
|
+
if (!OP_WAVE_HOOK_MOMENTS.includes(when))
|
|
126
|
+
throw new Error(`environments.${stage}.hooks.${when}: <when> is one of ${OP_WAVE_HOOK_MOMENTS.join(", ")}`);
|
|
127
|
+
if (!Array.isArray(list) || list.length === 0)
|
|
128
|
+
continue;
|
|
129
|
+
const mapped = list.map((h) => {
|
|
130
|
+
const onFailure = h.on_failure ?? h.onFailure;
|
|
131
|
+
const perRun = h.per_run ?? h.perRun;
|
|
132
|
+
return {
|
|
133
|
+
...(h.name !== undefined ? { name: h.name } : {}),
|
|
134
|
+
command: [...h.command],
|
|
135
|
+
...(onFailure !== undefined ? { onFailure } : {}),
|
|
136
|
+
...(perRun ? { perRun: true } : {}),
|
|
137
|
+
...(h.targets && h.targets.length > 0 ? { targets: [...h.targets] } : {}),
|
|
138
|
+
};
|
|
139
|
+
});
|
|
140
|
+
const [side, step] = when.split("-");
|
|
141
|
+
const group = (out[side] ?? (out[side] = {}));
|
|
142
|
+
group[step] = mapped;
|
|
143
|
+
}
|
|
144
|
+
return Object.keys(out).length > 0 ? out : undefined;
|
|
145
|
+
}
|
|
146
|
+
function holdOf(hold) {
|
|
147
|
+
if (hold === undefined || hold === false)
|
|
148
|
+
return undefined;
|
|
149
|
+
if (hold === true)
|
|
150
|
+
return true;
|
|
151
|
+
return { ...(hold.reason ? { reason: hold.reason } : {}), ...(hold.until ? { until: hold.until } : {}), ...(hold.description ? { description: hold.description } : {}) };
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* A declaration from a product's config, in the vocabulary's keys. Throws
|
|
155
|
+
* when `promotion` names a stage `waves` has none for, or the declaration
|
|
156
|
+
* does not check.
|
|
157
|
+
*/
|
|
158
|
+
export function pipelineFromConfig(input) {
|
|
159
|
+
const stages = input.promotion.map((name) => {
|
|
160
|
+
const env = input.environments?.[name] ?? {};
|
|
161
|
+
const waves = input.waves[name];
|
|
162
|
+
if (!waves || waves.length === 0)
|
|
163
|
+
throw new Error(`promotion names ${name}, and no waves were given for it`);
|
|
164
|
+
const policy = env.gate ?? input.gate;
|
|
165
|
+
const approvalRaw = env.approval ?? input.approval;
|
|
166
|
+
const approval = typeof approvalRaw === "object" ? approvalRaw.mode : approvalRaw;
|
|
167
|
+
const quorum = rulesOf(env.approval_rules ?? env.approvalRules ?? input.approvalRules);
|
|
168
|
+
const risk = riskOf(env.risk, name);
|
|
169
|
+
const gate = { ...(policy ? { policy } : {}), ...(approval ? { approval } : {}), ...(quorum ? { quorum } : {}), ...(env.urgent ? { urgent: { role: env.urgent.role } } : {}), ...(risk ? { holds: { risk } } : {}) };
|
|
170
|
+
const replan = env.replan_dependents ?? env.replanDependents;
|
|
171
|
+
const pauseAfterRollback = env.pause_after_rollback ?? env.pauseAfterRollback;
|
|
172
|
+
const onVerifyFail = env.on_verify_fail ?? env.onVerifyFail;
|
|
173
|
+
const hold = holdOf(env.hold);
|
|
174
|
+
const hooks = hooksOf(env.hooks, name);
|
|
175
|
+
const tolerance = env.failure_tolerance ?? env.failureTolerance;
|
|
176
|
+
const forgeRaw = env.forge_environment ?? env.forgeEnvironment;
|
|
177
|
+
const forge = typeof forgeRaw === "string" ? { name: forgeRaw } : forgeRaw;
|
|
178
|
+
return {
|
|
179
|
+
name,
|
|
180
|
+
...(env.canary ? { canary: true } : {}),
|
|
181
|
+
...(replan && replan.length > 0 ? { replanDependents: [...replan] } : {}),
|
|
182
|
+
waves: waves.map((w) => structuredClone(w)),
|
|
183
|
+
...(Object.keys(gate).length > 0 ? { gate } : {}),
|
|
184
|
+
...(hooks ? { hooks } : {}),
|
|
185
|
+
...(hold ? { hold } : {}),
|
|
186
|
+
...(env.freeze && env.freeze.length > 0 ? { freeze: env.freeze.map((w) => ({ ...w })) } : {}),
|
|
187
|
+
...(tolerance !== undefined ? { failureTolerance: tolerance } : {}),
|
|
188
|
+
...(forge ? { forgeEnvironment: forge } : {}),
|
|
189
|
+
...(publishOf(env.publish) ? { publish: publishOf(env.publish) } : {}),
|
|
190
|
+
...(agentStepsOf(env.agent_steps ?? env.agentSteps) ? { agentSteps: agentStepsOf(env.agent_steps ?? env.agentSteps) } : {}),
|
|
191
|
+
...(env.reads && Object.keys(env.reads).length > 0 ? { reads: Object.fromEntries(Object.entries(env.reads).map(([k, r]) => [k, { stage: r.stage, artifact: r.artifact }])) } : {}),
|
|
192
|
+
...(env.after && env.after.length > 0 ? { after: [...env.after] } : {}),
|
|
193
|
+
...(env.queue !== undefined ? { queue: env.queue } : {}),
|
|
194
|
+
...(pauseAfterRollback ? { pauseAfterRollback: true } : {}),
|
|
195
|
+
...(env.soak ? { soak: soakOf(env.soak) } : {}),
|
|
196
|
+
// #5328: `hold` is the default, so it is left out; any other value is written, and the check refuses one it does not know.
|
|
197
|
+
...(onVerifyFail !== undefined && onVerifyFail !== "hold" ? { onVerifyFail } : {}),
|
|
198
|
+
};
|
|
199
|
+
});
|
|
200
|
+
const declaration = {
|
|
201
|
+
name: input.name,
|
|
202
|
+
stages,
|
|
203
|
+
...(input.defaults ? { defaults: structuredClone(input.defaults) } : {}),
|
|
204
|
+
...(input.release ? { release: { ...input.release } } : {}),
|
|
205
|
+
...(input.control ? { control: structuredClone(input.control) } : {}),
|
|
206
|
+
...(input.recheck ? { recheck: { schedule: input.recheck.schedule } } : {}),
|
|
207
|
+
};
|
|
208
|
+
asPipelineSpec(declaration);
|
|
209
|
+
return declaration;
|
|
210
|
+
}
|
|
211
|
+
/**
|
|
212
|
+
* The text of `.chant/pipeline.ts` for a declaration: a header naming the
|
|
213
|
+
* product and the command that writes it, the helper's import, and the
|
|
214
|
+
* declaration as one object literal. Folds to the declaration. Throws on a
|
|
215
|
+
* declaration that does not check.
|
|
216
|
+
*/
|
|
217
|
+
export function pipelineSource(declaration, options) {
|
|
218
|
+
const { kind: _kind, ...plain } = asPipelineSpec(structuredClone(declaration));
|
|
219
|
+
return [
|
|
220
|
+
`// Written by ${options.product} from ${options.config}. Change the config and run \`${options.command}\`;`,
|
|
221
|
+
`// \`${options.product} ci --check\` fails while this file differs from what the config writes.`,
|
|
222
|
+
`import { pipeline } from "${PIPELINE_MODULE}";`,
|
|
223
|
+
"",
|
|
224
|
+
`export default pipeline(${JSON.stringify(plain, null, 2)});`,
|
|
225
|
+
"",
|
|
226
|
+
].join("\n");
|
|
227
|
+
}
|
|
228
|
+
/**
|
|
229
|
+
* Whether the committed `.chant/pipeline.ts` in `dir` is `expected`, the
|
|
230
|
+
* text {@link pipelineSource} writes from the config now. A stale file's
|
|
231
|
+
* result carries the line diff and a message naming the command.
|
|
232
|
+
*/
|
|
233
|
+
export function checkPipelineFile(dir, expected, options) {
|
|
234
|
+
const file = join(dir, PIPELINE_FILE);
|
|
235
|
+
if (!existsSync(file))
|
|
236
|
+
return { status: "missing", file: PIPELINE_FILE, message: `${PIPELINE_FILE} is missing; run \`${options.command}\` to write it` };
|
|
237
|
+
const actual = readFileSync(file, "utf-8");
|
|
238
|
+
if (actual === expected)
|
|
239
|
+
return { status: "current", file: PIPELINE_FILE };
|
|
240
|
+
const folded = foldPipelineSource(actual, PIPELINE_FILE);
|
|
241
|
+
const why = "finding" in folded ? `, and it does not fold: ${pipelineFindingLine(PIPELINE_FILE, folded.finding)}` : "";
|
|
242
|
+
return {
|
|
243
|
+
status: "stale",
|
|
244
|
+
file: PIPELINE_FILE,
|
|
245
|
+
message: `${PIPELINE_FILE} is not what the config writes${why}; run \`${options.command}\` and commit it`,
|
|
246
|
+
diff: lineDiff(actual.split("\n"), expected.split("\n")),
|
|
247
|
+
};
|
|
248
|
+
}
|
|
249
|
+
/** Write `text` to `.chant/pipeline.ts` in `dir`, creating `.chant`. Returns whether the file changed. */
|
|
250
|
+
export function writePipelineFile(dir, text) {
|
|
251
|
+
const file = join(dir, PIPELINE_FILE);
|
|
252
|
+
if (existsSync(file) && readFileSync(file, "utf-8") === text)
|
|
253
|
+
return false;
|
|
254
|
+
mkdirSync(dirname(file), { recursive: true });
|
|
255
|
+
writeFileSync(file, text);
|
|
256
|
+
return true;
|
|
257
|
+
}
|
|
@@ -0,0 +1,404 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a promote reads from the folded pipeline (#5324).
|
|
3
|
+
*
|
|
4
|
+
* `chant components promote --to <stage>` in a member with a pipeline reads
|
|
5
|
+
* it at the default branch's tip (`./read.ts`'s `promoteBase`):
|
|
6
|
+
*
|
|
7
|
+
* 1. A held stage, or one in a freeze window, refuses with exit 3 and says
|
|
8
|
+
* until when.
|
|
9
|
+
* 2. `--from` defaults to the stage before; a promote that skips a stage is
|
|
10
|
+
* refused, as with `environments`. `--allow-skip` passes only through
|
|
11
|
+
* each skipped stage's gate: gate `<stage>-skip` under the pipeline's
|
|
12
|
+
* op, bound to the promoted digest, unless that stage's gate policy is
|
|
13
|
+
* `never`. A held skipped stage refuses too. Each skip is recorded on
|
|
14
|
+
* `_gates/<pipeline>/applied.jsonl`, which spends the approval it went
|
|
15
|
+
* through.
|
|
16
|
+
* 3. The target stage's gate: gate `<stage>` under the pipeline's op, bound
|
|
17
|
+
* to the release's digest (or the promoted digests'), with the stage's
|
|
18
|
+
* quorum rules. A policy of `never` lets it through; `always` and
|
|
19
|
+
* `on-destructive` wait, since a promote has no plan to call destructive
|
|
20
|
+
* before it is gated.
|
|
21
|
+
*
|
|
22
|
+
* Before the gates, the soak of the stage promoted from (#5326,
|
|
23
|
+
* `./soak-gate.ts`): while it holds, the promote records the soak's pending
|
|
24
|
+
* fact (gate `<from>-soak`) and exits 3 with the time left. Its clock starts
|
|
25
|
+
* at the newest apply of the promoted components in the `from` stage's
|
|
26
|
+
* release ledger. Then the soak of each canary stage `to` follows (#5327,
|
|
27
|
+
* `canaryStagesBefore`), through the canary's own gate `<canary>-soak` and
|
|
28
|
+
* its own clock: a promote from a later stage reads it again, and a skip
|
|
29
|
+
* past the canary finds no apply there and holds until a person ends the
|
|
30
|
+
* canary's soak early.
|
|
31
|
+
*
|
|
32
|
+
* A gate that waits records its pending fact and the promote exits 3, as a
|
|
33
|
+
* gated run does; `chant approve <pipeline> <gate> --plan <digest>` passes it.
|
|
34
|
+
*
|
|
35
|
+
* A stage that names `after` (#5353) follows those stages: `--from`
|
|
36
|
+
* defaults to the first it names and must be one of them, and the stage
|
|
37
|
+
* opens for a release only once that release applied in each, read from
|
|
38
|
+
* the stage log (`../lifecycle/stage-log.ts`); the first stage counts when
|
|
39
|
+
* its ledger holds a deploy of the release's commit. Until then the promote
|
|
40
|
+
* exits 3. `--allow-skip` takes each stage still missing through its skip
|
|
41
|
+
* gate. A stage with `queue: "replace"` takes one release at a time: a
|
|
42
|
+
* newer release waiting replaces an older one, and a release that waits
|
|
43
|
+
* while another is in the stage exits 3 until that one finishes.
|
|
44
|
+
*
|
|
45
|
+
* A release rejected at a stage's gate (#5354, `chant reject <pipeline>
|
|
46
|
+
* <stage>`) does not enter the stage, and is not skipped past it: the
|
|
47
|
+
* promote exits 8 and says who rejected it and why, before any approval is
|
|
48
|
+
* read, so more approvals never clear it. A rejection counts by the proof
|
|
49
|
+
* rules the gate's approvals count by (`../op/gate-reject.ts`): the gate's
|
|
50
|
+
* `approval` mode (a `sealed` gate counts sealed approvals and rejections
|
|
51
|
+
* only), the workspace's `identity.gates` rule, and the gate's rules.
|
|
52
|
+
* The urgent path (#5355), `promote --urgent --release <label>` into a stage
|
|
53
|
+
* whose gate declares `urgent: { role }`: the stage's gate passes on one
|
|
54
|
+
* approval of gate `<stage>-urgent`, bound to the release's digest, from an
|
|
55
|
+
* approver who holds the role and whose approval a seal against the signers
|
|
56
|
+
* at base proves. A plain `chant approve` line never counts, whatever the
|
|
57
|
+
* stage's approval mode. Holds, freeze windows and a pause still refuse it.
|
|
58
|
+
* It skips no stage, `--allow-skip` or not, and the release must have
|
|
59
|
+
* succeeded in every stage upstream of the one promoted to
|
|
60
|
+
* ({@link urgentUpstreamStages}).
|
|
61
|
+
*
|
|
62
|
+
* A promote under a release reads the change risk its cut carries (#5387,
|
|
63
|
+
* `../lifecycle/release-risk.ts`) at each gate whose stage sets
|
|
64
|
+
* `holds.risk`. Over the stage's threshold the gate takes the risk's
|
|
65
|
+
* `quorum` rules on top of its own, and a gate whose policy is `never` waits
|
|
66
|
+
* for an approval of its own. The gate then counts only people's approvals,
|
|
67
|
+
* and a permit that reads the score only from a person `.chant/trust.json`
|
|
68
|
+
* at base proves. A release with no record, or a stage with no `holds.risk`,
|
|
69
|
+
* has the gate it had before.
|
|
70
|
+
*/
|
|
71
|
+
import { type GateLedgerPort } from "../op/gate.js";
|
|
72
|
+
import { type PipelineSpec, type PipelineStage } from "./spec.js";
|
|
73
|
+
import { type StageLine, type StageLogPort } from "../lifecycle/stage-log.js";
|
|
74
|
+
import { type GateSigners } from "../lifecycle/gate-seal.js";
|
|
75
|
+
import type { GateResolutionRecord } from "../lifecycle/gate-ledger.js";
|
|
76
|
+
import { type PolicyAgentAnswer, type StageAgentAnswerPort } from "./agent-steps.js";
|
|
77
|
+
import { type ReleaseRisk } from "../lifecycle/release-risk.js";
|
|
78
|
+
import { type ChangeRiskReason } from "../change-risk.js";
|
|
79
|
+
import { type SoakGateInput, type SoakGateOutcome } from "./soak-gate.js";
|
|
80
|
+
import type { SoakCheckReader } from "./soak.js";
|
|
81
|
+
/** A refusal or a wait, with the exit code the promote ends with. */
|
|
82
|
+
export interface PipelinePromoteStop {
|
|
83
|
+
exitCode: number;
|
|
84
|
+
message: string;
|
|
85
|
+
hint?: string;
|
|
86
|
+
code?: "pipeline-stage-held" | "promote-skips-environment" | "promote-no-previous-environment" | "pipeline-gate-waiting" | "pipeline-from-not-upstream" | "pipeline-join-needs-release" | "pipeline-upstream-waiting" | "pipeline-release-replaced" | "pipeline-stage-busy" | "pipeline-release-rejected" | "pipeline-stage-paused" | "pipeline-release-superseded" | "pipeline-no-urgent-rule" | "pipeline-urgent-skips" | "pipeline-urgent-upstream" | "pipeline-soak-waiting" | "pipeline-agent-step-holding" | "pipeline-agent-step-no-release" | "pipeline-agent-policy-denied";
|
|
87
|
+
/** Lines the promote prints before the stop, such as a rejection that does not count and why (#5354). */
|
|
88
|
+
lines?: string[];
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* What proves who approved or rejected at a stage's gate (#5354): the
|
|
92
|
+
* signers and passkeys, and the role grants, at the commit the gate is read
|
|
93
|
+
* at. Absent, nothing proves anyone: a `sealed` gate passes nothing, and
|
|
94
|
+
* counts no rejection.
|
|
95
|
+
*/
|
|
96
|
+
export interface PipelineGateProof {
|
|
97
|
+
signers: GateSigners;
|
|
98
|
+
roles: Readonly<Record<string, readonly string[]>>;
|
|
99
|
+
}
|
|
100
|
+
/** The digest a stage gate binds when there is no release: the components and digests promoted, in order. */
|
|
101
|
+
export declare function promotedDigest(items: readonly {
|
|
102
|
+
component: string;
|
|
103
|
+
digest: string;
|
|
104
|
+
}[]): string;
|
|
105
|
+
/**
|
|
106
|
+
* The order and holds part, before anything is planned: the stage promoted
|
|
107
|
+
* from, or a stop. `undefined` when the pipeline has no stage `to`, so the
|
|
108
|
+
* pipeline has nothing to say about it.
|
|
109
|
+
*/
|
|
110
|
+
export declare function pipelinePromoteSource(input: {
|
|
111
|
+
spec: PipelineSpec;
|
|
112
|
+
to: string;
|
|
113
|
+
from?: string;
|
|
114
|
+
allowSkip?: boolean;
|
|
115
|
+
/** `--urgent` (#5355): the stage must declare an urgent rule, and no stage is skipped. */
|
|
116
|
+
urgent?: boolean;
|
|
117
|
+
now: Date;
|
|
118
|
+
}): {
|
|
119
|
+
from: string;
|
|
120
|
+
skipped: PipelineStage[];
|
|
121
|
+
upstreams?: string[];
|
|
122
|
+
} | PipelinePromoteStop | undefined;
|
|
123
|
+
/** What {@link pipelinePromoteGates} decided: every gate passed, or the stop. */
|
|
124
|
+
export type PipelineGatesOutcome = {
|
|
125
|
+
passed: true;
|
|
126
|
+
lines: string[];
|
|
127
|
+
urgent?: {
|
|
128
|
+
approval: GateResolutionRecord;
|
|
129
|
+
role: string;
|
|
130
|
+
};
|
|
131
|
+
} | ({
|
|
132
|
+
passed: false;
|
|
133
|
+
} & PipelinePromoteStop);
|
|
134
|
+
/**
|
|
135
|
+
* The rejections a promote reads before the soak (#5326, #5354): those at
|
|
136
|
+
* each skipped stage's gate and skip gate, then at the target stage's gate
|
|
137
|
+
* (and its urgent gate under `--urgent`). A rejection stops the promote
|
|
138
|
+
* with exit 8 before any soak is read or recorded, so a rejected release
|
|
139
|
+
* never leaves a soak's pending fact. {@link pipelinePromoteGates} reads them
|
|
140
|
+
* again, with the same answer, before its approvals.
|
|
141
|
+
*/
|
|
142
|
+
export declare function pipelinePromoteRejected(input: {
|
|
143
|
+
spec: PipelineSpec;
|
|
144
|
+
to: string;
|
|
145
|
+
skipped: readonly PipelineStage[];
|
|
146
|
+
digest: string;
|
|
147
|
+
releaseDigest?: string;
|
|
148
|
+
port: GateLedgerPort;
|
|
149
|
+
proof?: PipelineGateProof;
|
|
150
|
+
urgent?: boolean;
|
|
151
|
+
}): Promise<({
|
|
152
|
+
passed: false;
|
|
153
|
+
} & PipelinePromoteStop) | undefined>;
|
|
154
|
+
/**
|
|
155
|
+
* The gates part, once the promote knows what it deploys: each skipped
|
|
156
|
+
* stage's skip gate, then the target stage's gate. `digest` is the release's
|
|
157
|
+
* digest, or {@link promotedDigest}. Records each skip it passes.
|
|
158
|
+
*/
|
|
159
|
+
export declare function pipelinePromoteGates(input: {
|
|
160
|
+
spec: PipelineSpec;
|
|
161
|
+
to: string;
|
|
162
|
+
skipped: readonly PipelineStage[];
|
|
163
|
+
digest: string;
|
|
164
|
+
releaseDigest?: string;
|
|
165
|
+
port: GateLedgerPort;
|
|
166
|
+
actor?: string;
|
|
167
|
+
gitSha?: string;
|
|
168
|
+
now: Date;
|
|
169
|
+
/** What proves an approver or a rejecter (#5354). */
|
|
170
|
+
proof?: PipelineGateProof;
|
|
171
|
+
/**
|
|
172
|
+
* `--urgent` (#5355): after the stage's rejections, its urgent rule
|
|
173
|
+
* ({@link pipelineUrgentGate}) stands in for its gate. A rejection at
|
|
174
|
+
* `<stage>` or at `<stage>-urgent` stops it, and nothing is skipped.
|
|
175
|
+
*/
|
|
176
|
+
urgent?: boolean;
|
|
177
|
+
/** The change risk the release's cut carries (#5387). Absent: the release carries none, and each gate is as it was. */
|
|
178
|
+
risk?: ReleaseRisk;
|
|
179
|
+
/**
|
|
180
|
+
* The reasons the target stage's agent steps add to the risk its gate
|
|
181
|
+
* reads (#5358), from {@link pipelinePromoteAgentSteps}. They only raise
|
|
182
|
+
* the score. Absent: none.
|
|
183
|
+
*/
|
|
184
|
+
agentRisk?: readonly ChangeRiskReason[];
|
|
185
|
+
}): Promise<PipelineGatesOutcome>;
|
|
186
|
+
/** How {@link pipelineStageEntry} ended: the stage's gate passed and the release entered, or the stop. */
|
|
187
|
+
export type PipelineEntryOutcome = {
|
|
188
|
+
passed: true;
|
|
189
|
+
lines: string[];
|
|
190
|
+
entered?: StageLine;
|
|
191
|
+
urgent?: {
|
|
192
|
+
approval: GateResolutionRecord;
|
|
193
|
+
role: string;
|
|
194
|
+
};
|
|
195
|
+
} | ({
|
|
196
|
+
passed: false;
|
|
197
|
+
} & PipelinePromoteStop);
|
|
198
|
+
/** The release a promote deploys, as the stage log names it. */
|
|
199
|
+
export interface PipelineEntryRelease {
|
|
200
|
+
releaseDigest: string;
|
|
201
|
+
label?: string;
|
|
202
|
+
/** The commit it was cut from: the first stage counts as applied when its ledger holds a deploy of it. */
|
|
203
|
+
commit: string;
|
|
204
|
+
/** When it was cut, which orders it against another release waiting. */
|
|
205
|
+
cutAt?: string;
|
|
206
|
+
/** The change risk its cut carries (#5387), which each stage gate with `holds.risk` reads. */
|
|
207
|
+
risk?: ReleaseRisk;
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Take a release into stage `to` (#5353): the upstream stages a stage with
|
|
211
|
+
* `after` waits on, its queue, and then {@link pipelinePromoteGates}. With
|
|
212
|
+
* a pipeline that declares neither `after` nor `queue`, this is
|
|
213
|
+
* {@link pipelinePromoteGates} and writes no stage line.
|
|
214
|
+
*
|
|
215
|
+
* - Each upstream the release has not applied in stops the promote with
|
|
216
|
+
* exit 3, or with `allowSkip` goes through that stage's skip gate.
|
|
217
|
+
* - Under `queue: "replace"`, a release replaced at the stage is refused
|
|
218
|
+
* (exit 1). A newer release replaces each older one waiting; one older
|
|
219
|
+
* than a release waiting is replaced itself and refused. The release
|
|
220
|
+
* then waits, its gate is read, and while another release is in the
|
|
221
|
+
* stage it exits 3. A release already in the stage carries on without
|
|
222
|
+
* its gate read again.
|
|
223
|
+
* - Once the gate passes, the release's `entered` line is written; the
|
|
224
|
+
* caller writes its `finished` line with {@link pipelineStageFinished}.
|
|
225
|
+
*/
|
|
226
|
+
export declare function pipelineStageEntry(input: {
|
|
227
|
+
spec: PipelineSpec;
|
|
228
|
+
to: string;
|
|
229
|
+
skipped: readonly PipelineStage[];
|
|
230
|
+
/** The stages `to` follows, from {@link pipelinePromoteSource}, when it names `after`. */
|
|
231
|
+
upstreams?: readonly string[];
|
|
232
|
+
allowSkip?: boolean;
|
|
233
|
+
digest: string;
|
|
234
|
+
release?: PipelineEntryRelease;
|
|
235
|
+
/** The commits the first stage's ledger records deploys of. */
|
|
236
|
+
firstStageCommits?: ReadonlySet<string>;
|
|
237
|
+
port: GateLedgerPort;
|
|
238
|
+
log: StageLogPort;
|
|
239
|
+
/** `--urgent` (#5355): the stage's urgent rule ({@link pipelineUrgentGate}) in place of its gate. */
|
|
240
|
+
urgent?: boolean;
|
|
241
|
+
actor?: string;
|
|
242
|
+
gitSha?: string;
|
|
243
|
+
runId?: string;
|
|
244
|
+
now: Date;
|
|
245
|
+
/** What proves an approver or a rejecter (#5354), handed to {@link pipelinePromoteGates}. */
|
|
246
|
+
proof?: PipelineGateProof;
|
|
247
|
+
/** The reasons the stage's agent steps add to its gate's risk (#5358), handed to {@link pipelinePromoteGates}. */
|
|
248
|
+
agentRisk?: readonly ChangeRiskReason[];
|
|
249
|
+
}): Promise<PipelineEntryOutcome>;
|
|
250
|
+
/** Write the `finished` line for a release that entered a stage (#5353): `applied` when its deploy did, else `failed`. */
|
|
251
|
+
export declare function pipelineStageFinished(log: StageLogPort, entered: StageLine, result: "applied" | "failed", now: Date): Promise<void>;
|
|
252
|
+
/** The gate an urgent promote into `stage` is approved at (#5355). */
|
|
253
|
+
export declare function urgentGateName(stage: string): string;
|
|
254
|
+
/**
|
|
255
|
+
* The stages a release must have succeeded in before an urgent promote into
|
|
256
|
+
* `to` (#5355), in the pipeline's order. A stage with `after` (#5353) takes
|
|
257
|
+
* the stages it names and every stage those follow, by
|
|
258
|
+
* {@link stageUpstreams}. A stage without `after` takes every stage before it.
|
|
259
|
+
*/
|
|
260
|
+
export declare function urgentUpstreamStages(spec: Pick<PipelineSpec, "stages">, to: string): string[];
|
|
261
|
+
/**
|
|
262
|
+
* The stages upstream of `to` ({@link urgentUpstreamStages}) in which the
|
|
263
|
+
* release has not succeeded, each with the components it lacks there
|
|
264
|
+
* (#5355). `missingIn` answers for one stage. Empty when it succeeded in
|
|
265
|
+
* every one.
|
|
266
|
+
*/
|
|
267
|
+
export declare function pipelineUrgentUpstream(input: {
|
|
268
|
+
spec: PipelineSpec;
|
|
269
|
+
to: string;
|
|
270
|
+
missingIn: (stage: string) => Promise<string[]>;
|
|
271
|
+
}): Promise<{
|
|
272
|
+
stage: string;
|
|
273
|
+
missing: string[];
|
|
274
|
+
}[]>;
|
|
275
|
+
/** The refusal for a release that has not succeeded in every stage before the one an urgent promote goes to. */
|
|
276
|
+
export declare function urgentUpstreamStop(release: string, missing: readonly {
|
|
277
|
+
stage: string;
|
|
278
|
+
missing: string[];
|
|
279
|
+
}[]): PipelinePromoteStop;
|
|
280
|
+
/** What {@link pipelineUrgentGate} decided: passed on an approval, or the stop. */
|
|
281
|
+
export type PipelineUrgentOutcome = {
|
|
282
|
+
passed: true;
|
|
283
|
+
lines: string[];
|
|
284
|
+
approval: GateResolutionRecord;
|
|
285
|
+
role: string;
|
|
286
|
+
} | ({
|
|
287
|
+
passed: false;
|
|
288
|
+
} & PipelinePromoteStop);
|
|
289
|
+
/**
|
|
290
|
+
* The urgent rule of stage `to` (#5355), in place of its gate: one approval
|
|
291
|
+
* of `<stage>-urgent` bound to the release's digest, from an approver the
|
|
292
|
+
* port's judge proves and gives the rule's role. The quorum rule is
|
|
293
|
+
* `{ count: 1, roles: [role], proven: true }`, so an unproven line never
|
|
294
|
+
* counts. The approval is spent on `_gates/<pipeline>/applied.jsonl`.
|
|
295
|
+
*/
|
|
296
|
+
export declare function pipelineUrgentGate(input: {
|
|
297
|
+
spec: PipelineSpec;
|
|
298
|
+
to: string;
|
|
299
|
+
digest: string;
|
|
300
|
+
releaseDigest?: string;
|
|
301
|
+
port: GateLedgerPort;
|
|
302
|
+
gitSha?: string;
|
|
303
|
+
now: Date;
|
|
304
|
+
}): Promise<PipelineUrgentOutcome>;
|
|
305
|
+
/**
|
|
306
|
+
* The soak that held a promotion (#5328): the stage whose soak it is, which
|
|
307
|
+
* is the stage a failed check of it rolls back, and the members that stage
|
|
308
|
+
* applied of what is promoted.
|
|
309
|
+
*/
|
|
310
|
+
export interface SoakHeldBy {
|
|
311
|
+
stage: string;
|
|
312
|
+
members: string[];
|
|
313
|
+
}
|
|
314
|
+
/**
|
|
315
|
+
* Every soak in front of a promotion into `to`, in order (#5326, #5327):
|
|
316
|
+
* the soak of each stage promoted from (`upstreams` on a join, else
|
|
317
|
+
* `from`), then the soak of each canary stage `to` follows and is not one
|
|
318
|
+
* of those ({@link canaryStagesBefore}). Each is read through its own gate
|
|
319
|
+
* by {@link pipelinePromoteSoak}; the first that holds stops the promote.
|
|
320
|
+
* `items` gives what a stage applied of what is promoted, and `read` its
|
|
321
|
+
* check reader. A canary with nothing applied says so in `notes` and
|
|
322
|
+
* holds, since its clock cannot start. `lines` are the passed soaks' lines.
|
|
323
|
+
* On a hold, `heldBy` names the stage whose soak held ({@link SoakHeldBy}).
|
|
324
|
+
*/
|
|
325
|
+
export declare function pipelinePromoteSoaks(input: {
|
|
326
|
+
spec: PipelineSpec;
|
|
327
|
+
from: string;
|
|
328
|
+
to: string;
|
|
329
|
+
upstreams?: readonly string[];
|
|
330
|
+
items: (stage: string) => Promise<readonly {
|
|
331
|
+
component: string;
|
|
332
|
+
source: {
|
|
333
|
+
timestamp: string;
|
|
334
|
+
};
|
|
335
|
+
}[]>;
|
|
336
|
+
digest: string;
|
|
337
|
+
releaseDigest?: string;
|
|
338
|
+
port: GateLedgerPort;
|
|
339
|
+
read: (stage: string) => SoakCheckReader;
|
|
340
|
+
now: Date;
|
|
341
|
+
gitSha?: string;
|
|
342
|
+
notify?: SoakGateInput["notify"];
|
|
343
|
+
}): Promise<SoakGateOutcome & {
|
|
344
|
+
notes: string[];
|
|
345
|
+
heldBy?: SoakHeldBy;
|
|
346
|
+
}>;
|
|
347
|
+
/**
|
|
348
|
+
* The soak of stage `from` in front of a promotion into `to` (#5326): each
|
|
349
|
+
* promoted component is a member that applied in `from` at its source
|
|
350
|
+
* record's time. Passed when `from` declares no soak or is no stage of the
|
|
351
|
+
* pipeline.
|
|
352
|
+
*/
|
|
353
|
+
export declare function pipelinePromoteSoak(input: {
|
|
354
|
+
spec: PipelineSpec;
|
|
355
|
+
from: string;
|
|
356
|
+
to: string;
|
|
357
|
+
items: readonly {
|
|
358
|
+
component: string;
|
|
359
|
+
source: {
|
|
360
|
+
timestamp: string;
|
|
361
|
+
};
|
|
362
|
+
}[];
|
|
363
|
+
digest: string;
|
|
364
|
+
releaseDigest?: string;
|
|
365
|
+
port: GateLedgerPort;
|
|
366
|
+
read: SoakCheckReader;
|
|
367
|
+
now: Date;
|
|
368
|
+
gitSha?: string;
|
|
369
|
+
notify?: SoakGateInput["notify"];
|
|
370
|
+
}): Promise<SoakGateOutcome>;
|
|
371
|
+
/** What a stage gate's policy said of the agent answers: a verdict, or undefined when no policy is named at base. */
|
|
372
|
+
export type AgentPolicyVerdict = {
|
|
373
|
+
result: "passed" | "denied" | "held" | "error";
|
|
374
|
+
reasons: string[];
|
|
375
|
+
} | undefined;
|
|
376
|
+
/** What {@link pipelinePromoteAgentSteps} decided. `agent` is what the policy read as `input.agent`. */
|
|
377
|
+
export type PipelineAgentStepsOutcome = {
|
|
378
|
+
passed: true;
|
|
379
|
+
lines: string[];
|
|
380
|
+
agent: Record<string, PolicyAgentAnswer>;
|
|
381
|
+
/** The reasons the answers' levels add to the risk the stage gate reads (#5325): hand them to {@link pipelineStageEntry} as `agentRisk`. */
|
|
382
|
+
risk: ChangeRiskReason[];
|
|
383
|
+
} | ({
|
|
384
|
+
passed: false;
|
|
385
|
+
} & PipelinePromoteStop);
|
|
386
|
+
/**
|
|
387
|
+
* The agent steps part of a promote (#5358), before the stage's gate: every
|
|
388
|
+
* step of the stage `to` needs an answer for the release that matches its
|
|
389
|
+
* schema, or the promote holds (exit 3) and says why. With
|
|
390
|
+
* `gate.holds.policy`, `policy` runs the workspace's `ci.policy` with the
|
|
391
|
+
* answers as `input.agent`: a deny refuses the promote, a hold is printed,
|
|
392
|
+
* and the gate still waits for a person either way. Nothing here passes a
|
|
393
|
+
* gate.
|
|
394
|
+
*/
|
|
395
|
+
export declare function pipelinePromoteAgentSteps(input: {
|
|
396
|
+
spec: PipelineSpec;
|
|
397
|
+
to: string;
|
|
398
|
+
release?: {
|
|
399
|
+
digest: string;
|
|
400
|
+
label?: string | null;
|
|
401
|
+
};
|
|
402
|
+
port: StageAgentAnswerPort;
|
|
403
|
+
policy?: (agent: Record<string, PolicyAgentAnswer>) => Promise<AgentPolicyVerdict>;
|
|
404
|
+
}): Promise<PipelineAgentStepsOutcome>;
|