@futurelastic/colab-handbook 1.14.0-rc.1 → 1.14.0-rc.3
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/audit/audit.mjs +11 -1
- package/package.json +1 -1
- package/templates/instruction-files.yml +5 -0
- package/tools/colab +13 -5
- package/tools/lib/ci-cure.js +10 -1
- package/tools/lib/cure-diff.js +27 -1
- package/tools/lib/workflow-triggers.js +57 -0
package/audit/audit.mjs
CHANGED
|
@@ -107,7 +107,7 @@ const ownerBranchLib = require("../tools/lib/owner-branch.js");
|
|
|
107
107
|
const npmGuard = require("../tools/lib/npm-publish-guard.js");
|
|
108
108
|
const installRoute = require("../tools/lib/install-route.js");
|
|
109
109
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
110
|
-
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
|
|
110
|
+
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
|
|
111
111
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
112
112
|
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
113
113
|
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
@@ -1792,6 +1792,9 @@ function auditRepo(target, ctx) {
|
|
|
1792
1792
|
// #419: and prose left in CLAUDE.md / no AGENTS.md at all — same posture, same reason.
|
|
1793
1793
|
// #588: and the same finding FAILS where the instruction-file ratchet trips (local repos only).
|
|
1794
1794
|
checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null });
|
|
1795
|
+
// #599: a caller of the reusable instruction-files workflow narrowed off session branches, or not
|
|
1796
|
+
// dispatchable, defeats the ratchet's point (fail on the branch) and the cure rule's way out.
|
|
1797
|
+
checkInstructionFilesCaller(src, workflows, cfg?.trunk ?? null, warn);
|
|
1795
1798
|
|
|
1796
1799
|
// ---- markdown anchor links resolve (#158) --------------------------------
|
|
1797
1800
|
// Unconditional, same posture as checkClaudeMdSize above: general markdown hygiene,
|
|
@@ -2756,6 +2759,13 @@ function checkInstructionFileShape(src, warn, fail = warn, opts = {}) {
|
|
|
2756
2759
|
// caller is `deploy: manual` (a human runs it) or `deploy: tag` deployed OUTSIDE CI (a GitOps
|
|
2757
2760
|
// poller runs it). Both share the same invariant: the deploy runs off no in-repo workflow, so the
|
|
2758
2761
|
// path to production must be WRITTEN DOWN or nobody but its author can ship it.
|
|
2762
|
+
// ---- the instruction-files caller's trigger (#599) ---------------------------
|
|
2763
|
+
// The logic lives in tools/lib/workflow-triggers.js beside the other trigger readers. WARN, never
|
|
2764
|
+
// fail: the caller is a copy the repo owns, and handbook-sync's trigger graft is the fix.
|
|
2765
|
+
function checkInstructionFilesCaller(src, workflows, trunk, warn) {
|
|
2766
|
+
for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
|
|
2767
|
+
}
|
|
2768
|
+
|
|
2759
2769
|
// ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
|
|
2760
2770
|
// The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
|
|
2761
2771
|
// same finding; this maps its severity onto the audit's fail/warn.
|
package/package.json
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
# Copy to .github/workflows/instruction-files.yml — CLAUDE.md must be @AGENTS.md + tool blocks (#588).
|
|
2
2
|
name: instruction-files
|
|
3
3
|
on:
|
|
4
|
+
# Keep `push:` UNFILTERED (#599). The ratchet is meant to fail on the session branch that breaks
|
|
5
|
+
# it, before trunk; narrowed to `branches: [main]`, it first fails ON trunk, and the cure branch's
|
|
6
|
+
# push run cannot prove the job (#297). The audit reports a narrowed copy.
|
|
4
7
|
push:
|
|
5
8
|
pull_request:
|
|
9
|
+
# Lets `colab ship` prove a red job on a cure branch by dispatch (#510), with no human ci-grant.
|
|
10
|
+
workflow_dispatch:
|
|
6
11
|
jobs:
|
|
7
12
|
instruction-files:
|
|
8
13
|
uses: futurelastic/colab-handbook/.github/workflows/instruction-files.yml@main
|
package/tools/colab
CHANGED
|
@@ -11819,12 +11819,14 @@ function ciGrantPayload(ciResult) {
|
|
|
11819
11819
|
* on its own.
|
|
11820
11820
|
*
|
|
11821
11821
|
* Measures, in order:
|
|
11822
|
-
* 1. containment — `git merge-base --is-ancestor <redSha> <
|
|
11822
|
+
* 1. containment — cure-diff's `cureContainment`: `git merge-base --is-ancestor <redSha> <ref>`
|
|
11823
|
+
* against the ref ship lands (local branch, else `<remote>/<branch>` — #589), translated to
|
|
11824
|
+
* true/false, or null ("could not resolve") when the ref or the red sha does not resolve.
|
|
11823
11825
|
* 2. evidence — a completed, successful CI run for `branch`'s CURRENT head, via the identical
|
|
11824
11826
|
* `ghRunForSha` the raw CI check and `shipCiGrants` both use.
|
|
11825
11827
|
* 3. anti-stacking — `computeAntiStacking`, the SAME function `cmdCiGrantCreate` calls, so a cure
|
|
11826
11828
|
* and a human grant can never independently disagree about whether trunk is mid-stack.
|
|
11827
|
-
* 4. the diff signals — tools/lib/cure-diff.js's `cureDiffSignals` over `<trunk>...<
|
|
11829
|
+
* 4. the diff signals — tools/lib/cure-diff.js's `cureDiffSignals` over `<trunk>...<ref>` (same ref)
|
|
11828
11830
|
* (merge-base-relative, the tree a squash lands), `--no-renames` so a workflow file or
|
|
11829
11831
|
* manifest MOVED away still counts (#297 — the old `--name-only` read listed only a rename's
|
|
11830
11832
|
* new path). It yields `workflowsTouched` (condition 4) and `manifestScriptsTouched`
|
|
@@ -11860,11 +11862,17 @@ function shipCiCure(repoAbs, gh, target, trunk, redSha, branch) {
|
|
|
11860
11862
|
if (!gh) {
|
|
11861
11863
|
return { ok: false, reason: `gh not usable (${ghUnusableWhy(repoAbs)}) — the cure rule needs a measured CI run`, redSha, evidenceSha: null };
|
|
11862
11864
|
}
|
|
11863
|
-
|
|
11865
|
+
// #589: containment and the diff read the ref ship lands — the local branch, else its remote-tracking
|
|
11866
|
+
// ref (a --handoff land has no local branch). The bare name failed there and read as "not an
|
|
11867
|
+
// ancestor"; an unresolvable ref now refuses as "could not resolve", never as "does not contain".
|
|
11868
|
+
// The CI read keeps the NAME: ghRunForSha resolves the remote head itself (ls-remote).
|
|
11869
|
+
const containment = cureDiff.cureContainment(git, repoAbs, redSha, branch);
|
|
11870
|
+
const containsRedSha = containment.contains;
|
|
11871
|
+
const branchRef = containment.ref || branch;
|
|
11864
11872
|
const evRun = git.ghRunForSha(repoAbs, branch);
|
|
11865
11873
|
const evidence = !evRun ? null : { ok: evRun.status === 'completed' && evRun.conclusion === 'success', sha: evRun.sha };
|
|
11866
11874
|
const stacking = computeAntiStacking(repoAbs, trunk, true /* trunkIsRed: shipCiCure is only ever reached from a HUMAN_GATED raw verdict */);
|
|
11867
|
-
const diff = cureDiff.cureDiffSignals(git, repoAbs, trunk,
|
|
11875
|
+
const diff = cureDiff.cureDiffSignals(git, repoAbs, trunk, branchRef);
|
|
11868
11876
|
// Measured only past containment + 2a: a verdict that already refuses on either never reads it,
|
|
11869
11877
|
// so a branch that cannot cure pays no job-level `gh` calls for it.
|
|
11870
11878
|
const jobEvidence = (containsRedSha && evidence && evidence.ok)
|
|
@@ -11876,7 +11884,7 @@ function shipCiCure(repoAbs, gh, target, trunk, redSha, branch) {
|
|
|
11876
11884
|
const dispatchable = jobEvidence && evidence ? dispatchableWorkflows(repoAbs, evidence.sha) : [];
|
|
11877
11885
|
// #477: a stacked refusal may be lifted by progress — measure the prior red set only then.
|
|
11878
11886
|
const priorRedJobs = jobEvidence && stacking && stacking.stacked ? priorExemptionRedJobs(repoAbs, trunk, stacking) : null;
|
|
11879
|
-
const verdict = ciCure.cureVerdict({ containsRedSha, evidence, redSha, stacking, jobEvidence, priorRedJobs,
|
|
11887
|
+
const verdict = ciCure.cureVerdict({ containsRedSha, containmentReason: containment.reason, evidence, redSha, stacking, jobEvidence, priorRedJobs,
|
|
11880
11888
|
workflowsTouched: diff.workflowsTouched,
|
|
11881
11889
|
manifestScriptsTouched: diff.manifestScriptsTouched, manifestPaths: diff.manifestPaths,
|
|
11882
11890
|
manifestScriptsAddOnly: diff.manifestScriptsAddOnly,
|
package/tools/lib/ci-cure.js
CHANGED
|
@@ -820,6 +820,8 @@ function stackingWithProgress(stacking, priorRedJobs, jobEvidence) {
|
|
|
820
820
|
* `containsRedSha` — bool, whether the branch's tree contains the red trunk sha as an ancestor
|
|
821
821
|
* (the caller's `git merge-base --is-ancestor <redSha> <branch>`, translated to a bool — never
|
|
822
822
|
* re-derived here, this module does not touch git).
|
|
823
|
+
* `null` (#589) means the caller could NOT measure it — the ref did not resolve, or git failed —
|
|
824
|
+
* and refuses with `containmentReason` ("could not resolve …"), never as "does not contain".
|
|
823
825
|
*
|
|
824
826
|
* `evidence` — `{ok, sha}` for a completed, successful CI run measured on the branch's CURRENT
|
|
825
827
|
* head, or `null` when the caller's own read of it FAILED. Passing `evidence: null` means "the
|
|
@@ -886,7 +888,14 @@ function stackingWithProgress(stacking, priorRedJobs, jobEvidence) {
|
|
|
886
888
|
*/
|
|
887
889
|
function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouched, jobEvidence,
|
|
888
890
|
manifestScriptsTouched, manifestPaths, manifestScriptsAddOnly, pythonManifestTouched, pythonManifestPaths,
|
|
889
|
-
pythonPinOnly, dryRunCapable, dispatchable, branchRuns, priorRedJobs }) {
|
|
891
|
+
pythonPinOnly, dryRunCapable, dispatchable, branchRuns, priorRedJobs, containmentReason }) {
|
|
892
|
+
// #589: `null` = containment could not be MEASURED (an unresolvable ref, a failed git read) — a
|
|
893
|
+
// different fact from "not an ancestor", whose remedy (rebase onto the red) would be wrong advice.
|
|
894
|
+
if (containsRedSha === null) {
|
|
895
|
+
return { ok: false,
|
|
896
|
+
reason: `${containmentReason || `could not resolve the branch or trunk's red head \`${redSha}\``} — ` +
|
|
897
|
+
'containment was not measured, so this cannot prove a cure (an unmeasured read is never a cure)' };
|
|
898
|
+
}
|
|
890
899
|
if (!containsRedSha) {
|
|
891
900
|
return { ok: false,
|
|
892
901
|
reason: `branch does not contain trunk's current red head \`${redSha}\` as an ancestor — ` +
|
package/tools/lib/cure-diff.js
CHANGED
|
@@ -358,6 +358,32 @@ function sideText(git, repo, sha) {
|
|
|
358
358
|
return r.ok ? r.stdout : null;
|
|
359
359
|
}
|
|
360
360
|
|
|
361
|
+
/**
|
|
362
|
+
* The cure rule's containment read (#281 condition 1), against the ref `ship` actually lands (#589).
|
|
363
|
+
*
|
|
364
|
+
* A `--handoff` land usually has no local branch — only `<remote>/<branch>` — so asking git about
|
|
365
|
+
* the bare name failed, and that failure read as "not an ancestor": a real cure refused until a
|
|
366
|
+
* local ref was made by hand. The ref is resolved here exactly as `shipRefFor` does (local branch,
|
|
367
|
+
* else its remote-tracking ref), and the three outcomes are kept apart:
|
|
368
|
+
* `{ref, contains: true}` · `{ref, contains: false}` (git exit 1 — genuinely not an ancestor) ·
|
|
369
|
+
* `{ref, contains: null, reason}` — the branch or the red sha could not be resolved, or git failed.
|
|
370
|
+
* `null` refuses in `cureVerdict` with the "could not resolve" reason, never "does not contain".
|
|
371
|
+
* Never throws.
|
|
372
|
+
*/
|
|
373
|
+
function cureContainment(git, repo, redSha, branch, remote) {
|
|
374
|
+
const refs = git.branchRefs(repo, branch, ...(remote ? [remote] : []));
|
|
375
|
+
const ref = refs.localSha || refs.remoteSha;
|
|
376
|
+
if (!ref) {
|
|
377
|
+
return { ref: null, contains: null,
|
|
378
|
+
reason: `could not resolve ${branch} — no local branch and no remote-tracking ref (fetch it first)` };
|
|
379
|
+
}
|
|
380
|
+
const r = git.git(['merge-base', '--is-ancestor', redSha, ref], repo);
|
|
381
|
+
if (r.ok) return { ref, contains: true, reason: '' };
|
|
382
|
+
if (r.code === 1) return { ref, contains: false, reason: '' };
|
|
383
|
+
return { ref, contains: null,
|
|
384
|
+
reason: `could not resolve trunk's red head \`${redSha}\` against ${branch} (${ref.slice(0, 7)}): ${(r.stderr || '').split('\n')[0] || `git exit ${r.code}`}` };
|
|
385
|
+
}
|
|
386
|
+
|
|
361
387
|
/**
|
|
362
388
|
* The diff signals for one branch against trunk, over the merge-base range (`trunk...branch` — the
|
|
363
389
|
* same tree a squash lands). Returns `{ ok, reason, workflowsTouched, manifestScriptsTouched,
|
|
@@ -452,5 +478,5 @@ function pythonSignal(git, repo, trunk, branch, entries) {
|
|
|
452
478
|
return { touched: paths.length > 0, paths, reason: '' };
|
|
453
479
|
}
|
|
454
480
|
|
|
455
|
-
module.exports = { cureDiffSignals, scriptsBlockDiffers, scriptsAddition, pythonPinChange, parseRequirement,
|
|
481
|
+
module.exports = { cureDiffSignals, cureContainment, scriptsBlockDiffers, scriptsAddition, pythonPinChange, parseRequirement,
|
|
456
482
|
isPythonManifest, pythonIncludes, ABSENT };
|
|
@@ -265,6 +265,62 @@ function prereleaseTagTriggers({ readFile, workflows, deploy }) {
|
|
|
265
265
|
return out;
|
|
266
266
|
}
|
|
267
267
|
|
|
268
|
+
// ---- callers of the reusable instruction-files workflow (#599) ---------------
|
|
269
|
+
// The ratchet (#588) is meant to fail on the SESSION BRANCH, before trunk. A caller narrowed to
|
|
270
|
+
// `push: branches: [main]` (measured: 15 of 16 adopting copies) never runs there, so a branch that
|
|
271
|
+
// trips it merges green and the failure first appears on trunk — where the cure rule (#297) then
|
|
272
|
+
// cannot find the job on the cure branch's push run and, with no `workflow_dispatch` to fall back on
|
|
273
|
+
// (#510), ships only through a human grant. A caller is recognised by what it RUNS — a job `uses:`
|
|
274
|
+
// the reusable `.github/workflows/instruction-files.yml` — never by its file name. One branch per
|
|
275
|
+
// session-branch type is probed (plus a machine-prefixed one, §4), so `branches: ['feat/**']` reads
|
|
276
|
+
// as narrowed too; the trunk itself is probed as well, since a caller that skips trunk is narrowed
|
|
277
|
+
// the other way.
|
|
278
|
+
const INSTRUCTION_FILES_USES = /^\s*(?:-\s*)?uses:\s*["']?[^\s"'#]*\.github\/workflows\/instruction-files\.ya?ml(?:@[^\s"'#]*)?["']?\s*(?:#.*)?$/m;
|
|
279
|
+
const SESSION_BRANCH_PROBES = ["feat/probe-1", "fix/probe-1", "docs/probe-1", "chore/probe-1", "refactor/probe-1",
|
|
280
|
+
"test/probe-1", "perf/probe-1", "design/probe-1", "ada/box-a/feat/probe-1"];
|
|
281
|
+
|
|
282
|
+
/** Does this workflow call the reusable instruction-files workflow? (#599) */
|
|
283
|
+
function isInstructionFilesCaller(text) {
|
|
284
|
+
return !!text && INSTRUCTION_FILES_USES.test(text);
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/**
|
|
288
|
+
* Each caller of the reusable instruction-files workflow whose trigger cannot run it on a session
|
|
289
|
+
* branch, or which cannot be dispatched (#599). `readFile(relPath)` returns the text or null;
|
|
290
|
+
* `trunk` is project.yml's value (`main` when absent). Returns
|
|
291
|
+
* [{ workflow, narrowed:[branch…], dispatchable:boolean, text }] — only callers with a problem.
|
|
292
|
+
*/
|
|
293
|
+
function instructionFilesCallerFindings({ readFile, workflows, trunk }) {
|
|
294
|
+
const out = [];
|
|
295
|
+
for (const wf of workflows || []) {
|
|
296
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
297
|
+
if (!isInstructionFilesCaller(text)) continue;
|
|
298
|
+
const on = parseWorkflowOn(text);
|
|
299
|
+
const probes = [trunk || "main", ...SESSION_BRANCH_PROBES];
|
|
300
|
+
const narrowed = probes.filter((b) => !workflowFiresOnBranchPush(on, b));
|
|
301
|
+
const dispatchable = on.events.has("workflow_dispatch");
|
|
302
|
+
if (!narrowed.length && dispatchable) continue;
|
|
303
|
+
const why = [];
|
|
304
|
+
if (narrowed.length) {
|
|
305
|
+
why.push(!on.events.has("push")
|
|
306
|
+
? "has no push trigger, so it never runs on a session branch"
|
|
307
|
+
: `its push trigger does not fire on ${narrowed.slice(0, 3).join(", ")}${narrowed.length > 3 ? ` (+${narrowed.length - 3} more)` : ""}` +
|
|
308
|
+
" — the ratchet then fails first on trunk instead of on the branch that broke it");
|
|
309
|
+
}
|
|
310
|
+
if (!dispatchable) {
|
|
311
|
+
why.push("it declares no workflow_dispatch, so a cure branch cannot prove the job by dispatch (#510) and a red trunk ships only through a human ci-grant");
|
|
312
|
+
}
|
|
313
|
+
out.push({
|
|
314
|
+
workflow: wf, narrowed, dispatchable,
|
|
315
|
+
text:
|
|
316
|
+
`.github/workflows/${wf} calls the reusable instruction-files workflow, but ${why.join("; and ")}. ` +
|
|
317
|
+
"Fix: use the template trigger — an unfiltered `push:`, `pull_request:` and `workflow_dispatch:` " +
|
|
318
|
+
"(templates/instruction-files.yml; handbook-sync grafts it) (#599)",
|
|
319
|
+
});
|
|
320
|
+
}
|
|
321
|
+
return out;
|
|
322
|
+
}
|
|
323
|
+
|
|
268
324
|
// --------------------------------------------------- workflow_dispatch inputs (#474)
|
|
269
325
|
//
|
|
270
326
|
// The names declared under `on: workflow_dispatch: inputs:`, in order. `[]` for a bare
|
|
@@ -318,4 +374,5 @@ module.exports = {
|
|
|
318
374
|
workflowFiresOnBranchPush, workflowsFiringOnBranchPush,
|
|
319
375
|
isDeployWorkflow, isReleaseTagTemplateCopy, prereleaseTagTriggers,
|
|
320
376
|
workflowDispatchInputs, workflowNameOf,
|
|
377
|
+
SESSION_BRANCH_PROBES, isInstructionFilesCaller, instructionFilesCallerFindings,
|
|
321
378
|
};
|