@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.1
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/README.md +243 -213
- package/README.vi.md +246 -186
- package/audit/audit.mjs +193 -10
- package/package.json +6 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1691 -254
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +203 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +4 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +151 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +716 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +762 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +303 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +106 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- package/tools/lib/workflow-triggers.js +48 -0
package/tools/lib/ci-cure.js
CHANGED
|
@@ -34,6 +34,13 @@
|
|
|
34
34
|
* trailer scan that feeds this (tools/colab's computeAntiStacking) to recognise BOTH a
|
|
35
35
|
* prior `CI-Grant:` trailer and a prior `CI-Cure:` trailer as "an exemption already merged
|
|
36
36
|
* against this red" — a cure and a grant are both exemptions for this guard's purposes.
|
|
37
|
+
* ONE NARROW ADMISSION (#477): PROGRESS. When the guard refuses because a prior exemption
|
|
38
|
+
* already merged on this continuous red, a further cure is still admitted iff trunk's red-job
|
|
39
|
+
* set at the current red sha is a STRICT subset of the red-job set at the red sha the prior
|
|
40
|
+
* exemption was measured against (`redSetShrank`, below). A fix that repaired one of two red
|
|
41
|
+
* jobs, or two independent failures healed by two successive fixes, then needs no human step;
|
|
42
|
+
* a cure that left the set unchanged — or grew it — still stops the chain, which is the loop
|
|
43
|
+
* condition 3 exists to break. Every other condition still applies to the remaining set.
|
|
37
44
|
* 4. NO WORKFLOW-FILE CHANGES — the branch diff must not touch `.github/workflows/**`. A
|
|
38
45
|
* branch that edits the CI configuration doing the grading is not allowed to grade itself;
|
|
39
46
|
* that door stays behind a human ci-grant (condition 4 in the original proposal, #281).
|
|
@@ -44,12 +51,29 @@
|
|
|
44
51
|
* and test run at all, and a skipped step leaves the job `success` — so deleting
|
|
45
52
|
* `scripts.test` weakens the instrument without touching a workflow file. No carve-out: see
|
|
46
53
|
* below for why the #321 door cannot adjudicate it.
|
|
54
|
+
* ONE NARROW ADMISSION (#475): an ADD-ONLY scripts change — keys added, none removed or changed,
|
|
55
|
+
* no lifecycle hook — makes the template run MORE, so it passes condition 5 on step evidence
|
|
56
|
+
* (`manifestStepProof`, below) instead of refusing.
|
|
47
57
|
* 6. NO PYTHON DEPENDENCY-MANIFEST CHANGES (#377) — the branch diff must not change a file the
|
|
48
58
|
* Python CI template installs from (`pyproject.toml`/`setup.py`/`setup.cfg`, `requirements*`
|
|
49
59
|
* files and what they include — tools/lib/cure-diff.js names the set). That template runs
|
|
50
60
|
* ruff/mypy/pytest only when the tool is importable after install, so removing `pytest` from
|
|
51
61
|
* `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.
|
|
62
|
+
* sibling door with no carve-out, for the same reason. ONE NARROW ADMISSION (#476): a PIN-ONLY
|
|
63
|
+
* change — only the version specifier of requirements present on both sides — passes on step
|
|
64
|
+
* evidence plus the no-late-skip test (`manifestStepProof`, below).
|
|
65
|
+
*
|
|
66
|
+
* THE STEP PROOF BEHIND BOTH ADMISSIONS (#475, #476). Every step that RAN in each red job on trunk —
|
|
67
|
+
* the failing one included — ran on the branch and concluded `success`: the 4b read, applied here
|
|
68
|
+
* without the carve-out's duration floor (no workflow changed, so no `run:` body can have been
|
|
69
|
+
* gutted). Check-runs name steps, not commands, so "the step that runs the added script" is not
|
|
70
|
+
* measurable as such; "the step trunk failed in now passes" is, and it is the claim a cure makes.
|
|
71
|
+
* The pin admission adds one test (#476's open question, answered): a pin can drop a TRANSITIVELY
|
|
72
|
+
* installed tool, and the Python template then skips that tool's step with the job still `success`.
|
|
73
|
+
* Steps before trunk's failure point are covered by the superset; steps AFTER it were skipped on
|
|
74
|
+
* trunk and so say nothing. So no step after the last one that ran on trunk may be `skipped` on the
|
|
75
|
+
* branch. That refuses a repo that never had, say, mypy when its red came before the Typecheck step
|
|
76
|
+
* — a false refusal, falling through to the ci-grant, the safe direction.
|
|
53
77
|
*
|
|
54
78
|
* THE WORKFLOW CARVE-OUT (#321) — why condition 4 could not simply stay absolute. The repair for
|
|
55
79
|
* a CI-INFRASTRUCTURE outage is, by construction, a workflow change: when trunk goes red because
|
|
@@ -126,6 +150,60 @@
|
|
|
126
150
|
* is the obvious first follow-up the moment that refusal is observed in the field, but adding it
|
|
127
151
|
* unmeasured is precisely the speculative loosening condition 4 exists to resist.
|
|
128
152
|
*
|
|
153
|
+
* DRY-RUN EVIDENCE FOR A MAIN-ONLY WORKFLOW (#474). Some checks never run on a branch at all:
|
|
154
|
+
* `release-auto.yml` fires on `workflow_run` after trunk CI, or on a schedule. 2b then refuses every
|
|
155
|
+
* fix for a red in it (the job is absent on the branch), and a human ci-grant was the only door,
|
|
156
|
+
* even for a mechanical defect. The workflow template therefore offers a DRY RUN: dispatched on the
|
|
157
|
+
* fix branch, it runs the same job and the same steps, but with every external write turned off. Steps
|
|
158
|
+
* that would publish are skipped, and their names end in `PUBLISH_STEP_MARKER`. A sentinel step named
|
|
159
|
+
* `DRY_RUN_STEP` runs only in that mode, and is how a job instance is recognised as a dry run here.
|
|
160
|
+
* Such an instance counts as the job's evidence for 2b (and hence 4a) only when, on top of 2b:
|
|
161
|
+
*
|
|
162
|
+
* D1. both step lists are measurable — trunk's ran-steps and the dry run's steps;
|
|
163
|
+
* D2. every step that RAN on trunk, the failing one included, concluded `success` in the dry run.
|
|
164
|
+
* This is the not-a-back-door proof: a red INSIDE a publishing step can never be cured this way,
|
|
165
|
+
* because the dry run skips exactly that step. It is 4b, applied to dry-run instances on every
|
|
166
|
+
* path, not only the carve-out's;
|
|
167
|
+
* D3. every step the dry run did NOT run to success is a skipped publishing step. A dry run that
|
|
168
|
+
* also skipped some ordinary step past trunk's failure point has not run the job, it has run
|
|
169
|
+
* part of it.
|
|
170
|
+
*
|
|
171
|
+
* Why a NAME marker and not a list declared in the workflow: steps are matched by exact name (D2/4b),
|
|
172
|
+
* so marking the very step that failed on trunk renames it, and D2 then reads it as absent and
|
|
173
|
+
* refuses. A list inside the workflow would be read from the branch, which is the party being graded.
|
|
174
|
+
*
|
|
175
|
+
* Limit, stated: a red in a publishing step, or in a later job that only runs after a tag (npm,
|
|
176
|
+
* deploy), cannot be cured by a dry run. That stays a ci-grant. So does a red job that ran ZERO steps
|
|
177
|
+
* (a runner that never picked it up) on the carve-out path: 4c has no usable duration for it and
|
|
178
|
+
* refuses, which is the safe direction and a deliberately unmade loosening, like the timeout case.
|
|
179
|
+
*
|
|
180
|
+
* DISPATCH EVIDENCE FOR A JOB A BRANCH PUSH SKIPS (#510). One level below #474: the WORKFLOW runs on a
|
|
181
|
+
* branch push, but one of its JOBS is trunk-only by its own `if:` (true on trunk, on a schedule and on
|
|
182
|
+
* `workflow_dispatch`, false on a branch push) — an E2E suite moved off the branch path to keep branch CI
|
|
183
|
+
* short. A branch push then shows that job skipped (or, for an unexpanded matrix, absent), 2b refuses,
|
|
184
|
+
* and a human ci-grant was the only door. The same workflow dispatched on the branch runs the job. A
|
|
185
|
+
* DISPATCH INSTANCE — a job row from a run with `event: workflow_dispatch` that is not a #474 dry run —
|
|
186
|
+
* counts as the job's evidence only when, on top of 2b's own tests (completed `success`; no instance at
|
|
187
|
+
* the head red or pending — so `skipped`, `neutral`, `cancelled` or absent never counts, and a job that
|
|
188
|
+
* ran and FAILED on the push run is never rescued by a green dispatch):
|
|
189
|
+
*
|
|
190
|
+
* W1. SAME WORKFLOW — the dispatch run's workflow id equals the red run's. Ids are per file and the same
|
|
191
|
+
* on every ref; the display name is not, two files can share a `name:`. Either id missing refuses.
|
|
192
|
+
* W2. SAME HEAD — the dispatch run's head sha is the branch evidence sha. Rows at any other sha are
|
|
193
|
+
* dropped by `shapeJobEvidence`; the check is repeated here so it holds without the caller.
|
|
194
|
+
* W5. THE FAILING STEP RAN — every step that went red on trunk is present by exact name in the dispatch
|
|
195
|
+
* instance and concluded `success`. GitHub reports a job whose steps were all skipped as `success`,
|
|
196
|
+
* so job-level success alone cannot see a step whose own `if:` depends on the event. Deliberately
|
|
197
|
+
* NOT the full executed-step superset (4b/D2): a cache-conditional step that ran on trunk is skipped
|
|
198
|
+
* on a cache hit, which would refuse genuine cures. A trunk red with no red STEP (a timeout, a lost
|
|
199
|
+
* runner) leaves W5 nothing to check, and job-level success decides — a stated limit.
|
|
200
|
+
* W6. PER JOB, BY EXACT NAME — the existing `jobKey`; matrix shards match by expanded name, one green
|
|
201
|
+
* shard never covers another, and nothing is matched by prefix.
|
|
202
|
+
*
|
|
203
|
+
* W1 and W2 apply to a #474 dry-run instance too when its row says `workflow_dispatch` — the same
|
|
204
|
+
* same-name hole. A green ordinary instance outranks a green dispatch instance, which outranks a green
|
|
205
|
+
* dry run: each rule set applies only when that instance is the job's sole evidence.
|
|
206
|
+
*
|
|
129
207
|
* PURE BY CONSTRUCTION, identical posture to ci-grant.js / migration-grant.js / readiness.js /
|
|
130
208
|
* shipguard.js: signals in, verdict out. No git, no network, no `gh`. The caller (tools/colab)
|
|
131
209
|
* measures containment, evidence, anti-stacking and the workflow-file diff, and hands them in.
|
|
@@ -177,6 +255,25 @@ const PYTHON_MANIFEST_REFUSAL =
|
|
|
177
255
|
* never ran is not a job that failed. */
|
|
178
256
|
const NOT_RED_CONCLUSIONS = new Set(['success', 'cancelled', 'skipped']);
|
|
179
257
|
|
|
258
|
+
/** The suffix a step name carries when the dry run skips it because it writes outside the run (#474).
|
|
259
|
+
* The template names its publishing steps with it; D3 admits no other skipped step. */
|
|
260
|
+
const PUBLISH_STEP_MARKER = '[publish]';
|
|
261
|
+
|
|
262
|
+
/** The sentinel step a dry-run job instance runs and an ordinary one skips (#474). Its successful
|
|
263
|
+
* presence is the only thing that marks an instance as a dry run here. Must match the template's
|
|
264
|
+
* step name byte for byte. */
|
|
265
|
+
const DRY_RUN_STEP = 'Dry run — nothing is tagged, released or published';
|
|
266
|
+
|
|
267
|
+
function isPublishStepName(name) {
|
|
268
|
+
return typeof name === 'string' && name.trimEnd().endsWith(PUBLISH_STEP_MARKER);
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/** A job instance is a dry run iff its sentinel step concluded `success`. A skipped sentinel is an
|
|
272
|
+
* ordinary run (the template's `if:` was false), never a dry one. */
|
|
273
|
+
function isDryRunSteps(steps) {
|
|
274
|
+
return Array.isArray(steps) && steps.some((s) => s && s.name === DRY_RUN_STEP && s.conclusion === 'success');
|
|
275
|
+
}
|
|
276
|
+
|
|
180
277
|
/** A step "ran" on trunk iff it reached a terminal conclusion that is not `skipped`/`cancelled`.
|
|
181
278
|
* Steps after the failing one are skipped by GitHub, and a skipped step constrains nothing. */
|
|
182
279
|
function stepRan(s) {
|
|
@@ -224,7 +321,7 @@ function usableMs(v) {
|
|
|
224
321
|
* half-finished red run cannot be adjudicated: a job still in flight may yet become the red one
|
|
225
322
|
* the branch would have to prove it repaired.
|
|
226
323
|
*/
|
|
227
|
-
function shapeJobEvidence({ redRunJobs, branchRunJobs } = {}) {
|
|
324
|
+
function shapeJobEvidence({ redRunJobs, branchRunJobs, branchSha } = {}) {
|
|
228
325
|
if (!Array.isArray(redRunJobs) || !Array.isArray(branchRunJobs)) return null;
|
|
229
326
|
if (redRunJobs.some((j) => !j || j.status !== 'completed')) return null;
|
|
230
327
|
|
|
@@ -233,21 +330,41 @@ function shapeJobEvidence({ redRunJobs, branchRunJobs } = {}) {
|
|
|
233
330
|
.map((j) => ({
|
|
234
331
|
name: j.name,
|
|
235
332
|
workflowName: j.workflowName || '',
|
|
333
|
+
workflowId: idOrNull(j.workflowId),
|
|
236
334
|
conclusion: j.conclusion,
|
|
237
335
|
durationMs: durationMs(j.startedAt, j.completedAt),
|
|
238
336
|
ranSteps: Array.isArray(j.steps) ? j.steps.filter(stepRan).map((s) => s.name) : null,
|
|
337
|
+
// #510 W5: the steps that went red on trunk — the ones a dispatch instance must show passing.
|
|
338
|
+
failedSteps: Array.isArray(j.steps) ? j.steps.filter((s) => stepRan(s) && s.conclusion !== 'success').map((s) => s.name) : null,
|
|
239
339
|
}));
|
|
240
340
|
|
|
241
|
-
const branchJobs = branchRunJobs
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
341
|
+
const branchJobs = branchRunJobs
|
|
342
|
+
// #510 W2: a row at another sha is never evidence for this head — dropped when both shas are known.
|
|
343
|
+
.filter((j) => !(branchSha && j && j.headSha && j.headSha !== branchSha))
|
|
344
|
+
.map((j) => {
|
|
345
|
+
const dryRun = !!j && isDryRunSteps(j.steps);
|
|
346
|
+
const event = (j && j.event) || null;
|
|
347
|
+
return {
|
|
348
|
+
name: j && j.name,
|
|
349
|
+
workflowName: (j && j.workflowName) || '',
|
|
350
|
+
workflowId: j ? idOrNull(j.workflowId) : null,
|
|
351
|
+
event,
|
|
352
|
+
headSha: (j && j.headSha) || null,
|
|
353
|
+
status: j && j.status,
|
|
354
|
+
conclusion: j && j.conclusion,
|
|
355
|
+
durationMs: j ? durationMs(j.startedAt, j.completedAt) : null,
|
|
356
|
+
steps: j && Array.isArray(j.steps) ? j.steps.map((s) => ({ name: s && s.name, conclusion: s && s.conclusion })) : null,
|
|
357
|
+
dryRun,
|
|
358
|
+
dispatch: event === 'workflow_dispatch' && !dryRun,
|
|
359
|
+
};
|
|
360
|
+
});
|
|
249
361
|
|
|
250
|
-
return { redJobs, branchJobs };
|
|
362
|
+
return { redJobs, branchJobs, branchSha: branchSha || null };
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
/** A workflow id as carried on a run row (#510 W1), or null — never `0`/`''` read as an id. */
|
|
366
|
+
function idOrNull(v) {
|
|
367
|
+
return (typeof v === 'number' && Number.isFinite(v) && v > 0) || (typeof v === 'string' && v !== '') ? v : null;
|
|
251
368
|
}
|
|
252
369
|
|
|
253
370
|
/** How a job is named in a reason string: `workflow / job` when the workflow is known. */
|
|
@@ -272,20 +389,107 @@ function jobKey(j) {
|
|
|
272
389
|
*/
|
|
273
390
|
function indexBranchJobs(branchJobs) {
|
|
274
391
|
const idx = new Map();
|
|
392
|
+
// A green ORDINARY instance outranks a green dispatch instance (#510), which outranks a green dry run
|
|
393
|
+
// (#474): each rule set applies only when that instance is the sole evidence the branch has for the job.
|
|
394
|
+
const rank = (x) => (x.status !== 'completed' || x.conclusion !== 'success' ? 0 : x.dryRun ? 1 : x.dispatch ? 2 : 3);
|
|
275
395
|
for (const j of branchJobs) {
|
|
276
396
|
if (!j || !j.name) continue;
|
|
277
397
|
const k = jobKey(j);
|
|
278
398
|
const prev = idx.get(k);
|
|
279
399
|
const isRed = j.status === 'completed' && !NOT_RED_CONCLUSIONS.has(j.conclusion);
|
|
280
400
|
const isPending = j.status !== 'completed';
|
|
281
|
-
|
|
282
|
-
const
|
|
283
|
-
|
|
284
|
-
|
|
401
|
+
// #510: every instance completed `skipped` — the shape a trunk-only job leaves on a branch push.
|
|
402
|
+
const isSkipped = j.status === 'completed' && j.conclusion === 'skipped';
|
|
403
|
+
if (!prev) { idx.set(k, { job: j, hasRed: isRed, hasPending: isPending, allSkipped: isSkipped }); continue; }
|
|
404
|
+
const better = rank(j) > rank(prev.job);
|
|
405
|
+
idx.set(k, { job: better ? j : prev.job, hasRed: prev.hasRed || isRed, hasPending: prev.hasPending || isPending,
|
|
406
|
+
allSkipped: prev.allSkipped && isSkipped });
|
|
285
407
|
}
|
|
286
408
|
return idx;
|
|
287
409
|
}
|
|
288
410
|
|
|
411
|
+
/**
|
|
412
|
+
* The dry-run rules (#474), D1–D3 — see the module header. `red` is a trunk red job (with
|
|
413
|
+
* `ranSteps`), `mine` the branch's dry-run instance of the same job (with `steps`). Returns a refusal
|
|
414
|
+
* reason, or '' when the dry run is admissible evidence for this job.
|
|
415
|
+
*/
|
|
416
|
+
function dryRunEvidence(red, mine) {
|
|
417
|
+
const label = jobLabel(red);
|
|
418
|
+
if (!Array.isArray(red.ranSteps) || !Array.isArray(mine.steps)) {
|
|
419
|
+
return `job \`${label}\` is proven only by a dry run, and its step lists could not be read — a dry run is admissible only step by step`;
|
|
420
|
+
}
|
|
421
|
+
const mySteps = new Map();
|
|
422
|
+
for (const s of mine.steps) if (s && s.name) mySteps.set(s.name, s);
|
|
423
|
+
for (const stepName of red.ranSteps) {
|
|
424
|
+
const s = mySteps.get(stepName);
|
|
425
|
+
if (!s) {
|
|
426
|
+
return `step \`${stepName}\` RAN in job \`${label}\` on trunk and is absent from the branch's dry run — a dry run proves only the steps it executes`;
|
|
427
|
+
}
|
|
428
|
+
if (s.conclusion !== 'success') {
|
|
429
|
+
return `step \`${stepName}\` RAN in job \`${label}\` on trunk and concluded \`${s.conclusion}\` in the branch's dry run — ` +
|
|
430
|
+
'a dry run cannot cure a red in a step it does not execute (a red in a publishing step stays a ci-grant)';
|
|
431
|
+
}
|
|
432
|
+
}
|
|
433
|
+
for (const s of mine.steps) {
|
|
434
|
+
if (!s || s.conclusion === 'success') continue;
|
|
435
|
+
if (s.conclusion === 'skipped' && isPublishStepName(s.name)) continue;
|
|
436
|
+
return `step \`${s && s.name}\` concluded \`${s && s.conclusion}\` in the branch's dry run of job \`${label}\` and is not a publishing step ` +
|
|
437
|
+
`(name ending \`${PUBLISH_STEP_MARKER}\`) — a dry run may skip only the steps that write outside the run`;
|
|
438
|
+
}
|
|
439
|
+
return '';
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
/**
|
|
443
|
+
* W1/W2 (#510) for any instance whose run was a `workflow_dispatch` — a #510 dispatch instance or a
|
|
444
|
+
* #474 dry run. Returns a refusal reason, or ''.
|
|
445
|
+
*/
|
|
446
|
+
function dispatchRunIdentity(red, mine, branchSha) {
|
|
447
|
+
const label = jobLabel(red);
|
|
448
|
+
if (red.workflowId === null || red.workflowId === undefined || mine.workflowId === null || mine.workflowId === undefined) {
|
|
449
|
+
return `job \`${label}\` is proven only by a workflow_dispatch run, and the workflow id of the red run or of that run could not be read — ` +
|
|
450
|
+
'a dispatch run counts only as the SAME workflow file, and a display name is not proof of that';
|
|
451
|
+
}
|
|
452
|
+
if (String(red.workflowId) !== String(mine.workflowId)) {
|
|
453
|
+
return `job \`${label}\` is proven only by a workflow_dispatch run of a DIFFERENT workflow (id ${mine.workflowId}, trunk's red run is ${red.workflowId}) — ` +
|
|
454
|
+
'a workflow that shares the display name is not the workflow that is red';
|
|
455
|
+
}
|
|
456
|
+
if (!branchSha || !mine.headSha || mine.headSha !== branchSha) {
|
|
457
|
+
return `job \`${label}\` is proven only by a workflow_dispatch run that is not at the branch's evidence head (\`${mine.headSha || '?'}\`) — ` +
|
|
458
|
+
'evidence counts only at the head being shipped';
|
|
459
|
+
}
|
|
460
|
+
return '';
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
/**
|
|
464
|
+
* The dispatch rules (#510) — W1, W2 and W5; see the module header. `red` is a trunk red job (with
|
|
465
|
+
* `workflowId` and `failedSteps`), `mine` the branch's dispatch instance of the same job. Returns a
|
|
466
|
+
* refusal reason, or '' when the dispatch run is admissible evidence for this job. W4 (job success, no
|
|
467
|
+
* red or pending sibling) and W6 (the per-job key) are applied by `redJobsProvenOnBranch` before this.
|
|
468
|
+
*/
|
|
469
|
+
function dispatchEvidence(red, mine, branchSha) {
|
|
470
|
+
const id = dispatchRunIdentity(red, mine, branchSha);
|
|
471
|
+
if (id) return id;
|
|
472
|
+
const label = jobLabel(red);
|
|
473
|
+
if (!Array.isArray(red.failedSteps) || !Array.isArray(mine.steps)) {
|
|
474
|
+
return `job \`${label}\` is proven only by a workflow_dispatch run, and the step lists could not be read — ` +
|
|
475
|
+
'a dispatch run proves a cure only if the step that failed on trunk ran and passed in it';
|
|
476
|
+
}
|
|
477
|
+
const mySteps = new Map();
|
|
478
|
+
for (const s of mine.steps) if (s && s.name) mySteps.set(s.name, s);
|
|
479
|
+
for (const stepName of red.failedSteps) {
|
|
480
|
+
const s = mySteps.get(stepName);
|
|
481
|
+
if (!s) {
|
|
482
|
+
return `step \`${stepName}\` failed in job \`${label}\` on trunk and is absent from the branch's workflow_dispatch run — ` +
|
|
483
|
+
'a dispatch run proves only the steps it executes';
|
|
484
|
+
}
|
|
485
|
+
if (s.conclusion !== 'success') {
|
|
486
|
+
return `step \`${stepName}\` failed in job \`${label}\` on trunk and concluded \`${s.conclusion}\` in the branch's workflow_dispatch run — ` +
|
|
487
|
+
'a job that reports success with that step skipped has not run it';
|
|
488
|
+
}
|
|
489
|
+
}
|
|
490
|
+
return '';
|
|
491
|
+
}
|
|
492
|
+
|
|
289
493
|
/**
|
|
290
494
|
* Sub-test 4a (#321), and — since #297 — condition 2b of EVERY cure: every job RED on trunk exists
|
|
291
495
|
* on the branch's runs at its own head, completed and successful.
|
|
@@ -299,7 +503,9 @@ function indexBranchJobs(branchJobs) {
|
|
|
299
503
|
* that exists only on the branch: this certifies that the branch cures trunk's red, not that the
|
|
300
504
|
* branch is spotless.
|
|
301
505
|
*
|
|
302
|
-
* Returns `{ok, reason, jobs}` — `jobs` is the list of red job names proven on
|
|
506
|
+
* Returns `{ok, reason, jobs, dryRunJobs, dispatchJobs}` — `jobs` is the list of red job names proven on
|
|
507
|
+
* the branch, `dryRunJobs` the subset proven only by a dry run (#474), each having passed D1–D3, and
|
|
508
|
+
* `dispatchJobs` the subset proven only by a workflow_dispatch run (#510), each having passed W1–W6.
|
|
303
509
|
* Every unmeasurable input is a refusal, never a pass.
|
|
304
510
|
*/
|
|
305
511
|
function redJobsProvenOnBranch(jobEvidence) {
|
|
@@ -317,6 +523,8 @@ function redJobsProvenOnBranch(jobEvidence) {
|
|
|
317
523
|
return { ok: false, jobs: [], reason: "the branch's own run reported no jobs to compare against" };
|
|
318
524
|
}
|
|
319
525
|
const idx = indexBranchJobs(branchJobs);
|
|
526
|
+
const dryRunJobs = [];
|
|
527
|
+
const dispatchJobs = [];
|
|
320
528
|
|
|
321
529
|
for (const red of redJobs) {
|
|
322
530
|
if (!red || !red.name) {
|
|
@@ -341,8 +549,19 @@ function redJobsProvenOnBranch(jobEvidence) {
|
|
|
341
549
|
return { ok: false, jobs: [],
|
|
342
550
|
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
551
|
}
|
|
552
|
+
if (mine.dryRun) {
|
|
553
|
+
const why = (mine.event === 'workflow_dispatch' ? dispatchRunIdentity(red, mine, jobEvidence.branchSha) : '')
|
|
554
|
+
|| dryRunEvidence(red, mine);
|
|
555
|
+
if (why) return { ok: false, jobs: [], reason: why };
|
|
556
|
+
dryRunJobs.push(red.name);
|
|
557
|
+
} else if (mine.dispatch) {
|
|
558
|
+
const why = dispatchEvidence(red, mine, jobEvidence.branchSha);
|
|
559
|
+
if (why) return { ok: false, jobs: [], reason: why };
|
|
560
|
+
dispatchJobs.push(red.name);
|
|
561
|
+
}
|
|
344
562
|
}
|
|
345
|
-
return { ok: true, jobs: redJobs.map((r) => r.name),
|
|
563
|
+
return { ok: true, jobs: redJobs.map((r) => r.name), ...(dryRunJobs.length ? { dryRunJobs } : {}),
|
|
564
|
+
...(dispatchJobs.length ? { dispatchJobs } : {}), reason: '' };
|
|
346
565
|
}
|
|
347
566
|
|
|
348
567
|
/**
|
|
@@ -402,6 +621,199 @@ function workflowCarveOut(jobEvidence) {
|
|
|
402
621
|
return { ok: true, jobs, reason: '' };
|
|
403
622
|
}
|
|
404
623
|
|
|
624
|
+
/**
|
|
625
|
+
* The step proof behind the #475/#476 manifest admissions — 4b without 4c, plus (for a pin) the
|
|
626
|
+
* no-late-skip test. See the module header. Returns `{ok, reason}`; every unmeasurable input refuses.
|
|
627
|
+
* Called only after `redJobsProvenOnBranch` passed, so every red job has a successful branch instance.
|
|
628
|
+
*/
|
|
629
|
+
function manifestStepProof(jobEvidence, { noLateSkip = false } = {}) {
|
|
630
|
+
if (!jobEvidence || !Array.isArray(jobEvidence.redJobs) || !Array.isArray(jobEvidence.branchJobs)) {
|
|
631
|
+
return { ok: false, reason: 'the job-level evidence could not be measured' };
|
|
632
|
+
}
|
|
633
|
+
const idx = indexBranchJobs(jobEvidence.branchJobs);
|
|
634
|
+
for (const red of jobEvidence.redJobs) {
|
|
635
|
+
// A dry-run instance (#474) is the job's branch evidence like any other — redJobsProvenOnBranch
|
|
636
|
+
// already held it to D1–D3, which imply the superset below. See the late-skip note.
|
|
637
|
+
const entry = idx.get(jobKey(red));
|
|
638
|
+
if (!entry) return { ok: false, reason: `job \`${jobLabel(red)}\` is absent on the branch` };
|
|
639
|
+
const mine = entry.job;
|
|
640
|
+
if (!Array.isArray(red.ranSteps) || !red.ranSteps.length) {
|
|
641
|
+
return { ok: false, reason: `the steps that ran in job \`${jobLabel(red)}\` on trunk could not be read` };
|
|
642
|
+
}
|
|
643
|
+
if (!Array.isArray(mine.steps)) {
|
|
644
|
+
return { ok: false, reason: `the steps of job \`${jobLabel(red)}\` on the branch could not be read` };
|
|
645
|
+
}
|
|
646
|
+
let last = -1;
|
|
647
|
+
for (const stepName of red.ranSteps) {
|
|
648
|
+
const at = mine.steps.findIndex((s) => s && s.name === stepName);
|
|
649
|
+
if (at === -1) {
|
|
650
|
+
return { ok: false, reason: `step \`${stepName}\` ran in job \`${jobLabel(red)}\` on trunk and is absent on the branch` };
|
|
651
|
+
}
|
|
652
|
+
if (mine.steps[at].conclusion !== 'success') {
|
|
653
|
+
return { ok: false,
|
|
654
|
+
reason: `step \`${stepName}\` ran in job \`${jobLabel(red)}\` on trunk and concluded \`${mine.steps[at].conclusion}\` on the branch` };
|
|
655
|
+
}
|
|
656
|
+
if (at > last) last = at;
|
|
657
|
+
}
|
|
658
|
+
if (noLateSkip) {
|
|
659
|
+
// A dry run (#474) skips its `[publish]` steps by design, and D3 already refused any OTHER skip
|
|
660
|
+
// in it — so those, and only those, are not a dropped tool.
|
|
661
|
+
const late = mine.steps.slice(last + 1)
|
|
662
|
+
.find((s) => s && s.conclusion === 'skipped' && !(mine.dryRun && isPublishStepName(s.name)));
|
|
663
|
+
if (late) {
|
|
664
|
+
return { ok: false,
|
|
665
|
+
reason: `step \`${late.name}\` in job \`${jobLabel(red)}\` comes after trunk's failure point and was skipped on the branch — ` +
|
|
666
|
+
'trunk never reached it, so whether the pin dropped the tool it needs is unmeasurable' };
|
|
667
|
+
}
|
|
668
|
+
}
|
|
669
|
+
}
|
|
670
|
+
return { ok: true, reason: '' };
|
|
671
|
+
}
|
|
672
|
+
|
|
673
|
+
/**
|
|
674
|
+
* Would a dry run on the branch supply the evidence 2b is missing (#474)? PURE. Returns the sorted
|
|
675
|
+
* workflow names to dispatch, or `[]`. Non-empty only when EVERY red job is either already passing
|
|
676
|
+
* on the branch (completed `success`, nothing red or pending beside it) or ABSENT from the branch's
|
|
677
|
+
* runs in a workflow listed in `dryRunCapable` — and at least one is absent. A red job that is
|
|
678
|
+
* present-but-failing, pending, or absent in a workflow without a dry-run mode means no dispatch
|
|
679
|
+
* would help, so none is asked for. Whether the dry run, once it exists, passes D1–D3 is decided
|
|
680
|
+
* then, not predicted now.
|
|
681
|
+
*/
|
|
682
|
+
function dryRunDispatchPlan(jobEvidence, dryRunCapable) {
|
|
683
|
+
return cureDispatchPlan(jobEvidence, { dryRunCapable }).dryRun;
|
|
684
|
+
}
|
|
685
|
+
|
|
686
|
+
/**
|
|
687
|
+
* Which dispatch(es) would supply the evidence 2b is missing — a #474 dry run, or a #510 plain
|
|
688
|
+
* `workflow_dispatch` of a branch workflow whose red job a branch push skips. PURE. Returns
|
|
689
|
+
* `{dryRun: [workflow names], dispatch: [workflow names]}`, both sorted; both empty unless EVERY red job
|
|
690
|
+
* is either already passing on the branch, or missing in a way one of the two dispatches answers:
|
|
691
|
+
*
|
|
692
|
+
* - ABSENT from the branch's runs in a workflow listed in `dryRunCapable` → a dry run (#474, unchanged);
|
|
693
|
+
* - ABSENT, or present only as `skipped` instances, in a workflow listed in `dispatchable` → a dispatch
|
|
694
|
+
* (#510), and only when `branchRuns` shows that workflow has a completed, successful NON-dispatch run
|
|
695
|
+
* at the head (gate d: it is branch CI, not a main-only workflow a dispatch could publish from) and NO
|
|
696
|
+
* `workflow_dispatch` run there yet, whatever its status (gate e: a dispatch already made either is
|
|
697
|
+
* still running, or ran and did not supply the job — dispatching again would not help).
|
|
698
|
+
*
|
|
699
|
+
* A red job present-but-failing, pending, or missing in a workflow neither list names means no dispatch
|
|
700
|
+
* would help, so none is asked for. Whether the run, once it exists, passes D1–D3 or W1–W6 is decided
|
|
701
|
+
* then, not predicted now.
|
|
702
|
+
*/
|
|
703
|
+
function cureDispatchPlan(jobEvidence, { dryRunCapable, dispatchable, branchRuns } = {}) {
|
|
704
|
+
const none = { dryRun: [], dispatch: [] };
|
|
705
|
+
const asSet = (x) => new Set(Array.isArray(x) ? x : x instanceof Set ? [...x] : []);
|
|
706
|
+
const capable = asSet(dryRunCapable);
|
|
707
|
+
const plain = asSet(dispatchable);
|
|
708
|
+
if ((!capable.size && !plain.size) || !jobEvidence || !Array.isArray(jobEvidence.redJobs) || !jobEvidence.redJobs.length) return none;
|
|
709
|
+
const idx = indexBranchJobs(Array.isArray(jobEvidence.branchJobs) ? jobEvidence.branchJobs : []);
|
|
710
|
+
const dry = new Set();
|
|
711
|
+
const disp = new Set();
|
|
712
|
+
for (const red of jobEvidence.redJobs) {
|
|
713
|
+
if (!red || !red.name) return none;
|
|
714
|
+
const entry = idx.get(jobKey(red));
|
|
715
|
+
const wf = red.workflowName;
|
|
716
|
+
if (!entry && wf && capable.has(wf)) { dry.add(wf); continue; }
|
|
717
|
+
if ((!entry || entry.allSkipped) && wf && plain.has(wf)) { disp.add(wf); continue; }
|
|
718
|
+
if (!entry) return none;
|
|
719
|
+
const mine = entry.job;
|
|
720
|
+
if (mine.status !== 'completed' || entry.hasPending || mine.conclusion !== 'success' || entry.hasRed) return none;
|
|
721
|
+
}
|
|
722
|
+
if (disp.size) {
|
|
723
|
+
if (!Array.isArray(branchRuns)) return none;
|
|
724
|
+
for (const wf of disp) {
|
|
725
|
+
const runs = branchRuns.filter((r) => r && r.workflowName === wf);
|
|
726
|
+
if (runs.some((r) => r.event === 'workflow_dispatch')) return none;
|
|
727
|
+
if (!runs.some((r) => r.event !== 'workflow_dispatch' && r.status === 'completed' && r.conclusion === 'success')) return none;
|
|
728
|
+
}
|
|
729
|
+
}
|
|
730
|
+
return { dryRun: [...dry].sort(), dispatch: [...disp].sort() };
|
|
731
|
+
}
|
|
732
|
+
|
|
733
|
+
/**
|
|
734
|
+
* The prior exemption's red sha (#477), read off its merge commit's message: both trailers carry
|
|
735
|
+
* `over-red <trunk>@<sha>` — `CI-Grant:` (#105) and `CI-Cure:` (#281) — and that sha is what the
|
|
736
|
+
* prior exemption was measured against. Returns the hex string as written (usually short) or `null`
|
|
737
|
+
* when no such trailer line is present. Only a line STARTING with one of the two prefixes counts,
|
|
738
|
+
* the same anchoring `computeAntiStacking`'s `--grep` uses, so prose quoting a trailer cannot feed it.
|
|
739
|
+
*/
|
|
740
|
+
function priorRedShaFromMessage(message) {
|
|
741
|
+
if (typeof message !== 'string') return null;
|
|
742
|
+
for (const line of message.split('\n')) {
|
|
743
|
+
const m = /^CI-(?:Grant|Cure):.*\bover-red \S*@([0-9a-f]{7,40})\b/.exec(line.trim());
|
|
744
|
+
if (m) return m[1];
|
|
745
|
+
}
|
|
746
|
+
return null;
|
|
747
|
+
}
|
|
748
|
+
|
|
749
|
+
/**
|
|
750
|
+
* The red-job SET at one trunk sha (#477), from the raw job rows of every not-green run there —
|
|
751
|
+
* the same selection `shapeJobEvidence` makes (an incomplete job → `null`, unmeasurable), reduced
|
|
752
|
+
* to `{name, workflowName}` identities.
|
|
753
|
+
*/
|
|
754
|
+
function redJobSet(redRunJobs) {
|
|
755
|
+
const shaped = shapeJobEvidence({ redRunJobs, branchRunJobs: [] });
|
|
756
|
+
if (!shaped) return null;
|
|
757
|
+
return shaped.redJobs.map((j) => ({ name: j.name, workflowName: j.workflowName }));
|
|
758
|
+
}
|
|
759
|
+
|
|
760
|
+
/**
|
|
761
|
+
* Progress past condition 3 (#477) — PURE. `prior` is the red-job set at the red sha the most recent
|
|
762
|
+
* exemption on this continuous red was measured against; `current` the red-job set at trunk's red
|
|
763
|
+
* sha now (the `redJobs` of `shapeJobEvidence`). Jobs are compared by `jobKey` — workflow AND name,
|
|
764
|
+
* the same identity 2b matches on.
|
|
765
|
+
*
|
|
766
|
+
* ok only when `current` is a STRICT subset of `prior`: every job red now was already red then, and
|
|
767
|
+
* at least one job red then is not red now. An equal set is no progress (the prior exemption fixed
|
|
768
|
+
* nothing that stayed fixed); a job red now that was not red then is a NEW failure and refuses even
|
|
769
|
+
* if another job was repaired — admitting it would let a chain of cures trade one red for another
|
|
770
|
+
* forever. Either set unmeasured (`null`, non-array) or empty refuses: an empty `prior` cannot have
|
|
771
|
+
* been the basis of an exemption, and an empty `current` on a red trunk is unmeasurable (same
|
|
772
|
+
* posture as 2b).
|
|
773
|
+
*/
|
|
774
|
+
function redSetShrank(prior, current) {
|
|
775
|
+
if (!Array.isArray(prior) || !Array.isArray(current)) {
|
|
776
|
+
return { ok: false, reason: 'the red-job set at the prior exemption\'s red sha could not be measured' };
|
|
777
|
+
}
|
|
778
|
+
if (!prior.length || !current.length) {
|
|
779
|
+
return { ok: false, reason: 'a red-job set to compare was empty — an unmeasurable red set is never progress' };
|
|
780
|
+
}
|
|
781
|
+
const before = new Map(prior.map((j) => [jobKey(j), j]));
|
|
782
|
+
const now = new Map(current.map((j) => [jobKey(j), j]));
|
|
783
|
+
const added = [...now.keys()].filter((k) => !before.has(k)).map((k) => jobLabel(now.get(k)));
|
|
784
|
+
const healed = [...before.keys()].filter((k) => !now.has(k)).map((k) => jobLabel(before.get(k)));
|
|
785
|
+
const still = [...now.values()].map(jobLabel);
|
|
786
|
+
if (added.length) {
|
|
787
|
+
return { ok: false, added, healed, still,
|
|
788
|
+
reason: `trunk's red set did not shrink: ${added.map((n) => `\`${n}\``).join(', ')} is red now and was not at the prior exemption's red sha — a new failure is not progress` };
|
|
789
|
+
}
|
|
790
|
+
if (!healed.length) {
|
|
791
|
+
return { ok: false, added, healed, still,
|
|
792
|
+
reason: `trunk's red set is unchanged since the prior exemption (${still.map((n) => `\`${n}\``).join(', ')}) — no progress` };
|
|
793
|
+
}
|
|
794
|
+
return { ok: true, added, healed, still,
|
|
795
|
+
reason: `trunk's red set shrank since the prior exemption: ${healed.map((n) => `\`${n}\``).join(', ')} healed, ` +
|
|
796
|
+
`${still.map((n) => `\`${n}\``).join(', ')} still red` };
|
|
797
|
+
}
|
|
798
|
+
|
|
799
|
+
/**
|
|
800
|
+
* Condition 3 as `cureVerdict` applies it (#477): the caller's `stacking` verdict, widened ONLY on
|
|
801
|
+
* its stacked refusal (`stacking.stacked`, set by ci-grant.js's stackingVerdict) and only by
|
|
802
|
+
* measured progress. Returns `{ok, reason, progress}` — `progress` is the `redSetShrank` result
|
|
803
|
+
* whenever it was consulted, so the success path can carry it into the trailer.
|
|
804
|
+
*/
|
|
805
|
+
function stackingWithProgress(stacking, priorRedJobs, jobEvidence) {
|
|
806
|
+
if (stacking && stacking.ok) return { ok: true, reason: '', progress: null };
|
|
807
|
+
const base = (stacking && stacking.reason) || 'anti-stacking verdict unavailable';
|
|
808
|
+
if (!stacking || !stacking.stacked) return { ok: false, reason: base, progress: null };
|
|
809
|
+
const current = jobEvidence && Array.isArray(jobEvidence.redJobs) ? jobEvidence.redJobs : null;
|
|
810
|
+
const progress = redSetShrank(priorRedJobs, current);
|
|
811
|
+
if (!progress.ok) {
|
|
812
|
+
return { ok: false, progress, reason: `${base} The progress admission (#477) does not admit it either: ${progress.reason}` };
|
|
813
|
+
}
|
|
814
|
+
return { ok: true, reason: '', progress };
|
|
815
|
+
}
|
|
816
|
+
|
|
405
817
|
/**
|
|
406
818
|
* The cure verdict for one branch's attempt to ship into a red trunk.
|
|
407
819
|
*
|
|
@@ -418,7 +830,11 @@ function workflowCarveOut(jobEvidence) {
|
|
|
418
830
|
* (the caller already used it to compute `containsRedSha` and `evidence`).
|
|
419
831
|
*
|
|
420
832
|
* `stacking` — `{ok, reason}`, the caller's `ciGrant.stackingVerdict(...)` result, reused
|
|
421
|
-
* verbatim (condition 3) — this module never recomputes it.
|
|
833
|
+
* verbatim (condition 3) — this module never recomputes it. Its stacked refusal carries
|
|
834
|
+
* `stacked: true`; only that refusal can be lifted, by progress (#477).
|
|
835
|
+
*
|
|
836
|
+
* `priorRedJobs` (#477) — `redJobSet(...)` at the red sha the prior exemption named in its trailer,
|
|
837
|
+
* or `null` when unmeasured. Consulted only on a stacked refusal; compared with `jobEvidence.redJobs`.
|
|
422
838
|
*
|
|
423
839
|
* `workflowsTouched` — bool, whether the branch's diff against trunk touches any path under
|
|
424
840
|
* `.github/workflows/` (condition 4 — tools/lib/cure-diff.js, `--no-renames`). `null` means the
|
|
@@ -429,10 +845,23 @@ function workflowCarveOut(jobEvidence) {
|
|
|
429
845
|
* which refuses: a caller that did not measure it has not shown the instrument is intact.
|
|
430
846
|
* `manifestPaths` — the manifests whose scripts changed, named in the refusal.
|
|
431
847
|
*
|
|
848
|
+
* `manifestScriptsAddOnly` (#475) — cure-diff's classifier: `[{path, added}]` when every touched
|
|
849
|
+
* manifest's scripts change is add-only, anything else (null/undefined) when not. Only consulted when
|
|
850
|
+
* `manifestScriptsTouched` is true; a caller that does not pass it gets the pre-#475 refusal.
|
|
851
|
+
*
|
|
432
852
|
* `pythonManifestTouched` — bool, whether the diff changes a Python dependency manifest the Python
|
|
433
853
|
* template installs from (condition 6, #377). `null`/`undefined` = unmeasured, which refuses.
|
|
434
854
|
* `pythonManifestPaths` — those files, named in the refusal.
|
|
435
855
|
*
|
|
856
|
+
* `pythonPinOnly` (#476) — cure-diff's classifier: `[{path, pins}]` when every touched Python
|
|
857
|
+
* manifest changed only version specifiers. Same posture as `manifestScriptsAddOnly`.
|
|
858
|
+
*
|
|
859
|
+
* `dispatchable` / `branchRuns` (#510) — the branch workflows a plain workflow_dispatch can run (by
|
|
860
|
+
* name), and the run-level rows at the branch head (`{workflowName, workflowId, event, status,
|
|
861
|
+
* conclusion}`). Read only on a 2b refusal, by `cureDispatchPlan`, to set `dispatchWanted`; a caller that
|
|
862
|
+
* passes neither gets the pre-#510 refusal unchanged. A cure proven by a dispatch instance returns
|
|
863
|
+
* `dispatch: {jobs}`, the same way a dry-run-proven one returns `dryRun`.
|
|
864
|
+
*
|
|
436
865
|
* `jobEvidence` — `shapeJobEvidence(...)`'s output, or `null`. Read on EVERY cure since #297 —
|
|
437
866
|
* condition 2b (`redJobsProvenOnBranch`) — and again by the #321 carve-out when workflows were
|
|
438
867
|
* touched. `null`, an empty `redJobs`, an empty `branchJobs`, an unreadable step list and an
|
|
@@ -448,12 +877,16 @@ function workflowCarveOut(jobEvidence) {
|
|
|
448
877
|
* branch touching both — exactly the "two instrument paths, two doors" composition #321 asked for.
|
|
449
878
|
*
|
|
450
879
|
* Returns `{ok, reason}`; on success also `provenJobs` (the red job names 2b proved, additive,
|
|
451
|
-
* #297)
|
|
880
|
+
* #297), `admitted` (#475/#476 — `{scripts: [{path, added}], pins: [{path, pins}]}`, present only
|
|
881
|
+
* when a manifest admission was used), `progress` (#477 — `{healed, still}`, present only when condition 3
|
|
882
|
+
* was passed by progress past a prior exemption) and — ONLY on a cure that went through the carve-out —
|
|
883
|
+
* `carveOut: {jobs}`. The ordinary
|
|
452
884
|
* cure's reason text is unchanged, which is what lets the caller answer "which door was this?" by
|
|
453
885
|
* the presence of `carveOut` rather than by re-deriving it.
|
|
454
886
|
*/
|
|
455
887
|
function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouched, jobEvidence,
|
|
456
|
-
manifestScriptsTouched, manifestPaths, pythonManifestTouched, pythonManifestPaths
|
|
888
|
+
manifestScriptsTouched, manifestPaths, manifestScriptsAddOnly, pythonManifestTouched, pythonManifestPaths,
|
|
889
|
+
pythonPinOnly, dryRunCapable, dispatchable, branchRuns, priorRedJobs }) {
|
|
457
890
|
if (!containsRedSha) {
|
|
458
891
|
return { ok: false,
|
|
459
892
|
reason: `branch does not contain trunk's current red head \`${redSha}\` as an ancestor — ` +
|
|
@@ -472,41 +905,99 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
|
|
|
472
905
|
'a bystander\'s PR runs against a merge ref that includes the red trunk, so it waits for green instead (#353)' };
|
|
473
906
|
}
|
|
474
907
|
const proven = redJobsProvenOnBranch(jobEvidence);
|
|
908
|
+
const cond3 = stackingWithProgress(stacking, priorRedJobs, jobEvidence);
|
|
475
909
|
if (!proven.ok) {
|
|
476
|
-
|
|
910
|
+
const out = { ok: false,
|
|
477
911
|
reason: `branch's run is green, but the check trunk is red on is not proven here: ${proven.reason} — ` +
|
|
478
912
|
'a cure must pass the named failing job(s), not merely produce a green run (#297)' };
|
|
913
|
+
// #474: say which dry run would supply the missing evidence — only when every LATER condition
|
|
914
|
+
// already holds, so a dispatch is never asked for on a branch that would refuse anyway.
|
|
915
|
+
// #510: and which plain workflow_dispatch would supply a job a branch push skipped.
|
|
916
|
+
const plan = cureDispatchPlan(jobEvidence, { dryRunCapable, dispatchable, branchRuns });
|
|
917
|
+
// An admissible manifest change (#475/#476) does not suppress the ask: the admission is judged on
|
|
918
|
+
// the dry run's steps once it exists, exactly like any other branch instance.
|
|
919
|
+
const scriptsOk = manifestScriptsTouched === false
|
|
920
|
+
|| (manifestScriptsTouched === true && Array.isArray(manifestScriptsAddOnly) && manifestScriptsAddOnly.length > 0);
|
|
921
|
+
const pythonOk = pythonManifestTouched === false
|
|
922
|
+
|| (pythonManifestTouched === true && Array.isArray(pythonPinOnly) && pythonPinOnly.length > 0);
|
|
923
|
+
if (cond3.ok && scriptsOk && pythonOk && typeof workflowsTouched === 'boolean') {
|
|
924
|
+
if (plan.dryRun.length) out.dryRunWanted = plan.dryRun;
|
|
925
|
+
if (plan.dispatch.length) out.dispatchWanted = plan.dispatch;
|
|
926
|
+
}
|
|
927
|
+
return out;
|
|
479
928
|
}
|
|
480
|
-
|
|
481
|
-
|
|
929
|
+
const dry = proven.dryRunJobs && proven.dryRunJobs.length ? { jobs: proven.dryRunJobs } : null;
|
|
930
|
+
const disp = proven.dispatchJobs && proven.dispatchJobs.length ? { jobs: proven.dispatchJobs } : null;
|
|
931
|
+
const drySuffix = (dry ? ` — the main-only job(s) ${dry.jobs.map((n) => `\`${n}\``).join(', ')} proven by a dry run on the branch (#474)` : '')
|
|
932
|
+
+ (disp ? ` — the trunk-only job(s) ${disp.jobs.map((n) => `\`${n}\``).join(', ')} proven by a workflow_dispatch run at the branch head (#510)` : '');
|
|
933
|
+
if (!cond3.ok) {
|
|
934
|
+
return { ok: false, reason: cond3.reason };
|
|
482
935
|
}
|
|
936
|
+
const prog = cond3.progress ? { progress: { healed: cond3.progress.healed, still: cond3.progress.still } } : {};
|
|
937
|
+
const progSuffix = cond3.progress ? `; past a prior exemption on this red because ${cond3.progress.reason} (#477)` : '';
|
|
483
938
|
if (typeof workflowsTouched !== 'boolean' || typeof manifestScriptsTouched !== 'boolean'
|
|
484
939
|
|| typeof pythonManifestTouched !== 'boolean') {
|
|
485
940
|
return { ok: false,
|
|
486
941
|
reason: 'branch diff could not be measured (which CI files and manifests it touches) — an unmeasured diff is never a cure' };
|
|
487
942
|
}
|
|
943
|
+
const admitted = {};
|
|
488
944
|
if (manifestScriptsTouched) {
|
|
489
945
|
const named = Array.isArray(manifestPaths) && manifestPaths.length ? manifestPaths.join(', ') : 'package.json';
|
|
490
|
-
|
|
946
|
+
if (!Array.isArray(manifestScriptsAddOnly) || !manifestScriptsAddOnly.length) {
|
|
947
|
+
return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named}; not add-only — a script removed, renamed, ` +
|
|
948
|
+
'changed, or a lifecycle hook added)' };
|
|
949
|
+
}
|
|
950
|
+
const proof = manifestStepProof(jobEvidence);
|
|
951
|
+
if (!proof.ok) {
|
|
952
|
+
return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named}). The add-only admission (#475) does not ` +
|
|
953
|
+
`admit it either: ${proof.reason}` };
|
|
954
|
+
}
|
|
955
|
+
admitted.scripts = manifestScriptsAddOnly;
|
|
491
956
|
}
|
|
492
957
|
if (pythonManifestTouched) {
|
|
493
958
|
const named = Array.isArray(pythonManifestPaths) && pythonManifestPaths.length
|
|
494
959
|
? pythonManifestPaths.join(', ') : 'a Python dependency manifest';
|
|
495
|
-
|
|
960
|
+
if (!Array.isArray(pythonPinOnly) || !pythonPinOnly.length) {
|
|
961
|
+
return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named}; not pin-only — a requirement, extra, ` +
|
|
962
|
+
'marker, include or option changed, or the file is setup.py/setup.cfg)' };
|
|
963
|
+
}
|
|
964
|
+
const proof = manifestStepProof(jobEvidence, { noLateSkip: true });
|
|
965
|
+
if (!proof.ok) {
|
|
966
|
+
return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named}). The pin-only admission (#476) does not ` +
|
|
967
|
+
`admit it either: ${proof.reason}` };
|
|
968
|
+
}
|
|
969
|
+
admitted.pins = pythonPinOnly;
|
|
496
970
|
}
|
|
971
|
+
const via = admittedText(admitted);
|
|
497
972
|
if (workflowsTouched) {
|
|
498
973
|
const carve = workflowCarveOut(jobEvidence);
|
|
499
974
|
if (!carve.ok) {
|
|
500
975
|
return { ok: false, reason: `${WORKFLOW_REFUSAL}. The #321 carve-out does not admit it either: ${carve.reason}` };
|
|
501
976
|
}
|
|
502
977
|
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 },
|
|
978
|
+
return { ok: true, provenJobs: proven.jobs, carveOut: { jobs: carve.jobs }, ...(dry ? { dryRun: dry } : {}), ...(disp ? { dispatch: disp } : {}),
|
|
979
|
+
...(via ? { admitted } : {}), ...prog,
|
|
504
980
|
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}` };
|
|
981
|
+
`admitted through the #321 workflow carve-out: every job red on trunk ran to success here with every step it took on trunk — ${detail}${drySuffix}${via}${progSuffix}` };
|
|
982
|
+
}
|
|
983
|
+
return { ok: true, provenJobs: proven.jobs, ...(dry ? { dryRun: dry } : {}), ...(disp ? { dispatch: disp } : {}),
|
|
984
|
+
...(via ? { admitted } : {}), ...prog,
|
|
985
|
+
reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure${drySuffix}${via}${progSuffix}` };
|
|
986
|
+
}
|
|
987
|
+
|
|
988
|
+
/** The reason-text suffix naming which manifest admission(s) a cure used (#475/#476), or ''. */
|
|
989
|
+
function admittedText(admitted) {
|
|
990
|
+
const parts = [];
|
|
991
|
+
if (admitted.scripts) {
|
|
992
|
+
parts.push(`add-only package.json scripts (${admitted.scripts.map((a) => `${a.path}: ${a.added.join(',')}`).join('; ')})`);
|
|
993
|
+
}
|
|
994
|
+
if (admitted.pins) {
|
|
995
|
+
parts.push(`pin-only Python requirements (${admitted.pins.map((a) => `${a.path}: ${a.pins.join(',')}`).join('; ')})`);
|
|
506
996
|
}
|
|
507
|
-
return {
|
|
508
|
-
reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure` };
|
|
997
|
+
return parts.length ? `; manifest change admitted as ${parts.join(' and ')}, every step trunk ran passing here` : '';
|
|
509
998
|
}
|
|
510
999
|
|
|
511
|
-
module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut,
|
|
512
|
-
|
|
1000
|
+
module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, manifestStepProof, shapeJobEvidence, dryRunDispatchPlan,
|
|
1001
|
+
cureDispatchPlan, dispatchEvidence,
|
|
1002
|
+
priorRedShaFromMessage, redJobSet, redSetShrank,
|
|
1003
|
+
WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP };
|