@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.8
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 +309 -3
- package/README.vi.md +279 -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 +117 -0
- package/templates/release-auto.yml +470 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13746 -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-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 +703 -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,143 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* The close gate (#74): `Closes #N` may only be composed when issue #N's `## Plan` checklist is
|
|
4
|
+
* fully accounted for — every box ticked, or the leftover boxes consciously handed to a declared
|
|
5
|
+
* `Remainder: #M` issue. This module is PURE (string in, verdict out) — all `gh` I/O stays in the
|
|
6
|
+
* CLI, the same split `lib/squash.js` uses and for the same reason: `tools/colab` has no test
|
|
7
|
+
* harness, `tools/lib/*.test.js` is wired into CI, and a parsing bug here is invisible without one.
|
|
8
|
+
*
|
|
9
|
+
* THE INCIDENT THIS FIXES. An issue was closed by squash-merge with one third of its three-section
|
|
10
|
+
* scope unimplemented. The sections were PROSE, so nothing could parse them — B1b's Done/Partial/
|
|
11
|
+
* Untouched classification (CONVENTIONS.md §4, code-ship SKILL.md B1b) was honour-system, and the
|
|
12
|
+
* honour system missed a section. A `## Plan` checklist is the mechanical version of the same
|
|
13
|
+
* classification: a box is either `[x]` or it is not, and nothing about reading it requires
|
|
14
|
+
* judgment the way "is this prose paragraph done" does.
|
|
15
|
+
*
|
|
16
|
+
* WHAT THIS DOES NOT COVER. An issue with no `## Plan` heading at all, or a `## Plan` section
|
|
17
|
+
* written as prose with no `- [ ]` lines, cannot be mechanically verified — there is nothing to
|
|
18
|
+
* count. `planVerdict` reports that shape (`proseOnly`) as a FINDING, not a block: `complete`
|
|
19
|
+
* comes back `true` for it, the same as a genuinely empty plan, because refusing every issue that
|
|
20
|
+
* predates this convention would make the gate impossible to adopt. The Convention this module
|
|
21
|
+
* backs (CONVENTIONS.md §4) is that a prose-section scope is itself worth reporting — reporting is
|
|
22
|
+
* this module's job via `proseOnly`; refusing is not.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
/** Heading that opens the checklist section — `## Plan` or `## Plan (checklist)`, either level 2. */
|
|
26
|
+
const PLAN_HEADING_RE = /^#{2,6}\s*Plan\b/i;
|
|
27
|
+
|
|
28
|
+
/** Any markdown heading, used to find where the Plan section ENDS. */
|
|
29
|
+
const ANY_HEADING_RE = /^#{1,6}\s+\S/;
|
|
30
|
+
|
|
31
|
+
/** A GitHub checklist line: `- [ ] …` or `- [x] …` (case-insensitive on the mark). */
|
|
32
|
+
const ITEM_RE = /^-\s*\[([ xX])\]\s*(.+)$/;
|
|
33
|
+
|
|
34
|
+
/** `Remainder: #M` — the trailer that hands unticked boxes to a follow-up issue, same shape as
|
|
35
|
+
* the `Filed-by:` / `Group:` / `Because:` trailers this repo already writes onto issues. */
|
|
36
|
+
const REMAINDER_RE = /^Remainder:\s*#(\d+)\b/im;
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* The raw text of the `## Plan` section (between its heading and the next heading, or the end of
|
|
40
|
+
* the body), or `null` if the body has no such heading at all. Body may be `null`/`undefined`
|
|
41
|
+
* (a `gh` read that failed) — treated the same as "no heading found".
|
|
42
|
+
*/
|
|
43
|
+
function parsePlanSection(body) {
|
|
44
|
+
const lines = String(body || '').split('\n');
|
|
45
|
+
let start = -1;
|
|
46
|
+
let end = lines.length;
|
|
47
|
+
for (let i = 0; i < lines.length; i++) {
|
|
48
|
+
if (start === -1) {
|
|
49
|
+
if (PLAN_HEADING_RE.test(lines[i])) start = i + 1;
|
|
50
|
+
continue;
|
|
51
|
+
}
|
|
52
|
+
if (ANY_HEADING_RE.test(lines[i])) { end = i; break; }
|
|
53
|
+
}
|
|
54
|
+
if (start === -1) return null;
|
|
55
|
+
return lines.slice(start, end).join('\n');
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Checklist items (`{checked, text}`) found in a section's text, in document order. */
|
|
59
|
+
function parseChecklistItems(sectionText) {
|
|
60
|
+
if (!sectionText) return [];
|
|
61
|
+
const out = [];
|
|
62
|
+
for (const raw of String(sectionText).split('\n')) {
|
|
63
|
+
const m = ITEM_RE.exec(raw.trim());
|
|
64
|
+
if (m) out.push({ checked: m[1].toLowerCase() === 'x', text: m[2].trim() });
|
|
65
|
+
}
|
|
66
|
+
return out;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* The scope verdict for one issue body.
|
|
71
|
+
*
|
|
72
|
+
* `complete` is `true` in three shapes, deliberately conflated because none of them is a reason to
|
|
73
|
+
* block a close: no `## Plan` heading at all (pre-convention issue), a heading with zero checklist
|
|
74
|
+
* items (nothing to verify — `proseOnly` distinguishes "genuinely empty" from "prose scope, a
|
|
75
|
+
* finding" for a caller that wants to report it), or a heading whose items are all ticked. It is
|
|
76
|
+
* `false` in exactly one shape: at least one real, unticked `- [ ]` box.
|
|
77
|
+
*/
|
|
78
|
+
function planVerdict(body) {
|
|
79
|
+
const section = parsePlanSection(body);
|
|
80
|
+
const hasHeading = section !== null;
|
|
81
|
+
const items = hasHeading ? parseChecklistItems(section) : [];
|
|
82
|
+
const total = items.length;
|
|
83
|
+
const checked = items.filter((i) => i.checked).length;
|
|
84
|
+
const unchecked = total - checked;
|
|
85
|
+
const proseOnly = hasHeading && total === 0 && section.trim().length > 0;
|
|
86
|
+
const complete = total === 0 || unchecked === 0;
|
|
87
|
+
return { hasHeading, items, total, checked, unchecked, proseOnly, complete };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* The declared remainder issue number, or `null`. Searched across the body AND every comment body
|
|
92
|
+
* (`gh issue view --json body,comments`'s `comments[].body`) — the remainder is typically declared
|
|
93
|
+
* in a wrap-time comment, written after the issue itself was opened, never by editing history into
|
|
94
|
+
* the original body.
|
|
95
|
+
*/
|
|
96
|
+
function findRemainder(body, comments) {
|
|
97
|
+
const texts = [String(body || ''), ...(Array.isArray(comments) ? comments : []).map((c) => String((c && c.body) || ''))];
|
|
98
|
+
for (const t of texts) {
|
|
99
|
+
const m = REMAINDER_RE.exec(t);
|
|
100
|
+
if (m) return Number(m[1]);
|
|
101
|
+
}
|
|
102
|
+
return null;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The close-gate verdict for one issue: may `colab ship` (or a human doing code-ship B2) write
|
|
107
|
+
* `Closes #N` for it?
|
|
108
|
+
*
|
|
109
|
+
* `ok: true` covers: nothing to verify (see `planVerdict`), a fully-ticked checklist, OR an
|
|
110
|
+
* unticked checklist with a declared `Remainder: #M` — the plan explicitly permits closing once
|
|
111
|
+
* the leftover boxes have a named home, they do not need to be ticked false-positive first.
|
|
112
|
+
*
|
|
113
|
+
* `ok: false` is the one shape the whole feature exists to catch: real unticked boxes, no
|
|
114
|
+
* remainder declared anywhere the caller looked.
|
|
115
|
+
*/
|
|
116
|
+
function closeGate(body, comments) {
|
|
117
|
+
const verdict = planVerdict(body);
|
|
118
|
+
if (verdict.complete) {
|
|
119
|
+
return {
|
|
120
|
+
ok: true, remainderIssue: null,
|
|
121
|
+
reason: verdict.total === 0 ? 'no Plan checklist to verify' : 'Plan checklist fully ticked',
|
|
122
|
+
...verdict,
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
const remainderIssue = findRemainder(body, comments);
|
|
126
|
+
if (remainderIssue) {
|
|
127
|
+
return {
|
|
128
|
+
ok: true, remainderIssue,
|
|
129
|
+
reason: `${verdict.unchecked}/${verdict.total} Plan item(s) unticked — remainder declared as #${remainderIssue}`,
|
|
130
|
+
...verdict,
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
return {
|
|
134
|
+
ok: false, remainderIssue: null,
|
|
135
|
+
reason: `${verdict.unchecked}/${verdict.total} Plan item(s) unticked, no declared remainder`,
|
|
136
|
+
...verdict,
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
module.exports = {
|
|
141
|
+
PLAN_HEADING_RE, ANY_HEADING_RE, ITEM_RE, REMAINDER_RE,
|
|
142
|
+
parsePlanSection, parseChecklistItems, planVerdict, findRemainder, closeGate,
|
|
143
|
+
};
|
|
@@ -0,0 +1,512 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* The cure rule (#281) — a machine-checkable arm added to `colab ship`'s trunk-CI-green
|
|
4
|
+
* precondition, alongside the human-only ci-grant (tools/lib/ci-grant.js, #105), which
|
|
5
|
+
* survives UNCHANGED for everything this rule does not cover.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS NEEDS NO HUMAN ATTESTATION, where a ci-grant does. A ci-grant's whole job is to
|
|
8
|
+
* let a human certify a fact the gate cannot measure on its own: "this branch is the cure for
|
|
9
|
+
* this specific red." The cure rule instead measures that fact directly, from two git+CI
|
|
10
|
+
* signals stronger than what a grant checks today:
|
|
11
|
+
*
|
|
12
|
+
* 1. CONTAINMENT — the branch contains trunk's current red head sha (a real ancestor, not
|
|
13
|
+
* merely "no conflicts"). A ci-grant's evidence guard checks the branch's own head is
|
|
14
|
+
* green, but never containment — a branch cut from an OLDER, green base can carry a
|
|
15
|
+
* green run that proves nothing about the redness it is being exempted from.
|
|
16
|
+
* 2. EVIDENCE — the branch's own CI is green AT ITS OWN CURRENT HEAD, measured (never
|
|
17
|
+
* asserted), same "ask by sha" discipline ci-grant.js already uses (2a) — AND, since #297,
|
|
18
|
+
* every job that is RED on trunk at the red sha exists in the branch's runs at that head,
|
|
19
|
+
* completed and concluded `success` (2b, `redJobsProvenOnBranch`). A green run alone never
|
|
20
|
+
* proved the check trunk is failing ran here: a `paths:` filter, a matrix change or a
|
|
21
|
+
* renamed job leaves the run green while the named check never ran.
|
|
22
|
+
*
|
|
23
|
+
* Containment + evidence TOGETHER mean the branch's tree passed the full suite INCLUDING the
|
|
24
|
+
* tests trunk is currently failing — merging it provably turns trunk green. That is the one
|
|
25
|
+
* thing the human click on a ci-grant is supposed to certify, mechanically checkable instead.
|
|
26
|
+
*
|
|
27
|
+
* THREE CONDITIONS THIS RULE ADDS ON TOP, deliberately narrowing it rather than trusting
|
|
28
|
+
* containment+evidence alone:
|
|
29
|
+
*
|
|
30
|
+
* 3. ANTI-STACKING — the identical guard ci-grant.js's stackingVerdict already computes,
|
|
31
|
+
* reused VERBATIM (not re-derived): a repo that auto-cures once and stays red anyway must
|
|
32
|
+
* not auto-cure again on the same continuous red — that is how a permanently broken repo
|
|
33
|
+
* ships anyway, exactly the failure trunk-CI-green exists to prevent. The caller widens the
|
|
34
|
+
* trailer scan that feeds this (tools/colab's computeAntiStacking) to recognise BOTH a
|
|
35
|
+
* prior `CI-Grant:` trailer and a prior `CI-Cure:` trailer as "an exemption already merged
|
|
36
|
+
* against this red" — a cure and a grant are both exemptions for this guard's purposes.
|
|
37
|
+
* 4. NO WORKFLOW-FILE CHANGES — the branch diff must not touch `.github/workflows/**`. A
|
|
38
|
+
* branch that edits the CI configuration doing the grading is not allowed to grade itself;
|
|
39
|
+
* that door stays behind a human ci-grant (condition 4 in the original proposal, #281).
|
|
40
|
+
* ONE GUARDED CARVE-OUT (#321), below, is the single way through it. The diff is read with
|
|
41
|
+
* `--no-renames` (tools/lib/cure-diff.js, #297), so moving a workflow file away counts.
|
|
42
|
+
* 5. NO MANIFEST-SCRIPTS CHANGES (#297) — the branch diff must not change the `scripts` block of
|
|
43
|
+
* any `package.json`. The Node CI template decides from that block whether typecheck, lint
|
|
44
|
+
* and test run at all, and a skipped step leaves the job `success` — so deleting
|
|
45
|
+
* `scripts.test` weakens the instrument without touching a workflow file. No carve-out: see
|
|
46
|
+
* below for why the #321 door cannot adjudicate it.
|
|
47
|
+
* 6. NO PYTHON DEPENDENCY-MANIFEST CHANGES (#377) — the branch diff must not change a file the
|
|
48
|
+
* Python CI template installs from (`pyproject.toml`/`setup.py`/`setup.cfg`, `requirements*`
|
|
49
|
+
* files and what they include — tools/lib/cure-diff.js names the set). That template runs
|
|
50
|
+
* ruff/mypy/pytest only when the tool is importable after install, so removing `pytest` from
|
|
51
|
+
* `requirements-dev.txt` skips the Test step and leaves the job `success`. Same shape as 5, a
|
|
52
|
+
* sibling door with no carve-out, for the same reason.
|
|
53
|
+
*
|
|
54
|
+
* THE WORKFLOW CARVE-OUT (#321) — why condition 4 could not simply stay absolute. The repair for
|
|
55
|
+
* a CI-INFRASTRUCTURE outage is, by construction, a workflow change: when trunk goes red because
|
|
56
|
+
* the runner pool cannot reach a service container, the branch that fixes it necessarily edits
|
|
57
|
+
* `.github/workflows/**`, and was therefore permanently cure-ineligible however green it was. The
|
|
58
|
+
* only exit was a human ci-grant — and a human reading a one-line grant prompt is measurably
|
|
59
|
+
* BADLY placed to judge this particular case: a genuine repair and a "CI fix" that pins every job
|
|
60
|
+
* to a runner missing a shared library read identically in prose, and granting the wrong one
|
|
61
|
+
* converts a stalled trunk into a permanently red one. The CI evidence tells them apart; the
|
|
62
|
+
* prompt does not.
|
|
63
|
+
*
|
|
64
|
+
* So condition 4 stays a refusal BY DEFAULT and gains exactly one guarded door, admissible only
|
|
65
|
+
* on evidence this gate can actually measure (`workflowCarveOut`, below). On top of conditions
|
|
66
|
+
* 1-3, ALL of:
|
|
67
|
+
*
|
|
68
|
+
* 4a. JOB-NAME SUPERSET — every job that is RED on trunk's run at the red sha exists on the
|
|
69
|
+
* branch's own green run, completed, concluded `success`. "I made the red job disappear"
|
|
70
|
+
* (deleted, renamed, filtered away) fails here.
|
|
71
|
+
* 4b. EXECUTED-STEP SUPERSET — for each of those jobs, every step that actually RAN on trunk
|
|
72
|
+
* (reached a terminal, non-skipped conclusion) is present on the branch's job and concluded
|
|
73
|
+
* `success`. Steps AFTER the failing one are `skipped` on trunk and so constrain nothing —
|
|
74
|
+
* only steps that demonstrably ran do. "I made it exit early" fails here. This sub-test is
|
|
75
|
+
* the structural, primary one: it embeds no constant, is self-calibrating, and is symmetric
|
|
76
|
+
* with 4a one level down.
|
|
77
|
+
* 4c. DURATION FLOOR — each of those jobs cost at least the wall time its failure did on trunk
|
|
78
|
+
* (`branchMs >= redMs`, both measurable and > 0). 4b proves the STEPS ran; it cannot see a
|
|
79
|
+
* step's `run:` body gutted to a no-op inside the very workflow file this door is carving
|
|
80
|
+
* an exception for, and duration is the only signal that touches that. The comparison is
|
|
81
|
+
* against a measurement taken in the SAME repo, on the SAME job, on the same runner class,
|
|
82
|
+
* minutes apart — so there is no repo-specific constant to tune and no floor to defend.
|
|
83
|
+
*
|
|
84
|
+
* WHY `conclusion === 'success'` ALONE IS NOT ENOUGH, even though it carries real weight: GitHub
|
|
85
|
+
* reports a job whose steps were ALL skipped as `conclusion: success`. Run-level and job-level
|
|
86
|
+
* success are both blind to the skip; step-level is not. That is why 4b exists rather than
|
|
87
|
+
* trusting the conclusion, and it is the same shape #297's `package.json`-scripts scenario
|
|
88
|
+
* produces.
|
|
89
|
+
*
|
|
90
|
+
* WHY `package.json`'s `scripts` BLOCK IS A SIBLING CONDITION (5), NOT A WIDENED
|
|
91
|
+
* `workflowsTouched` (the seam #321 left, filled by #297 in exactly this shape). It is tempting to fold every path that
|
|
92
|
+
* forms "the instrument" into one boolean and let this carve-out serve them all. It must not be:
|
|
93
|
+
* the carve-out's evidence CANNOT adjudicate a `package.json`-scripts weakening in the general
|
|
94
|
+
* case — that change happens inside a step whose name and conclusion are unchanged and whose
|
|
95
|
+
* duration delta may sit below any signal, so 4b and 4c would both silently pass a change they
|
|
96
|
+
* are structurally unable to see. Two instrument paths, two different doors. What this module
|
|
97
|
+
* names once is the carve-out PREDICATE (`workflowCarveOut`, `redJobsProvenOnBranch`), never the
|
|
98
|
+
* path list. Condition 5 is checked BEFORE the workflow block (see `cureVerdict`), because that
|
|
99
|
+
* block returns success when the carve-out admits — a branch touching both must still meet door 5.
|
|
100
|
+
*
|
|
101
|
+
* WHY ONLY 4a IS HOISTED (as 2b), NOT 4b/4c (#297). The executed-step superset refuses genuine
|
|
102
|
+
* cures often on the ordinary path — a cache-conditional step that ran on trunk is skipped on a
|
|
103
|
+
* cache hit, and a push-only step that ran on trunk is skipped on the `pull_request` run a branch
|
|
104
|
+
* frequently offers as evidence. It would catch the scripts case, but condition 5 already does,
|
|
105
|
+
* without those false refusals. 4b/4c stay the carve-out's, where the workflow itself changed.
|
|
106
|
+
*
|
|
107
|
+
* HONEST LIMIT, stated rather than glossed (same posture as the #281 proposal): test-file
|
|
108
|
+
* self-weakening is not detectable at this gate. A branch can go green by gutting the failing
|
|
109
|
+
* tests. Check-runs name jobs, not files, so this module cannot see it; condition 4 closes only
|
|
110
|
+
* the adjacent, checkable door (weakening the CI config itself). Content weakening is caught
|
|
111
|
+
* where it is caught today — review/grade time, downstream of ship.
|
|
112
|
+
*
|
|
113
|
+
* HONEST LIMIT OF THE CARVE-OUT (#321), in the same register: it proves the red jobs still
|
|
114
|
+
* exist, still ran the steps they ran on trunk, and still cost at least the wall time the failure
|
|
115
|
+
* did. It cannot see what those steps ASSERTED. A workflow edit that preserves every step name
|
|
116
|
+
* and every second of wall time while weakening what the commands actually check passes this
|
|
117
|
+
* door — the same content-blindness the rule already confesses at test-file level, moved one
|
|
118
|
+
* layer down into the workflow itself. What the carve-out closes is the STRUCTURAL form:
|
|
119
|
+
* deleting, renaming, `if:`-ing away, or fast-exiting the job trunk is red on.
|
|
120
|
+
*
|
|
121
|
+
* KNOWN, ACCEPTED FALSE REFUSAL (4c): a trunk job that failed by TIMEOUT or hang ran longer than
|
|
122
|
+
* any healthy green run, so the duration floor refuses the genuine repair. The direction of that
|
|
123
|
+
* error is the safe one — it falls through to the ordinary ci-grant, exactly as before this
|
|
124
|
+
* carve-out existed — and the refusal reason says so in as many words. Relaxing 4c when the red
|
|
125
|
+
* job concluded `timed_out`/`cancelled` is a DELIBERATELY UNMADE decision: it is one `if`, and it
|
|
126
|
+
* is the obvious first follow-up the moment that refusal is observed in the field, but adding it
|
|
127
|
+
* unmeasured is precisely the speculative loosening condition 4 exists to resist.
|
|
128
|
+
*
|
|
129
|
+
* PURE BY CONSTRUCTION, identical posture to ci-grant.js / migration-grant.js / readiness.js /
|
|
130
|
+
* shipguard.js: signals in, verdict out. No git, no network, no `gh`. The caller (tools/colab)
|
|
131
|
+
* measures containment, evidence, anti-stacking and the workflow-file diff, and hands them in.
|
|
132
|
+
* The carve-out's job-level signal is shaped here too (`shapeJobEvidence`), from raw `gh run view
|
|
133
|
+
* --json jobs` rows the caller reads — so the red-job SELECTION rule is unit-testable and the
|
|
134
|
+
* caller's untestable residue stays plain I/O.
|
|
135
|
+
*
|
|
136
|
+
* DELIBERATELY NOT THE SAME DOOR AS A CI GRANT: no label, no per-issue tracker comment, no
|
|
137
|
+
* `COLAB_HUMAN=1` bar to pass through — the whole point of proving the fact mechanically is
|
|
138
|
+
* that nothing here needs a human write. If any condition fails, the ordinary ci-grant remains
|
|
139
|
+
* available as the fallback door, unaffected by anything in this module.
|
|
140
|
+
*/
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* The condition-4 refusal, verbatim — the text a workflow-touching branch gets when the carve-out
|
|
144
|
+
* (#321) does not admit it. Held as a constant so the plain refusal and the carve-out's more
|
|
145
|
+
* specific one can never drift apart: the carve-out appends its own reason to THIS string rather
|
|
146
|
+
* than restating it.
|
|
147
|
+
*/
|
|
148
|
+
const WORKFLOW_REFUSAL =
|
|
149
|
+
'branch diff touches .github/workflows/** — the cure rule refuses to let a branch self-certify ' +
|
|
150
|
+
'a change to the CI configuration that is grading it; a human ci-grant is the door for this case';
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* The condition-5 refusal (#297) — the text a branch gets when its diff changes the `scripts` block
|
|
154
|
+
* of any `package.json`. No carve-out follows it, deliberately: the #321 carve-out's evidence (job
|
|
155
|
+
* names, executed steps, duration) cannot see a scripts weakening, which happens INSIDE a step whose
|
|
156
|
+
* name and conclusion are unchanged.
|
|
157
|
+
*/
|
|
158
|
+
const MANIFEST_SCRIPTS_REFUSAL =
|
|
159
|
+
'branch diff changes the `scripts` block of package.json — CI templates read that block to decide which ' +
|
|
160
|
+
'checks run, so it is part of the instrument grading this branch and the cure rule will not let a branch ' +
|
|
161
|
+
'change it and grade itself; there is no carve-out for this case, a human ci-grant is the door';
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* The condition-6 refusal (#377) — a branch whose diff changes a Python dependency manifest. No
|
|
165
|
+
* carve-out, for the same reason as condition 5: the skip happens inside a job whose name and
|
|
166
|
+
* conclusion are unchanged.
|
|
167
|
+
*/
|
|
168
|
+
const PYTHON_MANIFEST_REFUSAL =
|
|
169
|
+
'branch diff changes a Python dependency manifest — the Python CI template runs lint, typecheck and test only ' +
|
|
170
|
+
'when the tool is installed from those files, so they are part of the instrument grading this branch and the cure ' +
|
|
171
|
+
'rule will not let a branch change them and grade itself (a version pin counts too); there is no carve-out for ' +
|
|
172
|
+
'this case, a human ci-grant is the door';
|
|
173
|
+
|
|
174
|
+
/** Conclusions that do NOT make a completed job red. Inverted allowlist, the same shape (and for
|
|
175
|
+
* the same reason) as tools/lib/git.js's run-level rule: a denylist gets chased value by value,
|
|
176
|
+
* an allowlist closes the family once. `skipped` joins the run-level pair here because a job that
|
|
177
|
+
* never ran is not a job that failed. */
|
|
178
|
+
const NOT_RED_CONCLUSIONS = new Set(['success', 'cancelled', 'skipped']);
|
|
179
|
+
|
|
180
|
+
/** A step "ran" on trunk iff it reached a terminal conclusion that is not `skipped`/`cancelled`.
|
|
181
|
+
* Steps after the failing one are skipped by GitHub, and a skipped step constrains nothing. */
|
|
182
|
+
function stepRan(s) {
|
|
183
|
+
return !!s && s.status === 'completed' && s.conclusion !== 'skipped' && s.conclusion !== 'cancelled';
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** Milliseconds between two ISO timestamps, or null when either is missing/unparseable. Never 0-by
|
|
187
|
+
* default: an unmeasurable duration must reach the caller as null so it can fail closed, not as a
|
|
188
|
+
* zero that would silently satisfy a `>= 0` comparison. */
|
|
189
|
+
function durationMs(startedAt, completedAt) {
|
|
190
|
+
if (!startedAt || !completedAt) return null;
|
|
191
|
+
const a = Date.parse(startedAt);
|
|
192
|
+
const b = Date.parse(completedAt);
|
|
193
|
+
if (!Number.isFinite(a) || !Number.isFinite(b)) return null;
|
|
194
|
+
const d = b - a;
|
|
195
|
+
return Number.isFinite(d) ? d : null;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/** A duration is usable for the 4c comparison only if it is a finite, strictly positive number.
|
|
199
|
+
* `0` is not "instant", it is "not measured" — a job GitHub reports with equal start and end
|
|
200
|
+
* timestamps tells us nothing, and admitting it would let a fast-exit satisfy the floor. */
|
|
201
|
+
function usableMs(v) {
|
|
202
|
+
return typeof v === 'number' && Number.isFinite(v) && v > 0;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/**
|
|
206
|
+
* Shapes the raw `gh run view --json jobs` rows the caller read into the `jobEvidence` structure
|
|
207
|
+
* `workflowCarveOut` consumes — PURE, so the red-job selection rule is unit-testable rather than
|
|
208
|
+
* buried in tools/colab's I/O.
|
|
209
|
+
*
|
|
210
|
+
* `redRunJobs` — every job of every NOT-GREEN workflow run at trunk's red sha, concatenated. The
|
|
211
|
+
* caller must pass jobs from ALL such runs, not just one: a sha can carry several workflow runs,
|
|
212
|
+
* and building the red set from one picked row could miss a second failing workflow and admit a
|
|
213
|
+
* carve-out while a job is still red.
|
|
214
|
+
*
|
|
215
|
+
* `branchRunJobs` — every job of EVERY run at the branch's own head, concatenated (#297). Not just
|
|
216
|
+
* the one green row the evidence read picked: once 2b applies to every cure, a red job living in a
|
|
217
|
+
* sibling workflow would otherwise read as "absent on the branch" and refuse a genuine cure.
|
|
218
|
+
*
|
|
219
|
+
* Each row may carry `workflowName` (the caller tags it from the run it came from); it is carried
|
|
220
|
+
* through on both sides so jobs are matched per workflow, never by bare name across workflows.
|
|
221
|
+
*
|
|
222
|
+
* Returns `null` — meaning "unmeasurable", which every consumer below fails closed on — when
|
|
223
|
+
* either input is not an array, or when ANY trunk job at the red sha has not COMPLETED. A
|
|
224
|
+
* half-finished red run cannot be adjudicated: a job still in flight may yet become the red one
|
|
225
|
+
* the branch would have to prove it repaired.
|
|
226
|
+
*/
|
|
227
|
+
function shapeJobEvidence({ redRunJobs, branchRunJobs } = {}) {
|
|
228
|
+
if (!Array.isArray(redRunJobs) || !Array.isArray(branchRunJobs)) return null;
|
|
229
|
+
if (redRunJobs.some((j) => !j || j.status !== 'completed')) return null;
|
|
230
|
+
|
|
231
|
+
const redJobs = redRunJobs
|
|
232
|
+
.filter((j) => !NOT_RED_CONCLUSIONS.has(j.conclusion))
|
|
233
|
+
.map((j) => ({
|
|
234
|
+
name: j.name,
|
|
235
|
+
workflowName: j.workflowName || '',
|
|
236
|
+
conclusion: j.conclusion,
|
|
237
|
+
durationMs: durationMs(j.startedAt, j.completedAt),
|
|
238
|
+
ranSteps: Array.isArray(j.steps) ? j.steps.filter(stepRan).map((s) => s.name) : null,
|
|
239
|
+
}));
|
|
240
|
+
|
|
241
|
+
const branchJobs = branchRunJobs.map((j) => ({
|
|
242
|
+
name: j && j.name,
|
|
243
|
+
workflowName: (j && j.workflowName) || '',
|
|
244
|
+
status: j && j.status,
|
|
245
|
+
conclusion: j && j.conclusion,
|
|
246
|
+
durationMs: j ? durationMs(j.startedAt, j.completedAt) : null,
|
|
247
|
+
steps: j && Array.isArray(j.steps) ? j.steps.map((s) => ({ name: s && s.name, conclusion: s && s.conclusion })) : null,
|
|
248
|
+
}));
|
|
249
|
+
|
|
250
|
+
return { redJobs, branchJobs };
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** How a job is named in a reason string: `workflow / job` when the workflow is known. */
|
|
254
|
+
function jobLabel(j) {
|
|
255
|
+
return j.workflowName ? `${j.workflowName} / ${j.name}` : j.name;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/** The matching key: workflow AND job name (#297). A bare-name key over the union of every run at
|
|
259
|
+
* the branch head would let a passing `test` in one workflow stand in for a missing or failed
|
|
260
|
+
* `test` in another — fail-open. A row with no workflow name keys under `''` on both sides. */
|
|
261
|
+
function jobKey(j) {
|
|
262
|
+
return `${j.workflowName || ''}\u0000${j.name}`;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* Index the branch's jobs by `jobKey`. The same key legitimately appears more than once — the push
|
|
267
|
+
* and the `pull_request` run of one workflow at one sha, or a cancelled attempt beside a green one.
|
|
268
|
+
* The instance kept is a completed `success` one when any exists; `hasRed` records that ANY instance
|
|
269
|
+
* completed with a red conclusion, and `hasPending` that any instance has not completed. Both refuse
|
|
270
|
+
* in `redJobsProvenOnBranch`: a job that passed once and failed once at the same sha has not proven
|
|
271
|
+
* anything, and one still in flight has not passed.
|
|
272
|
+
*/
|
|
273
|
+
function indexBranchJobs(branchJobs) {
|
|
274
|
+
const idx = new Map();
|
|
275
|
+
for (const j of branchJobs) {
|
|
276
|
+
if (!j || !j.name) continue;
|
|
277
|
+
const k = jobKey(j);
|
|
278
|
+
const prev = idx.get(k);
|
|
279
|
+
const isRed = j.status === 'completed' && !NOT_RED_CONCLUSIONS.has(j.conclusion);
|
|
280
|
+
const isPending = j.status !== 'completed';
|
|
281
|
+
if (!prev) { idx.set(k, { job: j, hasRed: isRed, hasPending: isPending }); continue; }
|
|
282
|
+
const better = j.status === 'completed' && j.conclusion === 'success'
|
|
283
|
+
&& !(prev.job.status === 'completed' && prev.job.conclusion === 'success');
|
|
284
|
+
idx.set(k, { job: better ? j : prev.job, hasRed: prev.hasRed || isRed, hasPending: prev.hasPending || isPending });
|
|
285
|
+
}
|
|
286
|
+
return idx;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Sub-test 4a (#321), and — since #297 — condition 2b of EVERY cure: every job RED on trunk exists
|
|
291
|
+
* on the branch's runs at its own head, completed and successful.
|
|
292
|
+
*
|
|
293
|
+
* WHY HOISTED (#297). Condition 2 used to read a single run-level conclusion. That is weaker than
|
|
294
|
+
* the rule's own claim — "the branch's tree provably turns trunk green" — because nothing checked
|
|
295
|
+
* that the check trunk is red ON ran here and passed: a `paths:` filter, a matrix change, or a job
|
|
296
|
+
* that simply no longer exists can leave a run green while the named check never ran. "The one
|
|
297
|
+
* check that was failing must now pass" is the claim stated exactly. It is scoped to trunk's RED
|
|
298
|
+
* set, so it never inherits a fold-every-check-run consumer's sensitivity to an advisory failure
|
|
299
|
+
* that exists only on the branch: this certifies that the branch cures trunk's red, not that the
|
|
300
|
+
* branch is spotless.
|
|
301
|
+
*
|
|
302
|
+
* Returns `{ok, reason, jobs}` — `jobs` is the list of red job names proven on the branch.
|
|
303
|
+
* Every unmeasurable input is a refusal, never a pass.
|
|
304
|
+
*/
|
|
305
|
+
function redJobsProvenOnBranch(jobEvidence) {
|
|
306
|
+
if (!jobEvidence || typeof jobEvidence !== 'object') {
|
|
307
|
+
return { ok: false, jobs: [], reason: 'the job-level evidence needed to judge it could not be measured (a failed read, or no run to read)' };
|
|
308
|
+
}
|
|
309
|
+
const { redJobs, branchJobs } = jobEvidence;
|
|
310
|
+
if (!Array.isArray(redJobs) || redJobs.length === 0) {
|
|
311
|
+
// An EMPTY red set is the dangerous shape, not a vacuous pass: trunk is red at run level, so
|
|
312
|
+
// "I could not name a single red job" is an unmeasurable state. Every `.every()` below would
|
|
313
|
+
// be trivially true over it.
|
|
314
|
+
return { ok: false, jobs: [], reason: 'trunk is red but no red JOB could be named on its run — an unmeasurable red is never cured' };
|
|
315
|
+
}
|
|
316
|
+
if (!Array.isArray(branchJobs) || branchJobs.length === 0) {
|
|
317
|
+
return { ok: false, jobs: [], reason: "the branch's own run reported no jobs to compare against" };
|
|
318
|
+
}
|
|
319
|
+
const idx = indexBranchJobs(branchJobs);
|
|
320
|
+
|
|
321
|
+
for (const red of redJobs) {
|
|
322
|
+
if (!red || !red.name) {
|
|
323
|
+
return { ok: false, jobs: [], reason: 'a job red on trunk has no name — it cannot be matched on the branch' };
|
|
324
|
+
}
|
|
325
|
+
const label = jobLabel(red);
|
|
326
|
+
const entry = idx.get(jobKey(red));
|
|
327
|
+
if (!entry) {
|
|
328
|
+
return { ok: false, jobs: [],
|
|
329
|
+
reason: `job \`${label}\` is red on trunk and does not exist on the branch's run — a cure may not make the failing job disappear (deleted, renamed, or filtered away)` };
|
|
330
|
+
}
|
|
331
|
+
const mine = entry.job;
|
|
332
|
+
if (mine.status !== 'completed' || entry.hasPending) {
|
|
333
|
+
return { ok: false, jobs: [],
|
|
334
|
+
reason: `job \`${label}\` is red on trunk and has not COMPLETED on the branch's run — a job still in flight has not passed` };
|
|
335
|
+
}
|
|
336
|
+
if (mine.conclusion !== 'success') {
|
|
337
|
+
return { ok: false, jobs: [],
|
|
338
|
+
reason: `job \`${label}\` is red on trunk and concluded \`${mine.conclusion}\` on the branch's run — every red job must pass, not merely exist` };
|
|
339
|
+
}
|
|
340
|
+
if (entry.hasRed) {
|
|
341
|
+
return { ok: false, jobs: [],
|
|
342
|
+
reason: `job \`${label}\` is red on trunk and failed in another run at the branch's own head — a job that both passed and failed at one sha has proven nothing` };
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
return { ok: true, jobs: redJobs.map((r) => r.name), reason: '' };
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/**
|
|
349
|
+
* The guarded carve-out through condition 4 (#321) — 4a (via `redJobsProvenOnBranch`), then 4b
|
|
350
|
+
* (executed-step superset) and 4c (duration floor). See the module header for why each sub-test
|
|
351
|
+
* exists and what the carve-out is honestly blind to.
|
|
352
|
+
*
|
|
353
|
+
* Returns `{ok, reason, jobs}` — on success `jobs` is `[{name, redMs, branchMs}]`, the audit
|
|
354
|
+
* detail the caller folds into the `CI-Cure:` trailer and the `--dry --json` payload so a later
|
|
355
|
+
* reader can tell WHICH door spent this red episode's single permitted exemption.
|
|
356
|
+
*/
|
|
357
|
+
function workflowCarveOut(jobEvidence) {
|
|
358
|
+
const proven = redJobsProvenOnBranch(jobEvidence);
|
|
359
|
+
if (!proven.ok) return { ok: false, jobs: [], reason: proven.reason };
|
|
360
|
+
|
|
361
|
+
const idx = indexBranchJobs(jobEvidence.branchJobs);
|
|
362
|
+
|
|
363
|
+
const jobs = [];
|
|
364
|
+
for (const red of jobEvidence.redJobs) {
|
|
365
|
+
const mine = idx.get(jobKey(red)).job; // present: redJobsProvenOnBranch above refused otherwise
|
|
366
|
+
|
|
367
|
+
// 4b — executed-step superset.
|
|
368
|
+
if (!Array.isArray(red.ranSteps)) {
|
|
369
|
+
return { ok: false, jobs: [], reason: `the steps that ran in job \`${red.name}\` on trunk could not be read — an unmeasurable step list is never a cure` };
|
|
370
|
+
}
|
|
371
|
+
if (!Array.isArray(mine.steps)) {
|
|
372
|
+
return { ok: false, jobs: [], reason: `the steps of job \`${red.name}\` on the branch's run could not be read — an unmeasurable step list is never a cure` };
|
|
373
|
+
}
|
|
374
|
+
const mySteps = new Map();
|
|
375
|
+
for (const s of mine.steps) if (s && s.name) mySteps.set(s.name, s);
|
|
376
|
+
for (const stepName of red.ranSteps) {
|
|
377
|
+
const s = mySteps.get(stepName);
|
|
378
|
+
if (!s) {
|
|
379
|
+
return { ok: false, jobs: [],
|
|
380
|
+
reason: `step \`${stepName}\` RAN in job \`${red.name}\` on trunk and is absent from the branch's run — a cure may not delete the steps the failure went through` };
|
|
381
|
+
}
|
|
382
|
+
if (s.conclusion !== 'success') {
|
|
383
|
+
return { ok: false, jobs: [],
|
|
384
|
+
reason: `step \`${stepName}\` RAN in job \`${red.name}\` on trunk and concluded \`${s.conclusion}\` on the branch — a step skipped away is not a step repaired` };
|
|
385
|
+
}
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
// 4c — duration floor, relative to the failure it replaces.
|
|
389
|
+
if (!usableMs(red.durationMs) || !usableMs(mine.durationMs)) {
|
|
390
|
+
return { ok: false, jobs: [],
|
|
391
|
+
reason: `job \`${red.name}\` has no usable wall-clock duration on one or both runs — the carve-out cannot tell a real run from a fast exit without it` };
|
|
392
|
+
}
|
|
393
|
+
if (mine.durationMs < red.durationMs) {
|
|
394
|
+
return { ok: false, jobs: [],
|
|
395
|
+
reason: `job \`${red.name}\` took ${mine.durationMs}ms on the branch but ${red.durationMs}ms to fail on trunk — too fast to have done the work the failure did. ` +
|
|
396
|
+
'(If trunk went red by TIMEOUT or hang, that failure ran LONGER than any healthy run and this refusal is a known false one — take the ordinary ci-grant door, which is unaffected.)' };
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
jobs.push({ name: red.name, redMs: red.durationMs, branchMs: mine.durationMs });
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
return { ok: true, jobs, reason: '' };
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
/**
|
|
406
|
+
* The cure verdict for one branch's attempt to ship into a red trunk.
|
|
407
|
+
*
|
|
408
|
+
* `containsRedSha` — bool, whether the branch's tree contains the red trunk sha as an ancestor
|
|
409
|
+
* (the caller's `git merge-base --is-ancestor <redSha> <branch>`, translated to a bool — never
|
|
410
|
+
* re-derived here, this module does not touch git).
|
|
411
|
+
*
|
|
412
|
+
* `evidence` — `{ok, sha}` for a completed, successful CI run measured on the branch's CURRENT
|
|
413
|
+
* head, or `null` when the caller's own read of it FAILED. Passing `evidence: null` means "the
|
|
414
|
+
* read failed", never "no evidence" — same fail-closed posture ci-grant.js's evaluateIssue
|
|
415
|
+
* takes on a failed record read.
|
|
416
|
+
*
|
|
417
|
+
* `redSha` — carried through only for the success/failure detail strings, never compared here
|
|
418
|
+
* (the caller already used it to compute `containsRedSha` and `evidence`).
|
|
419
|
+
*
|
|
420
|
+
* `stacking` — `{ok, reason}`, the caller's `ciGrant.stackingVerdict(...)` result, reused
|
|
421
|
+
* verbatim (condition 3) — this module never recomputes it.
|
|
422
|
+
*
|
|
423
|
+
* `workflowsTouched` — bool, whether the branch's diff against trunk touches any path under
|
|
424
|
+
* `.github/workflows/` (condition 4 — tools/lib/cure-diff.js, `--no-renames`). `null` means the
|
|
425
|
+
* diff could not be measured, and refuses.
|
|
426
|
+
*
|
|
427
|
+
* `manifestScriptsTouched` — bool, whether the diff changes the `scripts` block of any
|
|
428
|
+
* `package.json` (condition 5, #297 — tools/lib/cure-diff.js). `null`/`undefined` = unmeasured,
|
|
429
|
+
* which refuses: a caller that did not measure it has not shown the instrument is intact.
|
|
430
|
+
* `manifestPaths` — the manifests whose scripts changed, named in the refusal.
|
|
431
|
+
*
|
|
432
|
+
* `pythonManifestTouched` — bool, whether the diff changes a Python dependency manifest the Python
|
|
433
|
+
* template installs from (condition 6, #377). `null`/`undefined` = unmeasured, which refuses.
|
|
434
|
+
* `pythonManifestPaths` — those files, named in the refusal.
|
|
435
|
+
*
|
|
436
|
+
* `jobEvidence` — `shapeJobEvidence(...)`'s output, or `null`. Read on EVERY cure since #297 —
|
|
437
|
+
* condition 2b (`redJobsProvenOnBranch`) — and again by the #321 carve-out when workflows were
|
|
438
|
+
* touched. `null`, an empty `redJobs`, an empty `branchJobs`, an unreadable step list and an
|
|
439
|
+
* unusable duration ALL refuse — evidence widens a door, the absence of it never does. The caller
|
|
440
|
+
* measures it only once containment and 2a have passed, so an ordinary green-trunk ship still pays
|
|
441
|
+
* no job-level `gh` calls.
|
|
442
|
+
*
|
|
443
|
+
* Order of checks: cheapest/most-fundamental first, each with a distinct actionable reason —
|
|
444
|
+
* identical posture to ci-grant.js's evaluateIssue: containment → 2a (run green) → 2b (the red jobs
|
|
445
|
+
* pass here) → anti-stacking → diff measurable → condition 5 (manifest scripts) → condition 6 (Python
|
|
446
|
+
* manifests) → condition 4 with its carve-out. Conditions 5 and 6 sit BEFORE the workflow block, not after it: that block RETURNS
|
|
447
|
+
* `ok: true` when the carve-out admits, so a check placed after it would never be reached by a
|
|
448
|
+
* branch touching both — exactly the "two instrument paths, two doors" composition #321 asked for.
|
|
449
|
+
*
|
|
450
|
+
* Returns `{ok, reason}`; on success also `provenJobs` (the red job names 2b proved, additive,
|
|
451
|
+
* #297) and — ONLY on a cure that went through the carve-out — `carveOut: {jobs}`. The ordinary
|
|
452
|
+
* cure's reason text is unchanged, which is what lets the caller answer "which door was this?" by
|
|
453
|
+
* the presence of `carveOut` rather than by re-deriving it.
|
|
454
|
+
*/
|
|
455
|
+
function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouched, jobEvidence,
|
|
456
|
+
manifestScriptsTouched, manifestPaths, pythonManifestTouched, pythonManifestPaths }) {
|
|
457
|
+
if (!containsRedSha) {
|
|
458
|
+
return { ok: false,
|
|
459
|
+
reason: `branch does not contain trunk's current red head \`${redSha}\` as an ancestor — ` +
|
|
460
|
+
'it cannot prove it cures this red without rebasing onto trunk first (this pays a fresh CI round, by design). ' +
|
|
461
|
+
'Only if this branch IS the patch: a bystander does not rebase onto the red, it waits for green trunk (#353)' };
|
|
462
|
+
}
|
|
463
|
+
if (!evidence) {
|
|
464
|
+
return { ok: false,
|
|
465
|
+
reason: 'branch\'s own CI run could not be measured (a failed read) — a failed evidence read is never a cure' };
|
|
466
|
+
}
|
|
467
|
+
if (!evidence.ok) {
|
|
468
|
+
return { ok: false,
|
|
469
|
+
reason: 'branch has no completed, successful CI run at its own current head — the cure rule requires ' +
|
|
470
|
+
'MEASURED evidence, never asserted, same bar a human ci-grant holds. Where the repo\'s workflows fire only on ' +
|
|
471
|
+
'trunk push / pull_request, a PR is the only way to get that run — open one ONLY for the branch carrying the fix; ' +
|
|
472
|
+
'a bystander\'s PR runs against a merge ref that includes the red trunk, so it waits for green instead (#353)' };
|
|
473
|
+
}
|
|
474
|
+
const proven = redJobsProvenOnBranch(jobEvidence);
|
|
475
|
+
if (!proven.ok) {
|
|
476
|
+
return { ok: false,
|
|
477
|
+
reason: `branch's run is green, but the check trunk is red on is not proven here: ${proven.reason} — ` +
|
|
478
|
+
'a cure must pass the named failing job(s), not merely produce a green run (#297)' };
|
|
479
|
+
}
|
|
480
|
+
if (!stacking || !stacking.ok) {
|
|
481
|
+
return { ok: false, reason: (stacking && stacking.reason) || 'anti-stacking verdict unavailable' };
|
|
482
|
+
}
|
|
483
|
+
if (typeof workflowsTouched !== 'boolean' || typeof manifestScriptsTouched !== 'boolean'
|
|
484
|
+
|| typeof pythonManifestTouched !== 'boolean') {
|
|
485
|
+
return { ok: false,
|
|
486
|
+
reason: 'branch diff could not be measured (which CI files and manifests it touches) — an unmeasured diff is never a cure' };
|
|
487
|
+
}
|
|
488
|
+
if (manifestScriptsTouched) {
|
|
489
|
+
const named = Array.isArray(manifestPaths) && manifestPaths.length ? manifestPaths.join(', ') : 'package.json';
|
|
490
|
+
return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named})` };
|
|
491
|
+
}
|
|
492
|
+
if (pythonManifestTouched) {
|
|
493
|
+
const named = Array.isArray(pythonManifestPaths) && pythonManifestPaths.length
|
|
494
|
+
? pythonManifestPaths.join(', ') : 'a Python dependency manifest';
|
|
495
|
+
return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named})` };
|
|
496
|
+
}
|
|
497
|
+
if (workflowsTouched) {
|
|
498
|
+
const carve = workflowCarveOut(jobEvidence);
|
|
499
|
+
if (!carve.ok) {
|
|
500
|
+
return { ok: false, reason: `${WORKFLOW_REFUSAL}. The #321 carve-out does not admit it either: ${carve.reason}` };
|
|
501
|
+
}
|
|
502
|
+
const detail = carve.jobs.map((j) => `\`${j.name}\` (${j.redMs}ms red on trunk, ${j.branchMs}ms passing here)`).join(', ');
|
|
503
|
+
return { ok: true, provenJobs: proven.jobs, carveOut: { jobs: carve.jobs },
|
|
504
|
+
reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure, ` +
|
|
505
|
+
`admitted through the #321 workflow carve-out: every job red on trunk ran to success here with every step it took on trunk — ${detail}` };
|
|
506
|
+
}
|
|
507
|
+
return { ok: true, provenJobs: proven.jobs,
|
|
508
|
+
reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure` };
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, shapeJobEvidence, WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL,
|
|
512
|
+
PYTHON_MANIFEST_REFUSAL };
|