@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.9
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/LICENSE +21 -0
- package/README.md +310 -3
- package/README.vi.md +280 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13785 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +481 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,641 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* The migration-grant marker (#98) — a per-issue, human-only, branch-bound, expiring exemption
|
|
4
|
+
* to `colab ship`'s no-new-migrations precondition (`newMigrations()` in tools/colab).
|
|
5
|
+
*
|
|
6
|
+
* WHY A GRANT EXISTS AT ALL. The no-new-migrations gate is right by default: a schema change
|
|
7
|
+
* merged into trunk is pulled by every other worktree next, and where dev data is shared a bad
|
|
8
|
+
* one costs everyone at once. But it makes one legitimate class of work permanently un-shippable
|
|
9
|
+
* without a person — an issue whose entire deliverable IS a schema change. Under a scheduled
|
|
10
|
+
* driver such an issue parks forever, every tick. This module is the narrow yes: a human reviewed
|
|
11
|
+
* THIS branch's migration and said so, for THIS issue, until THIS issue closes.
|
|
12
|
+
*
|
|
13
|
+
* TWO MARKERS, TWO DIFFERENT JOBS — read together, never one alone:
|
|
14
|
+
* - a LABEL (`migration-granted`, tools/lib/labels.js) — makes an outstanding grant a cheap
|
|
15
|
+
* `gh issue list --label` query (requirement 7), and — the load-bearing half — applying a
|
|
16
|
+
* label on GitHub requires triage/write permission on the repo, so a drive-by commenter on a
|
|
17
|
+
* public repo cannot manufacture a grant merely by posting a well-formed comment.
|
|
18
|
+
* - a COMMENT (this module's GRANT_MARK/REVOKE_MARK) — carries what a label cannot: the BRANCH
|
|
19
|
+
* the grant is bound to (label names cap at 50 chars; this repo's branch names run longer),
|
|
20
|
+
* who granted it, and when. The comment is the authority; the label is the gate.
|
|
21
|
+
*
|
|
22
|
+
* Both are required for a grant to read as live (evaluateIssue, below) — a label with no live
|
|
23
|
+
* comment is exactly the state a rolled-back/failed write leaves, and must refuse, not "grant".
|
|
24
|
+
*
|
|
25
|
+
* PURE BY CONSTRUCTION, same posture as readiness.js / landed.js / shipguard.js: signals in,
|
|
26
|
+
* verdict out. No git, no network, no `gh`. `tools/colab` has no test harness of its own (see the
|
|
27
|
+
* comment at its `branchCommits` — the reason logic worth pinning lives in tools/lib/*.js instead),
|
|
28
|
+
* so every decision here that is worth getting right on purpose lives in a file `node --test` can
|
|
29
|
+
* reach directly.
|
|
30
|
+
*
|
|
31
|
+
* WHO IS ALLOWED TO WRITE THE COMMENT is a DIFFERENT question from who is allowed to APPLY the
|
|
32
|
+
* label, and this module answers only the second by requiring TRUSTED_ASSOCIATIONS on read —
|
|
33
|
+
* closing the "drive-by comment on a public repo" hole the label already narrows but does not, by
|
|
34
|
+
* itself, close. A repo collaborator can still be a machine account — an agent under its own login
|
|
35
|
+
* reports `MEMBER` exactly like the operator — and the repo states that policy with `trust-humans`
|
|
36
|
+
* in project.yml (#407, tools/lib/trust-humans.js): when set, only a listed login's grant is human,
|
|
37
|
+
* and the label's latest applier must be listed too. The human-only property on the WRITE path (nobody but a person
|
|
38
|
+
* may run `colab migration-grant`) is enforced in tools/colab via COLAB_HUMAN=1 — the identical
|
|
39
|
+
* bar `cmdPromote` already holds a production promotion to. This module has no opinion on how the
|
|
40
|
+
* comment got posted; it only judges whether what's on the tracker, right now, is a live grant
|
|
41
|
+
* this branch and this issue may rely on.
|
|
42
|
+
*/
|
|
43
|
+
|
|
44
|
+
/** The two comment markers. STABLE WIRE FORMAT — do not reword casually; `tools/colab` and any
|
|
45
|
+
* vendored reader parse these verbatim, the same posture as CLAIM_MARK/RELEASE_MARK in tools/colab. */
|
|
46
|
+
const GRANT_MARK = '🛢 Migration grant';
|
|
47
|
+
const REVOKE_MARK = '🚫 Migration grant revoked';
|
|
48
|
+
|
|
49
|
+
// Deliberately DIFFERENT leading emoji (not just different trailing text) so neither `startsWith`
|
|
50
|
+
// nor either regex can ever match the other mark's body — a revoke mark that merely suffixed the
|
|
51
|
+
// grant mark would make every revoke parse as a fresh grant, silently reopening exactly the door
|
|
52
|
+
// it was posted to close. Covered by a dedicated test (grant-revoke-mark-collision).
|
|
53
|
+
const GRANT_RE = /^🛢 Migration grant — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
|
|
54
|
+
const REVOKE_RE = /^🚫 Migration grant revoked — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
|
|
55
|
+
|
|
56
|
+
/** The exact grant-comment body. Keep in lockstep with GRANT_RE. */
|
|
57
|
+
function grantCommentBody(branch, host, iso) {
|
|
58
|
+
return `${GRANT_MARK} — branch \`${branch}\` · host \`${host}\` · ${iso}`
|
|
59
|
+
+ ' — this exempts THIS BRANCH only, and expires when this issue closes.';
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** The exact revoke-comment body. Keep in lockstep with REVOKE_RE. `branch` is the branch named in
|
|
63
|
+
* the record for the audit trail — revocation itself is NOT branch-scoped (see evaluateIssue doc). */
|
|
64
|
+
function revokeCommentBody(branch, host, iso) {
|
|
65
|
+
return `${REVOKE_MARK} — branch \`${branch}\` · host \`${host}\` · ${iso}`
|
|
66
|
+
+ ' — every grant on this issue up to this point is cancelled.';
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Every GRANT_MARK comment not cancelled by a LATER REVOKE_MARK — whoever posted the revoke.
|
|
71
|
+
*
|
|
72
|
+
* Deliberately NOT author-scoped, unlike liveClaimComments() in tools/colab: a claim is a
|
|
73
|
+
* per-identity assertion racing other identities, so cancellation there is scoped to "the same
|
|
74
|
+
* author can undo their own claim." A grant has no race to settle — it is a standing authorization
|
|
75
|
+
* a human is meant to be able to pull the instant it looks wrong, from any trusted account, on any
|
|
76
|
+
* machine. Scoping revocation by author would let a grant outlive a revoke posted from the other
|
|
77
|
+
* maintainer's login or the other machine, which is exactly backwards for a safety gate.
|
|
78
|
+
*
|
|
79
|
+
* Sort is by `createdAt` (GitHub's own timestamp, sub-second, authoritative — never comment order
|
|
80
|
+
* in the array, which is not guaranteed). A grant AFTER the latest revoke is live again: grant,
|
|
81
|
+
* revoke, grant is "currently granted," not "permanently revoked."
|
|
82
|
+
*
|
|
83
|
+
* Returns [{branch, host, at, login, authorAssociation}], oldest-first — a live grant is the LAST
|
|
84
|
+
* entry a caller cares about, but the whole ordered list is returned so a caller (e.g. `--list`)
|
|
85
|
+
* can show history, not just the current verdict.
|
|
86
|
+
*/
|
|
87
|
+
function liveGrants(comments) {
|
|
88
|
+
const list = Array.isArray(comments) ? comments : [];
|
|
89
|
+
const sorted = [...list].sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
|
|
90
|
+
|
|
91
|
+
let lastRevokeAt = null;
|
|
92
|
+
for (const c of sorted) {
|
|
93
|
+
const body = String(c.body || '').trim();
|
|
94
|
+
if (REVOKE_RE.test(body)) {
|
|
95
|
+
if (lastRevokeAt === null || c.createdAt > lastRevokeAt) lastRevokeAt = c.createdAt;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
const live = [];
|
|
100
|
+
for (const c of sorted) {
|
|
101
|
+
const body = String(c.body || '').trim();
|
|
102
|
+
const m = body.match(GRANT_RE);
|
|
103
|
+
if (!m) continue;
|
|
104
|
+
const at = c.createdAt;
|
|
105
|
+
const cancelled = lastRevokeAt !== null && lastRevokeAt > at;
|
|
106
|
+
if (cancelled) continue;
|
|
107
|
+
live.push({
|
|
108
|
+
branch: m[1],
|
|
109
|
+
host: m[2],
|
|
110
|
+
at,
|
|
111
|
+
login: (c.author && c.author.login) || '',
|
|
112
|
+
authorAssociation: c.authorAssociation || '',
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
return live;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** Association values GitHub reports (`gh issue view --json comments`'s `authorAssociation`) that
|
|
119
|
+
* this module treats as trustworthy enough to write a permission a scheduled driver will rely on.
|
|
120
|
+
* This closes a DIFFERENT hole than COLAB_HUMAN (tools/colab): that gates WHO MAY WRITE the
|
|
121
|
+
* comment (a human, via the CLI); this gates WHOSE COMMENT ship WILL HONOR ON READ — closing the
|
|
122
|
+
* gap a public repo has by default, where anyone can post a perfectly-formed comment by hand. */
|
|
123
|
+
const { TRUSTED_ASSOCIATIONS, authorIsHuman, labelApplierIsHuman } = require('./trust-humans.js');
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* One issue's verdict for a branch about to ship. `record` is exactly what
|
|
127
|
+
* `git.ghIssueView(repo, num, ['state', 'labels', 'comments'])` returns, or `null` when that read
|
|
128
|
+
* FAILED — never treat `null` as "no grant"; that conflates "could not confirm" with "confirmed
|
|
129
|
+
* absent," and the caller (tools/colab) must fail closed on the former exactly as hard as the latter.
|
|
130
|
+
*
|
|
131
|
+
* `labelName` is passed in rather than imported from labels.js, keeping this module free of any
|
|
132
|
+
* dependency beyond its own two regexes — the caller (tools/colab) already has labels.js loaded
|
|
133
|
+
* and is the one place that should know the label's name.
|
|
134
|
+
*
|
|
135
|
+
* Order of checks is deliberate: cheapest/most-fundamental failures first, and each has a distinct,
|
|
136
|
+
* actionable reason string — an operator or a scheduled driver's park-and-say-once log reads this
|
|
137
|
+
* directly, so vague reasons cost a person re-deriving what to do.
|
|
138
|
+
*
|
|
139
|
+
* `opts` (#407) — OPTIONAL `{ trust, labelActors }`. `trust` is trust-humans.js parseTrustHumans()
|
|
140
|
+
* of the TARGET's project.yml; absent/undeclared keeps the association check byte-identical. When
|
|
141
|
+
* declared, the grant's author must be a listed login, and `labelActors(issue)` — the logins of
|
|
142
|
+
* every `labeled` event for the label, or null on a failed read — must end in a listed login too.
|
|
143
|
+
*/
|
|
144
|
+
function evaluateIssue(record, branch, issueNum, labelName, opts) {
|
|
145
|
+
const trust = opts && opts.trust;
|
|
146
|
+
const issue = issueNum;
|
|
147
|
+
if (!record) {
|
|
148
|
+
return { issue, ok: false, grant: null,
|
|
149
|
+
reason: `#${issue} could not be read from the tracker — a failed read is never a grant` };
|
|
150
|
+
}
|
|
151
|
+
if (record.state !== 'OPEN') {
|
|
152
|
+
return { issue, ok: false, grant: null,
|
|
153
|
+
reason: `#${issue} is ${record.state || 'not open'} — a grant expires when its issue closes` };
|
|
154
|
+
}
|
|
155
|
+
const labelNames = (record.labels || []).map((l) => (l && typeof l === 'object' ? l.name : l));
|
|
156
|
+
if (!labelNames.includes(labelName)) {
|
|
157
|
+
return { issue, ok: false, grant: null,
|
|
158
|
+
reason: `#${issue} does not carry the \`${labelName}\` label` };
|
|
159
|
+
}
|
|
160
|
+
const grants = liveGrants(record.comments);
|
|
161
|
+
if (grants.length === 0) {
|
|
162
|
+
return { issue, ok: false, grant: null,
|
|
163
|
+
reason: `#${issue} carries the label but has no live grant comment (revoked, or never posted)` };
|
|
164
|
+
}
|
|
165
|
+
const g = grants[grants.length - 1]; // most recent live grant
|
|
166
|
+
if (g.branch !== branch) {
|
|
167
|
+
return { issue, ok: false, grant: g,
|
|
168
|
+
reason: `#${issue}'s grant is bound to branch "${g.branch}", not "${branch}"` };
|
|
169
|
+
}
|
|
170
|
+
const who = authorIsHuman(g, trust);
|
|
171
|
+
if (!who.ok) {
|
|
172
|
+
return { issue, ok: false, grant: g,
|
|
173
|
+
reason: trust && trust.declared
|
|
174
|
+
? `#${issue}'s grant is not a human's: ${who.reason}`
|
|
175
|
+
: `#${issue}'s grant was posted by ${who.reason}` };
|
|
176
|
+
}
|
|
177
|
+
if (trust && trust.declared) {
|
|
178
|
+
// #407 Wanted 2 — read only here: key declared, and every cheaper check already passed.
|
|
179
|
+
let actors = null;
|
|
180
|
+
try { actors = opts && typeof opts.labelActors === 'function' ? opts.labelActors(issue) : null; } catch (_) { actors = null; }
|
|
181
|
+
const lab = labelApplierIsHuman(actors, trust, labelName);
|
|
182
|
+
if (!lab.ok) return { issue, ok: false, grant: g, reason: `#${issue}: ${lab.reason}` };
|
|
183
|
+
}
|
|
184
|
+
return { issue, ok: true, grant: g, reason: '' };
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* The ship set's verdict (#98 requirement 5) — every issue the branch carries, not just the
|
|
189
|
+
* subset that would close (`closeIssues`). A migration cannot be mechanically attributed to one
|
|
190
|
+
* member of a group branch, so if ANY claimed issue lacks a valid grant, the whole set fails —
|
|
191
|
+
* one granted issue must never smuggle an unreviewed migration in for its siblings.
|
|
192
|
+
*
|
|
193
|
+
* NON-VACUITY, on purpose: `[].every(...)` is `true` in JavaScript, and a branch carrying a
|
|
194
|
+
* migration with ZERO claimed issues must NOT read as granted by default — there is no issue for
|
|
195
|
+
* a human to have reviewed against. Refuses explicitly rather than falling through an empty loop.
|
|
196
|
+
*
|
|
197
|
+
* `records` maps issue number → the `ghIssueView` result for that issue, or `null` on a failed
|
|
198
|
+
* read (the caller's job, not this function's — see tools/colab's shipMigrationGate).
|
|
199
|
+
*
|
|
200
|
+
* `ctx` (#401) — OPTIONAL, and absent means exactly the pre-#401 behaviour (human grants only,
|
|
201
|
+
* byte-identical output). Given, it is `{ policy, headSha, roundtrip }` and the ONE rule every
|
|
202
|
+
* ship path shares (`--dry`, `--dry --json`, a real/auto-trunk ship, and batch — which reads
|
|
203
|
+
* through `--dry --json`) — so no path can accept a grant another refuses. Per issue:
|
|
204
|
+
* 1. a live human grant passes, unchanged — it wins where both roles exist;
|
|
205
|
+
* 2. otherwise a reviewer grant passes only when ALL of: P policy is `reviewer` · M a valid,
|
|
206
|
+
* passing, trusted, branch-bound reviewer marker + record · HEAD the record's head equals
|
|
207
|
+
* `headSha` · R `roundtrip()` says the live CI round-trip passed on that HEAD.
|
|
208
|
+
* R is a THUNK, called at most once per set and only once some issue has cleared P, M and HEAD —
|
|
209
|
+
* so a no-migration, human-granted or already-failing ship pays for no CI read. A thunk returning
|
|
210
|
+
* anything but `{ ok: true }` (including `null`, a failed read) fails R closed.
|
|
211
|
+
* `ctx.trust` / `ctx.labelActors` (#407) are evaluateIssue's opts — they decide only what a HUMAN
|
|
212
|
+
* grant is; a reviewer grant is judged by P · M · HEAD · R alone, never by the human list.
|
|
213
|
+
* Every `missing` entry then names the condition that failed in `failed`
|
|
214
|
+
* (`issue` | `human` | `policy` | `marker` | `head` | `roundtrip`), and its reason says so.
|
|
215
|
+
*/
|
|
216
|
+
function evaluateShipSet(issues, records, branch, labelName, ctx) {
|
|
217
|
+
const list = Array.isArray(issues) ? issues : [];
|
|
218
|
+
if (list.length === 0) {
|
|
219
|
+
return { ok: false, granted: [],
|
|
220
|
+
missing: [{ issue: null, reason: 'no claimed issue on this branch could carry a grant' }] };
|
|
221
|
+
}
|
|
222
|
+
if (!ctx) return evaluateHumanOnly(list, records, branch, labelName);
|
|
223
|
+
const policy = ctx.policy === 'reviewer' ? 'reviewer' : 'human';
|
|
224
|
+
const granted = [];
|
|
225
|
+
const missing = [];
|
|
226
|
+
const pending = []; // cleared P+M+HEAD, awaiting R
|
|
227
|
+
for (const n of list) {
|
|
228
|
+
const rec = records ? records[n] : null;
|
|
229
|
+
const h = evaluateIssue(rec, branch, n, labelName, { trust: ctx.trust, labelActors: ctx.labelActors });
|
|
230
|
+
if (h.ok) {
|
|
231
|
+
granted.push({ issue: n, role: 'human', branch: h.grant.branch, by: h.grant.login, at: h.grant.at });
|
|
232
|
+
continue;
|
|
233
|
+
}
|
|
234
|
+
// Failures no grant of any role can get past: the issue itself cannot carry one.
|
|
235
|
+
if (!rec || rec.state !== 'OPEN' || !labelNamesOf(rec).includes(labelName)) {
|
|
236
|
+
missing.push({ issue: n, failed: 'issue', reason: h.reason });
|
|
237
|
+
continue;
|
|
238
|
+
}
|
|
239
|
+
const hasReviewer = liveGrantRecords(rec.comments).some((g) => g.role !== 'human');
|
|
240
|
+
if (!hasReviewer) {
|
|
241
|
+
missing.push({ issue: n, failed: 'human',
|
|
242
|
+
reason: policy === 'reviewer' ? `${h.reason}, and no live reviewer grant either` : h.reason });
|
|
243
|
+
continue;
|
|
244
|
+
}
|
|
245
|
+
const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, issueNum: n, labelName, policy });
|
|
246
|
+
if (!r.ok) {
|
|
247
|
+
const failed = !r.checks.policy ? 'policy' : !r.checks.marker ? 'marker' : 'head';
|
|
248
|
+
missing.push({ issue: n, failed, reason: `reviewer grant [${SHIP_CONDITION_TAG[failed]}]: ${r.reason}` });
|
|
249
|
+
continue;
|
|
250
|
+
}
|
|
251
|
+
pending.push({ n, g: r.grant });
|
|
252
|
+
}
|
|
253
|
+
if (pending.length > 0) {
|
|
254
|
+
let rt = null;
|
|
255
|
+
try { rt = typeof ctx.roundtrip === 'function' ? ctx.roundtrip() : null; } catch (_) { rt = null; }
|
|
256
|
+
const ok = !!rt && rt.ok === true;
|
|
257
|
+
const why = rt && rt.reason ? rt.reason : 'the CI round-trip could not be read — an unread result is never a pass';
|
|
258
|
+
for (const { n, g } of pending) {
|
|
259
|
+
if (ok) {
|
|
260
|
+
granted.push({ issue: n, role: 'reviewer', reviewer: g.reviewer, head: g.head,
|
|
261
|
+
branch: g.branch, by: g.login, at: g.at });
|
|
262
|
+
} else {
|
|
263
|
+
missing.push({ issue: n, failed: 'roundtrip',
|
|
264
|
+
reason: `reviewer grant [${SHIP_CONDITION_TAG.roundtrip}]: #${n}: ${why}` });
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
const order = new Map(list.map((n, i) => [n, i]));
|
|
269
|
+
granted.sort((a, b) => order.get(a.issue) - order.get(b.issue));
|
|
270
|
+
missing.sort((a, b) => order.get(a.issue) - order.get(b.issue));
|
|
271
|
+
return { ok: missing.length === 0, granted, missing };
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** The pre-#401 verdict, kept verbatim so a caller passing no ctx sees no change at all. */
|
|
275
|
+
function evaluateHumanOnly(list, records, branch, labelName) {
|
|
276
|
+
const granted = [];
|
|
277
|
+
const missing = [];
|
|
278
|
+
for (const n of list) {
|
|
279
|
+
const v = evaluateIssue(records ? records[n] : null, branch, n, labelName);
|
|
280
|
+
if (v.ok) granted.push({ issue: n, branch: v.grant.branch, by: v.grant.login, at: v.grant.at });
|
|
281
|
+
else missing.push({ issue: n, reason: v.reason });
|
|
282
|
+
}
|
|
283
|
+
return { ok: missing.length === 0, granted, missing };
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
function labelNamesOf(record) {
|
|
287
|
+
return ((record && record.labels) || []).map((l) => (l && typeof l === 'object' ? l.name : l));
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/** The condition names a refusal is prefixed with — P · M · HEAD · R in the issue's own words. */
|
|
291
|
+
const SHIP_CONDITION_TAG = Object.freeze({ policy: 'P policy', marker: 'M record', head: 'HEAD', roundtrip: 'R round-trip' });
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* The CI round-trip job (#399's `templates/ci-laravel.yml`) is found by NAME PREFIX: its matrix
|
|
295
|
+
* legs are named `Migration round-trip (<engine>)`. Nothing in project.yml names it today (#401
|
|
296
|
+
* risk 1) — a repo that renames the job, or has no such job, cannot pass R, and ships a migration
|
|
297
|
+
* on a human grant exactly as before. STABLE: renaming the template's job breaks this reader.
|
|
298
|
+
*/
|
|
299
|
+
const ROUNDTRIP_JOB_PREFIX = 'Migration round-trip';
|
|
300
|
+
|
|
301
|
+
/**
|
|
302
|
+
* R — did the live CI round-trip pass on the shipped HEAD? Pure: `jobs` is every job of every run
|
|
303
|
+
* at that sha (git.ghRunJobs rows, flattened), or null when any read failed. Passes only when:
|
|
304
|
+
* - the branch does not edit `.github/workflows/**` (`workflowsTouched`) — a branch that can
|
|
305
|
+
* rewrite the job that grades it is not graded by it (the same refusal ci-cure makes);
|
|
306
|
+
* - at least one job named `ROUNDTRIP_JOB_PREFIX…` exists at the sha;
|
|
307
|
+
* - every distinct leg name has an instance that completed `success` with at least one step that
|
|
308
|
+
* actually ran (an all-skipped leg proves nothing). A leg that only failed, is still running,
|
|
309
|
+
* or only skipped fails R and is named. Duplicate instances (a push run and a PR run, or a
|
|
310
|
+
* cancelled straggler) are fine as long as one instance of the leg genuinely passed.
|
|
311
|
+
* Returns { ok, reason, legs }.
|
|
312
|
+
*/
|
|
313
|
+
function roundtripVerdict(jobs, opts) {
|
|
314
|
+
const o = opts || {};
|
|
315
|
+
const sha = o.headSha ? String(o.headSha).slice(0, 7) : 'this HEAD';
|
|
316
|
+
if (o.workflowsTouched) {
|
|
317
|
+
return { ok: false, legs: [], reason: `this branch edits .github/workflows/ — a round-trip it can rewrite does not grade it; ship it on a human grant` };
|
|
318
|
+
}
|
|
319
|
+
if (!Array.isArray(jobs)) {
|
|
320
|
+
return { ok: false, legs: [], reason: `the CI jobs at ${sha} could not be read — an unread result is never a pass` };
|
|
321
|
+
}
|
|
322
|
+
const byLeg = new Map();
|
|
323
|
+
for (const j of jobs) {
|
|
324
|
+
if (!j || typeof j.name !== 'string' || !j.name.startsWith(ROUNDTRIP_JOB_PREFIX)) continue;
|
|
325
|
+
if (!byLeg.has(j.name)) byLeg.set(j.name, []);
|
|
326
|
+
byLeg.get(j.name).push(j);
|
|
327
|
+
}
|
|
328
|
+
if (byLeg.size === 0) {
|
|
329
|
+
return { ok: false, legs: [], reason: `no "${ROUNDTRIP_JOB_PREFIX}" job ran at ${sha}` };
|
|
330
|
+
}
|
|
331
|
+
const legs = [];
|
|
332
|
+
const bad = [];
|
|
333
|
+
for (const [name, inst] of byLeg) {
|
|
334
|
+
const passed = inst.some((j) => j.status === 'completed' && j.conclusion === 'success'
|
|
335
|
+
&& Array.isArray(j.steps) && j.steps.some(stepRanOk));
|
|
336
|
+
legs.push({ name, ok: passed });
|
|
337
|
+
if (!passed) {
|
|
338
|
+
const seen = inst.map((j) => (j.status === 'completed'
|
|
339
|
+
? (j.conclusion === 'success' ? 'success with no step run' : j.conclusion || 'no conclusion')
|
|
340
|
+
: j.status || 'unknown')).join(', ');
|
|
341
|
+
bad.push(`"${name}" did not pass (${seen})`);
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
if (bad.length) return { ok: false, legs, reason: `the CI round-trip at ${sha} failed: ${bad.join('; ')}` };
|
|
345
|
+
return { ok: true, legs, reason: '' };
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/** A step that reached a terminal conclusion other than skipped/cancelled — ci-cure.js stepRan. */
|
|
349
|
+
function stepRanOk(s) {
|
|
350
|
+
return !!s && s.status === 'completed' && s.conclusion !== 'skipped' && s.conclusion !== 'cancelled';
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
// ============================================================================================
|
|
354
|
+
// ROLE-TAGGED GRANTS (#397) and the repo policy that says whether a reviewer may grant (#398).
|
|
355
|
+
//
|
|
356
|
+
// WHAT THIS ADDS, AND WHAT IT DELIBERATELY DOES NOT. A human grant (above) is a label plus a
|
|
357
|
+
// comment, and the comment says nothing about WHO decided: one minted through a dashboard is
|
|
358
|
+
// byte-identical to one any trusted account could post. The reviewer role gives that decision a
|
|
359
|
+
// shape — a declared reviewer identity, and a REVIEW RECORD (verdict, checklist result, which
|
|
360
|
+
// escalation condition was checked, the CI round-trip result, the reviewed HEAD) — so a later
|
|
361
|
+
// reader can check the review rather than trust the comment.
|
|
362
|
+
//
|
|
363
|
+
// HOW SHIP READS IT (#401). liveGrants()/evaluateIssue() above read ONLY the human marker, and the
|
|
364
|
+
// reviewer marker is built so GRANT_RE can never match it (different leading emoji — the same
|
|
365
|
+
// collision discipline as grant vs revoke). evaluateShipSet() above honours a reviewer grant only
|
|
366
|
+
// when given a ctx, and then only with all four of P (policy) · M (this block's record) · HEAD ·
|
|
367
|
+
// R (live CI round-trip) — evaluateReviewerGrant() below is its P/M/HEAD half.
|
|
368
|
+
//
|
|
369
|
+
// THE REVIEWER IDENTITY IS DECLARED, NOT ATTESTED. The only anti-forgery properties are the same
|
|
370
|
+
// two the human grant has — the label needs write/triage permission, and TRUSTED_ASSOCIATIONS on
|
|
371
|
+
// read. A reader must not treat `reviewer:` as proof of who reviewed; it is who the grant SAYS
|
|
372
|
+
// reviewed. Likewise `ci-roundtrip:` is the reviewer's report — a gate should re-verify CI for
|
|
373
|
+
// `head` itself rather than rely on the recorded value.
|
|
374
|
+
// ============================================================================================
|
|
375
|
+
|
|
376
|
+
/** The reviewer grant's first-line mark. STABLE WIRE FORMAT. Distinct leading emoji on purpose:
|
|
377
|
+
* GRANT_RE (the human marker, the one today's ship gate reads) must never match a reviewer grant. */
|
|
378
|
+
const REVIEW_GRANT_MARK = '🔎 Migration review grant';
|
|
379
|
+
const REVIEWER_ROLE = 'migration-reviewer';
|
|
380
|
+
const GRANT_ROLES = Object.freeze(['human', REVIEWER_ROLE]);
|
|
381
|
+
|
|
382
|
+
const REVIEW_GRANT_RE = /^🔎 Migration review grant — role `([^`]*)` · reviewer `([^`]*)` · branch `([^`]*)` · head `([^`]*)` · host `([^`]*)` · (\S+)/;
|
|
383
|
+
|
|
384
|
+
/** The fenced block's info string — the record is found by it, never by position. */
|
|
385
|
+
const REVIEW_RECORD_FENCE = 'migration-review';
|
|
386
|
+
const REVIEW_RECORD_VERSION = '1';
|
|
387
|
+
|
|
388
|
+
const SHA40_RE = /^[0-9a-f]{40}$/;
|
|
389
|
+
const REVIEWER_ID_RE = /^[A-Za-z0-9._@-]+$/;
|
|
390
|
+
const CONDITION_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
|
|
391
|
+
|
|
392
|
+
/** Every key a v1 record may carry, and what each accepts. `required: false` keys may be absent.
|
|
393
|
+
* Order here is the order reviewGrantCommentBody() writes them in. */
|
|
394
|
+
const REVIEW_RECORD_FIELDS = Object.freeze([
|
|
395
|
+
{ key: 'v', required: true, values: [REVIEW_RECORD_VERSION] },
|
|
396
|
+
{ key: 'role', required: true, values: [REVIEWER_ROLE] },
|
|
397
|
+
{ key: 'reviewer', required: true, re: REVIEWER_ID_RE, hint: 'letters, digits, . _ @ -' },
|
|
398
|
+
{ key: 'head', required: true, re: SHA40_RE, hint: 'a full 40-hex commit sha' },
|
|
399
|
+
{ key: 'verdict', required: true, values: ['approve', 'reject'] },
|
|
400
|
+
{ key: 'checklist', required: true, values: ['pass', 'fail'] },
|
|
401
|
+
{ key: 'checklist-items', required: false, re: /^\d+\/\d+$/, hint: 'N/M, e.g. 7/7' },
|
|
402
|
+
{ key: 'escalation', required: true, re: CONDITION_ID_RE, hint: 'a condition id, lowercase-hyphenated' },
|
|
403
|
+
{ key: 'escalation-result', required: true, values: ['clear', 'escalated'] },
|
|
404
|
+
{ key: 'ci-roundtrip', required: true, values: ['pass', 'fail', 'pending'] },
|
|
405
|
+
{ key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
|
|
406
|
+
]);
|
|
407
|
+
const REVIEW_RECORD_KEYS = new Set(REVIEW_RECORD_FIELDS.map((f) => f.key));
|
|
408
|
+
|
|
409
|
+
/**
|
|
410
|
+
* Validate a record object (key → string) — from a parsed comment or from CLI flags, the SAME
|
|
411
|
+
* function for both, so the mint path and the read path can never disagree about what is valid.
|
|
412
|
+
* `marker` (optional) is the parsed first line; when given, `head` and `reviewer` must agree with
|
|
413
|
+
* it — a record reviewing one sha under a marker naming another is not a review of anything.
|
|
414
|
+
*
|
|
415
|
+
* Returns { valid, passing, problems }. VALID = well-formed. PASSING = valid AND the review said
|
|
416
|
+
* yes on every axis (approve · checklist pass · escalation clear · CI round-trip pass). The two are
|
|
417
|
+
* separate because a well-formed failing review is a real, recordable outcome — just never a grant.
|
|
418
|
+
*/
|
|
419
|
+
function validateReviewRecord(rec, marker) {
|
|
420
|
+
const problems = [];
|
|
421
|
+
const r = rec && typeof rec === 'object' ? rec : {};
|
|
422
|
+
for (const k of Object.keys(r)) {
|
|
423
|
+
if (!REVIEW_RECORD_KEYS.has(k)) problems.push(`unknown key "${k}" — a v${REVIEW_RECORD_VERSION} review record has no such field`);
|
|
424
|
+
}
|
|
425
|
+
for (const f of REVIEW_RECORD_FIELDS) {
|
|
426
|
+
const has = Object.prototype.hasOwnProperty.call(r, f.key) && r[f.key] !== undefined && r[f.key] !== null && String(r[f.key]) !== '';
|
|
427
|
+
if (!has) {
|
|
428
|
+
if (f.required) problems.push(`missing "${f.key}"`);
|
|
429
|
+
continue;
|
|
430
|
+
}
|
|
431
|
+
const v = String(r[f.key]);
|
|
432
|
+
if (f.values && !f.values.includes(v)) problems.push(`"${f.key}" is ${JSON.stringify(v)}, expected ${f.values.join(' | ')}`);
|
|
433
|
+
if (f.re && !f.re.test(v)) problems.push(`"${f.key}" is ${JSON.stringify(v)}, expected ${f.hint}`);
|
|
434
|
+
}
|
|
435
|
+
if (r['checklist-items'] && /^\d+\/\d+$/.test(r['checklist-items'])) {
|
|
436
|
+
const [a, b] = String(r['checklist-items']).split('/').map(Number);
|
|
437
|
+
if (b === 0 || a > b) problems.push(`"checklist-items" is ${r['checklist-items']} — N must be ≤ M and M > 0`);
|
|
438
|
+
}
|
|
439
|
+
if (marker) {
|
|
440
|
+
if (r.head && marker.head !== r.head) problems.push(`record head ${String(r.head).slice(0, 7)} differs from the marker's head ${String(marker.head).slice(0, 7)}`);
|
|
441
|
+
if (r.reviewer && marker.reviewer !== r.reviewer) problems.push(`record reviewer "${r.reviewer}" differs from the marker's reviewer "${marker.reviewer}"`);
|
|
442
|
+
if (marker.role !== REVIEWER_ROLE) problems.push(`marker role is "${marker.role}", expected "${REVIEWER_ROLE}"`);
|
|
443
|
+
if (!SHA40_RE.test(String(marker.head || ''))) problems.push(`marker head "${marker.head}" is not a full 40-hex sha`);
|
|
444
|
+
}
|
|
445
|
+
const valid = problems.length === 0;
|
|
446
|
+
const passing = valid && r.verdict === 'approve' && r.checklist === 'pass'
|
|
447
|
+
&& r['escalation-result'] === 'clear' && r['ci-roundtrip'] === 'pass';
|
|
448
|
+
return { valid, passing, problems };
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
/** Why a VALID record is not passing, as one line — or '' when it passes. */
|
|
452
|
+
function reviewRecordFailure(rec) {
|
|
453
|
+
const why = [];
|
|
454
|
+
if (rec.verdict !== 'approve') why.push(`verdict ${rec.verdict}`);
|
|
455
|
+
if (rec.checklist !== 'pass') why.push(`checklist ${rec.checklist}`);
|
|
456
|
+
if (rec['escalation-result'] !== 'clear') why.push(`escalation ${rec.escalation} ${rec['escalation-result']}`);
|
|
457
|
+
if (rec['ci-roundtrip'] !== 'pass') why.push(`CI round-trip ${rec['ci-roundtrip']}`);
|
|
458
|
+
return why.join(', ');
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
/**
|
|
462
|
+
* The exact reviewer-grant comment body: marker line, blank line, fenced record. Keep in lockstep
|
|
463
|
+
* with REVIEW_GRANT_RE and parseReviewRecord. `rec` must carry at least role/reviewer/head; the
|
|
464
|
+
* caller (tools/colab) validates it with validateReviewRecord BEFORE calling this.
|
|
465
|
+
*/
|
|
466
|
+
function reviewGrantCommentBody(branch, host, iso, rec) {
|
|
467
|
+
const head = `${REVIEW_GRANT_MARK} — role \`${rec.role}\` · reviewer \`${rec.reviewer}\` · branch \`${branch}\``
|
|
468
|
+
+ ` · head \`${rec.head}\` · host \`${host}\` · ${iso}`
|
|
469
|
+
+ ' — bound to this HEAD: any new commit voids it; expires when this issue closes.';
|
|
470
|
+
const lines = [];
|
|
471
|
+
for (const f of REVIEW_RECORD_FIELDS) {
|
|
472
|
+
const v = rec[f.key];
|
|
473
|
+
if (v === undefined || v === null || String(v) === '') continue;
|
|
474
|
+
lines.push(`${f.key}: ${v}`);
|
|
475
|
+
}
|
|
476
|
+
return `${head}\n\n\`\`\`${REVIEW_RECORD_FENCE}\n${lines.join('\n')}\n\`\`\``;
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
/**
|
|
480
|
+
* Parse a reviewer-grant comment body → { marker, record, problems } or null when the first line
|
|
481
|
+
* is not a reviewer-grant marker at all. The record is the FIRST fenced block whose info string is
|
|
482
|
+
* exactly `migration-review`; text outside it is ignored. A marker with no such block, or a block
|
|
483
|
+
* with a malformed line, returns problems — never a record silently missing fields.
|
|
484
|
+
*/
|
|
485
|
+
function parseReviewGrant(body) {
|
|
486
|
+
const text = String(body || '').replace(/\r\n/g, '\n').trim();
|
|
487
|
+
const m = text.match(REVIEW_GRANT_RE);
|
|
488
|
+
if (!m) return null;
|
|
489
|
+
const marker = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], host: m[5], at: m[6] };
|
|
490
|
+
const problems = [];
|
|
491
|
+
const fence = new RegExp('^```' + REVIEW_RECORD_FENCE + '[ \\t]*\\n([\\s\\S]*?)^```[ \\t]*$', 'm');
|
|
492
|
+
const fm = text.match(fence);
|
|
493
|
+
if (!fm) {
|
|
494
|
+
problems.push(`no \`\`\`${REVIEW_RECORD_FENCE} block — a reviewer grant without its review record is not a grant`);
|
|
495
|
+
return { marker, record: null, problems };
|
|
496
|
+
}
|
|
497
|
+
const record = {};
|
|
498
|
+
for (const raw of fm[1].split('\n')) {
|
|
499
|
+
const line = raw.trim();
|
|
500
|
+
if (line === '') continue;
|
|
501
|
+
const kv = line.match(/^([a-z][a-z-]*):\s*(.*)$/);
|
|
502
|
+
if (!kv) { problems.push(`record line ${JSON.stringify(line)} is not "key: value"`); continue; }
|
|
503
|
+
if (Object.prototype.hasOwnProperty.call(record, kv[1])) { problems.push(`"${kv[1]}" appears twice`); continue; }
|
|
504
|
+
record[kv[1]] = kv[2].trim();
|
|
505
|
+
}
|
|
506
|
+
const v = validateReviewRecord(record, marker);
|
|
507
|
+
problems.push(...v.problems);
|
|
508
|
+
return { marker, record, problems };
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
/**
|
|
512
|
+
* Every live grant of EVERY role — the human ones liveGrants() returns, plus reviewer grants —
|
|
513
|
+
* after the same revoke rule (a revoke cancels every earlier grant, whichever role, whoever posted
|
|
514
|
+
* it). Oldest-first. Reviewer entries carry { role, reviewer, head, record, problems, valid,
|
|
515
|
+
* passing }; human entries carry role 'human'. For listing and for evaluateReviewerGrant — the
|
|
516
|
+
* ship gate's evaluateIssue deliberately keeps reading liveGrants() (human only).
|
|
517
|
+
*/
|
|
518
|
+
function liveGrantRecords(comments) {
|
|
519
|
+
const list = Array.isArray(comments) ? comments : [];
|
|
520
|
+
const sorted = [...list].sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
|
|
521
|
+
let lastRevokeAt = null;
|
|
522
|
+
for (const c of sorted) {
|
|
523
|
+
if (REVOKE_RE.test(String(c.body || '').trim())) {
|
|
524
|
+
if (lastRevokeAt === null || c.createdAt > lastRevokeAt) lastRevokeAt = c.createdAt;
|
|
525
|
+
}
|
|
526
|
+
}
|
|
527
|
+
const out = [];
|
|
528
|
+
for (const c of sorted) {
|
|
529
|
+
const at = c.createdAt;
|
|
530
|
+
if (lastRevokeAt !== null && lastRevokeAt > at) continue;
|
|
531
|
+
const body = String(c.body || '').trim();
|
|
532
|
+
const base = { at, login: (c.author && c.author.login) || '', authorAssociation: c.authorAssociation || '' };
|
|
533
|
+
const h = body.match(GRANT_RE);
|
|
534
|
+
if (h) { out.push({ role: 'human', branch: h[1], host: h[2], ...base }); continue; }
|
|
535
|
+
const r = parseReviewGrant(body);
|
|
536
|
+
if (r) {
|
|
537
|
+
const v = r.record ? validateReviewRecord(r.record, r.marker) : { valid: false, passing: false };
|
|
538
|
+
out.push({
|
|
539
|
+
role: r.marker.role, reviewer: r.marker.reviewer, branch: r.marker.branch, head: r.marker.head,
|
|
540
|
+
host: r.marker.host, ...base, record: r.record, problems: r.problems,
|
|
541
|
+
valid: r.problems.length === 0 && v.valid, passing: r.problems.length === 0 && v.passing,
|
|
542
|
+
});
|
|
543
|
+
}
|
|
544
|
+
}
|
|
545
|
+
return out;
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
/**
|
|
549
|
+
* HEAD binding. A human grant is branch-bound, not HEAD-bound (unchanged since #98) → unbound, ok.
|
|
550
|
+
* A reviewer grant covers exactly the commit it reviewed: ok only when `branchHeadSha` is a full
|
|
551
|
+
* 40-hex sha equal (case-insensitively) to the grant's head. A short or missing sha is NOT ok —
|
|
552
|
+
* "could not confirm the HEAD" is never read as "the HEAD matches", and never a prefix match.
|
|
553
|
+
*/
|
|
554
|
+
function grantHeadBinding(grant, branchHeadSha) {
|
|
555
|
+
if (!grant || grant.role === 'human' || grant.role === undefined) return { bound: false, ok: true, reason: '' };
|
|
556
|
+
const want = String(grant.head || '').toLowerCase();
|
|
557
|
+
const have = String(branchHeadSha || '').toLowerCase();
|
|
558
|
+
if (!SHA40_RE.test(have)) {
|
|
559
|
+
return { bound: true, ok: false, reason: `cannot confirm the branch HEAD (${have ? `"${have}" is not a full sha` : 'no sha given'}) — a reviewer grant is bound to one commit` };
|
|
560
|
+
}
|
|
561
|
+
if (want !== have) {
|
|
562
|
+
return { bound: true, ok: false, reason: `reviewer grant is bound to ${want.slice(0, 7)}, branch is at ${have.slice(0, 7)} — a new commit voids it` };
|
|
563
|
+
}
|
|
564
|
+
return { bound: true, ok: true, reason: '' };
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
/** `migration-grant:` values, in project.yml (#398). Absent = human, today's behaviour. */
|
|
568
|
+
const GRANT_POLICIES = Object.freeze(['human', 'reviewer']);
|
|
569
|
+
|
|
570
|
+
/**
|
|
571
|
+
* `migration-grant:` from a parsed project.yml → { policy, declared, valid, reason }. A flat key,
|
|
572
|
+
* NOT nested under `migrations:` (which stays a list of path prefixes — three readers depend on
|
|
573
|
+
* that shape, and a map there would fail every descriptor not yet migrated). An invalid value is
|
|
574
|
+
* read as `human` — the stricter reading, same posture as parseShipBatch — and `valid: false` so
|
|
575
|
+
* the audit fails it.
|
|
576
|
+
*/
|
|
577
|
+
function parseGrantPolicy(doc) {
|
|
578
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'migration-grant');
|
|
579
|
+
const raw = has ? doc['migration-grant'] : undefined;
|
|
580
|
+
if (!has || raw === null || raw === undefined) {
|
|
581
|
+
return { policy: 'human', declared: false, valid: true, reason: 'migration-grant absent — human grants only' };
|
|
582
|
+
}
|
|
583
|
+
const v = typeof raw === 'string' ? raw.trim() : raw;
|
|
584
|
+
if (typeof v === 'string' && GRANT_POLICIES.includes(v)) {
|
|
585
|
+
return { policy: v, declared: true, valid: true, reason: `migration-grant: ${v}` };
|
|
586
|
+
}
|
|
587
|
+
return { policy: 'human', declared: true, valid: false,
|
|
588
|
+
reason: `migration-grant is ${JSON.stringify(raw)}, expected ${GRANT_POLICIES.join(' | ')} (omit for human)` };
|
|
589
|
+
}
|
|
590
|
+
|
|
591
|
+
/**
|
|
592
|
+
* The reviewer-grant verdict for one issue — P, M and HEAD of the ship rule; evaluateShipSet()
|
|
593
|
+
* (#401) calls it and adds R. `ctx` = { branch, headSha, issueNum, labelName, policy } where
|
|
594
|
+
* `policy` is parseGrantPolicy(...).policy. Checks, cheapest/most-fundamental first, each with its
|
|
595
|
+
* own reason: read failed · not open · no label · policy not `reviewer` · no live reviewer grant ·
|
|
596
|
+
* branch mismatch · untrusted author · record invalid · record not passing · HEAD binding.
|
|
597
|
+
* The CI round-trip is checked here only as RECORDED; re-verifying it against live CI for `head`
|
|
598
|
+
* is the gate's job. Returns { ok, grant, reason, checks: { policy, marker, head } }.
|
|
599
|
+
*/
|
|
600
|
+
function evaluateReviewerGrant(record, ctx) {
|
|
601
|
+
const c = ctx || {};
|
|
602
|
+
const issue = c.issueNum;
|
|
603
|
+
const checks = { policy: false, marker: false, head: false };
|
|
604
|
+
const no = (reason, grant = null) => ({ issue, ok: false, grant, reason, checks });
|
|
605
|
+
if (!record) return no(`#${issue} could not be read from the tracker — a failed read is never a grant`);
|
|
606
|
+
if (record.state !== 'OPEN') return no(`#${issue} is ${record.state || 'not open'} — a grant expires when its issue closes`);
|
|
607
|
+
const labelNames = (record.labels || []).map((l) => (l && typeof l === 'object' ? l.name : l));
|
|
608
|
+
if (!labelNames.includes(c.labelName)) return no(`#${issue} does not carry the \`${c.labelName}\` label`);
|
|
609
|
+
if (c.policy !== 'reviewer') return no(`this repo's migration-grant policy is "${c.policy || 'human'}" — a reviewer grant is honoured only under migration-grant: reviewer`);
|
|
610
|
+
checks.policy = true;
|
|
611
|
+
const reviewer = liveGrantRecords(record.comments).filter((g) => g.role !== 'human');
|
|
612
|
+
if (reviewer.length === 0) return no(`#${issue} has no live reviewer grant (revoked, or never posted)`);
|
|
613
|
+
const g = reviewer[reviewer.length - 1];
|
|
614
|
+
if (g.branch !== c.branch) return no(`#${issue}'s reviewer grant is bound to branch "${g.branch}", not "${c.branch}"`, g);
|
|
615
|
+
if (!TRUSTED_ASSOCIATIONS.has(g.authorAssociation)) {
|
|
616
|
+
return no(`#${issue}'s reviewer grant was posted by ${g.login || '(unknown)'} (${g.authorAssociation || 'unknown association'}) — not a repo owner/member/collaborator`, g);
|
|
617
|
+
}
|
|
618
|
+
if (!g.valid) return no(`#${issue}'s reviewer grant has an invalid review record: ${(g.problems || []).join('; ') || 'unreadable'}`, g);
|
|
619
|
+
if (!g.passing) return no(`#${issue}'s review record does not pass: ${reviewRecordFailure(g.record)}`, g);
|
|
620
|
+
checks.marker = true;
|
|
621
|
+
const hb = grantHeadBinding(g, c.headSha);
|
|
622
|
+
if (!hb.ok) return no(`#${issue}: ${hb.reason}`, g);
|
|
623
|
+
checks.head = true;
|
|
624
|
+
return { issue, ok: true, grant: g, reason: '', checks };
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
module.exports = {
|
|
628
|
+
GRANT_MARK, REVOKE_MARK, GRANT_RE, REVOKE_RE,
|
|
629
|
+
grantCommentBody, revokeCommentBody,
|
|
630
|
+
liveGrants, TRUSTED_ASSOCIATIONS,
|
|
631
|
+
evaluateIssue, evaluateShipSet,
|
|
632
|
+
// #397 — role-tagged grants
|
|
633
|
+
REVIEW_GRANT_MARK, REVIEW_GRANT_RE, REVIEWER_ROLE, GRANT_ROLES,
|
|
634
|
+
REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS,
|
|
635
|
+
validateReviewRecord, reviewRecordFailure, reviewGrantCommentBody, parseReviewGrant,
|
|
636
|
+
liveGrantRecords, grantHeadBinding, evaluateReviewerGrant,
|
|
637
|
+
// #398 — repo policy
|
|
638
|
+
GRANT_POLICIES, parseGrantPolicy,
|
|
639
|
+
// #401 — ship honours a reviewer grant
|
|
640
|
+
ROUNDTRIP_JOB_PREFIX, roundtripVerdict, SHIP_CONDITION_TAG,
|
|
641
|
+
};
|