rungate 0.5.0 → 0.7.0
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/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,790 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* branch-protection.ts — PROTECT-1: does this repo's protection serialise
|
|
3
|
+
* every swarm's PRs? (#909)
|
|
4
|
+
*
|
|
5
|
+
* `required_status_checks.strict` is GitHub's "Require branches to be up to
|
|
6
|
+
* date before merging". Under it, merging PR #1 invalidates #2..#N: each then
|
|
7
|
+
* needs `gh pr update-branch`, a full CI re-run, then a merge. Measured on a
|
|
8
|
+
* real consumer on 2026-10-21 at **2.5 minutes per PR, strictly serial** — 18
|
|
9
|
+
* open PRs, every one `BEHIND`, not one of them broken. A 30-PR swarm is ~90
|
|
10
|
+
* minutes of serialisation during which the swarm opens more PRs, so it never
|
|
11
|
+
* converges. #909 has the repo and the figures.
|
|
12
|
+
*
|
|
13
|
+
* It is the single biggest throughput limit on a RunGate consumer and it is
|
|
14
|
+
* invisible from every direction a reviewer looks: each PR is individually
|
|
15
|
+
* healthy, CI is green, nothing is red anywhere. The only place the cause is
|
|
16
|
+
* visible is a repo setting nothing in the harness had ever read.
|
|
17
|
+
*
|
|
18
|
+
* ## Why the remedy is not one sentence
|
|
19
|
+
*
|
|
20
|
+
* The normal fix is a merge queue, which batches N PRs into one speculative
|
|
21
|
+
* commit and tests once. **It is not available on a user-owned repo.** GitHub
|
|
22
|
+
* restricts merge queues to organization-owned repositories, and private org
|
|
23
|
+
* repos additionally need Enterprise Cloud. Measured the same day:
|
|
24
|
+
*
|
|
25
|
+
* gh api repos/hornjason/pai-harness -q .owner.type -> "User"
|
|
26
|
+
* POST /repos/hornjason/pai-harness/rulesets, merge_queue rule
|
|
27
|
+
* -> 422 Validation Failed, "Invalid rule 'merge_queue': "
|
|
28
|
+
*
|
|
29
|
+
* The identical ruleset without that one rule is accepted, so the 422 is
|
|
30
|
+
* GitHub refusing on owner type rather than rejecting a malformed payload.
|
|
31
|
+
* And the LEGACY branch-protection endpoint silently *ignores* a
|
|
32
|
+
* `required_merge_queue` field, which is why this reads as "configured" to
|
|
33
|
+
* anyone who sets it there and then checks for an error.
|
|
34
|
+
*
|
|
35
|
+
* So one message for both owner types would be the defect, not the feature:
|
|
36
|
+
* on a user-owned repo "enable a merge queue" is advice that cannot be
|
|
37
|
+
* followed, and a gate that refuses with an impossible remedy gets switched
|
|
38
|
+
* off. Organization → merge queue. User → `strict: false`.
|
|
39
|
+
*
|
|
40
|
+
* ## Why `strict: false` is not advised unconditionally
|
|
41
|
+
*
|
|
42
|
+
* `strict: true` is doing one real job: catching the SEMANTIC conflict — two
|
|
43
|
+
* PRs each green alone and broken together, which no textual merge conflict
|
|
44
|
+
* reports. Turning it off is safe only when something else catches that, and
|
|
45
|
+
* the something else is CI on `push:` to the default branch: the pair lands,
|
|
46
|
+
* main goes red within minutes, and a human sees it.
|
|
47
|
+
*
|
|
48
|
+
* Without push-CI, `strict: false` removes the only check standing between a
|
|
49
|
+
* swarm and a quietly broken default branch. This module therefore REFUSES to
|
|
50
|
+
* recommend `strict: false` on a repo whose required contexts do not run on
|
|
51
|
+
* push, and says that is why. Recommending it there would be this gate
|
|
52
|
+
* causing the outage it exists to prevent.
|
|
53
|
+
*
|
|
54
|
+
* ## Reads. Never writes.
|
|
55
|
+
*
|
|
56
|
+
* Nothing here calls a mutating endpoint. A scaffold that silently rewrote a
|
|
57
|
+
* repository's security settings would be a worse problem than the one it
|
|
58
|
+
* fixes — the operator's next read of their own protection config would be a
|
|
59
|
+
* reading of what a tool decided, with no record that it decided it. The
|
|
60
|
+
* output is a refusal naming the setting, the cost and the exact remedy; the
|
|
61
|
+
* change is the operator's.
|
|
62
|
+
*
|
|
63
|
+
* ## UNMEASURED is not a pass
|
|
64
|
+
*
|
|
65
|
+
* The protection endpoint needs admin on the repo, and the default Actions
|
|
66
|
+
* token does not have it — so 403 is the ORDINARY outcome in a consumer's CI,
|
|
67
|
+
* not an exotic one. If a 403 fell through to "no violations found", this
|
|
68
|
+
* check would report clean on every repo it cannot see, which is the whole of
|
|
69
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`: `0`, `{}`, `null` and SKIP
|
|
70
|
+
* are indistinguishable from success. Every unreadable path lands on
|
|
71
|
+
* UNMEASURED with the cause named.
|
|
72
|
+
*
|
|
73
|
+
* The one thing that is NOT UNMEASURED is an unprotected branch. That is read
|
|
74
|
+
* from `GET /repos/{owner}/{repo}/branches/{branch}`, which needs only read
|
|
75
|
+
* access and returns `protected`, so "not protected" is a fact this check
|
|
76
|
+
* establishes rather than a status code it has to guess at.
|
|
77
|
+
*
|
|
78
|
+
* That pre-call is load-bearing, and the measurement says so. Probing
|
|
79
|
+
* `oven-sh/bun` on 2026-10-21 with a token that has no admin there:
|
|
80
|
+
*
|
|
81
|
+
* GET /repos/oven-sh/bun/branches/main -> protected: true
|
|
82
|
+
* GET /repos/oven-sh/bun/branches/main/protection -> 404 Not Found
|
|
83
|
+
*
|
|
84
|
+
* **404, not 403.** The non-admin response is byte-identical to the response
|
|
85
|
+
* for a branch with no protection at all. Asking the protection endpoint
|
|
86
|
+
* first and reading its 404 as "nothing configured" would therefore report a
|
|
87
|
+
* confident PASS on every repo the token cannot see into — which is this
|
|
88
|
+
* check certifying the exact thing it exists to find.
|
|
89
|
+
*/
|
|
90
|
+
|
|
91
|
+
import { readFileSync, readdirSync, statSync } from "fs";
|
|
92
|
+
import { join } from "path";
|
|
93
|
+
|
|
94
|
+
import { createGitHubClient, parseOwnerRepo, type GitHubClient } from "./github";
|
|
95
|
+
import { originSlug } from "./verified-push";
|
|
96
|
+
|
|
97
|
+
// ── Facts ───────────────────────────────────────────────
|
|
98
|
+
|
|
99
|
+
/** What one reading of a repo's protection established. */
|
|
100
|
+
export interface ProtectionFacts {
|
|
101
|
+
/** `owner/name` the facts are about. */
|
|
102
|
+
slug: string;
|
|
103
|
+
/** The default branch the protection was read for, or null when unknown. */
|
|
104
|
+
branch: string | null;
|
|
105
|
+
/**
|
|
106
|
+
* `required_status_checks.strict`, or null when it could not be determined.
|
|
107
|
+
*
|
|
108
|
+
* `false` is a measured fact and includes the unprotected branch: nothing
|
|
109
|
+
* is requiring anything, so nothing is serialising.
|
|
110
|
+
*/
|
|
111
|
+
strict: boolean | null;
|
|
112
|
+
/** `owner.type` — "User", "Organization", or whatever GitHub said. */
|
|
113
|
+
ownerType: string | null;
|
|
114
|
+
/** `required_status_checks.contexts`, in the order GitHub returned them. */
|
|
115
|
+
contexts: string[];
|
|
116
|
+
/**
|
|
117
|
+
* Whether a merge queue is already in front of this branch, or null when
|
|
118
|
+
* the payload said nothing either way.
|
|
119
|
+
*
|
|
120
|
+
* Honest about its own limits: the legacy protection endpoint is not a
|
|
121
|
+
* reliable reporter of merge-queue state, which is the same quirk that made
|
|
122
|
+
* `required_merge_queue` writes vanish. `null` therefore means "not
|
|
123
|
+
* established", never "absent", and only an explicit `true` is allowed to
|
|
124
|
+
* excuse `strict: true`.
|
|
125
|
+
*/
|
|
126
|
+
mergeQueueEnabled: boolean | null;
|
|
127
|
+
/**
|
|
128
|
+
* Non-null when something could not be read: no credential, no remote, a
|
|
129
|
+
* 403, a network failure. Named, because a cause the operator cannot see is
|
|
130
|
+
* a cause they cannot fix.
|
|
131
|
+
*/
|
|
132
|
+
unreadable: string | null;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/** What the local tree says about CI on `push:` to the default branch. */
|
|
136
|
+
export interface PushCiReading {
|
|
137
|
+
/** Required contexts proven to run on push to the default branch. */
|
|
138
|
+
onPush: string[];
|
|
139
|
+
/** Required contexts with no such trigger. Non-empty blocks `strict: false`. */
|
|
140
|
+
missing: string[];
|
|
141
|
+
/**
|
|
142
|
+
* Non-null when the workflows could not be read at all, so neither list
|
|
143
|
+
* means anything. An empty `missing` from an unread directory is the
|
|
144
|
+
* fail-open this field exists to prevent.
|
|
145
|
+
*/
|
|
146
|
+
unmeasured: string | null;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
export type ProtectionVerdict = "PASS" | "FAIL" | "UNMEASURED";
|
|
150
|
+
|
|
151
|
+
export interface ProtectionReading {
|
|
152
|
+
verdict: ProtectionVerdict;
|
|
153
|
+
/** A sentence naming why, in every branch including PASS. */
|
|
154
|
+
reason: string;
|
|
155
|
+
/**
|
|
156
|
+
* What to do about it, differing by owner type. Empty string on PASS and on
|
|
157
|
+
* UNMEASURED — there is nothing to remedy and nothing established to remedy
|
|
158
|
+
* it from.
|
|
159
|
+
*/
|
|
160
|
+
remedy: string;
|
|
161
|
+
/** Whether GitHub would allow a merge queue here. null when unestablished. */
|
|
162
|
+
mergeQueuePossible: boolean | null;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
// ── The measured cost, quoted once ──────────────────────
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* One sentence, used in every FAIL. A refusal that says "this is slow"
|
|
169
|
+
* is an opinion; one that says 2.5 minutes per PR over 18 PRs is a number the
|
|
170
|
+
* operator can weigh against the thing they were about to do instead.
|
|
171
|
+
*
|
|
172
|
+
* The consumer it was measured on is NOT named, and this string is the reason
|
|
173
|
+
* that matters more than the usual one. It is not a comment — it ships into
|
|
174
|
+
* the findings report of whichever consumer runs this check, so naming the
|
|
175
|
+
* repo would print one consumer's name to every other one. SC-A1 in
|
|
176
|
+
* `test/anti.test.ts` refuses the harness naming a consumer anywhere under
|
|
177
|
+
* `lib/`; #909 carries the repo and the full table.
|
|
178
|
+
*/
|
|
179
|
+
const MEASURED_COST =
|
|
180
|
+
"measured 2026-10-21 on a real consumer at ~2.5 min per PR, strictly serial — " +
|
|
181
|
+
"18 open PRs, every one BEHIND, none merging and none broken (rungate#909)";
|
|
182
|
+
|
|
183
|
+
const SERIALISES =
|
|
184
|
+
"required_status_checks.strict = true (\"Require branches to be up to date before merging\") " +
|
|
185
|
+
"means merging one PR invalidates every other open PR: each then needs a branch update, a " +
|
|
186
|
+
"full CI re-run, and a merge, one at a time";
|
|
187
|
+
|
|
188
|
+
// ── The classification ──────────────────────────────────
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* The verdict for one repo, from its protection facts and its push-CI.
|
|
192
|
+
*
|
|
193
|
+
* Pure, and separate from the fetching, because every interesting decision
|
|
194
|
+
* here is a classification rather than a network call — and the
|
|
195
|
+
* classification is the part that has to be wrong-proof. `readCi` in
|
|
196
|
+
* `lib/github.ts` is split the same way for the same reason.
|
|
197
|
+
*
|
|
198
|
+
* **No branch reaches PASS by not finding a problem.** PASS requires either a
|
|
199
|
+
* positively-read `strict === false`, or a merge queue explicitly reported as
|
|
200
|
+
* enabled. Unknown owner type, unknown strict, unreadable anything: all
|
|
201
|
+
* UNMEASURED.
|
|
202
|
+
*/
|
|
203
|
+
export function readMergeSerialisation(
|
|
204
|
+
facts: ProtectionFacts,
|
|
205
|
+
pushCi: PushCiReading,
|
|
206
|
+
): ProtectionReading {
|
|
207
|
+
const where = facts.branch ? `${facts.slug}@${facts.branch}` : facts.slug;
|
|
208
|
+
|
|
209
|
+
if (facts.unreadable) {
|
|
210
|
+
return {
|
|
211
|
+
verdict: "UNMEASURED",
|
|
212
|
+
reason:
|
|
213
|
+
`UNMEASURED: branch protection for ${where} was not read — ${facts.unreadable}. ` +
|
|
214
|
+
"Nothing was checked, which is NOT the same as nothing being wrong: the protection " +
|
|
215
|
+
"endpoint needs admin on the repo, so a token without it produces this and a correctly " +
|
|
216
|
+
"configured repo must not look the same.",
|
|
217
|
+
remedy: "",
|
|
218
|
+
mergeQueuePossible: null,
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
if (facts.strict === null) {
|
|
223
|
+
return {
|
|
224
|
+
verdict: "UNMEASURED",
|
|
225
|
+
reason:
|
|
226
|
+
`UNMEASURED: the protection payload for ${where} carried no ` +
|
|
227
|
+
"required_status_checks.strict, so whether merges serialise here is not established.",
|
|
228
|
+
remedy: "",
|
|
229
|
+
mergeQueuePossible: null,
|
|
230
|
+
};
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
if (facts.strict === false) {
|
|
234
|
+
const ctx = facts.contexts.length
|
|
235
|
+
? `required contexts kept: ${facts.contexts.join(", ")}`
|
|
236
|
+
: "no required contexts are configured";
|
|
237
|
+
return {
|
|
238
|
+
verdict: "PASS",
|
|
239
|
+
reason: `${where} has required_status_checks.strict = false, so merging one PR does not invalidate the others — ${ctx}.`,
|
|
240
|
+
remedy: "",
|
|
241
|
+
mergeQueuePossible: facts.ownerType === "Organization",
|
|
242
|
+
};
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
// strict === true from here down. The serialisation is a measured fact; the
|
|
246
|
+
// only open question is what to tell the operator to do about it.
|
|
247
|
+
|
|
248
|
+
if (facts.mergeQueueEnabled === true) {
|
|
249
|
+
return {
|
|
250
|
+
verdict: "PASS",
|
|
251
|
+
reason:
|
|
252
|
+
`${where} has required_status_checks.strict = true, but a merge queue is enabled in ` +
|
|
253
|
+
"front of it — the queue batches PRs into one speculative commit and tests once, which " +
|
|
254
|
+
"is what makes strict safe. This is the configuration strict was designed for.",
|
|
255
|
+
remedy: "",
|
|
256
|
+
mergeQueuePossible: true,
|
|
257
|
+
};
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
if (facts.ownerType === null) {
|
|
261
|
+
return {
|
|
262
|
+
verdict: "UNMEASURED",
|
|
263
|
+
reason:
|
|
264
|
+
`UNMEASURED: ${where} has required_status_checks.strict = true, but owner.type was not ` +
|
|
265
|
+
"read, and the remedy differs by it — an organization can enable a merge queue and a " +
|
|
266
|
+
"user account cannot. Refusing with the wrong remedy is worse than not refusing.",
|
|
267
|
+
remedy: "",
|
|
268
|
+
mergeQueuePossible: null,
|
|
269
|
+
};
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
if (facts.ownerType === "Organization") {
|
|
273
|
+
return {
|
|
274
|
+
verdict: "FAIL",
|
|
275
|
+
reason:
|
|
276
|
+
`${where} serialises every PR: ${SERIALISES} — ${MEASURED_COST}. ` +
|
|
277
|
+
"This repo is organization-owned, so the proper fix is available.",
|
|
278
|
+
remedy:
|
|
279
|
+
"Enable a merge queue on the default branch (Settings → Branches, or a ruleset with a " +
|
|
280
|
+
"merge_queue rule). It batches queued PRs into one speculative commit and tests once, " +
|
|
281
|
+
"which keeps strict: true honest instead of serial. Note that a PRIVATE org repo needs " +
|
|
282
|
+
"GitHub Enterprise Cloud for this; if that is not available, treat this repo as the " +
|
|
283
|
+
"user-owned case and set strict: false with push-CI covering the required contexts. " +
|
|
284
|
+
"Also give ci.yml and gates.yml a `merge_group:` trigger — without it the queue waits " +
|
|
285
|
+
"forever on a required check that never reports.",
|
|
286
|
+
mergeQueuePossible: true,
|
|
287
|
+
};
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
// User-owned: no merge queue is possible here, at any price. GitHub refuses
|
|
291
|
+
// the merge_queue rule on owner.type alone.
|
|
292
|
+
const base =
|
|
293
|
+
`${where} serialises every PR: ${SERIALISES} — ${MEASURED_COST}. ` +
|
|
294
|
+
`This repo is owned by a ${facts.ownerType} account, and GitHub restricts merge queues to ` +
|
|
295
|
+
"ORGANIZATION-owned repositories — POSTing a ruleset with a merge_queue rule here returns " +
|
|
296
|
+
"422 \"Invalid rule 'merge_queue'\", while the identical ruleset without it is accepted. " +
|
|
297
|
+
"So the usual advice does not apply: there is no merge queue to enable.";
|
|
298
|
+
|
|
299
|
+
if (pushCi.unmeasured) {
|
|
300
|
+
return {
|
|
301
|
+
verdict: "FAIL",
|
|
302
|
+
reason: `${base} ${pushCi.unmeasured}`,
|
|
303
|
+
remedy:
|
|
304
|
+
"REFUSING to recommend strict: false — this check could not establish that the required " +
|
|
305
|
+
"contexts run on push: to the default branch, and strict: true is the only thing " +
|
|
306
|
+
"catching a semantic conflict (two PRs each green alone, broken together) when they do " +
|
|
307
|
+
"not. Fix the reading first, then re-run: the answer may well be that push-CI is " +
|
|
308
|
+
"already there.",
|
|
309
|
+
mergeQueuePossible: false,
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
if (pushCi.missing.length > 0) {
|
|
314
|
+
return {
|
|
315
|
+
verdict: "FAIL",
|
|
316
|
+
reason:
|
|
317
|
+
`${base} It is ALSO not safe to simply turn strict off here: ` +
|
|
318
|
+
`${pushCi.missing.join(", ")} ` +
|
|
319
|
+
`${pushCi.missing.length === 1 ? "does" : "do"} not run on push: to ` +
|
|
320
|
+
`${facts.branch ?? "the default branch"}.`,
|
|
321
|
+
remedy:
|
|
322
|
+
"REFUSING to recommend strict: false. strict: true is doing one real job — catching the " +
|
|
323
|
+
"semantic conflict, two PRs each green alone and broken together, which no textual merge " +
|
|
324
|
+
"conflict reports. Without CI on push: to the default branch, turning it off removes the " +
|
|
325
|
+
"only thing that catches it and main breaks quietly. Do this first: add " +
|
|
326
|
+
`\`on: push: branches: [${facts.branch ?? "main"}]\` to the workflow(s) providing ` +
|
|
327
|
+
`${pushCi.missing.join(", ")}, confirm a push run reports, and only then set strict: false.`,
|
|
328
|
+
mergeQueuePossible: false,
|
|
329
|
+
};
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
const covered = pushCi.onPush.length
|
|
333
|
+
? `All ${pushCi.onPush.length} required context(s) — ${pushCi.onPush.join(", ")} — already run on push: to ${facts.branch ?? "the default branch"}`
|
|
334
|
+
: "No contexts are required, so nothing is lost by it";
|
|
335
|
+
return {
|
|
336
|
+
verdict: "FAIL",
|
|
337
|
+
reason: `${base} ${covered}, so the safe remedy is available.`,
|
|
338
|
+
remedy:
|
|
339
|
+
"Set required_status_checks.strict = false and KEEP the required contexts " +
|
|
340
|
+
`(${facts.contexts.length ? facts.contexts.join(", ") : "none configured"}). ` +
|
|
341
|
+
`${covered}, so a semantic conflict — two PRs each green alone, broken together — still ` +
|
|
342
|
+
"reds the default branch within minutes of landing, which is the thing strict was buying. " +
|
|
343
|
+
"Apply it yourself; this check reads and refuses and never writes protection. " +
|
|
344
|
+
"The read-only command that shows the current state: " +
|
|
345
|
+
`gh api repos/${facts.slug}/branches/${facts.branch ?? "main"}/protection ` +
|
|
346
|
+
"-q .required_status_checks",
|
|
347
|
+
mergeQueuePossible: false,
|
|
348
|
+
};
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
// ── The probe: the one seam, used by production and by tests ────────────
|
|
352
|
+
|
|
353
|
+
/**
|
|
354
|
+
* Establish the protection facts for one repo.
|
|
355
|
+
*
|
|
356
|
+
* This type IS the seam. `runBranchProtectionValidation` takes one of these
|
|
357
|
+
* and defaults to `githubProtectionProbe`, so a test substituting a probe is
|
|
358
|
+
* substituting the thing production substitutes into — not a parallel path
|
|
359
|
+
* that only tests take. A test seam the production code does not go through
|
|
360
|
+
* measures the seam.
|
|
361
|
+
*/
|
|
362
|
+
export type ProtectionProbe = (slug: string) => Promise<ProtectionFacts>;
|
|
363
|
+
|
|
364
|
+
/** A facts object that established nothing, with the cause named. */
|
|
365
|
+
export function unreadableFacts(slug: string, why: string): ProtectionFacts {
|
|
366
|
+
return {
|
|
367
|
+
slug,
|
|
368
|
+
branch: null,
|
|
369
|
+
strict: null,
|
|
370
|
+
ownerType: null,
|
|
371
|
+
contexts: [],
|
|
372
|
+
mergeQueueEnabled: null,
|
|
373
|
+
unreadable: why,
|
|
374
|
+
};
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/** The status an Octokit error carried, or null for a non-HTTP failure. */
|
|
378
|
+
function httpStatus(e: unknown): number | null {
|
|
379
|
+
const s = (e as { status?: unknown })?.status;
|
|
380
|
+
return typeof s === "number" ? s : null;
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
function describeError(e: unknown): string {
|
|
384
|
+
const status = httpStatus(e);
|
|
385
|
+
const msg = (e as Error)?.message ?? String(e);
|
|
386
|
+
return status === null ? msg : `HTTP ${status}: ${msg}`;
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
/**
|
|
390
|
+
* Give up rather than hang. A conformity suite that blocks on a socket is a
|
|
391
|
+
* suite nobody runs, and an indefinite wait and a 403 are the same
|
|
392
|
+
* non-answer — so the timeout lands on UNMEASURED like every other one.
|
|
393
|
+
*/
|
|
394
|
+
const PROBE_TIMEOUT_MS = 15_000;
|
|
395
|
+
|
|
396
|
+
function withTimeout<T>(p: Promise<T>, ms: number, what: string): Promise<T> {
|
|
397
|
+
return Promise.race([
|
|
398
|
+
p,
|
|
399
|
+
new Promise<T>((_, reject) =>
|
|
400
|
+
setTimeout(() => reject(new Error(`${what} did not answer within ${ms}ms`)), ms).unref?.(),
|
|
401
|
+
),
|
|
402
|
+
]);
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
/**
|
|
406
|
+
* Read a repo's protection from GitHub. Three GETs, no writes.
|
|
407
|
+
*
|
|
408
|
+
* Order matters and is the reason this is not one call:
|
|
409
|
+
*
|
|
410
|
+
* 1. `GET /repos/{o}/{r}` — owner.type, default_branch
|
|
411
|
+
* 2. `GET /repos/{o}/{r}/branches/{b}` — `protected`, readable without admin
|
|
412
|
+
* 3. `GET /…/branches/{b}/protection` — strict, contexts; ADMIN ONLY
|
|
413
|
+
*
|
|
414
|
+
* Step 2 exists so that step 3's absence is never guessed at. Without it, an
|
|
415
|
+
* unprotected branch and a token lacking admin both arrive as a 404 at step 3
|
|
416
|
+
* and the check would have to pick one; with it, `protected: false` is a fact
|
|
417
|
+
* and a 403/404 at step 3 is UNMEASURED.
|
|
418
|
+
*/
|
|
419
|
+
export const githubProtectionProbe: ProtectionProbe = async (slug) => {
|
|
420
|
+
let client: GitHubClient;
|
|
421
|
+
try {
|
|
422
|
+
client = createGitHubClient();
|
|
423
|
+
} catch (e) {
|
|
424
|
+
return unreadableFacts(
|
|
425
|
+
slug,
|
|
426
|
+
`no usable GitHub credential (${(e as Error).message}); set GITHUB_TOKEN or GH_TOKEN to a ` +
|
|
427
|
+
"token with admin:repo access to read branch protection",
|
|
428
|
+
);
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
let owner: string;
|
|
432
|
+
let repo: string;
|
|
433
|
+
try {
|
|
434
|
+
({ owner, repo } = parseOwnerRepo(slug));
|
|
435
|
+
} catch (e) {
|
|
436
|
+
return unreadableFacts(slug, (e as Error).message);
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
let ownerType: string | null = null;
|
|
440
|
+
let branch: string;
|
|
441
|
+
try {
|
|
442
|
+
const r = await withTimeout(client.rest.repos.get({ owner, repo }), PROBE_TIMEOUT_MS, `GET /repos/${slug}`);
|
|
443
|
+
const t = r.data?.owner?.type;
|
|
444
|
+
ownerType = typeof t === "string" ? t : null;
|
|
445
|
+
const b = r.data?.default_branch;
|
|
446
|
+
if (typeof b !== "string" || !b) {
|
|
447
|
+
return unreadableFacts(slug, `GET /repos/${slug} returned no default_branch`);
|
|
448
|
+
}
|
|
449
|
+
branch = b;
|
|
450
|
+
} catch (e) {
|
|
451
|
+
return unreadableFacts(slug, `GET /repos/${slug} failed — ${describeError(e)}`);
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
const partial = (why: string): ProtectionFacts => ({
|
|
455
|
+
...unreadableFacts(slug, why),
|
|
456
|
+
branch,
|
|
457
|
+
ownerType,
|
|
458
|
+
});
|
|
459
|
+
|
|
460
|
+
let isProtected: boolean;
|
|
461
|
+
try {
|
|
462
|
+
const r = await withTimeout(
|
|
463
|
+
client.rest.repos.getBranch({ owner, repo, branch }),
|
|
464
|
+
PROBE_TIMEOUT_MS,
|
|
465
|
+
`GET /repos/${slug}/branches/${branch}`,
|
|
466
|
+
);
|
|
467
|
+
const p = r.data?.protected;
|
|
468
|
+
if (typeof p !== "boolean") {
|
|
469
|
+
return partial(`GET /repos/${slug}/branches/${branch} returned no boolean 'protected' field`);
|
|
470
|
+
}
|
|
471
|
+
isProtected = p;
|
|
472
|
+
} catch (e) {
|
|
473
|
+
return partial(`GET /repos/${slug}/branches/${branch} failed — ${describeError(e)}`);
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
// An unprotected branch requires nothing, so nothing is strict and nothing
|
|
477
|
+
// serialises. Measured false, not an unread null.
|
|
478
|
+
if (!isProtected) {
|
|
479
|
+
return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: null, unreadable: null };
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
try {
|
|
483
|
+
const r = await withTimeout(
|
|
484
|
+
client.rest.repos.getBranchProtection({ owner, repo, branch }),
|
|
485
|
+
PROBE_TIMEOUT_MS,
|
|
486
|
+
`GET /repos/${slug}/branches/${branch}/protection`,
|
|
487
|
+
);
|
|
488
|
+
return protectionFactsFromPayload(slug, branch, ownerType, r.data);
|
|
489
|
+
} catch (e) {
|
|
490
|
+
const status = httpStatus(e);
|
|
491
|
+
const note =
|
|
492
|
+
status === 403 || status === 404
|
|
493
|
+
? " — this endpoint requires ADMIN on the repository, and the default GitHub Actions " +
|
|
494
|
+
"token does not have it, so this is the ordinary outcome in CI rather than an error"
|
|
495
|
+
: "";
|
|
496
|
+
return partial(`GET /repos/${slug}/branches/${branch}/protection failed — ${describeError(e)}${note}`);
|
|
497
|
+
}
|
|
498
|
+
};
|
|
499
|
+
|
|
500
|
+
/**
|
|
501
|
+
* The protection payload reduced to the four fields a verdict depends on.
|
|
502
|
+
*
|
|
503
|
+
* Exported and pure so the shape-handling is testable without a network: the
|
|
504
|
+
* API returns `required_status_checks` only when checks are required, and a
|
|
505
|
+
* reader that assumed it was always present would throw on exactly the repos
|
|
506
|
+
* that have nothing to report.
|
|
507
|
+
*/
|
|
508
|
+
export function protectionFactsFromPayload(
|
|
509
|
+
slug: string,
|
|
510
|
+
branch: string,
|
|
511
|
+
ownerType: string | null,
|
|
512
|
+
data: unknown,
|
|
513
|
+
): ProtectionFacts {
|
|
514
|
+
const d = (data ?? {}) as Record<string, any>;
|
|
515
|
+
const rsc = d.required_status_checks;
|
|
516
|
+
|
|
517
|
+
// No required_status_checks block: protection exists but requires no
|
|
518
|
+
// checks, so there is no strictness and nothing to be out of date against.
|
|
519
|
+
if (!rsc || typeof rsc !== "object") {
|
|
520
|
+
return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: mergeQueueFrom(d), unreadable: null };
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
const strict = typeof rsc.strict === "boolean" ? rsc.strict : null;
|
|
524
|
+
// `contexts` is the legacy field and `checks[].context` the current one.
|
|
525
|
+
// Both are read because branch protection still answers with either, and a
|
|
526
|
+
// reader of one alone reports "no required contexts" on a repo that has
|
|
527
|
+
// several — which would make the push-CI precondition vacuously satisfied.
|
|
528
|
+
const legacy = Array.isArray(rsc.contexts) ? rsc.contexts : [];
|
|
529
|
+
const modern = Array.isArray(rsc.checks) ? rsc.checks.map((c: any) => c?.context) : [];
|
|
530
|
+
const contexts = [...new Set([...legacy, ...modern])].filter(
|
|
531
|
+
(c: unknown): c is string => typeof c === "string" && c.length > 0,
|
|
532
|
+
);
|
|
533
|
+
|
|
534
|
+
return { slug, branch, strict, ownerType, contexts, mergeQueueEnabled: mergeQueueFrom(d), unreadable: null };
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
function mergeQueueFrom(d: Record<string, any>): boolean | null {
|
|
538
|
+
const e = d.required_merge_queue?.enabled;
|
|
539
|
+
return typeof e === "boolean" ? e : null;
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
/** The `owner/name` this tree pushes to, for the probe to ask about. */
|
|
543
|
+
export function protectionSubject(root: string): string | null {
|
|
544
|
+
return originSlug(root);
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
// ── Push-CI, read from the local tree ───────────────────
|
|
548
|
+
|
|
549
|
+
const WORKFLOW_EXT = /\.ya?ml$/i;
|
|
550
|
+
|
|
551
|
+
/**
|
|
552
|
+
* Which of `contexts` run on `push:` to `branch`, judged from
|
|
553
|
+
* `.github/workflows/`.
|
|
554
|
+
*
|
|
555
|
+
* Read from the tree and not from GitHub's API on purpose: the question is
|
|
556
|
+
* what the code in THIS commit does, and that is what the operator is about
|
|
557
|
+
* to change protection against. A run-history query would answer a question
|
|
558
|
+
* about the past.
|
|
559
|
+
*
|
|
560
|
+
* An absent or unreadable workflows directory is `unmeasured`, never an empty
|
|
561
|
+
* `missing`. Those two produce byte-identical lists and mean opposite things,
|
|
562
|
+
* and the empty one would silently clear the push-CI precondition for
|
|
563
|
+
* `strict: false` — the gate recommending the change on exactly the repos
|
|
564
|
+
* where it is least safe.
|
|
565
|
+
*/
|
|
566
|
+
export function readPushCi(root: string, contexts: string[], branch: string): PushCiReading {
|
|
567
|
+
const dir = join(root, ".github", "workflows");
|
|
568
|
+
|
|
569
|
+
let entries: string[];
|
|
570
|
+
try {
|
|
571
|
+
if (!statSync(dir).isDirectory()) {
|
|
572
|
+
return unmeasuredPushCi(`${dir} is not a directory, so no push: trigger could be read`);
|
|
573
|
+
}
|
|
574
|
+
entries = readdirSync(dir).filter(n => WORKFLOW_EXT.test(n)).sort();
|
|
575
|
+
} catch (e) {
|
|
576
|
+
const why = (e as NodeJS.ErrnoException).code === "ENOENT"
|
|
577
|
+
? `${dir} does not exist`
|
|
578
|
+
: `${dir} is unreadable — ${(e as Error).message}`;
|
|
579
|
+
return unmeasuredPushCi(`${why}, so no push: trigger could be read`);
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
const unreadable: string[] = [];
|
|
583
|
+
const pushContexts = new Set<string>();
|
|
584
|
+
for (const name of entries) {
|
|
585
|
+
let text: string;
|
|
586
|
+
try {
|
|
587
|
+
text = readFileSync(join(dir, name), "utf-8");
|
|
588
|
+
} catch (e) {
|
|
589
|
+
// Not "has no push trigger" and not "has one": both are claims about
|
|
590
|
+
// bytes nobody read.
|
|
591
|
+
unreadable.push(`${name} (${(e as Error).message})`);
|
|
592
|
+
continue;
|
|
593
|
+
}
|
|
594
|
+
if (!runsOnPushTo(text, branch)) continue;
|
|
595
|
+
for (const job of jobContextNames(text)) pushContexts.add(job);
|
|
596
|
+
}
|
|
597
|
+
|
|
598
|
+
if (unreadable.length > 0) {
|
|
599
|
+
return unmeasuredPushCi(
|
|
600
|
+
`${unreadable.length} workflow file(s) could not be read — ${unreadable.join(", ")} — ` +
|
|
601
|
+
"so whether the required contexts run on push is not established",
|
|
602
|
+
);
|
|
603
|
+
}
|
|
604
|
+
|
|
605
|
+
return {
|
|
606
|
+
onPush: contexts.filter(c => pushContexts.has(c)),
|
|
607
|
+
missing: contexts.filter(c => !pushContexts.has(c)),
|
|
608
|
+
unmeasured: null,
|
|
609
|
+
};
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
function unmeasuredPushCi(why: string): PushCiReading {
|
|
613
|
+
return {
|
|
614
|
+
onPush: [],
|
|
615
|
+
missing: [],
|
|
616
|
+
unmeasured: `UNMEASURED push-CI: ${why}.`,
|
|
617
|
+
};
|
|
618
|
+
}
|
|
619
|
+
|
|
620
|
+
// ── The small amount of YAML this needs ─────────────────
|
|
621
|
+
//
|
|
622
|
+
// A real parser is not pulled in for this. The two questions are "is there a
|
|
623
|
+
// `push:` under `on:` that matches this branch" and "what are the job context
|
|
624
|
+
// names", both of which are top-level structure in a file GitHub itself
|
|
625
|
+
// requires to be conventionally shaped. What a parser would buy is handling of
|
|
626
|
+
// forms no CI workflow uses; what it would cost is a dependency in the one
|
|
627
|
+
// module a consumer's conformity suite imports.
|
|
628
|
+
//
|
|
629
|
+
// Every function here is deliberately conservative: when the shape is not one
|
|
630
|
+
// it recognises, it reports NOT-matching rather than guessing, and the gate
|
|
631
|
+
// upstream turns a non-match into a refusal to recommend `strict: false`. The
|
|
632
|
+
// error direction is toward "we did not establish it", never toward "fine".
|
|
633
|
+
|
|
634
|
+
/** Lines with whole-line comments dropped and indentation preserved. */
|
|
635
|
+
function significantLines(text: string): string[] {
|
|
636
|
+
return text
|
|
637
|
+
.split("\n")
|
|
638
|
+
.filter(l => l.trim() !== "" && !l.trimStart().startsWith("#"));
|
|
639
|
+
}
|
|
640
|
+
|
|
641
|
+
/** The lines of the block introduced by top-level `key:`, excluding the key line. */
|
|
642
|
+
function topLevelBlock(lines: string[], keys: string[]): { header: string; body: string[] } | null {
|
|
643
|
+
for (let i = 0; i < lines.length; i++) {
|
|
644
|
+
const m = lines[i].match(/^(["']?)([A-Za-z_][A-Za-z0-9_-]*)\1\s*:(.*)$/);
|
|
645
|
+
if (!m || !keys.includes(m[2])) continue;
|
|
646
|
+
const body: string[] = [];
|
|
647
|
+
for (let j = i + 1; j < lines.length; j++) {
|
|
648
|
+
if (/^\S/.test(lines[j])) break;
|
|
649
|
+
body.push(lines[j]);
|
|
650
|
+
}
|
|
651
|
+
return { header: m[3].trim(), body };
|
|
652
|
+
}
|
|
653
|
+
return null;
|
|
654
|
+
}
|
|
655
|
+
|
|
656
|
+
/** Indentation width of a line, in spaces. */
|
|
657
|
+
function indentOf(line: string): number {
|
|
658
|
+
return line.length - line.trimStart().length;
|
|
659
|
+
}
|
|
660
|
+
|
|
661
|
+
/** The sub-block of `key:` within an already-dedented-by-context block. */
|
|
662
|
+
function childBlock(body: string[], key: string): { header: string; body: string[] } | null {
|
|
663
|
+
const base = body.length ? Math.min(...body.map(indentOf)) : 0;
|
|
664
|
+
for (let i = 0; i < body.length; i++) {
|
|
665
|
+
if (indentOf(body[i]) !== base) continue;
|
|
666
|
+
const m = body[i].trim().match(/^(["']?)([A-Za-z_][A-Za-z0-9_-]*)\1\s*:(.*)$/);
|
|
667
|
+
if (!m || m[2] !== key) continue;
|
|
668
|
+
const out: string[] = [];
|
|
669
|
+
for (let j = i + 1; j < body.length; j++) {
|
|
670
|
+
if (indentOf(body[j]) <= base) break;
|
|
671
|
+
out.push(body[j]);
|
|
672
|
+
}
|
|
673
|
+
return { header: m[3].trim(), body: out };
|
|
674
|
+
}
|
|
675
|
+
return null;
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
/** Entries of a YAML sequence in either flow (`[a, b]`) or block (`- a`) form. */
|
|
679
|
+
function sequenceEntries(header: string, body: string[]): string[] {
|
|
680
|
+
const out: string[] = [];
|
|
681
|
+
const flow = header.match(/^\[(.*)\]$/);
|
|
682
|
+
if (flow) {
|
|
683
|
+
for (const part of flow[1].split(",")) {
|
|
684
|
+
const v = unquote(part.trim());
|
|
685
|
+
if (v) out.push(v);
|
|
686
|
+
}
|
|
687
|
+
return out;
|
|
688
|
+
}
|
|
689
|
+
for (const line of body) {
|
|
690
|
+
const m = line.trim().match(/^-\s*(.+)$/);
|
|
691
|
+
if (m) out.push(unquote(m[1].trim()));
|
|
692
|
+
}
|
|
693
|
+
return out;
|
|
694
|
+
}
|
|
695
|
+
|
|
696
|
+
function unquote(s: string): string {
|
|
697
|
+
const m = s.match(/^(["'])(.*)\1$/);
|
|
698
|
+
return m ? m[2] : s;
|
|
699
|
+
}
|
|
700
|
+
|
|
701
|
+
/**
|
|
702
|
+
* Does a `branches:` pattern cover `branch`?
|
|
703
|
+
*
|
|
704
|
+
* Supports exactly what GitHub's filter syntax does for the cases that occur:
|
|
705
|
+
* a literal name, `*` within a path segment, and `**` across them. An
|
|
706
|
+
* unrecognised pattern does not match, so an exotic filter produces "we did
|
|
707
|
+
* not establish push-CI" rather than a confident wrong yes.
|
|
708
|
+
*/
|
|
709
|
+
export function branchPatternMatches(pattern: string, branch: string): boolean {
|
|
710
|
+
if (pattern === branch) return true;
|
|
711
|
+
if (!pattern.includes("*")) return false;
|
|
712
|
+
const rx = pattern
|
|
713
|
+
.split("**")
|
|
714
|
+
.map(seg => seg.split("*").map(escapeRegex).join("[^/]*"))
|
|
715
|
+
.join(".*");
|
|
716
|
+
try {
|
|
717
|
+
return new RegExp(`^${rx}$`).test(branch);
|
|
718
|
+
} catch {
|
|
719
|
+
return false;
|
|
720
|
+
}
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
function escapeRegex(s: string): string {
|
|
724
|
+
return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
725
|
+
}
|
|
726
|
+
|
|
727
|
+
/**
|
|
728
|
+
* Whether this workflow runs on a push to `branch`.
|
|
729
|
+
*
|
|
730
|
+
* The `on:` key is the one place YAML's own history bites: unquoted `on` is a
|
|
731
|
+
* boolean in YAML 1.1, so files in the wild write `'on':` and `"on":` too, and
|
|
732
|
+
* a reader matching only the bare form silently sees no triggers at all.
|
|
733
|
+
*/
|
|
734
|
+
export function runsOnPushTo(text: string, branch: string): boolean {
|
|
735
|
+
const lines = significantLines(text);
|
|
736
|
+
const on = topLevelBlock(lines, ["on"]);
|
|
737
|
+
if (!on) return false;
|
|
738
|
+
|
|
739
|
+
// `on: push` and `on: [push, pull_request]` carry no branch filter at all,
|
|
740
|
+
// which in GitHub's semantics means every branch — including this one.
|
|
741
|
+
if (on.header) {
|
|
742
|
+
if (on.header === "push") return true;
|
|
743
|
+
const flow = on.header.match(/^\[(.*)\]$/);
|
|
744
|
+
if (flow) return flow[1].split(",").map(p => unquote(p.trim())).includes("push");
|
|
745
|
+
return false;
|
|
746
|
+
}
|
|
747
|
+
|
|
748
|
+
const push = childBlock(on.body, "push");
|
|
749
|
+
if (!push) return false;
|
|
750
|
+
|
|
751
|
+
const ignore = childBlock(push.body, "branches-ignore");
|
|
752
|
+
if (ignore) {
|
|
753
|
+
return !sequenceEntries(ignore.header, ignore.body).some(p => branchPatternMatches(p, branch));
|
|
754
|
+
}
|
|
755
|
+
|
|
756
|
+
const branches = childBlock(push.body, "branches");
|
|
757
|
+
// `push:` with no filter fires on every branch.
|
|
758
|
+
if (!branches) return true;
|
|
759
|
+
return sequenceEntries(branches.header, branches.body).some(p => branchPatternMatches(p, branch));
|
|
760
|
+
}
|
|
761
|
+
|
|
762
|
+
/**
|
|
763
|
+
* The status-check context names a workflow contributes.
|
|
764
|
+
*
|
|
765
|
+
* A job's context is its `name:` when it has one and its key otherwise —
|
|
766
|
+
* which is why the key alone is not enough: `test:` with `name: Suite`
|
|
767
|
+
* reports as `Suite` in branch protection, and a check looking for `test`
|
|
768
|
+
* would call a configured repo unconfigured.
|
|
769
|
+
*/
|
|
770
|
+
export function jobContextNames(text: string): string[] {
|
|
771
|
+
const lines = significantLines(text);
|
|
772
|
+
const jobs = topLevelBlock(lines, ["jobs"]);
|
|
773
|
+
if (!jobs || jobs.body.length === 0) return [];
|
|
774
|
+
const base = Math.min(...jobs.body.map(indentOf));
|
|
775
|
+
|
|
776
|
+
const names: string[] = [];
|
|
777
|
+
for (let i = 0; i < jobs.body.length; i++) {
|
|
778
|
+
if (indentOf(jobs.body[i]) !== base) continue;
|
|
779
|
+
const key = jobs.body[i].trim().match(/^(["']?)([A-Za-z_][A-Za-z0-9_-]*)\1\s*:\s*$/);
|
|
780
|
+
if (!key) continue;
|
|
781
|
+
const block: string[] = [];
|
|
782
|
+
for (let j = i + 1; j < jobs.body.length; j++) {
|
|
783
|
+
if (indentOf(jobs.body[j]) <= base) break;
|
|
784
|
+
block.push(jobs.body[j]);
|
|
785
|
+
}
|
|
786
|
+
const name = childBlock(block, "name");
|
|
787
|
+
names.push(name?.header ? unquote(name.header) : key[2]);
|
|
788
|
+
}
|
|
789
|
+
return names;
|
|
790
|
+
}
|