@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
package/dist/op/gate-quorum.d.ts
CHANGED
|
@@ -23,6 +23,24 @@
|
|
|
23
23
|
* with none, no approval proves anything, so a rule naming roles or
|
|
24
24
|
* `notAuthor` is never met.
|
|
25
25
|
*
|
|
26
|
+
* With `proven` (#5349), only a proven approver counts toward the rule's
|
|
27
|
+
* `count` at all. Without it a `count` counts every human approver of the
|
|
28
|
+
* plan, proven or not, so under a mode that takes plain `chant approve`
|
|
29
|
+
* lines (`ledger`, `pr-review`, `pull-request`) one person who can push to
|
|
30
|
+
* `chant/lifecycle` can write two lines in two names and meet `count: 2`.
|
|
31
|
+
* Off by default.
|
|
32
|
+
*
|
|
33
|
+
* Rules combine with `all` and `any` (#5354): a group `{ all: [...] }` is
|
|
34
|
+
* met when every rule in it is, and `{ any: [...] }` when one is, so a gate
|
|
35
|
+
* can take "two approvers, or one with the `release-manager` role". The list
|
|
36
|
+
* a gate takes is an `all`. Groups nest up to {@link QUORUM_MAX_DEPTH} deep,
|
|
37
|
+
* and every rule and group may carry a `name`, which the progress lines, the
|
|
38
|
+
* plan note and the pending fact on the ledger show. A group whose rules a
|
|
39
|
+
* gate's targets leave out is dropped, never met by nobody: an `any` is met
|
|
40
|
+
* only by a rule that counts real approvers, so it opens no way past the
|
|
41
|
+
* gate's approval. Only a caller that passes `combine: true` to
|
|
42
|
+
* {@link quorumProblems} reads groups and names.
|
|
43
|
+
*
|
|
26
44
|
* `notAuthor` reads who was involved in the change (#4333): the pull
|
|
27
45
|
* request's author, each login a `Requested-by:` trailer on its commits
|
|
28
46
|
* names, and the accounts an agent acts as. With `excludeInvolved`, an
|
|
@@ -36,6 +54,8 @@ import { type GateSigners } from "../lifecycle/gate-seal.js";
|
|
|
36
54
|
import type { GateResolutionRecord } from "../lifecycle/gate-ledger.js";
|
|
37
55
|
/** One approval rule. */
|
|
38
56
|
export interface GateQuorumRule {
|
|
57
|
+
/** The rule's name (#5354), shown in its progress line, the plan note and the pending fact. */
|
|
58
|
+
name?: string;
|
|
39
59
|
/** Globs over the gate's targets (an Op wave's run targets, an Op gate's environment). Absent, the rule covers every target. */
|
|
40
60
|
targets?: string[];
|
|
41
61
|
/** Distinct human approvers the rule needs. At least 1. */
|
|
@@ -44,9 +64,37 @@ export interface GateQuorumRule {
|
|
|
44
64
|
roles?: string[];
|
|
45
65
|
/** When true, at least one counted approver is proven and is not the change's author. */
|
|
46
66
|
notAuthor?: boolean;
|
|
67
|
+
/**
|
|
68
|
+
* When true (#5349), only a proven approver counts toward `count`: a seal
|
|
69
|
+
* that verifies against the signers at base, or a review the judge proves.
|
|
70
|
+
* Default false: every human approver of the plan counts.
|
|
71
|
+
*/
|
|
72
|
+
proven?: boolean;
|
|
73
|
+
}
|
|
74
|
+
/** A group met when every rule in it is met (#5354). */
|
|
75
|
+
export interface GateQuorumAll {
|
|
76
|
+
name?: string;
|
|
77
|
+
all: GateQuorumNode[];
|
|
47
78
|
}
|
|
48
|
-
/** A
|
|
49
|
-
export
|
|
79
|
+
/** A group met when one rule in it is met (#5354). */
|
|
80
|
+
export interface GateQuorumAny {
|
|
81
|
+
name?: string;
|
|
82
|
+
any: GateQuorumNode[];
|
|
83
|
+
}
|
|
84
|
+
/** A rule, or a group of rules (#5354). */
|
|
85
|
+
export type GateQuorumNode = GateQuorumRule | GateQuorumAll | GateQuorumAny;
|
|
86
|
+
/** A gate's quorum: one rule (the form before #4290), or a list of rules and groups, all of which must be met. */
|
|
87
|
+
export type GateQuorumSpec = GateQuorumRule | readonly GateQuorumNode[];
|
|
88
|
+
/** How deep `all` and `any` groups nest (#5354): a group in a group in a group, and no further. */
|
|
89
|
+
export declare const QUORUM_MAX_DEPTH = 3;
|
|
90
|
+
/** Whether `node` is an `all` group. */
|
|
91
|
+
export declare const isQuorumAll: (node: GateQuorumNode) => node is GateQuorumAll;
|
|
92
|
+
/** Whether `node` is an `any` group. */
|
|
93
|
+
export declare const isQuorumAny: (node: GateQuorumNode) => node is GateQuorumAny;
|
|
94
|
+
/** Whether `node` is a group, `all` or `any`. */
|
|
95
|
+
export declare const isQuorumGroup: (node: GateQuorumNode) => node is GateQuorumAll | GateQuorumAny;
|
|
96
|
+
/** The rules and groups a quorum lists, at the top. Absent, none. */
|
|
97
|
+
export declare function quorumNodes(quorum: GateQuorumSpec | undefined): GateQuorumNode[];
|
|
50
98
|
/** What a judge says about one approval. */
|
|
51
99
|
export interface QuorumJudgement {
|
|
52
100
|
/** The approval proves who `resolvedBy` is: a verified seal, or the forge's review. */
|
|
@@ -72,13 +120,30 @@ export interface GateQuorumRuleProgress {
|
|
|
72
120
|
count: number;
|
|
73
121
|
roles?: string[];
|
|
74
122
|
notAuthor?: boolean;
|
|
123
|
+
proven?: boolean;
|
|
75
124
|
/** The approvers it counts, oldest first. */
|
|
76
125
|
approvers: string[];
|
|
77
126
|
met: boolean;
|
|
78
127
|
/** Why the author could not be told apart, when `notAuthor` is set and nobody knows the author. */
|
|
79
128
|
authorUnknown?: boolean;
|
|
129
|
+
/** The rule's name (#5354). */
|
|
130
|
+
name?: string;
|
|
131
|
+
}
|
|
132
|
+
/** How far a group of rules is met (#5354). */
|
|
133
|
+
export interface GateQuorumGroupProgress {
|
|
134
|
+
kind: "all" | "any";
|
|
135
|
+
name?: string;
|
|
136
|
+
met: boolean;
|
|
137
|
+
children: Array<GateQuorumRuleProgress | GateQuorumGroupProgress>;
|
|
80
138
|
}
|
|
81
|
-
/**
|
|
139
|
+
/** Whether a progress entry is a group's. */
|
|
140
|
+
export declare const isGroupProgress: (p: GateQuorumRuleProgress | GateQuorumGroupProgress) => p is GateQuorumGroupProgress;
|
|
141
|
+
/**
|
|
142
|
+
* The rules of a quorum, as a flat list: every rule, inside groups too
|
|
143
|
+
* (#5354). For a quorum with no groups, the list it is. Read it to ask what
|
|
144
|
+
* any rule needs (proof, a count); judge whether the quorum is met with
|
|
145
|
+
* {@link quorumTreeProgress}, which reads the groups.
|
|
146
|
+
*/
|
|
82
147
|
export declare function quorumRules(quorum: GateQuorumSpec | undefined): GateQuorumRule[];
|
|
83
148
|
/**
|
|
84
149
|
* Whether `target` matches `glob`: `*` within a `/` segment, `**` across
|
|
@@ -87,17 +152,35 @@ export declare function quorumRules(quorum: GateQuorumSpec | undefined): GateQuo
|
|
|
87
152
|
* one thing in both.
|
|
88
153
|
*/
|
|
89
154
|
export declare function targetGlobMatch(glob: string, target: string): boolean;
|
|
90
|
-
/**
|
|
91
|
-
|
|
155
|
+
/**
|
|
156
|
+
* The rules a gate whose targets are `targets` takes: those with no
|
|
157
|
+
* `targets`, and those a glob of matches one. A group keeps the rules in it
|
|
158
|
+
* the gate takes, and is dropped when it keeps none (#5354), so an `any`
|
|
159
|
+
* is never met by a rule left out.
|
|
160
|
+
*/
|
|
161
|
+
export declare function quorumRulesFor<T extends GateQuorumNode>(rules: readonly T[], targets: readonly string[]): T[];
|
|
92
162
|
/** The most approvers any rule needs, 1 with none. */
|
|
93
163
|
export declare function quorumNeed(rules: readonly GateQuorumRule[]): number;
|
|
164
|
+
/** Every rule with where it is written (#5354): `approvals.quorum[1].any[0]`, under `where`. */
|
|
165
|
+
export declare function quorumRuleSites(quorum: GateQuorumSpec | undefined, where: string): Array<{
|
|
166
|
+
rule: GateQuorumRule;
|
|
167
|
+
at: string;
|
|
168
|
+
}>;
|
|
169
|
+
/** A rule or group's name (#5354): lowercase letters, digits, `-` and `_`. */
|
|
170
|
+
export declare const QUORUM_NAME: RegExp;
|
|
94
171
|
/**
|
|
95
172
|
* Everything wrong with a quorum, one line each. `where` names it
|
|
96
173
|
* (`approval.quorum`). With `notAuthor: false`, a rule naming `notAuthor` is
|
|
97
|
-
* refused, since that caller has no author to judge by.
|
|
174
|
+
* refused, since that caller has no author to judge by. Without `proven:
|
|
175
|
+
* true`, a rule naming `proven` is refused (#5349): an Op waves spec's
|
|
176
|
+
* `approvals.quorum` reads it. Without `combine: true`, a group (`all`,
|
|
177
|
+
* `any`) and a `name` are refused (#5354): an Op waves spec's
|
|
178
|
+
* `approvals.quorum` and a pipeline stage's gate read them.
|
|
98
179
|
*/
|
|
99
180
|
export declare function quorumProblems(value: unknown, where: string, opts: {
|
|
100
181
|
notAuthor: boolean;
|
|
182
|
+
proven?: boolean;
|
|
183
|
+
combine?: boolean;
|
|
101
184
|
}): string[];
|
|
102
185
|
/** Whether two principals name the same person, compared trimmed and lower-cased. */
|
|
103
186
|
export declare const samePrincipal: (a: string, b: string) => boolean;
|
|
@@ -111,14 +194,37 @@ export interface QuorumApprover {
|
|
|
111
194
|
}
|
|
112
195
|
/** How far `rule` is met by `approvers`: each counted once, by name, oldest first. */
|
|
113
196
|
export declare function quorumRuleProgress(rule: GateQuorumRule, approvers: readonly QuorumApprover[]): GateQuorumRuleProgress;
|
|
197
|
+
/** Whether `approver` counts toward `rule` on their own, before the count (#5354): not left out, proven when the rule needs it, holding a role it names. */
|
|
198
|
+
export declare function ruleAdmits(rule: GateQuorumRule, judged: QuorumJudgement): boolean;
|
|
199
|
+
/** What {@link quorumTreeProgress} found. */
|
|
200
|
+
export interface GateQuorumTreeProgress {
|
|
201
|
+
/** Every rule (#5354), groups' included, in the order written. */
|
|
202
|
+
rules: GateQuorumRuleProgress[];
|
|
203
|
+
/** The top-level rules and groups, with each group's. Absent when the quorum has no group. */
|
|
204
|
+
groups?: Array<GateQuorumRuleProgress | GateQuorumGroupProgress>;
|
|
205
|
+
/** Every top-level rule and group is met. False with none. */
|
|
206
|
+
met: boolean;
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* How far a list of rules and groups is met by `approvers` (#5354): each
|
|
210
|
+
* rule as {@link quorumRuleProgress} counts it, an `all` group when every
|
|
211
|
+
* rule in it is met, an `any` group when one is, and the list when every
|
|
212
|
+
* entry is. A list with no entry is not met; a caller with no rules asks for
|
|
213
|
+
* one human approval itself.
|
|
214
|
+
*/
|
|
215
|
+
export declare function quorumTreeProgress(nodes: readonly GateQuorumNode[], approvers: readonly QuorumApprover[]): GateQuorumTreeProgress;
|
|
216
|
+
/** A group's line (#5354): `any fast-path: met by release-manager`, or what it waits on. */
|
|
217
|
+
export declare function quorumGroupLine(g: GateQuorumGroupProgress): string;
|
|
218
|
+
/** Every group's line, outermost first (#5354). */
|
|
219
|
+
export declare function quorumGroupLines(groups: ReadonlyArray<GateQuorumRuleProgress | GateQuorumGroupProgress> | undefined): string[];
|
|
114
220
|
/**
|
|
115
221
|
* Where a rule stands, in one line: `prod-*: 1 of 2 approvals (github:alice),
|
|
116
|
-
* needs 1 more from platform`.
|
|
222
|
+
* needs 1 more from platform`. A named rule (#5354) leads with its name.
|
|
117
223
|
*/
|
|
118
224
|
export declare function quorumRuleLine(p: GateQuorumRuleProgress): string;
|
|
119
225
|
/** The rules that are not met, one line each joined by `; `. */
|
|
120
226
|
export declare function quorumWaiting(progress: readonly GateQuorumRuleProgress[]): string;
|
|
121
|
-
/** Whether a rule needs a proven approver: it names roles, or `
|
|
227
|
+
/** Whether a rule needs a proven approver: it names roles, `notAuthor` or `proven`. */
|
|
122
228
|
export declare const ruleNeedsProof: (rule: GateQuorumRule) => boolean;
|
|
123
229
|
/** Someone involved in a change (#4333), and why: `github:bob asked for abc1234`. */
|
|
124
230
|
export interface QuorumInvolvement {
|
package/dist/op/gate-quorum.js
CHANGED
|
@@ -23,6 +23,24 @@
|
|
|
23
23
|
* with none, no approval proves anything, so a rule naming roles or
|
|
24
24
|
* `notAuthor` is never met.
|
|
25
25
|
*
|
|
26
|
+
* With `proven` (#5349), only a proven approver counts toward the rule's
|
|
27
|
+
* `count` at all. Without it a `count` counts every human approver of the
|
|
28
|
+
* plan, proven or not, so under a mode that takes plain `chant approve`
|
|
29
|
+
* lines (`ledger`, `pr-review`, `pull-request`) one person who can push to
|
|
30
|
+
* `chant/lifecycle` can write two lines in two names and meet `count: 2`.
|
|
31
|
+
* Off by default.
|
|
32
|
+
*
|
|
33
|
+
* Rules combine with `all` and `any` (#5354): a group `{ all: [...] }` is
|
|
34
|
+
* met when every rule in it is, and `{ any: [...] }` when one is, so a gate
|
|
35
|
+
* can take "two approvers, or one with the `release-manager` role". The list
|
|
36
|
+
* a gate takes is an `all`. Groups nest up to {@link QUORUM_MAX_DEPTH} deep,
|
|
37
|
+
* and every rule and group may carry a `name`, which the progress lines, the
|
|
38
|
+
* plan note and the pending fact on the ledger show. A group whose rules a
|
|
39
|
+
* gate's targets leave out is dropped, never met by nobody: an `any` is met
|
|
40
|
+
* only by a rule that counts real approvers, so it opens no way past the
|
|
41
|
+
* gate's approval. Only a caller that passes `combine: true` to
|
|
42
|
+
* {@link quorumProblems} reads groups and names.
|
|
43
|
+
*
|
|
26
44
|
* `notAuthor` reads who was involved in the change (#4333): the pull
|
|
27
45
|
* request's author, each login a `Requested-by:` trailer on its commits
|
|
28
46
|
* names, and the accounts an agent acts as. With `excludeInvolved`, an
|
|
@@ -33,14 +51,43 @@
|
|
|
33
51
|
* caller from the trust policy it read at base ({@link trustQuorumJudge}).
|
|
34
52
|
*/
|
|
35
53
|
import { gateSealRefusal } from "../lifecycle/gate-seal.js";
|
|
36
|
-
/**
|
|
37
|
-
export const
|
|
38
|
-
/**
|
|
39
|
-
export
|
|
54
|
+
/** How deep `all` and `any` groups nest (#5354): a group in a group in a group, and no further. */
|
|
55
|
+
export const QUORUM_MAX_DEPTH = 3;
|
|
56
|
+
/** Whether `node` is an `all` group. */
|
|
57
|
+
export const isQuorumAll = (node) => Array.isArray(node.all);
|
|
58
|
+
/** Whether `node` is an `any` group. */
|
|
59
|
+
export const isQuorumAny = (node) => Array.isArray(node.any);
|
|
60
|
+
/** Whether `node` is a group, `all` or `any`. */
|
|
61
|
+
export const isQuorumGroup = (node) => isQuorumAll(node) || isQuorumAny(node);
|
|
62
|
+
/** The rules and groups a quorum lists, at the top. Absent, none. */
|
|
63
|
+
export function quorumNodes(quorum) {
|
|
40
64
|
if (quorum === undefined)
|
|
41
65
|
return [];
|
|
42
66
|
return Array.isArray(quorum) ? [...quorum] : [quorum];
|
|
43
67
|
}
|
|
68
|
+
/** The judge with nothing to judge by: no approval proves anyone, and nobody's author is known. */
|
|
69
|
+
export const UNPROVEN_JUDGE = () => ({ proven: false, roles: [] });
|
|
70
|
+
/** Whether a progress entry is a group's. */
|
|
71
|
+
export const isGroupProgress = (p) => "children" in p;
|
|
72
|
+
/**
|
|
73
|
+
* The rules of a quorum, as a flat list: every rule, inside groups too
|
|
74
|
+
* (#5354). For a quorum with no groups, the list it is. Read it to ask what
|
|
75
|
+
* any rule needs (proof, a count); judge whether the quorum is met with
|
|
76
|
+
* {@link quorumTreeProgress}, which reads the groups.
|
|
77
|
+
*/
|
|
78
|
+
export function quorumRules(quorum) {
|
|
79
|
+
const out = [];
|
|
80
|
+
const walk = (n) => {
|
|
81
|
+
if (isQuorumAll(n))
|
|
82
|
+
n.all.forEach(walk);
|
|
83
|
+
else if (isQuorumAny(n))
|
|
84
|
+
n.any.forEach(walk);
|
|
85
|
+
else
|
|
86
|
+
out.push(n);
|
|
87
|
+
};
|
|
88
|
+
quorumNodes(quorum).forEach(walk);
|
|
89
|
+
return out;
|
|
90
|
+
}
|
|
44
91
|
/**
|
|
45
92
|
* Whether `target` matches `glob`: `*` within a `/` segment, `**` across
|
|
46
93
|
* segments (and `a/**\/b` across none), `?` one character. The same reading
|
|
@@ -71,31 +118,94 @@ export function targetGlobMatch(glob, target) {
|
|
|
71
118
|
}
|
|
72
119
|
return new RegExp(`^${re}$`).test(target.replace(/\\/g, "/").replace(/\/+$/, ""));
|
|
73
120
|
}
|
|
74
|
-
/**
|
|
121
|
+
/**
|
|
122
|
+
* The rules a gate whose targets are `targets` takes: those with no
|
|
123
|
+
* `targets`, and those a glob of matches one. A group keeps the rules in it
|
|
124
|
+
* the gate takes, and is dropped when it keeps none (#5354), so an `any`
|
|
125
|
+
* is never met by a rule left out.
|
|
126
|
+
*/
|
|
75
127
|
export function quorumRulesFor(rules, targets) {
|
|
76
|
-
|
|
128
|
+
const prune = (n) => {
|
|
129
|
+
if (isQuorumGroup(n)) {
|
|
130
|
+
const kids = (isQuorumAll(n) ? n.all : n.any).map(prune).filter((k) => k !== undefined);
|
|
131
|
+
if (kids.length === 0)
|
|
132
|
+
return undefined;
|
|
133
|
+
return isQuorumAll(n) ? { ...(n.name !== undefined ? { name: n.name } : {}), all: kids } : { ...(n.name !== undefined ? { name: n.name } : {}), any: kids };
|
|
134
|
+
}
|
|
135
|
+
return n.targets === undefined || n.targets.some((g) => targets.some((t) => targetGlobMatch(g, t))) ? n : undefined;
|
|
136
|
+
};
|
|
137
|
+
return rules.map(prune).filter((n) => n !== undefined);
|
|
77
138
|
}
|
|
78
139
|
/** The most approvers any rule needs, 1 with none. */
|
|
79
140
|
export function quorumNeed(rules) {
|
|
80
141
|
return rules.reduce((n, r) => Math.max(n, r.count), 1);
|
|
81
142
|
}
|
|
143
|
+
/** Every rule with where it is written (#5354): `approvals.quorum[1].any[0]`, under `where`. */
|
|
144
|
+
export function quorumRuleSites(quorum, where) {
|
|
145
|
+
const out = [];
|
|
146
|
+
const walk = (n, at) => {
|
|
147
|
+
if (isQuorumAll(n))
|
|
148
|
+
n.all.forEach((k, i) => walk(k, `${at}.all[${i}]`));
|
|
149
|
+
else if (isQuorumAny(n))
|
|
150
|
+
n.any.forEach((k, i) => walk(k, `${at}.any[${i}]`));
|
|
151
|
+
else
|
|
152
|
+
out.push({ rule: n, at });
|
|
153
|
+
};
|
|
154
|
+
quorumNodes(quorum).forEach((n, i) => walk(n, Array.isArray(quorum) ? `${where}[${i}]` : where));
|
|
155
|
+
return out;
|
|
156
|
+
}
|
|
157
|
+
/** A rule or group's name (#5354): lowercase letters, digits, `-` and `_`. */
|
|
158
|
+
export const QUORUM_NAME = /^[a-z0-9][a-z0-9_-]*$/;
|
|
82
159
|
/**
|
|
83
160
|
* Everything wrong with a quorum, one line each. `where` names it
|
|
84
161
|
* (`approval.quorum`). With `notAuthor: false`, a rule naming `notAuthor` is
|
|
85
|
-
* refused, since that caller has no author to judge by.
|
|
162
|
+
* refused, since that caller has no author to judge by. Without `proven:
|
|
163
|
+
* true`, a rule naming `proven` is refused (#5349): an Op waves spec's
|
|
164
|
+
* `approvals.quorum` reads it. Without `combine: true`, a group (`all`,
|
|
165
|
+
* `any`) and a `name` are refused (#5354): an Op waves spec's
|
|
166
|
+
* `approvals.quorum` and a pipeline stage's gate read them.
|
|
86
167
|
*/
|
|
87
168
|
export function quorumProblems(value, where, opts) {
|
|
88
169
|
const list = Array.isArray(value) ? value : [value];
|
|
89
170
|
const problems = [];
|
|
90
171
|
if (Array.isArray(value) && value.length === 0)
|
|
91
172
|
problems.push(`\`${where}\` must name at least one rule`);
|
|
92
|
-
|
|
93
|
-
|
|
173
|
+
const names = new Set();
|
|
174
|
+
const nameProblem = (q, at) => {
|
|
175
|
+
if (q.name === undefined)
|
|
176
|
+
return;
|
|
177
|
+
if (!opts.combine)
|
|
178
|
+
return;
|
|
179
|
+
if (typeof q.name !== "string" || !QUORUM_NAME.test(q.name))
|
|
180
|
+
problems.push(`\`${at}.name\` must be lowercase letters, digits, - and _`);
|
|
181
|
+
else if (names.has(q.name))
|
|
182
|
+
problems.push(`\`${at}.name\` is ${JSON.stringify(q.name)}, which another rule of the gate already names`);
|
|
183
|
+
else
|
|
184
|
+
names.add(q.name);
|
|
185
|
+
};
|
|
186
|
+
const node = (rule, at, depth) => {
|
|
94
187
|
if (typeof rule !== "object" || rule === null || Array.isArray(rule)) {
|
|
95
188
|
problems.push(`\`${at}\` must be an object`);
|
|
96
189
|
return;
|
|
97
190
|
}
|
|
98
191
|
const q = rule;
|
|
192
|
+
if (opts.combine && ("all" in q || "any" in q)) {
|
|
193
|
+
nameProblem(q, at);
|
|
194
|
+
if ("all" in q && "any" in q)
|
|
195
|
+
problems.push(`\`${at}\` names both all and any; a group is one of them`);
|
|
196
|
+
const kind = "all" in q ? "all" : "any";
|
|
197
|
+
const kids = q[kind];
|
|
198
|
+
if (depth >= QUORUM_MAX_DEPTH)
|
|
199
|
+
problems.push(`\`${at}\` nests groups deeper than ${QUORUM_MAX_DEPTH}; all and any nest up to ${QUORUM_MAX_DEPTH} groups deep`);
|
|
200
|
+
else if (!Array.isArray(kids) || kids.length === 0)
|
|
201
|
+
problems.push(`\`${at}.${kind}\` must list at least one rule`);
|
|
202
|
+
else
|
|
203
|
+
kids.forEach((k, i) => node(k, `${at}.${kind}[${i}]`, depth + 1));
|
|
204
|
+
for (const key of Object.keys(q))
|
|
205
|
+
if (key !== "name" && key !== "all" && key !== "any")
|
|
206
|
+
problems.push(`\`${at}.${key}\` is not read on a group; a group takes name and one of all or any`);
|
|
207
|
+
return;
|
|
208
|
+
}
|
|
99
209
|
if (typeof q.count !== "number" || !Number.isInteger(q.count) || q.count < 1)
|
|
100
210
|
problems.push(`\`${at}.count\` must be an integer of at least 1`);
|
|
101
211
|
if (q.roles !== undefined && (!Array.isArray(q.roles) || q.roles.length === 0 || q.roles.some((r) => typeof r !== "string" || r === ""))) {
|
|
@@ -109,11 +219,20 @@ export function quorumProblems(value, where, opts) {
|
|
|
109
219
|
if (q.notAuthor === true && !opts.notAuthor) {
|
|
110
220
|
problems.push(`\`${at}.notAuthor\` is not read here: an Op gate has no author to judge by. An Op waves spec's \`approvals.quorum\` reads it from the merged pull request`);
|
|
111
221
|
}
|
|
112
|
-
|
|
222
|
+
if (q.proven !== undefined && typeof q.proven !== "boolean")
|
|
223
|
+
problems.push(`\`${at}.proven\` must be true or false`);
|
|
224
|
+
if (q.proven !== undefined && opts.proven !== true) {
|
|
225
|
+
problems.push(`\`${at}.proven\` is not read here. An Op waves spec's \`approvals.quorum\` reads it`);
|
|
226
|
+
}
|
|
227
|
+
nameProblem(q, at);
|
|
228
|
+
const known = new Set(["targets", "count", "roles", "notAuthor", ...(opts.proven ? ["proven"] : []), ...(opts.combine ? ["name"] : [])]);
|
|
229
|
+
const fields = [...known];
|
|
230
|
+
const words = `${fields.slice(0, -1).join(", ")} or ${fields[fields.length - 1]}`;
|
|
113
231
|
for (const key of Object.keys(q))
|
|
114
|
-
if (!known.has(key))
|
|
115
|
-
problems.push(`\`${at}.${key}\` is not a quorum field; use
|
|
116
|
-
}
|
|
232
|
+
if (!known.has(key) && key !== "proven")
|
|
233
|
+
problems.push(`\`${at}.${key}\` is not a quorum field; use ${words}${opts.combine ? ", or a group of all or any" : ""}`);
|
|
234
|
+
};
|
|
235
|
+
list.forEach((rule, i) => node(rule, Array.isArray(value) ? `${where}[${i}]` : where, 0));
|
|
117
236
|
return problems;
|
|
118
237
|
}
|
|
119
238
|
const norm = (s) => s.normalize("NFKC").trim().toLowerCase();
|
|
@@ -131,9 +250,7 @@ export function quorumRuleProgress(rule, approvers) {
|
|
|
131
250
|
const seen = new Set();
|
|
132
251
|
const counted = [];
|
|
133
252
|
for (const a of [...approvers].sort((x, y) => Date.parse(x.at) - Date.parse(y.at))) {
|
|
134
|
-
if (seen.has(norm(a.who)) || a.judged
|
|
135
|
-
continue;
|
|
136
|
-
if (rule.roles?.length && !(a.judged.proven && a.judged.roles.some((r) => rule.roles.includes(r))))
|
|
253
|
+
if (seen.has(norm(a.who)) || !ruleAdmits(rule, a.judged))
|
|
137
254
|
continue;
|
|
138
255
|
seen.add(norm(a.who));
|
|
139
256
|
counted.push(a);
|
|
@@ -141,28 +258,88 @@ export function quorumRuleProgress(rule, approvers) {
|
|
|
141
258
|
const notAuthor = !rule.notAuthor || counted.some((a) => a.judged.proven && a.judged.author === false);
|
|
142
259
|
const authorUnknown = rule.notAuthor === true && !notAuthor && counted.some((a) => a.judged.proven && a.judged.author === undefined);
|
|
143
260
|
return {
|
|
261
|
+
...(rule.name !== undefined ? { name: rule.name } : {}),
|
|
144
262
|
...(rule.targets ? { targets: [...rule.targets] } : {}),
|
|
145
263
|
count: rule.count,
|
|
146
264
|
...(rule.roles?.length ? { roles: [...rule.roles] } : {}),
|
|
147
265
|
...(rule.notAuthor ? { notAuthor: true } : {}),
|
|
266
|
+
...(rule.proven ? { proven: true } : {}),
|
|
148
267
|
approvers: counted.map((a) => a.who),
|
|
149
268
|
met: counted.length >= rule.count && notAuthor,
|
|
150
269
|
...(authorUnknown ? { authorUnknown: true } : {}),
|
|
151
270
|
};
|
|
152
271
|
}
|
|
272
|
+
/** Whether `approver` counts toward `rule` on their own, before the count (#5354): not left out, proven when the rule needs it, holding a role it names. */
|
|
273
|
+
export function ruleAdmits(rule, judged) {
|
|
274
|
+
if (judged.excluded !== undefined)
|
|
275
|
+
return false;
|
|
276
|
+
if (rule.proven && !judged.proven)
|
|
277
|
+
return false;
|
|
278
|
+
if (rule.roles?.length && !(judged.proven && judged.roles.some((r) => rule.roles.includes(r))))
|
|
279
|
+
return false;
|
|
280
|
+
return true;
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* How far a list of rules and groups is met by `approvers` (#5354): each
|
|
284
|
+
* rule as {@link quorumRuleProgress} counts it, an `all` group when every
|
|
285
|
+
* rule in it is met, an `any` group when one is, and the list when every
|
|
286
|
+
* entry is. A list with no entry is not met; a caller with no rules asks for
|
|
287
|
+
* one human approval itself.
|
|
288
|
+
*/
|
|
289
|
+
export function quorumTreeProgress(nodes, approvers) {
|
|
290
|
+
const rules = [];
|
|
291
|
+
let grouped = false;
|
|
292
|
+
const walk = (n) => {
|
|
293
|
+
if (isQuorumGroup(n)) {
|
|
294
|
+
grouped = true;
|
|
295
|
+
const kind = isQuorumAll(n) ? "all" : "any";
|
|
296
|
+
const children = (isQuorumAll(n) ? n.all : n.any).map(walk);
|
|
297
|
+
const met = children.length > 0 && (kind === "all" ? children.every((c) => c.met) : children.some((c) => c.met));
|
|
298
|
+
return { kind, ...(n.name !== undefined ? { name: n.name } : {}), met, children };
|
|
299
|
+
}
|
|
300
|
+
const p = quorumRuleProgress(n, approvers);
|
|
301
|
+
rules.push(p);
|
|
302
|
+
return p;
|
|
303
|
+
};
|
|
304
|
+
const top = nodes.map(walk);
|
|
305
|
+
return { rules, ...(grouped ? { groups: top } : {}), met: top.length > 0 && top.every((p) => p.met) };
|
|
306
|
+
}
|
|
307
|
+
/** A group's line (#5354): `any fast-path: met by release-manager`, or what it waits on. */
|
|
308
|
+
export function quorumGroupLine(g) {
|
|
309
|
+
const label = (c, i) => c.name ?? `${isGroupProgress(c) ? c.kind : "rule"} ${i + 1}`;
|
|
310
|
+
const head = `${g.kind}${g.name !== undefined ? ` ${g.name}` : ""}`;
|
|
311
|
+
const met = g.children.map((c, i) => [c, i]).filter(([c]) => c.met).map(([c, i]) => label(c, i));
|
|
312
|
+
if (g.met)
|
|
313
|
+
return `${head}: met by ${met.join(", ")}`;
|
|
314
|
+
const open = g.children.map((c, i) => [c, i]).filter(([c]) => !c.met).map(([c, i]) => label(c, i));
|
|
315
|
+
return g.kind === "any" ? `${head}: waits for one of ${open.join(", ")}` : `${head}: waits for ${open.join(", ")}`;
|
|
316
|
+
}
|
|
317
|
+
/** Every group's line, outermost first (#5354). */
|
|
318
|
+
export function quorumGroupLines(groups) {
|
|
319
|
+
const out = [];
|
|
320
|
+
const walk = (p) => {
|
|
321
|
+
if (!isGroupProgress(p))
|
|
322
|
+
return;
|
|
323
|
+
out.push(quorumGroupLine(p));
|
|
324
|
+
p.children.forEach(walk);
|
|
325
|
+
};
|
|
326
|
+
(groups ?? []).forEach(walk);
|
|
327
|
+
return out;
|
|
328
|
+
}
|
|
153
329
|
/**
|
|
154
330
|
* Where a rule stands, in one line: `prod-*: 1 of 2 approvals (github:alice),
|
|
155
|
-
* needs 1 more from platform`.
|
|
331
|
+
* needs 1 more from platform`. A named rule (#5354) leads with its name.
|
|
156
332
|
*/
|
|
157
333
|
export function quorumRuleLine(p) {
|
|
158
|
-
const
|
|
334
|
+
const where = p.targets ? p.targets.join(", ") : "every target";
|
|
335
|
+
const scope = p.name !== undefined ? `${p.name} (${where})` : where;
|
|
159
336
|
const have = `${p.approvers.length} of ${p.count} approval${p.count === 1 ? "" : "s"}${p.approvers.length ? ` (${p.approvers.join(", ")})` : ""}`;
|
|
160
337
|
if (p.met)
|
|
161
338
|
return `${scope}: ${have}, met`;
|
|
162
339
|
const more = p.count - p.approvers.length;
|
|
163
340
|
const needs = [];
|
|
164
341
|
if (more > 0)
|
|
165
|
-
needs.push(`${more} more${p.roles?.length ? ` from ${p.roles.join(" or ")}` : ""}`);
|
|
342
|
+
needs.push(`${more} more${p.proven && !p.roles?.length ? " proven" : ""}${p.roles?.length ? ` from ${p.roles.join(" or ")}` : ""}`);
|
|
166
343
|
if (p.notAuthor)
|
|
167
344
|
needs.push(more > 0 ? "one of them not the author" : "an approver who is not the author");
|
|
168
345
|
const unknown = p.authorUnknown ? " (the change's author is not known, so no approver can show they are someone else)" : "";
|
|
@@ -172,8 +349,8 @@ export function quorumRuleLine(p) {
|
|
|
172
349
|
export function quorumWaiting(progress) {
|
|
173
350
|
return progress.filter((p) => !p.met).map(quorumRuleLine).join("; ");
|
|
174
351
|
}
|
|
175
|
-
/** Whether a rule needs a proven approver: it names roles, or `
|
|
176
|
-
export const ruleNeedsProof = (rule) => (rule.roles?.length ?? 0) > 0 || rule.notAuthor === true;
|
|
352
|
+
/** Whether a rule needs a proven approver: it names roles, `notAuthor` or `proven`. */
|
|
353
|
+
export const ruleNeedsProof = (rule) => (rule.roles?.length ?? 0) > 0 || rule.notAuthor === true || rule.proven === true;
|
|
177
354
|
/** A login as a forge allows it, and a GitHub App's `[bot]` suffix. */
|
|
178
355
|
const LOGIN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\[bot\])?$/;
|
|
179
356
|
/**
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which rejections stop a gate (#5354).
|
|
3
|
+
*
|
|
4
|
+
* `chant reject <op> <gate>` records a rejection of the digest a gate waits
|
|
5
|
+
* on (`../lifecycle/gate-rejection.ts`). At a stage's gate that digest is a
|
|
6
|
+
* release's, so a rejection turns that release down at that stage. A
|
|
7
|
+
* rejection that counts stops the gate before any approval is read: more
|
|
8
|
+
* approvals never clear it. Only a new release, with a new digest, goes
|
|
9
|
+
* through again.
|
|
10
|
+
*
|
|
11
|
+
* A rejection counts by the proof rules an approval of the same gate counts
|
|
12
|
+
* by:
|
|
13
|
+
*
|
|
14
|
+
* - it is a person's, as only a person's approval counts toward a quorum;
|
|
15
|
+
* - a gate whose `approval` mode is `sealed` counts only a rejection whose
|
|
16
|
+
* seal verifies against the signers at base, as it counts only sealed
|
|
17
|
+
* approvals. `ledger`, `pr-review` and `pull-request` take a plain
|
|
18
|
+
* `chant approve` line, so they take a plain `chant reject` line too;
|
|
19
|
+
* - a gate the workspace's `identity.gates` names counts only a rejection
|
|
20
|
+
* that rule admits (signed, from its class);
|
|
21
|
+
* - a gate with approval rules counts a rejection only from someone one of
|
|
22
|
+
* its rules would count as an approver: a rule with `proven` or `roles`
|
|
23
|
+
* counts only a proven approver, one holding a role it names.
|
|
24
|
+
*
|
|
25
|
+
* A rejection that does not count is listed with why, so the run says so.
|
|
26
|
+
* Pure: no git, no clock.
|
|
27
|
+
*/
|
|
28
|
+
import { type GateRejectionRecord } from "../lifecycle/gate-rejection.js";
|
|
29
|
+
import type { GateSigners } from "../lifecycle/gate-seal.js";
|
|
30
|
+
import { type GateQuorumSpec } from "./gate-quorum.js";
|
|
31
|
+
import type { GateApprovalSource } from "./op-waves.js";
|
|
32
|
+
/**
|
|
33
|
+
* The first chant with `chant reject` (#5354): a rejection of the digest a
|
|
34
|
+
* gate waits on, which stops a release at a pipeline stage's gate by the
|
|
35
|
+
* proof rules the gate's approvals count by, and with approval rules that
|
|
36
|
+
* combine in `all` and `any` groups, nested up to three deep, each rule and
|
|
37
|
+
* group with a `name` the progress lines, the plan note and the ledger
|
|
38
|
+
* show, a stage hold's `description`, and a `reject` comment command a
|
|
39
|
+
* comment job records under the author's forge identity (`../ci-comment-reject.ts`).
|
|
40
|
+
*/
|
|
41
|
+
export declare const GATE_REJECTION_FLOOR = "0.124.110";
|
|
42
|
+
/** What a gate's rejections are judged by. */
|
|
43
|
+
export interface GateRejectionInput {
|
|
44
|
+
gate: string;
|
|
45
|
+
/** The digest the gate waits on: a release's at a stage's gate. */
|
|
46
|
+
planDigest: string;
|
|
47
|
+
/** The gate's environment: a stage's name. A rejection that names another environment is for another gate. */
|
|
48
|
+
environment?: string;
|
|
49
|
+
/** The release the gate binds. A rejection that names another release is for another release. */
|
|
50
|
+
releaseDigest?: string;
|
|
51
|
+
/** The gate's approval mode. Default `ledger`. */
|
|
52
|
+
mode?: GateApprovalSource;
|
|
53
|
+
/** The rules the gate takes, after its targets are applied. */
|
|
54
|
+
quorum?: GateQuorumSpec;
|
|
55
|
+
/** The signers and passkeys at base, which prove who signed a rejection. */
|
|
56
|
+
signers: GateSigners;
|
|
57
|
+
/** `.chant/trust.json`'s role grants at base. */
|
|
58
|
+
roles: Readonly<Record<string, readonly string[]>>;
|
|
59
|
+
/** The workspace's `identity.gates` rule for the gate, when one applies. */
|
|
60
|
+
identity?: ((r: GateRejectionRecord) => string | null) | null;
|
|
61
|
+
}
|
|
62
|
+
/** What {@link gateRejections} found. */
|
|
63
|
+
export interface GateRejections {
|
|
64
|
+
/** The rejections that stop the gate, oldest first. */
|
|
65
|
+
standing: GateRejectionRecord[];
|
|
66
|
+
/** Rejections of this digest that do not count, with why, oldest first. */
|
|
67
|
+
ignored: {
|
|
68
|
+
rejection: GateRejectionRecord;
|
|
69
|
+
why: string;
|
|
70
|
+
}[];
|
|
71
|
+
}
|
|
72
|
+
/** Whether `r` rejects this gate's digest: its gate, digest, environment and release. */
|
|
73
|
+
export declare function rejectsDigest(r: GateRejectionRecord, input: Pick<GateRejectionInput, "gate" | "planDigest" | "environment" | "releaseDigest">): boolean;
|
|
74
|
+
/** Why `r` does not count at the gate, or null when it does. */
|
|
75
|
+
export declare function rejectionRefusal(r: GateRejectionRecord, input: GateRejectionInput): string | null;
|
|
76
|
+
/** The rejections of the gate's digest, split into those that stop it and those that do not count. */
|
|
77
|
+
export declare function gateRejections(records: readonly GateRejectionRecord[], input: GateRejectionInput): GateRejections;
|
|
78
|
+
/** The line a stopped gate prints for one rejection: who, when and why. */
|
|
79
|
+
export declare function rejectionLine(r: GateRejectionRecord): string;
|