@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,425 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Release artifacts (#5356): named values a stage publishes for the release
|
|
3
|
+
* it applied, which later stages and other repositories read.
|
|
4
|
+
*
|
|
5
|
+
* A stage often produces a value a later stage or another repository needs:
|
|
6
|
+
* a cluster endpoint, an image tag, a database host. A stage declares what
|
|
7
|
+
* it publishes under `publish`, each artifact by name:
|
|
8
|
+
*
|
|
9
|
+
* {
|
|
10
|
+
* name: "dev",
|
|
11
|
+
* waves: [...],
|
|
12
|
+
* publish: {
|
|
13
|
+
* endpoint: { member: "cluster", output: "endpoint" },
|
|
14
|
+
* db_password: { secret: { awsSecretsManager: "arn:aws:secretsmanager:...:secret:dev/db" } },
|
|
15
|
+
* },
|
|
16
|
+
* }
|
|
17
|
+
*
|
|
18
|
+
* - `{ member, output }` publishes the member's output as the stage left it
|
|
19
|
+
* once it applied: a string, or any JSON value. An output the engine marks
|
|
20
|
+
* sensitive or secret (a Terraform output with `sensitive = true`, a Pulumi
|
|
21
|
+
* secret) is refused, and nothing of that publish is recorded.
|
|
22
|
+
* - `{ secret }` publishes where a secret is kept, in the words of #5348's
|
|
23
|
+
* config and secret sets (a forge secret's name, an AWS Secrets Manager
|
|
24
|
+
* secret, a Google Secret Manager version or an Azure Key Vault secret).
|
|
25
|
+
* The reference is recorded and the secret itself is never read.
|
|
26
|
+
*
|
|
27
|
+
* Artifacts are values, never files: a value's JSON text is at most
|
|
28
|
+
* {@link STAGE_ARTIFACT_MAX_BYTES}.
|
|
29
|
+
*
|
|
30
|
+
* Each publish is one line of `<stage>/artifacts.jsonl` on `chant/lifecycle`
|
|
31
|
+
* ({@link STAGE_ARTIFACTS_FILE}), beside the stage's `releases.jsonl`: the
|
|
32
|
+
* pipeline, the stage, the release digest, its label, the commit, and every
|
|
33
|
+
* artifact the stage declares. The first stage publishes once its last wave
|
|
34
|
+
* applied and the merge cut its release (an after-apply hook after the cut,
|
|
35
|
+
* `./stages.ts`). A later stage publishes once `chant components promote
|
|
36
|
+
* --to <stage> --release <ref>` deployed.
|
|
37
|
+
*
|
|
38
|
+
* A later stage reads an upstream stage's artifact of the same release under
|
|
39
|
+
* `reads`, keyed by the variable name its deploy gets the value in:
|
|
40
|
+
*
|
|
41
|
+
* { name: "staging", waves: [...], reads: { TF_VAR_dev_endpoint: { stage: "dev", artifact: "endpoint" } } }
|
|
42
|
+
*
|
|
43
|
+
* `chant build` refuses a read of a stage that is not upstream of the reading
|
|
44
|
+
* stage (#5385): earlier in the list when no stage declares `after`, else an
|
|
45
|
+
* ancestor through `after`, so a sibling is refused. It also refuses a read of an artifact that stage does not publish
|
|
46
|
+
* ({@link stageArtifactsSpecProblems}). The promote refuses before anything
|
|
47
|
+
* deploys when the upstream has not published the artifact for the release
|
|
48
|
+
* being promoted ({@link resolveStageReads}). A string reaches the variable
|
|
49
|
+
* as it is, any other JSON value as its JSON text, and a secret as its
|
|
50
|
+
* reference's JSON.
|
|
51
|
+
*
|
|
52
|
+
* Another repository reads with {@link readStageArtifacts} (`chant pipeline
|
|
53
|
+
* artifacts read --stage <stage> --from <dir>`): the artifacts of the release
|
|
54
|
+
* the stage last published for, or of a named release. The `<product>-applied`
|
|
55
|
+
* dispatch carries the release digest when `control.release` is set
|
|
56
|
+
* (../control/dispatch.ts), and the read takes it from `CHANT_CONTROL_RELEASE`,
|
|
57
|
+
* so a downstream run pins to the release the member applied.
|
|
58
|
+
*
|
|
59
|
+
* Off by default: a stage with no `publish` publishes nothing, and its jobs
|
|
60
|
+
* render as before.
|
|
61
|
+
*
|
|
62
|
+
* This module imports types alone at load, and the ledger at call time.
|
|
63
|
+
*/
|
|
64
|
+
import { environmentSecretSource } from "../components/environment-sets.js";
|
|
65
|
+
/**
|
|
66
|
+
* The first chant with release artifacts (#5356): a stage's `publish` and
|
|
67
|
+
* `reads` in `.chant/pipeline.ts`, the build's refusal of a read no upstream
|
|
68
|
+
* publishes, the publish after the first stage's release cut and after a
|
|
69
|
+
* promote under a release, `chant pipeline artifacts publish|read`, `chant
|
|
70
|
+
* pipeline release-of`, and `control.release` on the `<product>-applied`
|
|
71
|
+
* dispatch. A product feature-detects release artifacts on this name.
|
|
72
|
+
*/
|
|
73
|
+
export const STAGE_ARTIFACTS_FLOOR = "0.124.110";
|
|
74
|
+
/** The ledger file a stage's publishes are kept in, beside its `releases.jsonl`. */
|
|
75
|
+
export const STAGE_ARTIFACTS_FILE = "artifacts.jsonl";
|
|
76
|
+
/** The record kind a line of {@link STAGE_ARTIFACTS_FILE} carries. A reader skips any other. */
|
|
77
|
+
export const STAGE_ARTIFACTS_KIND = "stage-artifacts";
|
|
78
|
+
/** The largest JSON text one artifact's value may have, in bytes. An artifact is a value, never a file. */
|
|
79
|
+
export const STAGE_ARTIFACT_MAX_BYTES = 65536;
|
|
80
|
+
/** The variable a read takes its release from when none is named: the one the `<product>-applied` dispatch carries. */
|
|
81
|
+
export const STAGE_ARTIFACTS_RELEASE_ENV = "CHANT_CONTROL_RELEASE";
|
|
82
|
+
const ARTIFACT_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
|
|
83
|
+
const VARIABLE = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
84
|
+
const isMap = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
85
|
+
/** What is wrong with a stage's `publish`, one line each. */
|
|
86
|
+
export function stagePublishProblems(publish, at) {
|
|
87
|
+
if (publish === undefined)
|
|
88
|
+
return [];
|
|
89
|
+
if (!isMap(publish))
|
|
90
|
+
return [`${at}.publish must be a map of artifact name to { "member", "output" } or { "secret" }`];
|
|
91
|
+
const out = [];
|
|
92
|
+
for (const [name, source] of Object.entries(publish)) {
|
|
93
|
+
const where = `${at}.publish.${name}`;
|
|
94
|
+
if (!ARTIFACT_NAME.test(name))
|
|
95
|
+
out.push(`${at}.publish names ${JSON.stringify(name)}; an artifact's name is a letter, then letters, digits, "-" and "_"`);
|
|
96
|
+
if (!isMap(source)) {
|
|
97
|
+
out.push(`${where} must be { "member", "output" } or { "secret" }`);
|
|
98
|
+
continue;
|
|
99
|
+
}
|
|
100
|
+
const keys = Object.keys(source).sort().join(",");
|
|
101
|
+
if (keys === "secret") {
|
|
102
|
+
const found = environmentSecretSource(source.secret);
|
|
103
|
+
if (typeof found === "string")
|
|
104
|
+
out.push(`${where}.secret ${found}`);
|
|
105
|
+
}
|
|
106
|
+
else if (keys === "member,output") {
|
|
107
|
+
if (typeof source.member !== "string" || source.member.trim() === "")
|
|
108
|
+
out.push(`${where}.member must name a member`);
|
|
109
|
+
if (typeof source.output !== "string" || source.output.trim() === "")
|
|
110
|
+
out.push(`${where}.output must name one of the member's outputs`);
|
|
111
|
+
}
|
|
112
|
+
else
|
|
113
|
+
out.push(`${where} must be { "member", "output" } or { "secret" }, and sets ${Object.keys(source).join(", ") || "nothing"}`);
|
|
114
|
+
}
|
|
115
|
+
return out;
|
|
116
|
+
}
|
|
117
|
+
/** What is wrong with a stage's `reads` on its own, one line each. Whether an upstream publishes each is {@link stageArtifactsSpecProblems}'s. */
|
|
118
|
+
export function stageReadsProblems(reads, at) {
|
|
119
|
+
if (reads === undefined)
|
|
120
|
+
return [];
|
|
121
|
+
if (!isMap(reads))
|
|
122
|
+
return [`${at}.reads must be a map of variable name to { "stage", "artifact" }`];
|
|
123
|
+
const out = [];
|
|
124
|
+
for (const [name, read] of Object.entries(reads)) {
|
|
125
|
+
const where = `${at}.reads.${name}`;
|
|
126
|
+
if (!VARIABLE.test(name))
|
|
127
|
+
out.push(`${at}.reads names ${JSON.stringify(name)}, which is not a variable name`);
|
|
128
|
+
else if (name.startsWith("CHANT_"))
|
|
129
|
+
out.push(`${at}.reads names ${name}; a variable starting CHANT_ is one chant's jobs set themselves`);
|
|
130
|
+
if (!isMap(read) || Object.keys(read).sort().join(",") !== "artifact,stage" || typeof read.stage !== "string" || typeof read.artifact !== "string") {
|
|
131
|
+
out.push(`${where} must be { "stage", "artifact" }`);
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
return out;
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* The indexes of every stage upstream of stage `index`, through `after`
|
|
138
|
+
* (#5353): a stage follows its `after`, else the stage before it. Mirrors
|
|
139
|
+
* `stageUpstreams` in ./spec, which this module cannot import at load. A
|
|
140
|
+
* cycle or an unknown name ends that path.
|
|
141
|
+
*/
|
|
142
|
+
export function ancestorsOf(stages, index) {
|
|
143
|
+
const found = new Set();
|
|
144
|
+
const visit = (i) => {
|
|
145
|
+
const stage = stages[i];
|
|
146
|
+
const ups = Array.isArray(stage.after) ? stage.after.map((n) => stages.findIndex((s) => s.name === n)) : i === 0 ? [] : [i - 1];
|
|
147
|
+
for (const up of ups) {
|
|
148
|
+
if (up < 0 || found.has(up))
|
|
149
|
+
continue;
|
|
150
|
+
found.add(up);
|
|
151
|
+
visit(up);
|
|
152
|
+
}
|
|
153
|
+
};
|
|
154
|
+
visit(index);
|
|
155
|
+
return found;
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* The reads no upstream publishes (#5356), one line each: a read of a stage
|
|
159
|
+
* that is not before the reading stage in promotion order, or of an
|
|
160
|
+
* artifact that stage's `publish` does not name, and a first stage that
|
|
161
|
+
* publishes while the merge cuts no release. `chant build` refuses each.
|
|
162
|
+
*/
|
|
163
|
+
export function stageArtifactsSpecProblems(spec) {
|
|
164
|
+
if (!Array.isArray(spec.stages))
|
|
165
|
+
return [];
|
|
166
|
+
const stages = spec.stages.filter(isMap);
|
|
167
|
+
const out = [];
|
|
168
|
+
const first = stages[0];
|
|
169
|
+
const cut = !(isMap(spec.release) && spec.release.cut === false);
|
|
170
|
+
if (first && isMap(first.publish) && Object.keys(first.publish).length > 0 && !cut) {
|
|
171
|
+
out.push(`stage "${first.name}" publishes artifacts, which are kept for the release the merge cuts, and release.cut is false`);
|
|
172
|
+
}
|
|
173
|
+
const graph = stages.some((s) => s.after !== undefined);
|
|
174
|
+
stages.forEach((stage, i) => {
|
|
175
|
+
if (!isMap(stage.reads))
|
|
176
|
+
return;
|
|
177
|
+
const upstream = graph ? ancestorsOf(stages, i) : undefined;
|
|
178
|
+
for (const [name, read] of Object.entries(stage.reads)) {
|
|
179
|
+
if (!isMap(read) || typeof read.stage !== "string" || typeof read.artifact !== "string")
|
|
180
|
+
continue;
|
|
181
|
+
const at = stages.findIndex((s) => s.name === read.stage);
|
|
182
|
+
if (at < 0)
|
|
183
|
+
out.push(`stage "${stage.name}" reads ${name} from stage "${read.stage}", which the pipeline does not have`);
|
|
184
|
+
else if (upstream && !upstream.has(at)) {
|
|
185
|
+
out.push(`stage "${stage.name}" reads ${name} from stage "${read.stage}", which "${stage.name}" does not follow through after; a stage reads its upstream stages, and "${read.stage}" is not one of them`);
|
|
186
|
+
}
|
|
187
|
+
else if (!upstream && at >= i)
|
|
188
|
+
out.push(`stage "${stage.name}" reads ${name} from stage "${read.stage}", which comes ${at === i ? "at the same place" : "after it"} in promotion order; a stage reads the stages before it`);
|
|
189
|
+
else if (!isMap(stages[at].publish) || !Object.prototype.hasOwnProperty.call(stages[at].publish, read.artifact)) {
|
|
190
|
+
out.push(`stage "${stage.name}" reads ${name} from artifact "${read.artifact}" of stage "${read.stage}", which that stage never publishes`);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
});
|
|
194
|
+
return out;
|
|
195
|
+
}
|
|
196
|
+
/** The records in a ledger file's text, oldest first, malformed lines left out. */
|
|
197
|
+
export function parseStageArtifactRecords(text) {
|
|
198
|
+
const out = [];
|
|
199
|
+
for (const line of text.split("\n")) {
|
|
200
|
+
if (line.trim() === "")
|
|
201
|
+
continue;
|
|
202
|
+
try {
|
|
203
|
+
const r = JSON.parse(line);
|
|
204
|
+
if (r.version === 1 && r.kind === STAGE_ARTIFACTS_KIND && typeof r.stage === "string" && typeof r.release === "string" && isMap(r.artifacts))
|
|
205
|
+
out.push(r);
|
|
206
|
+
}
|
|
207
|
+
catch {
|
|
208
|
+
// A line that does not read is skipped.
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
return out;
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* {@link StageArtifactPort} on `chant/lifecycle`, at `<stage>/artifacts.jsonl`.
|
|
215
|
+
* `cwd` may be a checkout of another repository, or a directory holding its
|
|
216
|
+
* `chant/lifecycle` alone; `member` or `ledgerPrefix` names a workspace
|
|
217
|
+
* member's records there.
|
|
218
|
+
*/
|
|
219
|
+
export function gitStageArtifactPort(opts = {}) {
|
|
220
|
+
return {
|
|
221
|
+
async read(stage) {
|
|
222
|
+
const { readBlobFromPath } = await import("../lifecycle/git.js");
|
|
223
|
+
return parseStageArtifactRecords((await readBlobFromPath(stage, STAGE_ARTIFACTS_FILE, opts)) ?? "");
|
|
224
|
+
},
|
|
225
|
+
async append(stage, record) {
|
|
226
|
+
const { appendLedgerLine } = await import("../lifecycle/git.js");
|
|
227
|
+
await appendLedgerLine(stage, STAGE_ARTIFACTS_FILE, JSON.stringify(record), `chant: artifacts of ${record.stage} for ${record.label ?? record.release}`, opts.cwd ? { cwd: opts.cwd } : {});
|
|
228
|
+
},
|
|
229
|
+
};
|
|
230
|
+
}
|
|
231
|
+
/** The JSON value `v` is, or why it is not one. Undefined, functions and the like are not. */
|
|
232
|
+
function jsonValueOf(v) {
|
|
233
|
+
let text;
|
|
234
|
+
try {
|
|
235
|
+
text = JSON.stringify(v);
|
|
236
|
+
}
|
|
237
|
+
catch {
|
|
238
|
+
return "is not a JSON value";
|
|
239
|
+
}
|
|
240
|
+
if (text === undefined)
|
|
241
|
+
return "is not a JSON value";
|
|
242
|
+
return { value: JSON.parse(text), bytes: Buffer.byteLength(text, "utf8") };
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
245
|
+
* Publish the artifacts `stage` declares for `release` (#5356): every one or
|
|
246
|
+
* none. A member output the engine marks sensitive is refused, by name; a
|
|
247
|
+
* secret is recorded as where it is kept. The record holds no value the
|
|
248
|
+
* engine marks sensitive and no secret, and neither does a refusal.
|
|
249
|
+
*/
|
|
250
|
+
export async function publishStageArtifacts(input) {
|
|
251
|
+
const stage = input.spec.stages.find((s) => s.name === input.stage);
|
|
252
|
+
if (!stage)
|
|
253
|
+
return { status: "refused", stage: input.stage, problems: [`the pipeline "${input.spec.name}" has no stage "${input.stage}"`] };
|
|
254
|
+
const declared = Object.entries(stage.publish ?? {});
|
|
255
|
+
if (declared.length === 0)
|
|
256
|
+
return { status: "none", stage: stage.name };
|
|
257
|
+
const problems = [];
|
|
258
|
+
const artifacts = {};
|
|
259
|
+
const cache = new Map();
|
|
260
|
+
for (const [name, source] of declared.sort(([a], [b]) => a.localeCompare(b))) {
|
|
261
|
+
if ("secret" in source) {
|
|
262
|
+
const found = environmentSecretSource(source.secret);
|
|
263
|
+
if (typeof found === "string")
|
|
264
|
+
problems.push(`${name}: the secret ${found}`);
|
|
265
|
+
else
|
|
266
|
+
artifacts[name] = { kind: "secret", source: found };
|
|
267
|
+
continue;
|
|
268
|
+
}
|
|
269
|
+
if (!cache.has(source.member))
|
|
270
|
+
cache.set(source.member, input.outputsOf(source.member));
|
|
271
|
+
const got = await cache.get(source.member);
|
|
272
|
+
if (!got) {
|
|
273
|
+
problems.push(`${name}: ${source.member}'s steps say no outputs`);
|
|
274
|
+
continue;
|
|
275
|
+
}
|
|
276
|
+
if (got.sensitive.includes(source.output)) {
|
|
277
|
+
problems.push(`${name}: ${source.member}'s output ${source.output} is marked sensitive, so it is not published; publish where it is kept with { "secret" } instead`);
|
|
278
|
+
continue;
|
|
279
|
+
}
|
|
280
|
+
if (!Object.prototype.hasOwnProperty.call(got.outputs, source.output)) {
|
|
281
|
+
problems.push(`${name}: ${source.member} has no output ${source.output}`);
|
|
282
|
+
continue;
|
|
283
|
+
}
|
|
284
|
+
const value = jsonValueOf(got.outputs[source.output]);
|
|
285
|
+
if (typeof value === "string")
|
|
286
|
+
problems.push(`${name}: ${source.member}'s output ${source.output} ${value}`);
|
|
287
|
+
else if (value.bytes > STAGE_ARTIFACT_MAX_BYTES)
|
|
288
|
+
problems.push(`${name}: ${source.member}'s output ${source.output} is ${value.bytes} bytes as JSON, above the ${STAGE_ARTIFACT_MAX_BYTES} an artifact holds; an artifact is a value, never a file`);
|
|
289
|
+
else
|
|
290
|
+
artifacts[name] = { kind: "value", value: value.value, member: source.member, output: source.output };
|
|
291
|
+
}
|
|
292
|
+
if (problems.length > 0)
|
|
293
|
+
return { status: "refused", stage: stage.name, problems };
|
|
294
|
+
const record = {
|
|
295
|
+
version: 1,
|
|
296
|
+
kind: STAGE_ARTIFACTS_KIND,
|
|
297
|
+
pipeline: input.spec.name,
|
|
298
|
+
stage: stage.name,
|
|
299
|
+
release: input.release.digest,
|
|
300
|
+
...(input.release.label ? { label: input.release.label } : {}),
|
|
301
|
+
...(input.release.gitSha ? { gitSha: input.release.gitSha } : {}),
|
|
302
|
+
at: (input.now ?? (() => new Date().toISOString()))(),
|
|
303
|
+
artifacts,
|
|
304
|
+
};
|
|
305
|
+
if (input.dryRun)
|
|
306
|
+
return { status: "published", record, dryRun: true };
|
|
307
|
+
await input.port.append(stage.name, record);
|
|
308
|
+
return { status: "published", record };
|
|
309
|
+
}
|
|
310
|
+
/**
|
|
311
|
+
* The artifacts `stage` published (#5356): for `release` when named (a
|
|
312
|
+
* digest), else for the release it last published for. The latest record
|
|
313
|
+
* wins when a release was published twice. Undefined when there is none.
|
|
314
|
+
*/
|
|
315
|
+
export async function readStageArtifacts(port, query) {
|
|
316
|
+
const records = (await port.read(query.stage)).filter((r) => r.stage === query.stage && (query.release === undefined || r.release === query.release));
|
|
317
|
+
return records[records.length - 1];
|
|
318
|
+
}
|
|
319
|
+
/** The text a variable holds for an artifact: a string as it is, any other value as JSON, a secret as its reference's JSON. */
|
|
320
|
+
export function stageArtifactText(entry) {
|
|
321
|
+
if (entry.kind === "secret")
|
|
322
|
+
return JSON.stringify(entry.source);
|
|
323
|
+
return typeof entry.value === "string" ? entry.value : JSON.stringify(entry.value);
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* The variables `stage`'s reads hold for `release` (#5356), each from the
|
|
327
|
+
* upstream stage's record of that same release. Refused, naming each, when
|
|
328
|
+
* an upstream has not published the artifact for this release, or when the
|
|
329
|
+
* stage reads and no release is named. Empty when the stage reads nothing.
|
|
330
|
+
*/
|
|
331
|
+
export async function resolveStageReads(spec, stage, release, port) {
|
|
332
|
+
const reads = Object.entries(spec.stages.find((s) => s.name === stage)?.reads ?? {}).sort(([a], [b]) => a.localeCompare(b));
|
|
333
|
+
if (reads.length === 0)
|
|
334
|
+
return { status: "resolved", variables: {}, reads: [] };
|
|
335
|
+
if (release === undefined)
|
|
336
|
+
return { status: "refused", problems: [`stage "${stage}" reads ${reads.map(([n]) => n).join(", ")} from the release it takes; promote a release with --release <label|digest>`] };
|
|
337
|
+
const variables = {};
|
|
338
|
+
const resolved = [];
|
|
339
|
+
const problems = [];
|
|
340
|
+
const byStage = new Map();
|
|
341
|
+
for (const [variable, read] of reads) {
|
|
342
|
+
if (!byStage.has(read.stage))
|
|
343
|
+
byStage.set(read.stage, readStageArtifacts(port, { stage: read.stage, release }));
|
|
344
|
+
const record = await byStage.get(read.stage);
|
|
345
|
+
const entry = record?.artifacts[read.artifact];
|
|
346
|
+
if (!entry) {
|
|
347
|
+
problems.push(`stage "${stage}" reads ${variable} from artifact "${read.artifact}" of stage "${read.stage}", which ${record ? "that stage's publish for" : "that stage has not published for"} release ${release}${record ? " does not hold" : ""}`);
|
|
348
|
+
continue;
|
|
349
|
+
}
|
|
350
|
+
variables[variable] = stageArtifactText(entry);
|
|
351
|
+
resolved.push({ variable, stage: read.stage, artifact: read.artifact, kind: entry.kind });
|
|
352
|
+
}
|
|
353
|
+
return problems.length > 0 ? { status: "refused", problems } : { status: "resolved", variables, reads: resolved };
|
|
354
|
+
}
|
|
355
|
+
/** A short form of a release digest for a line a person reads. */
|
|
356
|
+
function shortRelease(record) {
|
|
357
|
+
return record.label ?? record.release;
|
|
358
|
+
}
|
|
359
|
+
/**
|
|
360
|
+
* The note a publish or a read prints (Markdown): each artifact, a value as
|
|
361
|
+
* JSON, a secret as where it is kept. Holds no secret: a secret artifact's
|
|
362
|
+
* record never holds one.
|
|
363
|
+
*/
|
|
364
|
+
export function stageArtifactsNote(record) {
|
|
365
|
+
const lines = [`### Artifacts of stage ${record.stage} for release ${shortRelease(record)}`, ""];
|
|
366
|
+
const names = Object.keys(record.artifacts).sort();
|
|
367
|
+
if (names.length === 0)
|
|
368
|
+
lines.push("None.");
|
|
369
|
+
for (const name of names) {
|
|
370
|
+
const entry = record.artifacts[name];
|
|
371
|
+
if (entry.kind === "secret")
|
|
372
|
+
lines.push(`- \`${name}\`: a secret kept in ${secretPlace(entry.source)}`);
|
|
373
|
+
else
|
|
374
|
+
lines.push(`- \`${name}\` = \`${JSON.stringify(entry.value)}\` (${entry.member}'s output ${entry.output})`);
|
|
375
|
+
}
|
|
376
|
+
lines.push("", `Release \`${record.release}\`${record.gitSha ? `, commit ${record.gitSha.slice(0, 12)}` : ""}, published ${record.at}.`);
|
|
377
|
+
return `${lines.join("\n")}\n`;
|
|
378
|
+
}
|
|
379
|
+
/** Where a secret is kept, as a person reads it. */
|
|
380
|
+
function secretPlace(source) {
|
|
381
|
+
switch (source.store) {
|
|
382
|
+
case "forge":
|
|
383
|
+
return `the forge secret ${source.secret}`;
|
|
384
|
+
case "aws-secrets-manager":
|
|
385
|
+
return `AWS Secrets Manager, ${source.id}${source.jsonKey ? ` (key ${source.jsonKey})` : ""}`;
|
|
386
|
+
case "gcp-secret-manager":
|
|
387
|
+
return `Google Secret Manager, ${source.name}`;
|
|
388
|
+
default:
|
|
389
|
+
return `Azure Key Vault, ${source.id}`;
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
/**
|
|
393
|
+
* The release cut from `commit` (#5356): the newest cut whose release names
|
|
394
|
+
* that commit, with its label. Undefined when none was cut from it.
|
|
395
|
+
*/
|
|
396
|
+
export async function releaseCutFrom(commit, opts = {}) {
|
|
397
|
+
const { readCuts, readRelease } = await import("../lifecycle/release-store.js");
|
|
398
|
+
const { cuts } = await readCuts(opts);
|
|
399
|
+
const seen = new Set();
|
|
400
|
+
for (const cut of [...cuts].reverse()) {
|
|
401
|
+
if (seen.has(cut.releaseDigest))
|
|
402
|
+
continue;
|
|
403
|
+
seen.add(cut.releaseDigest);
|
|
404
|
+
const release = await readRelease(cut.releaseDigest, opts);
|
|
405
|
+
if (release && (release.commit === commit || (commit.length >= 7 && release.commit.startsWith(commit))))
|
|
406
|
+
return { digest: release.releaseDigest, label: cut.label, commit: release.commit };
|
|
407
|
+
}
|
|
408
|
+
return undefined;
|
|
409
|
+
}
|
|
410
|
+
/** The variables of {@link resolveStageReads} set in `env` for the length of `run`, then put back as they were. */
|
|
411
|
+
export async function withStageReadVariables(variables, run, env = process.env) {
|
|
412
|
+
const before = new Map(Object.keys(variables).map((k) => [k, env[k]]));
|
|
413
|
+
Object.assign(env, variables);
|
|
414
|
+
try {
|
|
415
|
+
return await run();
|
|
416
|
+
}
|
|
417
|
+
finally {
|
|
418
|
+
for (const [k, v] of before) {
|
|
419
|
+
if (v === undefined)
|
|
420
|
+
delete env[k];
|
|
421
|
+
else
|
|
422
|
+
env[k] = v;
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The folded pipeline's diff (#5324): what a pull request changes in the
|
|
3
|
+
* pipeline, as lines of its folded spec, for the plan note and for a
|
|
4
|
+
* product's `ci --check`.
|
|
5
|
+
*/
|
|
6
|
+
import { type PipelineShow } from "./read.js";
|
|
7
|
+
import { type PipelineSpec } from "./spec.js";
|
|
8
|
+
import { type GateQuorumNode } from "../op/gate-quorum.js";
|
|
9
|
+
/**
|
|
10
|
+
* The plan note's section for the soaks a change passes through once it
|
|
11
|
+
* merges (#5326): each stage's soak, with the stages it holds, and each
|
|
12
|
+
* wave's, with the wave it holds. Read from the pipeline at base, which is
|
|
13
|
+
* where the gates are read. Undefined when nothing soaks.
|
|
14
|
+
*/
|
|
15
|
+
export declare function pipelineSoakSection(spec: PipelineSpec | undefined): string | undefined;
|
|
16
|
+
/** The folded spec's lines, as the diff compares them. */
|
|
17
|
+
export declare function pipelineSpecLines(spec: PipelineSpec | undefined): string[];
|
|
18
|
+
/** A line diff of `before` against `after`, each line marked ` `, `-` or `+`. Unchanged runs longer than `context` lines each side are cut. */
|
|
19
|
+
export declare function lineDiff(before: readonly string[], after: readonly string[], context?: number): string[];
|
|
20
|
+
/** What a pull request does to the pipeline, read at two commits. */
|
|
21
|
+
export interface PipelineChange {
|
|
22
|
+
/** The folded spec's diff; empty when the folded spec did not change. */
|
|
23
|
+
diff: string[];
|
|
24
|
+
/** The head's file is outside the subset: its finding, in place of a diff. */
|
|
25
|
+
refused?: string;
|
|
26
|
+
/**
|
|
27
|
+
* What a reader of the change needs before it merges (#5354), one line
|
|
28
|
+
* each: each stage held at the head, each hold the change lifts, with what
|
|
29
|
+
* the person who lifts it reads first, and each stage gate whose rules
|
|
30
|
+
* are named or grouped. Absent when there is none.
|
|
31
|
+
*/
|
|
32
|
+
notes?: string[];
|
|
33
|
+
}
|
|
34
|
+
/** One rule or group, in words (#5354): `fast-path: any of (release-manager: 1 approval from release-manager)`. */
|
|
35
|
+
export declare function quorumNodeWords(n: GateQuorumNode): string;
|
|
36
|
+
/** The notes for a change from `before` to `after` (#5354): holds at the head, holds lifted, and named or grouped gate rules. */
|
|
37
|
+
export declare function pipelineChangeNotes(before: PipelineSpec | undefined, after: PipelineSpec | undefined): string[];
|
|
38
|
+
/**
|
|
39
|
+
* The pipeline change between `base` and `head` in the member at `cwd`, or
|
|
40
|
+
* undefined when neither commit has a pipeline or its folded spec is the
|
|
41
|
+
* same at both. Reads both commits' files and folds them: nothing runs.
|
|
42
|
+
*/
|
|
43
|
+
export declare function pipelineChange(base: string, head: string, cwd: string, show?: PipelineShow): PipelineChange | undefined;
|
|
44
|
+
/** The plan note's section for a pipeline change: a heading and the diff in a fence, every `<!--` written as text. */
|
|
45
|
+
export declare function pipelineChangeSection(change: PipelineChange): string;
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The folded pipeline's diff (#5324): what a pull request changes in the
|
|
3
|
+
* pipeline, as lines of its folded spec, for the plan note and for a
|
|
4
|
+
* product's `ci --check`.
|
|
5
|
+
*/
|
|
6
|
+
import { readPipelineAt, gitShowPipeline } from "./read.js";
|
|
7
|
+
import { canaryStagesBefore, stageUpstreams } from "./spec.js";
|
|
8
|
+
import { isQuorumAll, isQuorumAny, isQuorumGroup, quorumNodes } from "../op/gate-quorum.js";
|
|
9
|
+
import { soakSummary } from "./soak.js";
|
|
10
|
+
/**
|
|
11
|
+
* The plan note's section for the soaks a change passes through once it
|
|
12
|
+
* merges (#5326): each stage's soak, with the stages it holds, and each
|
|
13
|
+
* wave's, with the wave it holds. Read from the pipeline at base, which is
|
|
14
|
+
* where the gates are read. Undefined when nothing soaks.
|
|
15
|
+
*/
|
|
16
|
+
export function pipelineSoakSection(spec) {
|
|
17
|
+
if (!spec)
|
|
18
|
+
return undefined;
|
|
19
|
+
const lines = [];
|
|
20
|
+
for (const stage of spec.stages) {
|
|
21
|
+
stage.waves.forEach((w, k) => {
|
|
22
|
+
const next = stage.waves[k + 1];
|
|
23
|
+
// #5327: a canary wave with no soak of its own takes the stage's, and holds every wave after it.
|
|
24
|
+
const soak = w.soak ?? (w.canary ? stage.soak : undefined);
|
|
25
|
+
if (!soak || !next)
|
|
26
|
+
return;
|
|
27
|
+
if (w.canary)
|
|
28
|
+
lines.push(`- In \`${stage.name}\`, every wave after the canary wave \`${w.name}\` waits for it to soak: ${soakSummary(soak)}.`);
|
|
29
|
+
else
|
|
30
|
+
lines.push(`- In \`${stage.name}\`, wave \`${next.name}\` waits for wave \`${w.name}\` to soak: ${soakSummary(soak)}.`);
|
|
31
|
+
});
|
|
32
|
+
if (!stage.soak)
|
|
33
|
+
continue;
|
|
34
|
+
const holds = spec.stages.filter((s) => stageUpstreams(spec, s.name).includes(stage.name)).map((s) => `\`${s.name}\``);
|
|
35
|
+
lines.push(holds.length > 0
|
|
36
|
+
? `- A promotion from \`${stage.name}\` into ${holds.join(", ")} waits for \`${stage.name}\` to soak: ${soakSummary(stage.soak)}.`
|
|
37
|
+
: `- \`${stage.name}\` soaks after it applies: ${soakSummary(stage.soak)}.`);
|
|
38
|
+
// #5327: the canary's soak holds every stage after it, not only the next.
|
|
39
|
+
const later = stage.canary ? spec.stages.filter((s) => canaryStagesBefore(spec, s.name).some((c) => c.name === stage.name) && !stageUpstreams(spec, s.name).includes(stage.name)).map((s) => `\`${s.name}\``) : [];
|
|
40
|
+
if (later.length > 0)
|
|
41
|
+
lines.push(`- \`${stage.name}\` is the canary: a promotion into ${later.join(", ")} waits for its soak too.`);
|
|
42
|
+
}
|
|
43
|
+
if (lines.length === 0)
|
|
44
|
+
return undefined;
|
|
45
|
+
return ["### Soak", "", "Once this merges, the change passes through these soaks. Each one holds and never approves; a person can end one early through its gate.", "", ...lines].join("\n").split("<!--").join("<!--");
|
|
46
|
+
}
|
|
47
|
+
/** The folded spec's lines, as the diff compares them. */
|
|
48
|
+
export function pipelineSpecLines(spec) {
|
|
49
|
+
return spec === undefined ? [] : JSON.stringify(spec, null, 2).split("\n");
|
|
50
|
+
}
|
|
51
|
+
/** A line diff of `before` against `after`, each line marked ` `, `-` or `+`. Unchanged runs longer than `context` lines each side are cut. */
|
|
52
|
+
export function lineDiff(before, after, context = 3) {
|
|
53
|
+
const n = before.length;
|
|
54
|
+
const m = after.length;
|
|
55
|
+
// Longest common subsequence, by suffix.
|
|
56
|
+
const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
|
|
57
|
+
for (let i = n - 1; i >= 0; i--)
|
|
58
|
+
for (let j = m - 1; j >= 0; j--)
|
|
59
|
+
lcs[i][j] = before[i] === after[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
|
|
60
|
+
const all = [];
|
|
61
|
+
let i = 0;
|
|
62
|
+
let j = 0;
|
|
63
|
+
while (i < n || j < m) {
|
|
64
|
+
if (i < n && j < m && before[i] === after[j]) {
|
|
65
|
+
all.push(` ${before[i]}`);
|
|
66
|
+
i++;
|
|
67
|
+
j++;
|
|
68
|
+
}
|
|
69
|
+
else if (i < n && (j === m || lcs[i + 1][j] >= lcs[i][j + 1])) {
|
|
70
|
+
all.push(`-${before[i]}`);
|
|
71
|
+
i++;
|
|
72
|
+
}
|
|
73
|
+
else {
|
|
74
|
+
all.push(`+${after[j]}`);
|
|
75
|
+
j++;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
const near = all.map((_, k) => all.slice(Math.max(0, k - context), k + context + 1).some((l) => !l.startsWith(" ")));
|
|
79
|
+
const out = [];
|
|
80
|
+
let cut = false;
|
|
81
|
+
all.forEach((line, k) => {
|
|
82
|
+
if (near[k]) {
|
|
83
|
+
out.push(line);
|
|
84
|
+
cut = false;
|
|
85
|
+
}
|
|
86
|
+
else if (!cut) {
|
|
87
|
+
out.push(" ...");
|
|
88
|
+
cut = true;
|
|
89
|
+
}
|
|
90
|
+
});
|
|
91
|
+
return out.some((l) => l.startsWith("+") || l.startsWith("-")) ? out : [];
|
|
92
|
+
}
|
|
93
|
+
/** One rule or group, in words (#5354): `fast-path: any of (release-manager: 1 approval from release-manager)`. */
|
|
94
|
+
export function quorumNodeWords(n) {
|
|
95
|
+
const named = (text) => (n.name !== undefined ? `${n.name}: ${text}` : text);
|
|
96
|
+
if (isQuorumGroup(n)) {
|
|
97
|
+
const kids = (isQuorumAll(n) ? n.all : isQuorumAny(n) ? n.any : []).map(quorumNodeWords);
|
|
98
|
+
return named(`${isQuorumAll(n) ? "all" : "any"} of (${kids.join("; ")})`);
|
|
99
|
+
}
|
|
100
|
+
const parts = [`${n.count} approval${n.count === 1 ? "" : "s"}`];
|
|
101
|
+
if (n.roles?.length)
|
|
102
|
+
parts.push(`from ${n.roles.join(" or ")}`);
|
|
103
|
+
if (n.proven)
|
|
104
|
+
parts.push("proven");
|
|
105
|
+
if (n.notAuthor)
|
|
106
|
+
parts.push("one not the author");
|
|
107
|
+
if (n.targets?.length)
|
|
108
|
+
parts.push(`on ${n.targets.join(", ")}`);
|
|
109
|
+
return named(parts.join(" "));
|
|
110
|
+
}
|
|
111
|
+
function holdWords(hold) {
|
|
112
|
+
const h = hold === true ? {} : hold;
|
|
113
|
+
return {
|
|
114
|
+
until: h.until ? ` until ${h.until}` : "",
|
|
115
|
+
reason: h.reason ? ` (${h.reason})` : "",
|
|
116
|
+
read: h.description ? ` Before it goes on: ${h.description}` : "",
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
/** The notes for a change from `before` to `after` (#5354): holds at the head, holds lifted, and named or grouped gate rules. */
|
|
120
|
+
export function pipelineChangeNotes(before, after) {
|
|
121
|
+
const out = [];
|
|
122
|
+
const at = (spec, name) => spec?.stages.find((s) => s.name === name);
|
|
123
|
+
for (const stage of before?.stages ?? []) {
|
|
124
|
+
if (stage.hold === undefined || at(after, stage.name)?.hold !== undefined)
|
|
125
|
+
continue;
|
|
126
|
+
const w = holdWords(stage.hold);
|
|
127
|
+
out.push(`This change lifts the hold on stage ${stage.name}${w.reason}.${w.read}`);
|
|
128
|
+
}
|
|
129
|
+
for (const stage of after?.stages ?? []) {
|
|
130
|
+
if (stage.hold !== undefined) {
|
|
131
|
+
const w = holdWords(stage.hold);
|
|
132
|
+
out.push(`Stage ${stage.name} is held${w.until}${w.reason}.${w.read}`);
|
|
133
|
+
}
|
|
134
|
+
const nodes = quorumNodes(stage.gate?.quorum);
|
|
135
|
+
const shown = (n) => n.name !== undefined || isQuorumGroup(n);
|
|
136
|
+
if (nodes.some(shown))
|
|
137
|
+
out.push(`Stage ${stage.name}'s gate takes all of: ${nodes.map(quorumNodeWords).join("; ")}.`);
|
|
138
|
+
}
|
|
139
|
+
return out;
|
|
140
|
+
}
|
|
141
|
+
function specOf(read) {
|
|
142
|
+
return read.status === "folded" ? read.spec : undefined;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* The pipeline change between `base` and `head` in the member at `cwd`, or
|
|
146
|
+
* undefined when neither commit has a pipeline or its folded spec is the
|
|
147
|
+
* same at both. Reads both commits' files and folds them: nothing runs.
|
|
148
|
+
*/
|
|
149
|
+
export function pipelineChange(base, head, cwd, show = gitShowPipeline) {
|
|
150
|
+
const before = readPipelineAt(base, cwd, show);
|
|
151
|
+
const after = readPipelineAt(head, cwd, show);
|
|
152
|
+
if (before.status === "absent" && after.status === "absent")
|
|
153
|
+
return undefined;
|
|
154
|
+
if (after.status === "refused")
|
|
155
|
+
return { diff: [], refused: after.line };
|
|
156
|
+
const diff = lineDiff(pipelineSpecLines(specOf(before)), pipelineSpecLines(specOf(after)));
|
|
157
|
+
if (diff.length === 0)
|
|
158
|
+
return undefined;
|
|
159
|
+
const notes = pipelineChangeNotes(specOf(before), specOf(after));
|
|
160
|
+
return { diff, ...(notes.length > 0 ? { notes } : {}) };
|
|
161
|
+
}
|
|
162
|
+
/** The plan note's section for a pipeline change: a heading and the diff in a fence, every `<!--` written as text. */
|
|
163
|
+
export function pipelineChangeSection(change) {
|
|
164
|
+
const body = change.refused
|
|
165
|
+
? [`The pipeline does not fold at the head, so nothing in it can run: ${change.refused}`]
|
|
166
|
+
: [
|
|
167
|
+
// #5354: the holds and named rules first, so the person who lifts a hold reads what it asks.
|
|
168
|
+
...(change.notes ?? []).flatMap((n) => [`- ${n.split("`").join("'")}`]),
|
|
169
|
+
...(change.notes?.length ? [""] : []),
|
|
170
|
+
"This pull request changes the pipeline. The folded spec's diff:",
|
|
171
|
+
"",
|
|
172
|
+
"```diff",
|
|
173
|
+
...change.diff.map((l) => l.split("```").join("` ` `")),
|
|
174
|
+
"```",
|
|
175
|
+
];
|
|
176
|
+
return ["### Pipeline", "", ...body].join("\n").split("<!--").join("<!--");
|
|
177
|
+
}
|