@futurelastic/colab-handbook 1.12.0-rc.37 → 1.12.0-rc.38
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/package.json +1 -1
- package/tools/colab +9 -1
- package/tools/lib/ci-cure.js +126 -11
- package/tools/lib/cure-diff.js +198 -9
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -9453,7 +9453,11 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
|
|
|
9453
9453
|
const via = (cureVerdict.carveOut
|
|
9454
9454
|
? ` via workflow-carve-out jobs ${cureVerdict.carveOut.jobs.map((j) => j.name).join(',')}`
|
|
9455
9455
|
: '') + (cureVerdict.dryRun ? ` via dry-run jobs ${cureVerdict.dryRun.jobs.join(',')}` : '');
|
|
9456
|
-
|
|
9456
|
+
// #475/#476: a cure that changed a manifest under an admission says which, for the same reason.
|
|
9457
|
+
const adm = cureVerdict.admitted || {};
|
|
9458
|
+
const manifest = [adm.scripts ? 'add-only-scripts' : null, adm.pins ? 'pin-only-requirements' : null].filter(Boolean);
|
|
9459
|
+
const admittedSuffix = manifest.length ? ` admitted ${manifest.join(',')}` : '';
|
|
9460
|
+
return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}`;
|
|
9457
9461
|
}
|
|
9458
9462
|
|
|
9459
9463
|
const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--session <id>] [--session-name <s>] [--dry] [--json]
|
|
@@ -10555,7 +10559,9 @@ function shipCiCure(repoAbs, gh, target, trunk, redSha, branch) {
|
|
|
10555
10559
|
const verdict = ciCure.cureVerdict({ containsRedSha, evidence, redSha, stacking, jobEvidence,
|
|
10556
10560
|
workflowsTouched: diff.workflowsTouched,
|
|
10557
10561
|
manifestScriptsTouched: diff.manifestScriptsTouched, manifestPaths: diff.manifestPaths,
|
|
10562
|
+
manifestScriptsAddOnly: diff.manifestScriptsAddOnly,
|
|
10558
10563
|
pythonManifestTouched: diff.pythonManifestTouched, pythonManifestPaths: diff.pythonManifestPaths,
|
|
10564
|
+
pythonPinOnly: diff.pythonPinOnly,
|
|
10559
10565
|
dryRunCapable: capable.map((w) => w.name) });
|
|
10560
10566
|
// The dispatch plan carries the FILE and the exact command, so the refusal can name it and the
|
|
10561
10567
|
// real ship path can run it — measurement only here; nothing is dispatched by this function.
|
|
@@ -10648,6 +10654,8 @@ function ciCurePayload(ciResult) {
|
|
|
10648
10654
|
// #474: on a refusal, the dry run(s) that would supply the missing 2b evidence — what the real
|
|
10649
10655
|
// ship dispatches; `--dry --json` only reports it. null when none would help.
|
|
10650
10656
|
dryRunWanted: c.dryRunDispatch ? c.dryRunDispatch.map((d) => ({ ...d })) : null,
|
|
10657
|
+
// #475/#476: the manifest change a cure was admitted with — `{scripts?, pins?}` — or null.
|
|
10658
|
+
admitted: c.admitted || null,
|
|
10651
10659
|
};
|
|
10652
10660
|
}
|
|
10653
10661
|
|
package/tools/lib/ci-cure.js
CHANGED
|
@@ -44,12 +44,29 @@
|
|
|
44
44
|
* and test run at all, and a skipped step leaves the job `success` — so deleting
|
|
45
45
|
* `scripts.test` weakens the instrument without touching a workflow file. No carve-out: see
|
|
46
46
|
* below for why the #321 door cannot adjudicate it.
|
|
47
|
+
* ONE NARROW ADMISSION (#475): an ADD-ONLY scripts change — keys added, none removed or changed,
|
|
48
|
+
* no lifecycle hook — makes the template run MORE, so it passes condition 5 on step evidence
|
|
49
|
+
* (`manifestStepProof`, below) instead of refusing.
|
|
47
50
|
* 6. NO PYTHON DEPENDENCY-MANIFEST CHANGES (#377) — the branch diff must not change a file the
|
|
48
51
|
* Python CI template installs from (`pyproject.toml`/`setup.py`/`setup.cfg`, `requirements*`
|
|
49
52
|
* files and what they include — tools/lib/cure-diff.js names the set). That template runs
|
|
50
53
|
* ruff/mypy/pytest only when the tool is importable after install, so removing `pytest` from
|
|
51
54
|
* `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.
|
|
55
|
+
* sibling door with no carve-out, for the same reason. ONE NARROW ADMISSION (#476): a PIN-ONLY
|
|
56
|
+
* change — only the version specifier of requirements present on both sides — passes on step
|
|
57
|
+
* evidence plus the no-late-skip test (`manifestStepProof`, below).
|
|
58
|
+
*
|
|
59
|
+
* THE STEP PROOF BEHIND BOTH ADMISSIONS (#475, #476). Every step that RAN in each red job on trunk —
|
|
60
|
+
* the failing one included — ran on the branch and concluded `success`: the 4b read, applied here
|
|
61
|
+
* without the carve-out's duration floor (no workflow changed, so no `run:` body can have been
|
|
62
|
+
* gutted). Check-runs name steps, not commands, so "the step that runs the added script" is not
|
|
63
|
+
* measurable as such; "the step trunk failed in now passes" is, and it is the claim a cure makes.
|
|
64
|
+
* The pin admission adds one test (#476's open question, answered): a pin can drop a TRANSITIVELY
|
|
65
|
+
* installed tool, and the Python template then skips that tool's step with the job still `success`.
|
|
66
|
+
* Steps before trunk's failure point are covered by the superset; steps AFTER it were skipped on
|
|
67
|
+
* trunk and so say nothing. So no step after the last one that ran on trunk may be `skipped` on the
|
|
68
|
+
* branch. That refuses a repo that never had, say, mypy when its red came before the Typecheck step
|
|
69
|
+
* — a false refusal, falling through to the ci-grant, the safe direction.
|
|
53
70
|
*
|
|
54
71
|
* THE WORKFLOW CARVE-OUT (#321) — why condition 4 could not simply stay absolute. The repair for
|
|
55
72
|
* a CI-INFRASTRUCTURE outage is, by construction, a workflow change: when trunk goes red because
|
|
@@ -489,6 +506,55 @@ function workflowCarveOut(jobEvidence) {
|
|
|
489
506
|
return { ok: true, jobs, reason: '' };
|
|
490
507
|
}
|
|
491
508
|
|
|
509
|
+
/**
|
|
510
|
+
* The step proof behind the #475/#476 manifest admissions — 4b without 4c, plus (for a pin) the
|
|
511
|
+
* no-late-skip test. See the module header. Returns `{ok, reason}`; every unmeasurable input refuses.
|
|
512
|
+
* Called only after `redJobsProvenOnBranch` passed, so every red job has a successful branch instance.
|
|
513
|
+
*/
|
|
514
|
+
function manifestStepProof(jobEvidence, { noLateSkip = false } = {}) {
|
|
515
|
+
if (!jobEvidence || !Array.isArray(jobEvidence.redJobs) || !Array.isArray(jobEvidence.branchJobs)) {
|
|
516
|
+
return { ok: false, reason: 'the job-level evidence could not be measured' };
|
|
517
|
+
}
|
|
518
|
+
const idx = indexBranchJobs(jobEvidence.branchJobs);
|
|
519
|
+
for (const red of jobEvidence.redJobs) {
|
|
520
|
+
// A dry-run instance (#474) is the job's branch evidence like any other — redJobsProvenOnBranch
|
|
521
|
+
// already held it to D1–D3, which imply the superset below. See the late-skip note.
|
|
522
|
+
const entry = idx.get(jobKey(red));
|
|
523
|
+
if (!entry) return { ok: false, reason: `job \`${jobLabel(red)}\` is absent on the branch` };
|
|
524
|
+
const mine = entry.job;
|
|
525
|
+
if (!Array.isArray(red.ranSteps) || !red.ranSteps.length) {
|
|
526
|
+
return { ok: false, reason: `the steps that ran in job \`${jobLabel(red)}\` on trunk could not be read` };
|
|
527
|
+
}
|
|
528
|
+
if (!Array.isArray(mine.steps)) {
|
|
529
|
+
return { ok: false, reason: `the steps of job \`${jobLabel(red)}\` on the branch could not be read` };
|
|
530
|
+
}
|
|
531
|
+
let last = -1;
|
|
532
|
+
for (const stepName of red.ranSteps) {
|
|
533
|
+
const at = mine.steps.findIndex((s) => s && s.name === stepName);
|
|
534
|
+
if (at === -1) {
|
|
535
|
+
return { ok: false, reason: `step \`${stepName}\` ran in job \`${jobLabel(red)}\` on trunk and is absent on the branch` };
|
|
536
|
+
}
|
|
537
|
+
if (mine.steps[at].conclusion !== 'success') {
|
|
538
|
+
return { ok: false,
|
|
539
|
+
reason: `step \`${stepName}\` ran in job \`${jobLabel(red)}\` on trunk and concluded \`${mine.steps[at].conclusion}\` on the branch` };
|
|
540
|
+
}
|
|
541
|
+
if (at > last) last = at;
|
|
542
|
+
}
|
|
543
|
+
if (noLateSkip) {
|
|
544
|
+
// A dry run (#474) skips its `[publish]` steps by design, and D3 already refused any OTHER skip
|
|
545
|
+
// in it — so those, and only those, are not a dropped tool.
|
|
546
|
+
const late = mine.steps.slice(last + 1)
|
|
547
|
+
.find((s) => s && s.conclusion === 'skipped' && !(mine.dryRun && isPublishStepName(s.name)));
|
|
548
|
+
if (late) {
|
|
549
|
+
return { ok: false,
|
|
550
|
+
reason: `step \`${late.name}\` in job \`${jobLabel(red)}\` comes after trunk's failure point and was skipped on the branch — ` +
|
|
551
|
+
'trunk never reached it, so whether the pin dropped the tool it needs is unmeasurable' };
|
|
552
|
+
}
|
|
553
|
+
}
|
|
554
|
+
}
|
|
555
|
+
return { ok: true, reason: '' };
|
|
556
|
+
}
|
|
557
|
+
|
|
492
558
|
/**
|
|
493
559
|
* Would a dry run on the branch supply the evidence 2b is missing (#474)? PURE. Returns the sorted
|
|
494
560
|
* workflow names to dispatch, or `[]`. Non-empty only when EVERY red job is either already passing
|
|
@@ -544,10 +610,17 @@ function dryRunDispatchPlan(jobEvidence, dryRunCapable) {
|
|
|
544
610
|
* which refuses: a caller that did not measure it has not shown the instrument is intact.
|
|
545
611
|
* `manifestPaths` — the manifests whose scripts changed, named in the refusal.
|
|
546
612
|
*
|
|
613
|
+
* `manifestScriptsAddOnly` (#475) — cure-diff's classifier: `[{path, added}]` when every touched
|
|
614
|
+
* manifest's scripts change is add-only, anything else (null/undefined) when not. Only consulted when
|
|
615
|
+
* `manifestScriptsTouched` is true; a caller that does not pass it gets the pre-#475 refusal.
|
|
616
|
+
*
|
|
547
617
|
* `pythonManifestTouched` — bool, whether the diff changes a Python dependency manifest the Python
|
|
548
618
|
* template installs from (condition 6, #377). `null`/`undefined` = unmeasured, which refuses.
|
|
549
619
|
* `pythonManifestPaths` — those files, named in the refusal.
|
|
550
620
|
*
|
|
621
|
+
* `pythonPinOnly` (#476) — cure-diff's classifier: `[{path, pins}]` when every touched Python
|
|
622
|
+
* manifest changed only version specifiers. Same posture as `manifestScriptsAddOnly`.
|
|
623
|
+
*
|
|
551
624
|
* `jobEvidence` — `shapeJobEvidence(...)`'s output, or `null`. Read on EVERY cure since #297 —
|
|
552
625
|
* condition 2b (`redJobsProvenOnBranch`) — and again by the #321 carve-out when workflows were
|
|
553
626
|
* touched. `null`, an empty `redJobs`, an empty `branchJobs`, an unreadable step list and an
|
|
@@ -563,12 +636,15 @@ function dryRunDispatchPlan(jobEvidence, dryRunCapable) {
|
|
|
563
636
|
* branch touching both — exactly the "two instrument paths, two doors" composition #321 asked for.
|
|
564
637
|
*
|
|
565
638
|
* Returns `{ok, reason}`; on success also `provenJobs` (the red job names 2b proved, additive,
|
|
566
|
-
* #297)
|
|
639
|
+
* #297), `admitted` (#475/#476 — `{scripts: [{path, added}], pins: [{path, pins}]}`, present only
|
|
640
|
+
* when a manifest admission was used) and — ONLY on a cure that went through the carve-out —
|
|
641
|
+
* `carveOut: {jobs}`. The ordinary
|
|
567
642
|
* cure's reason text is unchanged, which is what lets the caller answer "which door was this?" by
|
|
568
643
|
* the presence of `carveOut` rather than by re-deriving it.
|
|
569
644
|
*/
|
|
570
645
|
function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouched, jobEvidence,
|
|
571
|
-
manifestScriptsTouched, manifestPaths, pythonManifestTouched, pythonManifestPaths,
|
|
646
|
+
manifestScriptsTouched, manifestPaths, manifestScriptsAddOnly, pythonManifestTouched, pythonManifestPaths,
|
|
647
|
+
pythonPinOnly, dryRunCapable }) {
|
|
572
648
|
if (!containsRedSha) {
|
|
573
649
|
return { ok: false,
|
|
574
650
|
reason: `branch does not contain trunk's current red head \`${redSha}\` as an ancestor — ` +
|
|
@@ -594,7 +670,13 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
|
|
|
594
670
|
// #474: say which dry run would supply the missing evidence — only when every LATER condition
|
|
595
671
|
// already holds, so a dispatch is never asked for on a branch that would refuse anyway.
|
|
596
672
|
const wanted = dryRunDispatchPlan(jobEvidence, dryRunCapable);
|
|
597
|
-
|
|
673
|
+
// An admissible manifest change (#475/#476) does not suppress the ask: the admission is judged on
|
|
674
|
+
// the dry run's steps once it exists, exactly like any other branch instance.
|
|
675
|
+
const scriptsOk = manifestScriptsTouched === false
|
|
676
|
+
|| (manifestScriptsTouched === true && Array.isArray(manifestScriptsAddOnly) && manifestScriptsAddOnly.length > 0);
|
|
677
|
+
const pythonOk = pythonManifestTouched === false
|
|
678
|
+
|| (pythonManifestTouched === true && Array.isArray(pythonPinOnly) && pythonPinOnly.length > 0);
|
|
679
|
+
if (wanted.length && stacking && stacking.ok && scriptsOk && pythonOk
|
|
598
680
|
&& typeof workflowsTouched === 'boolean') {
|
|
599
681
|
out.dryRunWanted = wanted;
|
|
600
682
|
}
|
|
@@ -610,15 +692,35 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
|
|
|
610
692
|
return { ok: false,
|
|
611
693
|
reason: 'branch diff could not be measured (which CI files and manifests it touches) — an unmeasured diff is never a cure' };
|
|
612
694
|
}
|
|
695
|
+
const admitted = {};
|
|
613
696
|
if (manifestScriptsTouched) {
|
|
614
697
|
const named = Array.isArray(manifestPaths) && manifestPaths.length ? manifestPaths.join(', ') : 'package.json';
|
|
615
|
-
|
|
698
|
+
if (!Array.isArray(manifestScriptsAddOnly) || !manifestScriptsAddOnly.length) {
|
|
699
|
+
return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named}; not add-only — a script removed, renamed, ` +
|
|
700
|
+
'changed, or a lifecycle hook added)' };
|
|
701
|
+
}
|
|
702
|
+
const proof = manifestStepProof(jobEvidence);
|
|
703
|
+
if (!proof.ok) {
|
|
704
|
+
return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named}). The add-only admission (#475) does not ` +
|
|
705
|
+
`admit it either: ${proof.reason}` };
|
|
706
|
+
}
|
|
707
|
+
admitted.scripts = manifestScriptsAddOnly;
|
|
616
708
|
}
|
|
617
709
|
if (pythonManifestTouched) {
|
|
618
710
|
const named = Array.isArray(pythonManifestPaths) && pythonManifestPaths.length
|
|
619
711
|
? pythonManifestPaths.join(', ') : 'a Python dependency manifest';
|
|
620
|
-
|
|
712
|
+
if (!Array.isArray(pythonPinOnly) || !pythonPinOnly.length) {
|
|
713
|
+
return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named}; not pin-only — a requirement, extra, ` +
|
|
714
|
+
'marker, include or option changed, or the file is setup.py/setup.cfg)' };
|
|
715
|
+
}
|
|
716
|
+
const proof = manifestStepProof(jobEvidence, { noLateSkip: true });
|
|
717
|
+
if (!proof.ok) {
|
|
718
|
+
return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named}). The pin-only admission (#476) does not ` +
|
|
719
|
+
`admit it either: ${proof.reason}` };
|
|
720
|
+
}
|
|
721
|
+
admitted.pins = pythonPinOnly;
|
|
621
722
|
}
|
|
723
|
+
const via = admittedText(admitted);
|
|
622
724
|
if (workflowsTouched) {
|
|
623
725
|
const carve = workflowCarveOut(jobEvidence);
|
|
624
726
|
if (!carve.ok) {
|
|
@@ -626,12 +728,25 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
|
|
|
626
728
|
}
|
|
627
729
|
const detail = carve.jobs.map((j) => `\`${j.name}\` (${j.redMs}ms red on trunk, ${j.branchMs}ms passing here)`).join(', ');
|
|
628
730
|
return { ok: true, provenJobs: proven.jobs, carveOut: { jobs: carve.jobs }, ...(dry ? { dryRun: dry } : {}),
|
|
731
|
+
...(via ? { admitted } : {}),
|
|
629
732
|
reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure, ` +
|
|
630
|
-
`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}` };
|
|
733
|
+
`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}` };
|
|
734
|
+
}
|
|
735
|
+
return { ok: true, provenJobs: proven.jobs, ...(dry ? { dryRun: dry } : {}), ...(via ? { admitted } : {}),
|
|
736
|
+
reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure${drySuffix}${via}` };
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
/** The reason-text suffix naming which manifest admission(s) a cure used (#475/#476), or ''. */
|
|
740
|
+
function admittedText(admitted) {
|
|
741
|
+
const parts = [];
|
|
742
|
+
if (admitted.scripts) {
|
|
743
|
+
parts.push(`add-only package.json scripts (${admitted.scripts.map((a) => `${a.path}: ${a.added.join(',')}`).join('; ')})`);
|
|
744
|
+
}
|
|
745
|
+
if (admitted.pins) {
|
|
746
|
+
parts.push(`pin-only Python requirements (${admitted.pins.map((a) => `${a.path}: ${a.pins.join(',')}`).join('; ')})`);
|
|
631
747
|
}
|
|
632
|
-
return
|
|
633
|
-
reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure${drySuffix}` };
|
|
748
|
+
return parts.length ? `; manifest change admitted as ${parts.join(' and ')}, every step trunk ran passing here` : '';
|
|
634
749
|
}
|
|
635
750
|
|
|
636
|
-
module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, shapeJobEvidence, dryRunDispatchPlan,
|
|
637
|
-
MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP };
|
|
751
|
+
module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, manifestStepProof, shapeJobEvidence, dryRunDispatchPlan,
|
|
752
|
+
WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP };
|
package/tools/lib/cure-diff.js
CHANGED
|
@@ -48,6 +48,26 @@
|
|
|
48
48
|
* (`poetry.lock`, `uv.lock`, `Pipfile.lock`) are NOT read by the template and do not count; an
|
|
49
49
|
* adopter whose CI installs from one has edited the template and owns extending this list.
|
|
50
50
|
*
|
|
51
|
+
* TWO NARROW ADMISSIONS (#475, #476) — the signals above stay whole (any change still sets the flag),
|
|
52
|
+
* and next to each sits a classifier saying whether EVERY touched manifest's change is of one shape
|
|
53
|
+
* the verdict may admit on step evidence (tools/lib/ci-cure.js):
|
|
54
|
+
*
|
|
55
|
+
* - `manifestScriptsAddOnly` (#475) — every touched `package.json` exists on both sides, keeps every
|
|
56
|
+
* base script byte-for-byte (canonically), and only ADDS keys. Adding a script makes the Node
|
|
57
|
+
* template run more, never less. An added npm LIFECYCLE hook is not admitted: `postinstall`,
|
|
58
|
+
* `prepare`, or `pre<x>`/`post<x>` for a script `<x>` run inside a step that already exists and
|
|
59
|
+
* can rewrite what that step measures (e.g. replace a test binary) without a name changing.
|
|
60
|
+
* - `pythonPinOnly` (#476) — every touched Python manifest exists on both sides and differs ONLY in
|
|
61
|
+
* the version specifier (or `--hash`) of requirements present at the same position on both sides:
|
|
62
|
+
* no requirement added, removed, reordered or renamed, no extras or marker changed, and no option
|
|
63
|
+
* line (`-r`/`-c`/`-e`/index) changed. Requirements files are read line-wise; a `pyproject.toml`
|
|
64
|
+
* only inside its dependency arrays (`[project] dependencies`, `[project.optional-dependencies]`,
|
|
65
|
+
* `[dependency-groups]`, `[build-system] requires`) — every other byte must match. `setup.py` is
|
|
66
|
+
* code and `setup.cfg` is not read here: a change to either is never pin-only.
|
|
67
|
+
*
|
|
68
|
+
* Each classifier is `null` whenever the shape is not met (or not measurable) — which leaves the
|
|
69
|
+
* condition refusing exactly as before. It is a list of what changed when it IS met.
|
|
70
|
+
*
|
|
51
71
|
* FAIL CLOSED. Every unmeasurable input is `null`, never `false`: a failed diff read, a manifest
|
|
52
72
|
* blob that could not be read, a manifest that does not parse, a manifest that is a symlink or a
|
|
53
73
|
* submodule. ci-cure.js's `cureVerdict` refuses on `null`.
|
|
@@ -187,6 +207,150 @@ function scriptsBlockDiffers(baseText, headText) {
|
|
|
187
207
|
return a !== b;
|
|
188
208
|
}
|
|
189
209
|
|
|
210
|
+
/** The `scripts` object as the Node template reads it, or null when not a JSON object / not an
|
|
211
|
+
* object-valued `scripts`. */
|
|
212
|
+
function scriptsObject(text) {
|
|
213
|
+
let obj;
|
|
214
|
+
try { obj = JSON.parse(String(text).replace(/^/, '')); } catch (_) { return null; }
|
|
215
|
+
if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null;
|
|
216
|
+
const sc = obj.scripts === undefined ? {} : obj.scripts;
|
|
217
|
+
if (!sc || typeof sc !== 'object' || Array.isArray(sc)) return null;
|
|
218
|
+
return sc;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/** npm runs these on its own (install, publish, pack) — never by a template step naming them. */
|
|
222
|
+
const NPM_LIFECYCLE = new Set(['preinstall', 'install', 'postinstall', 'prepare', 'prepublish',
|
|
223
|
+
'prepublishOnly', 'prepack', 'postpack', 'dependencies', 'preuninstall', 'uninstall', 'postuninstall']);
|
|
224
|
+
/** Scripts npm knows by name, whose `pre`/`post` hooks fire even when the script itself is absent. */
|
|
225
|
+
const NPM_BUILTIN = new Set(['install', 'uninstall', 'publish', 'pack', 'test', 'start', 'stop', 'restart',
|
|
226
|
+
'version', 'shrinkwrap']);
|
|
227
|
+
|
|
228
|
+
/** Whether adding script `key` (to a block whose keys are `keys`) adds a hook npm fires implicitly. */
|
|
229
|
+
function isLifecycleKey(key, keys) {
|
|
230
|
+
if (NPM_LIFECYCLE.has(key)) return true;
|
|
231
|
+
const m = /^(pre|post)(.+)$/.exec(key);
|
|
232
|
+
return !!m && (keys.has(m[2]) || NPM_BUILTIN.has(m[2]));
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* PURE (#475). Whether a `package.json` scripts change is ADD-ONLY. Returns `{added: [names]}` when
|
|
237
|
+
* both sides are present, every base key is kept with an identical command, at least one key was
|
|
238
|
+
* added, and no added key is an npm lifecycle hook — else null (not admissible, or unmeasurable).
|
|
239
|
+
*/
|
|
240
|
+
function scriptsAddition(baseText, headText) {
|
|
241
|
+
if (baseText === ABSENT || headText === ABSENT || baseText === null || headText === null) return null;
|
|
242
|
+
const a = scriptsObject(baseText);
|
|
243
|
+
const b = scriptsObject(headText);
|
|
244
|
+
if (!a || !b) return null;
|
|
245
|
+
for (const k of Object.keys(a)) {
|
|
246
|
+
if (!Object.prototype.hasOwnProperty.call(b, k) || canonical(a[k]) !== canonical(b[k])) return null;
|
|
247
|
+
}
|
|
248
|
+
const keys = new Set(Object.keys(b));
|
|
249
|
+
const added = Object.keys(b).filter((k) => !Object.prototype.hasOwnProperty.call(a, k));
|
|
250
|
+
if (!added.length) return null;
|
|
251
|
+
if (added.some((k) => typeof b[k] !== 'string' || isLifecycleKey(k, keys))) return null;
|
|
252
|
+
return { added: added.sort() };
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
const SPEC_RE = /^(?:(?:~=|===|==|!=|<=|>=|<|>)\s*[A-Za-z0-9.*+!_-]+\s*)(?:,\s*(?:~=|===|==|!=|<=|>=|<|>)\s*[A-Za-z0-9.*+!_-]+\s*)*,?$/;
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* PURE. One PEP 508 requirement split into its IDENTITY (normalised name, sorted extras, marker) and
|
|
259
|
+
* its version SPECIFIER — or null when it is not a plain name requirement (a URL `@`, a path, the old
|
|
260
|
+
* parenthesised form). Only the specifier may differ for a change to read as a pin.
|
|
261
|
+
*/
|
|
262
|
+
function parseRequirement(text) {
|
|
263
|
+
const s = String(text).trim();
|
|
264
|
+
const semi = s.indexOf(';');
|
|
265
|
+
const head = semi === -1 ? s : s.slice(0, semi);
|
|
266
|
+
// Whitespace outside quoted values is insignificant in a marker; inside one it is data.
|
|
267
|
+
const marker = semi === -1 ? '' : s.slice(semi + 1).split(/("[^"]*"|'[^']*')/)
|
|
268
|
+
.map((part, i) => (i % 2 ? part : part.replace(/\s+/g, ''))).join('');
|
|
269
|
+
if (head.includes('@')) return null;
|
|
270
|
+
const m = /^([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)\s*(?:\[([^\]]*)\])?\s*(.*)$/.exec(head.trim());
|
|
271
|
+
if (!m) return null;
|
|
272
|
+
const spec = m[3].replace(/\s+/g, '');
|
|
273
|
+
if (spec && !SPEC_RE.test(spec)) return null;
|
|
274
|
+
const name = m[1].toLowerCase().replace(/[-_.]+/g, '-');
|
|
275
|
+
const extras = (m[2] || '').split(',').map((e) => e.trim().toLowerCase()).filter(Boolean).sort().join(',');
|
|
276
|
+
return { name, identity: `${name}[${extras}];${marker}`, spec: spec.replace(/,$/, '') };
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/** A requirements-format file as `{skeleton: [...], reqs: [{name, spec}]}`: comment, blank and
|
|
280
|
+
* `--hash` stripped; each requirement line reduced to its identity; every other line kept verbatim
|
|
281
|
+
* (whitespace-collapsed), so an option line or an unparseable requirement must match exactly. */
|
|
282
|
+
function requirementsShape(text) {
|
|
283
|
+
const skeleton = [];
|
|
284
|
+
const reqs = [];
|
|
285
|
+
for (const raw of String(text).replace(/\\\r?\n/g, ' ').split(/\r?\n/)) {
|
|
286
|
+
const line = raw.replace(/(^|\s)#.*$/, '').replace(/\s+/g, ' ').trim();
|
|
287
|
+
if (!line) continue;
|
|
288
|
+
if (line.startsWith('-')) { skeleton.push(`opt ${line}`); continue; }
|
|
289
|
+
const bare = line.replace(/\s--hash(?:=|\s+)\S+/g, '').trim();
|
|
290
|
+
const r = parseRequirement(bare);
|
|
291
|
+
if (!r) { skeleton.push(`raw ${line}`); continue; }
|
|
292
|
+
skeleton.push(`req ${r.identity}`);
|
|
293
|
+
reqs.push({ name: r.name, spec: r.spec });
|
|
294
|
+
}
|
|
295
|
+
return { skeleton, reqs };
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
/** Is this `pyproject.toml` array (key `key` in table `table`) a dependency list pip installs from? */
|
|
299
|
+
function isDependencyArray(table, key) {
|
|
300
|
+
const k = key.replace(/^["']|["']$/g, '');
|
|
301
|
+
return (table === 'project' && k === 'dependencies')
|
|
302
|
+
|| table === 'project.optional-dependencies'
|
|
303
|
+
|| table === 'dependency-groups'
|
|
304
|
+
|| (table === 'build-system' && k === 'requires');
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
const TOML_STRING = /"((?:[^"\\]|\\.)*)"|'([^']*)'/g;
|
|
308
|
+
|
|
309
|
+
/** A `pyproject.toml` as `{skeleton, reqs}`: every line verbatim, except that inside a dependency array
|
|
310
|
+
* each requirement string is reduced to its identity. */
|
|
311
|
+
function pyprojectShape(text) {
|
|
312
|
+
const skeleton = [];
|
|
313
|
+
const reqs = [];
|
|
314
|
+
let table = '';
|
|
315
|
+
let depth = 0; // bracket depth of the dependency array we are inside; 0 = not in one
|
|
316
|
+
for (const line of String(text).split(/\r?\n/)) {
|
|
317
|
+
const bare = line.replace(TOML_STRING, '""');
|
|
318
|
+
if (!depth) {
|
|
319
|
+
const sec = /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/.exec(line);
|
|
320
|
+
if (sec) { table = sec[1].replace(/\s+/g, ''); skeleton.push(line); continue; }
|
|
321
|
+
const kv = /^\s*("[^"]*"|'[^']*'|[A-Za-z0-9_.-]+)\s*=\s*\[/.exec(line);
|
|
322
|
+
if (!kv || !isDependencyArray(table, kv[1])) { skeleton.push(line); continue; }
|
|
323
|
+
}
|
|
324
|
+
depth += (bare.match(/\[/g) || []).length - (bare.match(/\]/g) || []).length;
|
|
325
|
+
if (depth < 0) depth = 0;
|
|
326
|
+
skeleton.push(line.replace(TOML_STRING, (all, dq, sq) => {
|
|
327
|
+
const r = parseRequirement(dq !== undefined ? dq : sq);
|
|
328
|
+
if (!r) return all;
|
|
329
|
+
reqs.push({ name: r.name, spec: r.spec });
|
|
330
|
+
return `<${r.identity}>`;
|
|
331
|
+
}));
|
|
332
|
+
}
|
|
333
|
+
return { skeleton, reqs };
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
/**
|
|
337
|
+
* PURE (#476). Whether a Python manifest change is PIN-ONLY. Returns `{pins: [names]}` — the
|
|
338
|
+
* requirements whose specifier changed — when both sides are present, the shapes match line for
|
|
339
|
+
* line and at least one specifier differs; else null. `setup.py`/`setup.cfg` → always null.
|
|
340
|
+
*/
|
|
341
|
+
function pythonPinChange(filePath, baseText, headText) {
|
|
342
|
+
if (baseText === ABSENT || headText === ABSENT || baseText === null || headText === null) return null;
|
|
343
|
+
const base = filePath.slice(filePath.lastIndexOf('/') + 1);
|
|
344
|
+
if (base === 'setup.py' || base === 'setup.cfg') return null;
|
|
345
|
+
const shape = base === 'pyproject.toml' ? pyprojectShape : requirementsShape;
|
|
346
|
+
const a = shape(baseText);
|
|
347
|
+
const b = shape(headText);
|
|
348
|
+
if (a.skeleton.length !== b.skeleton.length || a.skeleton.some((l, i) => l !== b.skeleton[i])) return null;
|
|
349
|
+
const pins = [];
|
|
350
|
+
for (let i = 0; i < a.reqs.length; i += 1) if (a.reqs[i].spec !== b.reqs[i].spec) pins.push(b.reqs[i].name);
|
|
351
|
+
return pins.length ? { pins } : null;
|
|
352
|
+
}
|
|
353
|
+
|
|
190
354
|
/** One side's text for a raw-diff entry: `ABSENT`, the blob text, or null on a failed read. */
|
|
191
355
|
function sideText(git, repo, sha) {
|
|
192
356
|
if (!sha || ZERO_SHA.test(sha)) return ABSENT;
|
|
@@ -197,35 +361,57 @@ function sideText(git, repo, sha) {
|
|
|
197
361
|
/**
|
|
198
362
|
* The diff signals for one branch against trunk, over the merge-base range (`trunk...branch` — the
|
|
199
363
|
* same tree a squash lands). Returns `{ ok, reason, workflowsTouched, manifestScriptsTouched,
|
|
200
|
-
* manifestPaths, pythonManifestTouched, pythonManifestPaths
|
|
201
|
-
*
|
|
202
|
-
*
|
|
364
|
+
* manifestPaths, manifestScriptsAddOnly, pythonManifestTouched, pythonManifestPaths, pythonPinOnly }`
|
|
365
|
+
* (the Python pair: condition 6, #377): `ok:false` with every flag `null` when the diff itself could
|
|
366
|
+
* not be read; `manifestScriptsTouched` `true`/`false`/`null` (unmeasurable), with `manifestPaths`
|
|
367
|
+
* listing every manifest whose scripts changed. `manifestScriptsAddOnly` (#475) and `pythonPinOnly`
|
|
368
|
+
* (#476): `[]` when their condition is untouched, `[{path, added|pins}]` when EVERY touched manifest
|
|
369
|
+
* is of the admissible shape, `null` otherwise. Never throws.
|
|
203
370
|
*/
|
|
204
371
|
function cureDiffSignals(git, repo, trunk, branch) {
|
|
205
372
|
const raw = git.git(['diff', '-z', '--no-renames', '--raw', '--no-abbrev', `${trunk}...${branch}`], repo);
|
|
206
373
|
if (!raw.ok) {
|
|
207
374
|
return { ok: false, reason: `git diff ${trunk}...${branch} failed: ${(raw.stderr || '').split('\n')[0] || raw.code}`,
|
|
208
|
-
workflowsTouched: null, manifestScriptsTouched: null, manifestPaths: [],
|
|
209
|
-
pythonManifestTouched: null, pythonManifestPaths: [] };
|
|
375
|
+
workflowsTouched: null, manifestScriptsTouched: null, manifestPaths: [], manifestScriptsAddOnly: null,
|
|
376
|
+
pythonManifestTouched: null, pythonManifestPaths: [], pythonPinOnly: null };
|
|
210
377
|
}
|
|
211
378
|
const entries = parseRaw(raw.stdout);
|
|
212
379
|
const workflowsTouched = entries.some((e) => e.path.startsWith('.github/workflows/'));
|
|
213
380
|
|
|
214
381
|
const touched = [];
|
|
215
382
|
const unmeasured = [];
|
|
383
|
+
let additions = [];
|
|
216
384
|
for (const e of entries) {
|
|
217
385
|
if (!isManifest(e.path)) continue;
|
|
218
386
|
if (!FILE_MODES.has(e.oldMode) || !FILE_MODES.has(e.newMode)) { unmeasured.push(e.path); continue; }
|
|
219
387
|
if (e.oldSha && e.oldSha === e.newSha) continue; // mode-only change: same content
|
|
220
|
-
const
|
|
221
|
-
|
|
222
|
-
|
|
388
|
+
const before = sideText(git, repo, e.oldSha);
|
|
389
|
+
const after = sideText(git, repo, e.newSha);
|
|
390
|
+
const differs = scriptsBlockDiffers(before, after);
|
|
391
|
+
if (differs === true) {
|
|
392
|
+
touched.push(e.path);
|
|
393
|
+
const add = additions && scriptsAddition(before, after);
|
|
394
|
+
additions = add ? additions.concat([{ path: e.path, added: add.added }]) : null;
|
|
395
|
+
} else if (differs === null) unmeasured.push(e.path);
|
|
223
396
|
}
|
|
224
397
|
let manifestScriptsTouched = false;
|
|
225
398
|
if (touched.length) manifestScriptsTouched = true;
|
|
226
399
|
else if (unmeasured.length) manifestScriptsTouched = null;
|
|
227
400
|
|
|
228
401
|
const py = pythonSignal(git, repo, trunk, branch, entries);
|
|
402
|
+
// #476: whether every touched Python manifest changed only a version specifier. Read only when
|
|
403
|
+
// condition 6 actually fires, so an ordinary diff pays nothing for it.
|
|
404
|
+
let pins = py.touched === true ? [] : (py.touched === false ? [] : null);
|
|
405
|
+
if (py.touched === true) {
|
|
406
|
+
const byPath = new Map(entries.map((e) => [e.path, e]));
|
|
407
|
+
for (const p of py.paths) {
|
|
408
|
+
const e = byPath.get(p);
|
|
409
|
+
const pin = e && FILE_MODES.has(e.oldMode) && FILE_MODES.has(e.newMode)
|
|
410
|
+
&& pythonPinChange(p, sideText(git, repo, e.oldSha), sideText(git, repo, e.newSha));
|
|
411
|
+
if (!pin) { pins = null; break; }
|
|
412
|
+
pins.push({ path: p, pins: pin.pins });
|
|
413
|
+
}
|
|
414
|
+
}
|
|
229
415
|
const reasons = [];
|
|
230
416
|
if (unmeasured.length && !touched.length) reasons.push(`could not read the scripts of: ${unmeasured.join(', ')}`);
|
|
231
417
|
if (py.touched === null) reasons.push(py.reason);
|
|
@@ -233,7 +419,9 @@ function cureDiffSignals(git, repo, trunk, branch) {
|
|
|
233
419
|
ok: true,
|
|
234
420
|
reason: reasons.join('; '),
|
|
235
421
|
workflowsTouched, manifestScriptsTouched, manifestPaths: touched,
|
|
422
|
+
manifestScriptsAddOnly: manifestScriptsTouched === false ? [] : (manifestScriptsTouched === true ? additions : null),
|
|
236
423
|
pythonManifestTouched: py.touched, pythonManifestPaths: py.paths,
|
|
424
|
+
pythonPinOnly: pins,
|
|
237
425
|
};
|
|
238
426
|
}
|
|
239
427
|
|
|
@@ -264,4 +452,5 @@ function pythonSignal(git, repo, trunk, branch, entries) {
|
|
|
264
452
|
return { touched: paths.length > 0, paths, reason: '' };
|
|
265
453
|
}
|
|
266
454
|
|
|
267
|
-
module.exports = { cureDiffSignals, scriptsBlockDiffers,
|
|
455
|
+
module.exports = { cureDiffSignals, scriptsBlockDiffers, scriptsAddition, pythonPinChange, parseRequirement,
|
|
456
|
+
isPythonManifest, pythonIncludes, ABSENT };
|