@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,653 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* The labels the conventions define, in one place — CONVENTIONS.md §9 (step 3) is the
|
|
4
|
+
* prose source; this is the machine copy the tooling reads, kept beside it the way the
|
|
5
|
+
* tier set lives in both the prose and the audit's VALID_TIERS.
|
|
6
|
+
*
|
|
7
|
+
* Why a single list matters here specifically: a repo that adopted at an OLDER handbook
|
|
8
|
+
* version — before one of these labels entered the set — silently never back-filled it,
|
|
9
|
+
* and the check that label powers can then never fire. The claim (`in-progress`) cannot
|
|
10
|
+
* land; the readiness column (`deps-checked`) can never leave "nobody looked"; provenance
|
|
11
|
+
* (`agent-filed`) reads every filed issue as human-approved. So adoption provisions the
|
|
12
|
+
* WHOLE set (not a subset marked optional), sync back-fills what a later version added,
|
|
13
|
+
* and the audit reports the gap — all three reading this one list, so they cannot drift
|
|
14
|
+
* about what "the full set" is.
|
|
15
|
+
*
|
|
16
|
+
* Each entry carries color + description so a provisioner (`gh label create`) and the
|
|
17
|
+
* audit's presence check share not just the names but how the label is meant to look.
|
|
18
|
+
*
|
|
19
|
+
* `epic` joined the set in #78: the scheduled-drivers model (#70) needs a driver to
|
|
20
|
+
* exclude tracking/umbrella records from what it starts unattended, exactly the way it
|
|
21
|
+
* already excludes `agent-filed` issues (CONVENTIONS.md §5, *Provenance*). An
|
|
22
|
+
* `epic`-labelled issue is informative — a container for sub-issues — never a start
|
|
23
|
+
* candidate and never claimed as a unit of work. It joins CONVENTION_LABELS rather than
|
|
24
|
+
* staying repo-local because an unattended decision now depends on it, the same bar the
|
|
25
|
+
* other three met; contrast `TRACKING_LABEL` below, which stays opt-in because nothing
|
|
26
|
+
* unattended reads it (yet).
|
|
27
|
+
*
|
|
28
|
+
* `needs-decision` (named `needs-ruling` before #122) joined the set in #75: a human must
|
|
29
|
+
* answer a blocking question before this issue can start — originally scoped to a
|
|
30
|
+
* designer's pre-approval, widened by #122 to the whole family a gate this shape actually
|
|
31
|
+
* covers (a design ruling, a business-logic call, a permission), because "ruling" read
|
|
32
|
+
* narrower than the gate. A readiness gate exactly like an open hard blocker or
|
|
33
|
+
* `in-progress`, not a softer advisory. Absent this label a repo cannot apply that gate at
|
|
34
|
+
* all, and a surface nobody has ruled on reads as a normal start candidate to a human
|
|
35
|
+
* session or a scheduled driver alike (CONVENTIONS.md §5, *Decision gate*). It joins
|
|
36
|
+
* CONVENTION_LABELS for the same reason `epic` did: an unattended decision (a scheduler's
|
|
37
|
+
* start-or-skip) depends on it.
|
|
38
|
+
*
|
|
39
|
+
* `decision-recorded` joined the set in #121, alongside the same rename: clearing
|
|
40
|
+
* `needs-decision` is not by itself evidence a human answered — a gate cleared by hand and
|
|
41
|
+
* a gate never applied read identically to a later reader, and #127 measured exactly that
|
|
42
|
+
* failure (a ruling sat live in a comment; a later triage pass, seeing no label, re-gated
|
|
43
|
+
* the issue). So recording a ruling is now a POSITIVE, machine-readable act — a
|
|
44
|
+
* `⚖ Decision recorded` comment (tools/lib/decision-record.js) plus this label, written
|
|
45
|
+
* together — never the mere absence of `needs-decision`. A consumer checking readiness
|
|
46
|
+
* must look for this label (or the live marker) before re-applying the gate, not just for
|
|
47
|
+
* the gate's absence.
|
|
48
|
+
*
|
|
49
|
+
* `needs-plan` joined the set in #94: `code-triage` flags an issue it judges genuinely
|
|
50
|
+
* hard — ambiguous scope, a novel design with no repo precedent, a coupling wider than
|
|
51
|
+
* file overlap — and `code-start` reads the flag to decide whether to run `code-plan`
|
|
52
|
+
* before coding, rather than the default 3-5-line stub. Unlike `needs-decision` it is NOT a
|
|
53
|
+
* readiness gate — a flagged issue is still startable now, it just should not go straight
|
|
54
|
+
* to code (CONVENTIONS.md §5, *Planning*). It is provisioned like the rest of this set,
|
|
55
|
+
* not created on demand the way `group:<key>` is, because its name is fixed and every
|
|
56
|
+
* adopting repo needs it before the first triage pass can flag anything.
|
|
57
|
+
*
|
|
58
|
+
* `migration-granted` joined the set in #98: a human-only, per-issue, branch-bound, expiring
|
|
59
|
+
* exemption to `colab ship`'s no-new-migrations precondition, for the one legitimate class of
|
|
60
|
+
* work that gate would otherwise make permanently un-shippable unattended — an issue whose
|
|
61
|
+
* entire deliverable IS a schema change (CONVENTIONS.md §5, *Migration exemption*). `colab ship`
|
|
62
|
+
* reads it, on EVERY issue a branch carries, when — and only when — that branch touches a
|
|
63
|
+
* migration path; absence is the ordinary, unexempted case and costs nothing. Its nearest
|
|
64
|
+
* neighbour is `needs-decision`, and the two point opposite directions: `needs-decision` *blocks* a
|
|
65
|
+
* start pending a human answer; `migration-granted` *unblocks* a ship because a
|
|
66
|
+
* human already reviewed the schema change. It joins `CONVENTION_LABELS` rather than staying
|
|
67
|
+
* repo-opt-in like `tracking`/`graph-empty` because its absence fails MALIGNANTLY, not benignly:
|
|
68
|
+
* a repo that adopted before this label existed cannot create a grant at all, so the schema-
|
|
69
|
+
* change issue parks forever under a scheduled driver — discovered only at the moment it hits
|
|
70
|
+
* the wall, with no prior signal — which is exactly the "silently never back-filled it, and the
|
|
71
|
+
* check that label powers can then never fire" failure this file's own opening paragraph names.
|
|
72
|
+
* The label alone authorizes nothing (the branch binding lives in a comment marker,
|
|
73
|
+
* tools/lib/migration-grant.js, and no automated path ever writes either half) — an unused label
|
|
74
|
+
* is inert, an absent one is a wall.
|
|
75
|
+
*
|
|
76
|
+
* `needs-migration-grant` joined the set in #230: the PLAN-TIME half of the same gate.
|
|
77
|
+
* `migration-granted` above is what `colab ship` reads at merge time; this one is what a
|
|
78
|
+
* consumer (the fleet dashboard) writes at plan/triage time, as soon as it can tell an
|
|
79
|
+
* issue's deliverable IS a schema migration — flagging the eventual grant request before
|
|
80
|
+
* `ship` has to refuse and discover it late. This repo's own tooling never reads it (unlike
|
|
81
|
+
* `needs-plan`, which `code-start` reads directly); it exists here purely to be
|
|
82
|
+
* PROVISIONABLE, on the same precedent `needs-plan` and `agent-filed` already set — a label
|
|
83
|
+
* whose semantics live in a downstream consumer, not in `colab` itself, can still belong to
|
|
84
|
+
* this set if leaving it repo-local would produce the identical malignant-absence failure
|
|
85
|
+
* `migration-granted` names: measured across four adopted repos, one lacked the label
|
|
86
|
+
* entirely and the plan-time flag silently did nothing there — no error, no audit finding,
|
|
87
|
+
* just a request that never surfaced until `ship` refused much later. It is explicitly never
|
|
88
|
+
* a substitute for `migration-granted` — it only widens detection of what might need a
|
|
89
|
+
* grant, it grants nothing itself, and only a human minting `migration-granted` still
|
|
90
|
+
* authorizes anything.
|
|
91
|
+
*
|
|
92
|
+
* `ci-granted` joined the set in #105: a human-only, per-issue, branch-bound, expiring
|
|
93
|
+
* exemption to `colab ship`'s trunk-CI-green precondition, for the one case that gate
|
|
94
|
+
* otherwise makes permanently un-shippable unattended — a GENUINELY red trunk, where the
|
|
95
|
+
* candidate branch IS the fix and cannot reach trunk without shipping, and shipping
|
|
96
|
+
* requires the green the fix would produce (CONVENTIONS.md §5, *Red-trunk exemption*). Its
|
|
97
|
+
* nearest neighbour is `migration-granted` (#98) — same shape, same write path
|
|
98
|
+
* (`COLAB_HUMAN=1`, label + branch-bound comment marker, tools/lib/ci-grant.js) — but this
|
|
99
|
+
* one is strictly more dangerous: a bad migration grant merges one reviewed schema change,
|
|
100
|
+
* a bad CI grant merges into a repo whose own test suite is known-failing. So unlike the
|
|
101
|
+
* migration grant it also carries a bound RED TRUNK SHA (the grant expires the instant
|
|
102
|
+
* trunk's head moves, granted or not) and requires MEASURED evidence — a real green run on
|
|
103
|
+
* the branch's own head — never a human's say-so alone. It joins `CONVENTION_LABELS` for
|
|
104
|
+
* the identical malignant-absence reason `migration-granted` did: a repo that adopted
|
|
105
|
+
* before this label existed cannot create a grant at all, so the fix for its own red trunk
|
|
106
|
+
* parks forever with no signal until the moment it hits the wall.
|
|
107
|
+
*
|
|
108
|
+
* `delivery:*` joined the set in #112: a tracker mixes issues whose delivery is NOT a code
|
|
109
|
+
* commit — a content push, an ops/production check, code for another repository — into a
|
|
110
|
+
* pipeline whose every stage (worktree, gate, mergeable, squash, `Closes #N`) assumes one. Such
|
|
111
|
+
* an issue can never reach a mergeable state, so it reads as eternally stuck, and — the expensive
|
|
112
|
+
* half — it looks STARTABLE to triage and a scheduled driver alike, because no existing readiness
|
|
113
|
+
* label says "this is real work, but not a diff" the way `epic` says "this is not a unit of work
|
|
114
|
+
* at all". Six labels (five in #112, `design` in #359), one classifier, deliberately (still) THREE-VALUED rather than boolean
|
|
115
|
+
* (CONVENTIONS.md §5, *Delivery type*): no `delivery:*` label at all reads as **not asked**, and
|
|
116
|
+
* must behave exactly as before this label set existed — every issue in every tracker is
|
|
117
|
+
* unlabelled the day this lands, so absence collapsing into "non-code" would freeze the start
|
|
118
|
+
* gate for everyone on day one. `delivery:code` is the explicit affirmative for a code issue;
|
|
119
|
+
* which values are non-code (route-not-start) and which are code-lane is spelled out in the
|
|
120
|
+
* #358/#359 paragraph below — the route rule itself is a companion to the `epic` rule and the
|
|
121
|
+
* `needs-decision` gate, not a merge of either. It joins `CONVENTION_LABELS` for the same reason
|
|
122
|
+
* `epic` did: an unattended decision (a scheduler's or triage's start-or-skip) depends on being
|
|
123
|
+
* able to tell the states apart, and a repo that adopted before this set existed cannot create
|
|
124
|
+
* the label at all — the malignant-absence failure this file's opening paragraph names.
|
|
125
|
+
*
|
|
126
|
+
* `delivery:elsewhere` joined the set in #274, after living un-provisioned on three separate
|
|
127
|
+
* trackers (21 issues, all hand-created — `colab labels --ensure` could never create a label
|
|
128
|
+
* absent from `CONVENTION_LABELS`). It names an issue whose deliverable IS code, but code that
|
|
129
|
+
* lands in a different repository than this tracker's own — so it belongs in the non-code-HERE
|
|
130
|
+
* bucket for exactly the reason `content`/`ops` do: this pipeline's worktree, gate,
|
|
131
|
+
* mergeable and squash machinery all assume the diff lands in the repo the issue lives in, and
|
|
132
|
+
* an `elsewhere` issue breaks that assumption the same way a content push does. Before this
|
|
133
|
+
* entry, `deliveryType()` returned `null` for it — byte-identical to an issue nobody ever
|
|
134
|
+
* labelled — so `isRouteNotStart()` read `false` and every one of those 21 issues reported
|
|
135
|
+
* STARTABLE to triage, the opposite of what applying the label was asking for.
|
|
136
|
+
*
|
|
137
|
+
* #358 and #359 settled the lanes. `delivery:docs-only` was provisioned in #112 as a non-code
|
|
138
|
+
* type ("a docs sync outside code review, not a commit"), but a docs-only deliverable in THIS
|
|
139
|
+
* repo is an in-repo commit like any other — worktree, gate, `colab ship` — and a consumer's
|
|
140
|
+
* scheduler already read it that way, so triage withheld `deps-checked` from issues the
|
|
141
|
+
* scheduler would have started and they sat with no park and no decision (one for 6 days). It
|
|
142
|
+
* is now a CODE-LANE value: classified (`deliveryType` returns `'docs-only'`, never `null`) and
|
|
143
|
+
* never route-not-start. It is not ship's #345 docs-only exception either — that is measured
|
|
144
|
+
* from the diff (`docs-only.js`), never read from this label. `delivery:design` (#359) is the
|
|
145
|
+
* deliverable-is-a-design-artifact value for a new surface: never a code start, so it joins
|
|
146
|
+
* NON_CODE_DELIVERY_TYPES and `isRouteNotStart()` reads true for it; keeping it apart from the
|
|
147
|
+
* route bucket is a REPORTING job (code-triage's own design bucket), not a second classifier
|
|
148
|
+
* nobody in this repo would read. Before #359 two consumers hand-created it and `deliveryType()`
|
|
149
|
+
* returned `null` for it — the #274 failure again. So the value list `deliveryType()` walks is
|
|
150
|
+
* now DERIVED from CONVENTION_LABELS (`DELIVERY_TYPES`), never hand-typed: any provisioned
|
|
151
|
+
* `delivery:*` value is classified by construction, and a partition test forces each new one
|
|
152
|
+
* into exactly one lane (`CODE_LANE_DELIVERY_TYPES` or `NON_CODE_DELIVERY_TYPES`) on purpose.
|
|
153
|
+
*
|
|
154
|
+
* `low-priority` joined the set in #268: it orders a queue, it does not remove work from
|
|
155
|
+
* one — unlike `epic` and a non-code `delivery:*` value above, a `low-priority` issue IS a start candidate,
|
|
156
|
+
* only ranked behind every other ready group (CONVENTIONS.md §5, *Priority*). It joins
|
|
157
|
+
* CONVENTION_LABELS for the same reason `epic` and `delivery:*` did: a scheduled driver's
|
|
158
|
+
* ordering decision depends on seeing the label, and a repo that adopted before it existed
|
|
159
|
+
* cannot create it at all — the identical malignant-absence failure. Before #268 the label
|
|
160
|
+
* was read three different, undocumented ways across one adopting fleet (a hard veto by one
|
|
161
|
+
* driver, a sort key nothing enforced by a sibling tool, and invisible to `code-triage`
|
|
162
|
+
* entirely, which reported `low-priority` groups READY with no distinguishing signal) —
|
|
163
|
+
* this entry, plus the matching `code-triage` verdict, is what makes those readings
|
|
164
|
+
* reconcilable instead of silently contradictory.
|
|
165
|
+
*
|
|
166
|
+
* `deferred:date` / `deferred:measurement` / `deferred:external-party` joined the set in
|
|
167
|
+
* #279: `deps-checked` was being asked to carry two orthogonal facts at once — "has a
|
|
168
|
+
* reasoning session evaluated this?" (process state, monotonic — the label's own
|
|
169
|
+
* definition above) and "is it startable right now?" (readiness, volatile) — and
|
|
170
|
+
* `code-triage` runs in practice sacrificed the first to express the second, by clearing
|
|
171
|
+
* the label on work it judged not startable for a reason that was never a blocker.
|
|
172
|
+
* Measured on one adopting fleet: one repo with 83 open issues had 40 carrying
|
|
173
|
+
* `deps-checked`, 9 genuinely untriaged, and 11 triaged-work-reporting-as-untriaged —
|
|
174
|
+
* more than half of the untriaged-looking backlog; a second, smaller repo had 4 such
|
|
175
|
+
* cases. `deps-checked` is now monotonic (CONVENTIONS.md §5, *Disposition*) and these
|
|
176
|
+
* three labels are the machine-readable carrier for the displaced fact: an issue is
|
|
177
|
+
* ready, but parked on a date, a measurement, or someone outside this repo, rather than
|
|
178
|
+
* on another issue (`blockedBy`, unchanged) or a human ruling (`needs-decision`,
|
|
179
|
+
* unchanged). They join `CONVENTION_LABELS` for the identical malignant-absence reason
|
|
180
|
+
* `delivery:*` did: a repo that adopted before this landed cannot create the label at
|
|
181
|
+
* all, so a park it wants to record instead reports as an unexamined issue — the exact
|
|
182
|
+
* confusion #279 measured. **Vocabulary only, deliberately inert on landing:** nothing in
|
|
183
|
+
* this repo's own tooling writes or reads these three yet (no `code-triage` write, no
|
|
184
|
+
* readiness wiring, no audit finding) — the sequencing hazard #279 itself names is that
|
|
185
|
+
* emitting the label before a consumer renders the disposition distinctly produces a
|
|
186
|
+
* label nothing reads, which is worse than the silent park it replaces. An unused label
|
|
187
|
+
* is inert; see `migration-granted`'s own paragraph above for the same argument.
|
|
188
|
+
*
|
|
189
|
+
* `review-by:<date>` is the wake condition a `deferred:*` park should usually name,
|
|
190
|
+
* deliberately NOT in `CONVENTION_LABELS` — same treatment as `group:<key>`: the date
|
|
191
|
+
* varies per issue, so there is no fixed set to provision up front, and it is created on
|
|
192
|
+
* demand by whoever applies the park. "A defer must name its wake condition" (#279): a
|
|
193
|
+
* `deferred:*` label with no `review-by:<date>`, no `blockedBy` edge and no checkable `wake:`
|
|
194
|
+
* (the closed vocabulary in tools/lib/wake.js, #382) is not a defer at all — it is a
|
|
195
|
+
* deprioritisation or a `wontfix` that should be said plainly, because an unbounded park is a
|
|
196
|
+
* silent `wontfix`.
|
|
197
|
+
*
|
|
198
|
+
* `release-hold` joined the set in #339: the human veto on a release candidate (CONVENTIONS.md
|
|
199
|
+
* §6, *The release rung*). It sits on a release TRACKING issue (`release: vX.Y.Z`, marker
|
|
200
|
+
* `<!-- colab:release version=vX.Y.Z -->`), and while it is present `colab release finalize`
|
|
201
|
+
* does not tag that version's final. Provisioned, not opt-in, for the sharpest form of the
|
|
202
|
+
* malignant-absence reason above: the moment a human wants to veto is a test period that is
|
|
203
|
+
* already counting down, and a label the repo never created cannot be applied in that moment —
|
|
204
|
+
* the veto would silently not exist. Only a human removes it; no command in this repo does.
|
|
205
|
+
*/
|
|
206
|
+
|
|
207
|
+
const CONVENTION_LABELS = [
|
|
208
|
+
{ name: 'in-progress', color: 'FBCA04', description: 'Claimed by an active session' },
|
|
209
|
+
{ name: 'deps-checked', color: '0E8A16', description: 'Dependencies verified — no open blocker' },
|
|
210
|
+
{ name: 'agent-filed', color: 'C5DEF5', description: 'Filed by an agent on its own initiative — not human-approved' },
|
|
211
|
+
{ name: 'epic', color: '3E4B9E', description: 'Container for sub-issues — informative, never a start candidate, never claimed as a unit of work' },
|
|
212
|
+
{ name: 'needs-decision', color: 'B60205', description: 'A human must answer a blocking question before this can start' },
|
|
213
|
+
{ name: 'decision-recorded', color: '006B75', description: 'A human answered here — ask a new question via colab decision --reopen, never a hand-added label' },
|
|
214
|
+
{ name: 'needs-plan', color: '0052CC', description: 'Triage judged this hard — code-start should run code-plan before coding' },
|
|
215
|
+
{ name: 'migration-granted', color: 'D93F0B', description: "A human granted this issue's branch an exemption from ship's no-new-migrations gate" },
|
|
216
|
+
{ name: 'needs-migration-grant', color: 'D4C5F9', description: 'Agent-flagged: deliverable is a schema migration; surfaces the grant request for a human to Accept' },
|
|
217
|
+
{ name: 'ci-granted', color: 'D73A4A', description: "A human granted this branch a one-shot exemption from ship's trunk-CI-green gate" },
|
|
218
|
+
{ name: 'low-priority', color: 'C2E0C6', description: 'Throttle, not a veto — startable, but code-triage ranks it behind every other ready group' },
|
|
219
|
+
{ name: 'delivery:code', color: '1D76DB', description: 'Delivery is a code commit — the ordinary code pipeline applies' },
|
|
220
|
+
{ name: 'delivery:content', color: 'FEF2C0', description: 'Delivery is a content push, not a code commit — route, do not start in the code pipeline' },
|
|
221
|
+
{ name: 'delivery:ops', color: 'D4C5F9', description: 'Delivery is an ops/production check, not a code commit — route, do not start in the code pipeline' },
|
|
222
|
+
{ name: 'delivery:docs-only', color: 'BFD4F2', description: 'Delivery is a docs-only commit in this repo — the ordinary code pipeline applies' },
|
|
223
|
+
{ name: 'delivery:elsewhere', color: 'F9D0C4', description: 'Delivery is code, but lands in a different repository — route, do not start here' },
|
|
224
|
+
{ name: 'delivery:design', color: 'C39BD3', description: 'Delivery is a design artifact for a new surface — a design session works it, never a code start' },
|
|
225
|
+
{ name: 'deferred:date', color: 'B08800', description: 'Parked until a specific date — pair with a review-by:<date> label naming it' },
|
|
226
|
+
{ name: 'deferred:measurement', color: '7C6F57', description: 'Parked until a metric crosses a threshold — name the metric and the threshold on the issue' },
|
|
227
|
+
{ name: 'deferred:external-party', color: '6E5494', description: 'Parked until someone outside this repo acts — name who, and pair with review-by:<date>' },
|
|
228
|
+
{ name: 'release-hold', color: 'E11D21', description: 'Human veto on a release tracking issue: its candidate is not finalized while this is present' },
|
|
229
|
+
];
|
|
230
|
+
|
|
231
|
+
// The DELIVERY label prefix (CONVENTIONS.md §5, Delivery type). Six fixed values, unlike
|
|
232
|
+
// `group:<key>` — provisioned up front in CONVENTION_LABELS above, not created on demand.
|
|
233
|
+
const DELIVERY_LABEL_PREFIX = 'delivery:';
|
|
234
|
+
|
|
235
|
+
// Every provisioned delivery value, in CONVENTION_LABELS order — DERIVED, never hand-typed
|
|
236
|
+
// (#358/#359): a value provisioned above is classified by `deliveryType()` by construction,
|
|
237
|
+
// so a new one can never read as "not asked" the way `elsewhere` did before #274.
|
|
238
|
+
const DELIVERY_TYPES = CONVENTION_LABELS
|
|
239
|
+
.map((l) => l.name)
|
|
240
|
+
.filter((n) => n.startsWith(DELIVERY_LABEL_PREFIX))
|
|
241
|
+
.map((n) => n.slice(DELIVERY_LABEL_PREFIX.length));
|
|
242
|
+
|
|
243
|
+
// The code-lane delivery types — an in-repo commit through worktree, gate and `colab ship`.
|
|
244
|
+
// `docs-only` is here since #358: a docs-only deliverable is still a commit. (It is NOT ship's
|
|
245
|
+
// #345 docs-only exception, which is measured from the diff, never read from this label.)
|
|
246
|
+
const CODE_LANE_DELIVERY_TYPES = ['code', 'docs-only'];
|
|
247
|
+
|
|
248
|
+
// The four non-code delivery types — the ones triage and the readiness gate treat as
|
|
249
|
+
// route-not-start. `design` (#359) is here because it is never a code start; code-triage
|
|
250
|
+
// reports it in its own design bucket rather than the route bucket.
|
|
251
|
+
const NON_CODE_DELIVERY_TYPES = ['content', 'ops', 'elsewhere', 'design'];
|
|
252
|
+
|
|
253
|
+
/**
|
|
254
|
+
* The three-valued delivery classifier (CONVENTIONS.md §5, *Delivery type*).
|
|
255
|
+
*
|
|
256
|
+
* Returns one of:
|
|
257
|
+
* - `null` — NOT ASKED. No `delivery:*` label present, or only a value the handbook does
|
|
258
|
+
* not define (a consumer-local one, e.g. `delivery:elsewhere-partial`, #366 —
|
|
259
|
+
* handbook-sync reports those as `value` drift; this classifier guesses no
|
|
260
|
+
* meaning for them). Must read identically to how the issue behaved before
|
|
261
|
+
* this label set existed — never as non-code.
|
|
262
|
+
* - `'code' | 'docs-only'` — a code-lane value present (CODE_LANE_DELIVERY_TYPES).
|
|
263
|
+
* - `'content' | 'ops' | 'elsewhere' | 'design'` — a non-code value present
|
|
264
|
+
* (NON_CODE_DELIVERY_TYPES).
|
|
265
|
+
*
|
|
266
|
+
* Tolerant of label objects or bare strings, the same shape every other helper in this file
|
|
267
|
+
* accepts. If more than one `delivery:*` label is somehow present (a tracker mistake, not a
|
|
268
|
+
* state this repo's tooling ever writes), the first match in CONVENTION_LABELS order wins —
|
|
269
|
+
* deterministic, and it is a contradiction worth surfacing rather than silently averaging.
|
|
270
|
+
*/
|
|
271
|
+
function deliveryType(present) {
|
|
272
|
+
const have = new Set(
|
|
273
|
+
(present || []).map((n) => (n && typeof n === 'object' ? n.name : n)).map((n) => String(n)),
|
|
274
|
+
);
|
|
275
|
+
for (const type of DELIVERY_TYPES) {
|
|
276
|
+
if (have.has(`${DELIVERY_LABEL_PREFIX}${type}`)) return type;
|
|
277
|
+
}
|
|
278
|
+
return null;
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
// Is this issue's delivery type one triage/the readiness gate should route rather than start?
|
|
282
|
+
// `null` (not asked) and a code-lane value (`'code'`, `'docs-only'`) read false here — only an
|
|
283
|
+
// explicit non-code type routes.
|
|
284
|
+
function isRouteNotStart(present) {
|
|
285
|
+
return NON_CODE_DELIVERY_TYPES.includes(deliveryType(present));
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
// The DEFERRED label prefix (CONVENTIONS.md §5, Disposition — #279). Three fixed values,
|
|
289
|
+
// same treatment as DELIVERY_LABEL_PREFIX: provisioned up front in CONVENTION_LABELS above,
|
|
290
|
+
// not created on demand.
|
|
291
|
+
const DEFERRED_LABEL_PREFIX = 'deferred:';
|
|
292
|
+
|
|
293
|
+
// The three park kinds a ready-but-not-started issue can carry — a date, a measurement, or
|
|
294
|
+
// a party outside this repo. Distinct from `blockedBy` (waiting on another issue) and from
|
|
295
|
+
// `needs-decision` (waiting on a human ruling), which are unchanged by this set.
|
|
296
|
+
const DEFERRED_KINDS = ['date', 'measurement', 'external-party'];
|
|
297
|
+
|
|
298
|
+
/**
|
|
299
|
+
* The deferred-kind classifier (CONVENTIONS.md §5, *Disposition*, #279) — same shape as
|
|
300
|
+
* `deliveryType()` above, deliberately: tolerant of label objects or bare strings, first
|
|
301
|
+
* match in canonical order wins if more than one is somehow present.
|
|
302
|
+
*
|
|
303
|
+
* Returns one of:
|
|
304
|
+
* - `null` — no `deferred:*` label present.
|
|
305
|
+
* - `'date' | 'measurement' | 'external-party'` — the matching `deferred:*` label present.
|
|
306
|
+
*
|
|
307
|
+
* Nothing in this repo's own tooling calls this yet (#279 ships the vocabulary only) — see
|
|
308
|
+
* the doc comment above CONVENTION_LABELS for why that is the deliberate end state, not an
|
|
309
|
+
* oversight.
|
|
310
|
+
*/
|
|
311
|
+
function deferredKind(present) {
|
|
312
|
+
const have = new Set(
|
|
313
|
+
(present || []).map((n) => (n && typeof n === 'object' ? n.name : n)).map((n) => String(n)),
|
|
314
|
+
);
|
|
315
|
+
for (const kind of DEFERRED_KINDS) {
|
|
316
|
+
if (have.has(`${DEFERRED_LABEL_PREFIX}${kind}`)) return kind;
|
|
317
|
+
}
|
|
318
|
+
return null;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
// Is this issue carrying a deferred:* park? Same shape as isRouteNotStart(): a thin,
|
|
322
|
+
// readable wrapper over the classifier for a caller that only needs the boolean.
|
|
323
|
+
function isDeferred(present) {
|
|
324
|
+
return deferredKind(present) !== null;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
// The REVIEW-BY label prefix (CONVENTIONS.md §5, Disposition — #279). Deliberately NOT in
|
|
328
|
+
// CONVENTION_LABELS, same reasoning as GROUP_LABEL_PREFIX below: the date varies per issue,
|
|
329
|
+
// so there is no fixed set to provision up front — created on demand by whoever applies the
|
|
330
|
+
// park, and it is the wake condition a `deferred:*` label should usually be paired with.
|
|
331
|
+
const REVIEW_BY_LABEL_PREFIX = 'review-by:';
|
|
332
|
+
|
|
333
|
+
// Is this label name a review-by marker? Guards against the bare prefix itself
|
|
334
|
+
// ("review-by:" with no date) reading as one, same shape as isGroupLabel below.
|
|
335
|
+
function isReviewByLabel(name) {
|
|
336
|
+
return typeof name === 'string' && name.length > REVIEW_BY_LABEL_PREFIX.length && name.startsWith(REVIEW_BY_LABEL_PREFIX);
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
// The review-by label names carried by a label list — same tolerant shape as
|
|
340
|
+
// groupLabelNames below (bare strings or {name} objects), order-preserving, deduplicated.
|
|
341
|
+
function reviewByLabelNames(present) {
|
|
342
|
+
const out = [];
|
|
343
|
+
const seen = new Set();
|
|
344
|
+
for (const n of (present || [])) {
|
|
345
|
+
const name = n && typeof n === 'object' ? n.name : n;
|
|
346
|
+
const s = name === undefined || name === null ? '' : String(name);
|
|
347
|
+
if (isReviewByLabel(s) && !seen.has(s)) { seen.add(s); out.push(s); }
|
|
348
|
+
}
|
|
349
|
+
return out;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Parse a `review-by:<date>` label's date, strictly — the sole purpose of this function is
|
|
354
|
+
* to make "is this actually a valid calendar date" checkable without a caller reaching for
|
|
355
|
+
* lenient `Date` parsing, which silently accepts what this must reject: `new Date('2026-02-30')`
|
|
356
|
+
* does not throw, it rolls over to March 2nd, and `Date.parse` accepts forms (two-digit
|
|
357
|
+
* years, unpadded months/days) this label was never meant to carry.
|
|
358
|
+
*
|
|
359
|
+
* Returns the `YYYY-MM-DD` string unchanged if it names a real calendar day, or `null` for
|
|
360
|
+
* anything else (wrong shape, out-of-range month/day, or not a review-by label at all).
|
|
361
|
+
*
|
|
362
|
+
* Pure, deliberately: no `Date.now()`, no "is this overdue" — that is a consumer's decision
|
|
363
|
+
* to make once one exists (#279 ships the vocabulary only), not this function's.
|
|
364
|
+
*/
|
|
365
|
+
function parseReviewByDate(name) {
|
|
366
|
+
const s = name && typeof name === 'object' ? name.name : name;
|
|
367
|
+
if (typeof s !== 'string') return null;
|
|
368
|
+
const m = /^review-by:(\d{4})-(\d{2})-(\d{2})$/.exec(s);
|
|
369
|
+
if (!m) return null;
|
|
370
|
+
const [, ys, ms, ds] = m;
|
|
371
|
+
const y = Number(ys), mo = Number(ms), d = Number(ds);
|
|
372
|
+
const asUtc = new Date(Date.UTC(y, mo - 1, d));
|
|
373
|
+
// Round-trip check: Date.UTC normalises out-of-range components (month 13 rolls into the
|
|
374
|
+
// next year, day 30 of February rolls into March) instead of rejecting them, so read the
|
|
375
|
+
// parts back and require an exact match.
|
|
376
|
+
if (asUtc.getUTCFullYear() !== y || asUtc.getUTCMonth() !== mo - 1 || asUtc.getUTCDate() !== d) return null;
|
|
377
|
+
return `${ys}-${ms}-${ds}`;
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
function conventionLabelNames() {
|
|
381
|
+
return CONVENTION_LABELS.map((l) => l.name);
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
// The LOAD-BEARING subset (#393) — the labels a session's own start/claim/file path writes, and
|
|
385
|
+
// therefore the only ones a repo the fleet does not own has to carry for code-start → code-wrap →
|
|
386
|
+
// colab ship to work there: `in-progress` (the claim's tracker mirror), `deps-checked` (readiness
|
|
387
|
+
// — without it no issue ever leaves "nobody looked"), `agent-filed` (provenance), `epic` (a
|
|
388
|
+
// container is never a start candidate). Everything else in CONVENTION_LABELS is opt-in by USE:
|
|
389
|
+
// it only has to exist where its mechanic is used, and creating 20+ labels on someone else's
|
|
390
|
+
// tracker is noise its owner never asked for. `colab labels --ensure --minimal` reads this list.
|
|
391
|
+
const MINIMAL_LABEL_NAMES = ['in-progress', 'deps-checked', 'agent-filed', 'epic'];
|
|
392
|
+
|
|
393
|
+
/** The CONVENTION_LABELS entries for MINIMAL_LABEL_NAMES, canonical order and definitions. */
|
|
394
|
+
function minimalConventionLabels() {
|
|
395
|
+
const want = new Set(MINIMAL_LABEL_NAMES);
|
|
396
|
+
return CONVENTION_LABELS.filter((l) => want.has(l.name));
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
// The readiness marker, named once. CONVENTIONS.md §5 (Readiness) is the prose source; the
|
|
400
|
+
// audit, the provisioner and now `colab readiness` all read the name from HERE rather than
|
|
401
|
+
// spelling the string themselves — a second literal is a second thing to typo, and a readiness
|
|
402
|
+
// write that targets `deps_checked` while the audit checks `deps-checked` fails silently, which
|
|
403
|
+
// is the whole class of bug this single list exists to make impossible.
|
|
404
|
+
const READINESS_LABEL = 'deps-checked';
|
|
405
|
+
|
|
406
|
+
// The marker for a long-lived MEMORY / TRACKING issue (CONVENTIONS.md §5, Tracking issues).
|
|
407
|
+
// A tracking issue is external memory for a whole domain — accumulated decisions and gotchas plus
|
|
408
|
+
// a checklist of still-open items — that a hygiene session legitimately CLAIMS (to signal work in
|
|
409
|
+
// the area) and REFERENCES, but does not complete. `colab ship` reads this name and emits `Refs #N`
|
|
410
|
+
// instead of `Closes #N` for any claimed issue that carries it, so shipping a small fix in the
|
|
411
|
+
// domain does not bury the memory behind a closed-issue lookup.
|
|
412
|
+
//
|
|
413
|
+
// Deliberately NOT in CONVENTION_LABELS: those are the labels whose absence makes a check silently
|
|
414
|
+
// impossible (a claim that cannot land, a readiness column that can never fill). This one is opt-in
|
|
415
|
+
// per repo and per issue — its absence just means every issue closes as before, which is the
|
|
416
|
+
// correct default. So adoption/sync do not force-provision it and the audit does not report its
|
|
417
|
+
// absence. A repo that wants the behaviour creates the label and applies it to its tracking issues.
|
|
418
|
+
const TRACKING_LABEL = 'tracking';
|
|
419
|
+
|
|
420
|
+
// The marker for a MECHANICAL readiness check (CONVENTIONS.md §5, Mechanical readiness — #69).
|
|
421
|
+
// `deps-checked` asserts a reasoning session looked and judged the issue clear — a claim a bare
|
|
422
|
+
// API read cannot make, because a blocker described only in prose is invisible to it. This label
|
|
423
|
+
// asserts the strictly weaker thing a mechanical read CAN prove honestly: the recorded graph
|
|
424
|
+
// (`blockedBy`) reads empty as of that read. It is a distinct name on purpose, never a synonym or
|
|
425
|
+
// a second color for `deps-checked` — the whole point of #69's resolution is that the two claims
|
|
426
|
+
// must not be allowed to collapse into one label a consumer cannot tell apart.
|
|
427
|
+
//
|
|
428
|
+
// Deliberately NOT in CONVENTION_LABELS, same reasoning as TRACKING_LABEL above: nothing
|
|
429
|
+
// unattended reads it (yet), so adoption/sync do not force-provision it and the audit does not
|
|
430
|
+
// report its absence. A repo that wants the faster, weaker lane creates the label itself and
|
|
431
|
+
// opts a consumer into `readiness.isStartableMechanical()`.
|
|
432
|
+
const MECHANICAL_READINESS_LABEL = 'graph-empty';
|
|
433
|
+
|
|
434
|
+
// The `gh issue edit` label arguments for owning the readiness marker. Pure, so the mapping
|
|
435
|
+
// "set ⇒ add, clear ⇒ remove" is pinned by a test without a network call: the command is a thin
|
|
436
|
+
// shell around ghIssueEdit(repo, num, readinessLabelArgs(...)), and the part worth getting right
|
|
437
|
+
// is exactly this arg vector.
|
|
438
|
+
function readinessLabelArgs({ clear } = {}) {
|
|
439
|
+
return clear
|
|
440
|
+
? ['--remove-label', READINESS_LABEL]
|
|
441
|
+
: ['--add-label', READINESS_LABEL];
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
// #388: the success line `colab readiness <N>` prints after ADDING deps-checked. It used to say
|
|
445
|
+
// "verified: no open blocker" unconditionally — a claim the default path never checked (only
|
|
446
|
+
// --mechanical reads blockedBy), printed verbatim even on issues with open blockers, and the one
|
|
447
|
+
// line operators copy into reports. It now says what was DONE (the review was recorded) and what
|
|
448
|
+
// the graph holds, from one blockedBy read (`summary` = blocked-by.js openBlockerSummary, or
|
|
449
|
+
// null/{ok:false} when the read failed). It never says "verified" and never "no open blocker":
|
|
450
|
+
// deps-checked is a review record, and an open edge carries the block on its own (§5, #279).
|
|
451
|
+
function readinessMarkedMessage({ num, repo, summary } = {}) {
|
|
452
|
+
const head = `Marked #${num} in ${repo} ${READINESS_LABEL} — dependencies reviewed`;
|
|
453
|
+
if (!summary || !summary.ok) {
|
|
454
|
+
return `${head}; blockedBy: unread (the label records your review, not a graph read)`;
|
|
455
|
+
}
|
|
456
|
+
const { total, read, open, unknownState } = summary;
|
|
457
|
+
const truncated = read < total;
|
|
458
|
+
let tail = `blockedBy: ${truncated ? '≥' : ''}${open} open`;
|
|
459
|
+
if (total > 0) tail += ` of ${total}`;
|
|
460
|
+
if (unknownState > 0) tail += `, ${unknownState} with unread state`;
|
|
461
|
+
if (truncated) tail += `, only ${read} read`;
|
|
462
|
+
if (open > 0) tail += ' (an open edge carries the block — this label does not lift it)';
|
|
463
|
+
return `${head}; ${tail}`;
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
// The `gh issue edit` label arguments for owning the MECHANICAL readiness marker. Same shape as
|
|
467
|
+
// readinessLabelArgs, kept as a separate function rather than a parameter on that one: the two
|
|
468
|
+
// markers must never be writable through the same call site, or a caller could flip one when it
|
|
469
|
+
// meant the other. See MECHANICAL_READINESS_LABEL above for what the label asserts.
|
|
470
|
+
function mechanicalReadinessLabelArgs({ clear } = {}) {
|
|
471
|
+
return clear
|
|
472
|
+
? ['--remove-label', MECHANICAL_READINESS_LABEL]
|
|
473
|
+
: ['--add-label', MECHANICAL_READINESS_LABEL];
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
// The migration-grant marker, named once (#98). CONVENTIONS.md §5 (Migration exemption) is the
|
|
477
|
+
// prose source; `colab migration-grant`, `colab ship`'s grant read, and the provisioner all read
|
|
478
|
+
// the name from HERE — the identical reason READINESS_LABEL is a shared constant, not a literal
|
|
479
|
+
// repeated at each call site.
|
|
480
|
+
const MIGRATION_GRANT_LABEL = 'migration-granted';
|
|
481
|
+
|
|
482
|
+
// The `gh issue edit` label arguments for owning the migration-grant marker. Pure, same shape and
|
|
483
|
+
// same reason as readinessLabelArgs: the write is a thin shell around
|
|
484
|
+
// ghIssueEdit(repo, num, migrationGrantLabelArgs(...)), and the arg vector is the part worth
|
|
485
|
+
// pinning with a test that makes no network call.
|
|
486
|
+
function migrationGrantLabelArgs({ clear } = {}) {
|
|
487
|
+
return clear
|
|
488
|
+
? ['--remove-label', MIGRATION_GRANT_LABEL]
|
|
489
|
+
: ['--add-label', MIGRATION_GRANT_LABEL];
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
// Given the label names a repo actually has, return the convention labels it is missing,
|
|
493
|
+
// in the canonical order. Tolerant of null/undefined (a repo whose labels could not be
|
|
494
|
+
// read is handled by the caller, not here) and of label objects vs bare strings.
|
|
495
|
+
function missingConventionLabels(present) {
|
|
496
|
+
const have = new Set(
|
|
497
|
+
(present || []).map((n) => (n && typeof n === 'object' ? n.name : n)).map((n) => String(n)),
|
|
498
|
+
);
|
|
499
|
+
return conventionLabelNames().filter((n) => !have.has(n));
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
// Given the labels a repo actually has, WITH their descriptions, return every convention label
|
|
503
|
+
// whose tracker description differs from CONVENTION_LABELS' text, in canonical order:
|
|
504
|
+
// [{ name, have, want }]. #364: `colab labels --ensure` creates a missing label and never touches
|
|
505
|
+
// an existing one, so a label created before the handbook reworded it keeps the old text for good
|
|
506
|
+
// — and a human or agent reading the tracker sees a meaning the handbook has since changed.
|
|
507
|
+
// An entry with no readable description — a bare name string, or an object whose `description`
|
|
508
|
+
// is not a string — is SKIPPED, never reported: a caller that only fetched names cannot know the
|
|
509
|
+
// text, and "could not read" must never surface as "differs" (the same contract as a null set).
|
|
510
|
+
// An empty-string description IS read, and differs, since every CONVENTION_LABELS entry has text.
|
|
511
|
+
// Labels outside the convention set are ignored (#364 out of scope), as are colours.
|
|
512
|
+
function staleConventionDescriptions(present) {
|
|
513
|
+
const want = new Map(CONVENTION_LABELS.map((l) => [l.name, l.description]));
|
|
514
|
+
const have = new Map();
|
|
515
|
+
for (const l of present || []) {
|
|
516
|
+
if (!l || typeof l !== 'object' || typeof l.description !== 'string') continue;
|
|
517
|
+
have.set(String(l.name), l.description);
|
|
518
|
+
}
|
|
519
|
+
return CONVENTION_LABELS
|
|
520
|
+
.filter((l) => have.has(l.name) && have.get(l.name) !== want.get(l.name))
|
|
521
|
+
.map((l) => ({ name: l.name, have: have.get(l.name), want: l.description }));
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
// A readiness ADD (`gh issue edit --add-label deps-checked`) fails for one recurring, diagnosable
|
|
525
|
+
// reason: the repo adopted the conventions before `deps-checked` entered the set and never
|
|
526
|
+
// back-filled it, so the label the write targets does not exist. Given the labels the repo
|
|
527
|
+
// actually has, return an actionable message naming that cause and its fix — or null, meaning
|
|
528
|
+
// "not this cause, use the generic error". Two nulls, deliberately different:
|
|
529
|
+
// - `present` is null → the label set could not be READ (no gh, no remote, network). We must
|
|
530
|
+
// not guess the cause from a read we did not get; fall back to the raw gh error.
|
|
531
|
+
// - the readiness label IS present → the ADD failed for some other reason; not ours to explain.
|
|
532
|
+
// This is where the doubly-silent failure of #49 is made loud: never report success on a write
|
|
533
|
+
// that did not land, and when it did not land for this reason, say precisely why and what fixes it.
|
|
534
|
+
function readinessMissingLabelHint(present) {
|
|
535
|
+
if (!present) return null;
|
|
536
|
+
if (!missingConventionLabels(present).includes(READINESS_LABEL)) return null;
|
|
537
|
+
return `this repo has no \`${READINESS_LABEL}\` label, so readiness cannot be marked — it adopted `
|
|
538
|
+
+ `the conventions before that label entered the set and never back-filled it. Run handbook-sync `
|
|
539
|
+
+ `(§7) to create the convention label set, then re-run the command.`;
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
// Same diagnosis as readinessMissingLabelHint, for the migration-grant marker (#98): a repo that
|
|
543
|
+
// adopted before `migration-granted` entered the set has no such label, so a grant ADD hits a
|
|
544
|
+
// label that does not exist. Same two-null contract: `present` null means the read itself failed
|
|
545
|
+
// (fall back to the raw gh error), the label being present means the ADD failed for some other
|
|
546
|
+
// reason — this function is not the one to explain that.
|
|
547
|
+
function migrationGrantMissingLabelHint(present) {
|
|
548
|
+
if (!present) return null;
|
|
549
|
+
if (!missingConventionLabels(present).includes(MIGRATION_GRANT_LABEL)) return null;
|
|
550
|
+
return `this repo has no \`${MIGRATION_GRANT_LABEL}\` label, so a migration grant cannot be marked — it `
|
|
551
|
+
+ `adopted the conventions before that label entered the set and never back-filled it. Run `
|
|
552
|
+
+ `handbook-sync (§7) to create the convention label set, then re-run the command.`;
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
// The ci-grant marker, named once (#105). CONVENTIONS.md §5 (Red-trunk exemption) is the prose
|
|
556
|
+
// source; `colab ci-grant`, `colab ship`'s grant read, and the provisioner all read the name from
|
|
557
|
+
// HERE — the identical reason MIGRATION_GRANT_LABEL is a shared constant, not a literal repeated
|
|
558
|
+
// at each call site.
|
|
559
|
+
const CI_GRANT_LABEL = 'ci-granted';
|
|
560
|
+
|
|
561
|
+
// The `gh issue edit` label arguments for owning the ci-grant marker. Pure, same shape and same
|
|
562
|
+
// reason as migrationGrantLabelArgs: the write is a thin shell around
|
|
563
|
+
// ghIssueEdit(repo, num, ciGrantLabelArgs(...)), and the arg vector is the part worth pinning
|
|
564
|
+
// with a test that makes no network call. A DIFFERENT function from migrationGrantLabelArgs on
|
|
565
|
+
// purpose — two grants that share a call site could let a caller flip one when it meant the
|
|
566
|
+
// other, exactly the reason mechanicalReadinessLabelArgs stays split from readinessLabelArgs.
|
|
567
|
+
function ciGrantLabelArgs({ clear } = {}) {
|
|
568
|
+
return clear
|
|
569
|
+
? ['--remove-label', CI_GRANT_LABEL]
|
|
570
|
+
: ['--add-label', CI_GRANT_LABEL];
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
// Same diagnosis as migrationGrantMissingLabelHint, for the ci-grant marker (#105): a repo that
|
|
574
|
+
// adopted before `ci-granted` entered the set has no such label, so a grant ADD hits a label that
|
|
575
|
+
// does not exist. Same two-null contract: `present` null means the read itself failed (fall back
|
|
576
|
+
// to the raw gh error), the label being present means the ADD failed for some other reason — this
|
|
577
|
+
// function is not the one to explain that.
|
|
578
|
+
function ciGrantMissingLabelHint(present) {
|
|
579
|
+
if (!present) return null;
|
|
580
|
+
if (!missingConventionLabels(present).includes(CI_GRANT_LABEL)) return null;
|
|
581
|
+
return `this repo has no \`${CI_GRANT_LABEL}\` label, so a CI grant cannot be marked — it `
|
|
582
|
+
+ `adopted the conventions before that label entered the set and never back-filled it. Run `
|
|
583
|
+
+ `handbook-sync (§7) to create the convention label set, then re-run the command.`;
|
|
584
|
+
}
|
|
585
|
+
|
|
586
|
+
// The decision-gate marker, named once (#75, renamed #122). CONVENTIONS.md §5 (Decision gate)
|
|
587
|
+
// is the prose source; `colab decision`, code-triage's readiness check, and the provisioner
|
|
588
|
+
// all read the name from HERE — the identical reason READINESS_LABEL is a shared constant.
|
|
589
|
+
const NEEDS_DECISION_LABEL = 'needs-decision';
|
|
590
|
+
|
|
591
|
+
// The positive decision-record marker, named once (#121). Paired with NEEDS_DECISION_LABEL:
|
|
592
|
+
// clearing the gate and recording the answer are ONE act (`colab decision --record`), never
|
|
593
|
+
// two — see the doc comment above CONVENTION_LABELS for why a cleared gate alone is not
|
|
594
|
+
// evidence anything was answered.
|
|
595
|
+
const DECISION_RECORDED_LABEL = 'decision-recorded';
|
|
596
|
+
|
|
597
|
+
// Same diagnosis as migrationGrantMissingLabelHint, for the decision-recorded marker (#121): a
|
|
598
|
+
// repo that adopted before this label entered the set has no such label, so `colab decision
|
|
599
|
+
// --record` cannot apply it. Same two-null contract as the others: `present` null means the
|
|
600
|
+
// read itself failed (fall back to the raw gh error), the label being present means the ADD
|
|
601
|
+
// failed for some other reason — this function is not the one to explain that.
|
|
602
|
+
function decisionRecordedMissingLabelHint(present) {
|
|
603
|
+
if (!present) return null;
|
|
604
|
+
if (!missingConventionLabels(present).includes(DECISION_RECORDED_LABEL)) return null;
|
|
605
|
+
return `this repo has no \`${DECISION_RECORDED_LABEL}\` label, so a decision cannot be recorded — it `
|
|
606
|
+
+ `adopted the conventions before that label entered the set and never back-filled it. Run `
|
|
607
|
+
+ `handbook-sync (§7) to create the convention label set, then re-run the command.`;
|
|
608
|
+
}
|
|
609
|
+
|
|
610
|
+
// The GROUP label prefix (CONVENTIONS.md §5, Grouping). `group:<key>` records that a set of
|
|
611
|
+
// issues must share one branch — the key is the branch slug minus its trailing issue numbers.
|
|
612
|
+
// Deliberately NOT in CONVENTION_LABELS: it is per-group (one label PER key, not one fixed
|
|
613
|
+
// name), created on demand by whoever computes the grouping (`code-triage`), not provisioned
|
|
614
|
+
// up front the way the fixed convention set is.
|
|
615
|
+
const GROUP_LABEL_PREFIX = 'group:';
|
|
616
|
+
|
|
617
|
+
// Is this label name a group marker? Guards against the bare prefix itself ("group:" with no
|
|
618
|
+
// key) reading as one — that string names no group and nothing should ever try to delete it.
|
|
619
|
+
function isGroupLabel(name) {
|
|
620
|
+
return typeof name === 'string' && name.length > GROUP_LABEL_PREFIX.length && name.startsWith(GROUP_LABEL_PREFIX);
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
// The group label names carried by a label list — same tolerant shape as missingConventionLabels
|
|
624
|
+
// (bare strings or {name} objects), so a caller can hand this `info.labels` straight off
|
|
625
|
+
// `gh issue view` / `gh issue list` without mapping first. Order-preserving, deduplicated: a
|
|
626
|
+
// caller unioning group labels across several issues (colab ship's B4, per #82) must not visit
|
|
627
|
+
// the same key twice.
|
|
628
|
+
function groupLabelNames(present) {
|
|
629
|
+
const out = [];
|
|
630
|
+
const seen = new Set();
|
|
631
|
+
for (const n of (present || [])) {
|
|
632
|
+
const name = n && typeof n === 'object' ? n.name : n;
|
|
633
|
+
const s = name === undefined || name === null ? '' : String(name);
|
|
634
|
+
if (isGroupLabel(s) && !seen.has(s)) { seen.add(s); out.push(s); }
|
|
635
|
+
}
|
|
636
|
+
return out;
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
module.exports = {
|
|
640
|
+
CONVENTION_LABELS, conventionLabelNames, missingConventionLabels, staleConventionDescriptions,
|
|
641
|
+
MINIMAL_LABEL_NAMES, minimalConventionLabels,
|
|
642
|
+
READINESS_LABEL, readinessLabelArgs, readinessMissingLabelHint, readinessMarkedMessage,
|
|
643
|
+
TRACKING_LABEL,
|
|
644
|
+
MECHANICAL_READINESS_LABEL, mechanicalReadinessLabelArgs,
|
|
645
|
+
MIGRATION_GRANT_LABEL, migrationGrantLabelArgs, migrationGrantMissingLabelHint,
|
|
646
|
+
CI_GRANT_LABEL, ciGrantLabelArgs, ciGrantMissingLabelHint,
|
|
647
|
+
NEEDS_DECISION_LABEL, DECISION_RECORDED_LABEL, decisionRecordedMissingLabelHint,
|
|
648
|
+
GROUP_LABEL_PREFIX, isGroupLabel, groupLabelNames,
|
|
649
|
+
DELIVERY_LABEL_PREFIX, DELIVERY_TYPES, CODE_LANE_DELIVERY_TYPES, NON_CODE_DELIVERY_TYPES,
|
|
650
|
+
deliveryType, isRouteNotStart,
|
|
651
|
+
DEFERRED_LABEL_PREFIX, DEFERRED_KINDS, deferredKind, isDeferred,
|
|
652
|
+
REVIEW_BY_LABEL_PREFIX, isReviewByLabel, reviewByLabelNames, parseReviewByDate,
|
|
653
|
+
};
|