@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.2

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.
Files changed (37) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +101 -11
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/tools/colab +750 -67
  14. package/tools/lib/batch-stats.js +66 -43
  15. package/tools/lib/claim-comments.js +3 -2
  16. package/tools/lib/codec/decision.d.ts +7 -0
  17. package/tools/lib/codec/decision.js +54 -0
  18. package/tools/lib/codec/hold.d.ts +8 -1
  19. package/tools/lib/codec/hold.js +42 -8
  20. package/tools/lib/codec/release.js +6 -3
  21. package/tools/lib/codec/samples.json +45 -0
  22. package/tools/lib/config-set.js +4 -3
  23. package/tools/lib/decision-record.js +42 -0
  24. package/tools/lib/docs-only.js +47 -0
  25. package/tools/lib/git.js +57 -8
  26. package/tools/lib/instruction-file.js +49 -0
  27. package/tools/lib/instruction-gate.js +150 -0
  28. package/tools/lib/landed-prs.js +58 -0
  29. package/tools/lib/migration-grant.js +29 -5
  30. package/tools/lib/owner-policy.js +133 -0
  31. package/tools/lib/release-finalize.js +66 -5
  32. package/tools/lib/ship-batch.js +188 -14
  33. package/tools/lib/ship-handoff.js +174 -0
  34. package/tools/lib/stamp.js +6 -2
  35. package/tools/lib/template-trunk.js +80 -0
  36. package/tools/lib/tree-green.js +21 -4
  37. package/tools/lib/workflow-triggers.js +57 -0
@@ -0,0 +1,80 @@
1
+ 'use strict';
2
+ /**
3
+ * Trunk substitution for a copied CI template (#526). Pure: text in, text out, no I/O.
4
+ *
5
+ * The CI templates protect two refs by name — `main` and `dev` — in three places: the concurrency
6
+ * `group`, `cancel-in-progress`, and the `dedupe` guard's `if:`. Those names are the defaults of the
7
+ * two shapes a repo can have, not facts about any one repo. Copied verbatim into a repo whose trunk
8
+ * is `master`, the trunk runs become cancellable (the deadlock CONVENTIONS §4 warns about) and the
9
+ * tree-reuse guard never fires there. `colab template` knows the trunk — it is in
10
+ * `.github/project.yml` — so it writes the right refs instead of leaving an EDIT point.
11
+ *
12
+ * Which refs a repo protects:
13
+ * - one branch (trunk `main`, or any trunk on a repo with no release branch) → `[trunk]`;
14
+ * - two branches (trunk ≠ `main` where the promotion into `main` releases — exposure live or
15
+ * released, or legacy tier A/C) → `['main', trunk]`.
16
+ *
17
+ * The Laravel template's test tier also names `main` as the branch whose suite gates a release;
18
+ * on a one-branch repo that branch is the trunk, so it is rewritten too.
19
+ *
20
+ * Only the exact expression shapes the templates ship are rewritten. A copy whose shape was
21
+ * already edited is left alone and reported as `missed`, never guessed at.
22
+ */
23
+
24
+ const TEMPLATE_REFS = ['main', 'dev'];
25
+
26
+ /** The refs a repo's CI protects, from its parsed descriptor. null when no `trunk:` is declared. */
27
+ function protectedRefs(doc) {
28
+ const trunk = doc && typeof doc.trunk === 'string' && doc.trunk.trim() ? doc.trunk.trim() : null;
29
+ if (!trunk) return null;
30
+ const exposure = doc.exposure == null ? null : String(doc.exposure);
31
+ const tier = doc.tier == null ? null : String(doc.tier).toUpperCase();
32
+ const promotes = exposure === 'live' || exposure === 'released' || (exposure == null && (tier === 'A' || tier === 'C'));
33
+ const twoBranch = trunk !== 'main' && promotes;
34
+ return { trunk, twoBranch, refs: twoBranch ? ['main', trunk] : [trunk] };
35
+ }
36
+
37
+ const eq = (r) => `github.ref == 'refs/heads/${r}'`;
38
+ const ne = (r) => `github.ref != 'refs/heads/${r}'`;
39
+
40
+ /**
41
+ * Rewrite the template's `main`/`dev` refs to `p` (protectedRefs' result).
42
+ * Returns { text, changes: [what], missed: [what] }. `changes` is empty when the template's own
43
+ * refs are already right (a `dev` trunk with a `main` release branch).
44
+ */
45
+ function substituteTrunk(text, p) {
46
+ const changes = [];
47
+ const missed = [];
48
+ let out = text;
49
+ const swap = (label, from, to) => {
50
+ if (!out.includes(from)) { missed.push(label); return; }
51
+ if (from !== to) { out = out.split(from).join(to); changes.push(label); }
52
+ };
53
+ const tplEq = TEMPLATE_REFS.map(eq);
54
+ swap('concurrency group', `(${tplEq.join(' || ')}) && format(`, `(${p.refs.map(eq).join(' || ')}) && format(`);
55
+ swap('cancel-in-progress', `cancel-in-progress: \${{ ${TEMPLATE_REFS.map(ne).join(' && ')} }}`,
56
+ `cancel-in-progress: \${{ ${p.refs.map(ne).join(' && ')} }}`);
57
+ swap("dedupe guard's if:", `github.event.created || ${tplEq.join(' || ')})`, `github.event.created || ${p.refs.map(eq).join(' || ')})`);
58
+ // ci-laravel's test tier (only present there): the release-gating branch is the trunk on a one-branch repo.
59
+ if (!p.twoBranch && p.trunk !== 'main' && out.includes('[ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]')) {
60
+ out = out.split('[ "$BASE_REF" = "main" ]').join(`[ "$BASE_REF" = "${p.trunk}" ]`);
61
+ out = out.split('[ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]')
62
+ .join(`[ "$REF" = "refs/heads/${p.trunk}" ] || [ "$trunk" = "${p.trunk}" ]`);
63
+ changes.push('test tier');
64
+ }
65
+ return { text: out, changes, missed };
66
+ }
67
+
68
+ /**
69
+ * What `colab template <name>` writes for a repo whose descriptor is `doc`: the body with this
70
+ * repo's refs when `name` is a CI template and a trunk is declared, else the body unchanged.
71
+ * `colab update` uses the same rendering both to recognise a pristine copy and to refresh one, so
72
+ * a refreshed file stays byte-identical to what `colab template <name> --force` would write.
73
+ */
74
+ function renderForRepo(name, body, doc) {
75
+ if (!/^ci-/.test(String(name || ''))) return body;
76
+ const p = protectedRefs(doc);
77
+ return p ? substituteTrunk(body, p).text : body;
78
+ }
79
+
80
+ module.exports = { TEMPLATE_REFS, protectedRefs, substituteTrunk, renderForRepo };
@@ -18,6 +18,8 @@
18
18
  */
19
19
 
20
20
  const NOTICE_TITLE = 'tree-already-green';
21
+ /** #570: the CI guard's docs-only mode leaves this notice instead — same run shape, a different reason. */
22
+ const DOCS_NOTICE_TITLE = 'docs-only-skip';
21
23
 
22
24
  /** `tree-reuse:` in project.yml. Absent = reuse on. `off` = the one legal value. */
23
25
  function parseTreeReuse(doc) {
@@ -72,17 +74,32 @@ function parseCitation(annotations) {
72
74
  return { url: m[1], runId, tree: m[2], head: m[3], branch: m[4] };
73
75
  }
74
76
 
77
+ /**
78
+ * #570: the docs-only notice in a check run's annotations (`base=<sha> files=<n> run=<url>`), or null.
79
+ * A docs-only skip has the same shape as a tree skip (the guard green, the rest skipped), so the
80
+ * reader must recognise it — otherwise it reads as a tree citation nobody can parse.
81
+ */
82
+ function parseDocsSkip(annotations) {
83
+ if (!Array.isArray(annotations)) return null;
84
+ const a = annotations.find((x) => x && x.title === DOCS_NOTICE_TITLE && typeof x.message === 'string');
85
+ if (!a) return null;
86
+ const m = a.message.trim().match(/^base=([0-9a-f]+)\s+files=(\d+)\s+run=(\S+)$/i);
87
+ if (!m) return null;
88
+ return { base: m[1], files: Number(m[2]), url: m[3] };
89
+ }
90
+
75
91
  /**
76
92
  * The verdict suffix for a green trunk read that relied on cited runs. `cites`: [{url, branch,
77
93
  * head, proof}] where proof is 'verified' | 'unverified'; `unreadable`: count of skip-runs whose
78
94
  * citation could not be read. '' when there is nothing to say (an ordinary green run).
79
95
  */
80
- function citationNote(cites, unreadable = 0) {
96
+ function citationNote(cites, unreadable = 0, docs = []) {
81
97
  const parts = (cites || []).map((c) =>
82
98
  `relied on ${c.url} (${c.branch}@${String(c.head).slice(0, 7)}${c.proof === 'verified' ? ', tree verified locally' : ', tree not verified locally'})`);
83
99
  for (let i = 0; i < unreadable; i++) parts.push('cited run unreadable');
84
- if (!parts.length) return '';
85
- return ` — tree already green (#493): suite skipped, ${parts.join('; ')}`;
100
+ const tree = parts.length ? ` — tree already green (#493): suite skipped, ${parts.join('; ')}` : '';
101
+ const doc = (docs || []).map((d) => `${d.files} path(s) since ${String(d.base).slice(0, 7)}, whose green run is ${d.url}`);
102
+ return tree + (doc.length ? ` — docs-only (#570): suite skipped, ${doc.join('; ')}` : '');
86
103
  }
87
104
 
88
- module.exports = { NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, citationNote };
105
+ module.exports = { NOTICE_TITLE, DOCS_NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, parseDocsSkip, citationNote };
@@ -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
  };