@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 CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.37"
30
+ "version": "1.12.0-rc.38"
31
31
  }
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
- return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}`;
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
 
@@ -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) and — ONLY on a cure that went through the carve-out — `carveOut: {jobs}`. The ordinary
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, dryRunCapable }) {
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
- if (wanted.length && stacking && stacking.ok && manifestScriptsTouched === false && pythonManifestTouched === false
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
- return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named})` };
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
- return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named})` };
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 { ok: true, provenJobs: proven.jobs, ...(dry ? { dryRun: dry } : {}),
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, WORKFLOW_REFUSAL,
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 };
@@ -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 }` (the last two: condition 6, #377): `ok:false` with both flags `null` when the diff itself could not be read;
201
- * `manifestScriptsTouched` `true`/`false`/`null` (unmeasurable), with `manifestPaths` listing every
202
- * manifest whose scripts changed. Never throws.
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 differs = scriptsBlockDiffers(sideText(git, repo, e.oldSha), sideText(git, repo, e.newSha));
221
- if (differs === true) touched.push(e.path);
222
- else if (differs === null) unmeasured.push(e.path);
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, isPythonManifest, pythonIncludes, ABSENT };
455
+ module.exports = { cureDiffSignals, scriptsBlockDiffers, scriptsAddition, pythonPinChange, parseRequirement,
456
+ isPythonManifest, pythonIncludes, ABSENT };