@futurelastic/colab-handbook 1.20.4-rc.3 → 1.20.4-rc.4

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
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.20.4-rc.3"
36
+ "version": "1.20.4-rc.4"
37
37
  }
package/tools/colab CHANGED
@@ -13514,8 +13514,9 @@ function shipMode(repoAbs, target, branch, commits) {
13514
13514
  * this ship actually closed, read its NATIVE parent and let lib/container-close.js decide; close
13515
13515
  * the parent with an evidence comment only on `close`, then ask the same question of ITS parent
13516
13516
  * (an epic of epics empties from the bottom up). Every other verdict leaves the parent exactly as
13517
- * it is; the ones a human should see (`not-container`, `unfiled-items`, `unknown`) are printed as
13518
- * findings. Best-effort like every post-merge write: a failure here warns, never fails the ship —
13517
+ * it is; the ones a human should see (`not-container`, `unfiled-items`, `done-when`, `unknown`)
13518
+ * are printed as findings. `done-when` (#713) also gets a one-line proposal comment on the epic —
13519
+ * every filed child is closed, but the body's `Done when` acceptance is the coordinator's to read. Best-effort like every post-merge write: a failure here warns, never fails the ship —
13519
13520
  * the merge already landed. A lagging `subIssuesSummary` reads as `children-open` and is caught by
13520
13521
  * the next ship of a sibling or by code-sweep §5, never by guessing.
13521
13522
  */
@@ -13540,6 +13541,10 @@ function shipCloseSpentContainers(repoAbs, closedIssues, { sha, target } = {}) {
13540
13541
  if (c.verdict !== 'close') {
13541
13542
  const finding = containerClose.containerFinding({ ...c, number: c.number === null ? pnum : c.number });
13542
13543
  if (finding) warn(`container ${finding}`);
13544
+ if (c.verdict === 'done-when') {
13545
+ const pc = git.ghIssueComment(repoAbs, pnum, containerClose.containerProposalComment({ child, sha, total: c.total, target }));
13546
+ if (!pc.ok) warnDeferred(`could not post the done-when proposal on #${pnum} — it stays open either way`);
13547
+ }
13543
13548
  break;
13544
13549
  }
13545
13550
  const body = containerClose.containerCloseComment({ child, sha, total: c.total, target });
@@ -20,6 +20,12 @@
20
20
  * - its body holds no unticked checklist line. An unticked `- [ ]` on an epic is an item
21
21
  * somebody listed and nobody filed as a sub-issue yet — the "two phases whose issues are not
22
22
  * written yet" B2c's rule was protecting. It is reported, never closed over;
23
+ * - its body states no `Done when` acceptance (#713). `file-issues` tells a filer to put an
24
+ * epic's end state in a `Done when:` line, never a body checklist — so on an epic written to
25
+ * that convention the unticked check above sees nothing, and a phase epic filed with only its
26
+ * design child (the code children to be filed once the design is approved) read as spent the
27
+ * moment that one child shipped. "Every filed child closed" says nothing about whether the
28
+ * stated end state holds; that reading is the coordinator's, so ship proposes and never closes;
23
29
  * - it is not a release tracking record (`<!-- colab:release …` body) — `colab release
24
30
  * finalize` owns that record's lifecycle, not a child's ship.
25
31
  *
@@ -36,6 +42,8 @@
36
42
  * children-open at least one sub-issue is still open — the normal state of a live epic
37
43
  * not-container every child closed, but no `epic` label — report for a human
38
44
  * unfiled-items every child closed, but the body still lists unticked items — report
45
+ * done-when every child closed, but the body states `Done when` acceptance — ship posts
46
+ * a one-line proposal for the coordinator to check it and close (#713)
39
47
  *
40
48
  * Fail toward keeping open, the same asymmetry `group-labels.js` states for its own delete: a
41
49
  * container closed early buries unwritten work behind a closed issue nobody browses, while one
@@ -52,6 +60,14 @@ const RELEASE_RECORD_RE = /^\s*<!--\s*colab:release\b/;
52
60
  /** An UNTICKED GitHub checklist line anywhere in the body — `- [ ] …` / `* [ ] …`. */
53
61
  const UNTICKED_RE = /^\s*[-*]\s*\[ \]\s*(.+)$/;
54
62
 
63
+ /**
64
+ * A `Done when` acceptance statement at the start of a line (#713): a heading (`## Done when`), a
65
+ * label line (`Done when:`, `**Done when:**`, `- Done when: …`), any case, `Done-when` too. Only at
66
+ * a line start, so prose that merely mentions the phrase mid-sentence does not count; a blockquote
67
+ * (`> Done when`) is a quotation, not this epic's own acceptance.
68
+ */
69
+ const DONE_WHEN_RE = /^\s*(?:#{1,6}\s+)?(?:[-*+]\s+)?(?:\*\*|__)?done[ -]when\b/i;
70
+
55
71
  function labelNames(labels) {
56
72
  return (labels || []).map((l) => (l && typeof l === 'object' ? l.name : l)).map((n) => String(n));
57
73
  }
@@ -70,6 +86,16 @@ function untickedItems(body) {
70
86
  return out;
71
87
  }
72
88
 
89
+ /** Does the body state `Done when` acceptance outside fenced code? (#713) */
90
+ function hasDoneWhen(body) {
91
+ let fenced = false;
92
+ for (const line of String(body || '').split('\n')) {
93
+ if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; continue; }
94
+ if (!fenced && DONE_WHEN_RE.test(line)) return true;
95
+ }
96
+ return false;
97
+ }
98
+
73
99
  /**
74
100
  * Classify ONE parent issue after a child of it closed.
75
101
  *
@@ -99,6 +125,7 @@ function classifyContainer(parent) {
99
125
  if (!labelNames(parent.labels).includes(EPIC_LABEL)) return { ...out, verdict: 'not-container' };
100
126
  const unticked = untickedItems(parent.body);
101
127
  if (unticked.length) return { ...out, unticked, verdict: 'unfiled-items' };
128
+ if (hasDoneWhen(parent.body)) return { ...out, verdict: 'done-when' };
102
129
  return { ...out, verdict: 'close' };
103
130
  }
104
131
 
@@ -120,6 +147,16 @@ function containerCloseComment({ child, sha, total, target }) {
120
147
  return `📦 Closed by colab ship — ${via}${at}; all ${total} sub-issue(s) are closed and the body lists no unticked item (#371).`;
121
148
  }
122
149
 
150
+ /**
151
+ * The proposal comment posted on an epic whose verdict is `done-when` (#713) — the epic stays OPEN.
152
+ * One line, issue-specific only: which child emptied it, and what the coordinator checks next.
153
+ */
154
+ function containerProposalComment({ child, sha, total, target }) {
155
+ const via = child ? `its last open sub-issue #${child} shipped` : 'its last open sub-issue closed';
156
+ const at = sha ? ` to ${target || 'trunk'} at ${sha}` : '';
157
+ return `📋 All ${total} sub-issue(s) closed — ${via}${at}. Left open: check \`Done when\` and close if met, or file the remaining work as sub-issues (#713).`;
158
+ }
159
+
123
160
  /** One report line for a verdict that is NOT `close` but still worth a human's eye; null otherwise. */
124
161
  function containerFinding(c) {
125
162
  const n = c.number !== null ? `#${c.number}` : 'parent';
@@ -128,6 +165,8 @@ function containerFinding(c) {
128
165
  return `${n}: all ${c.total} sub-issue(s) closed, but it is not labelled \`epic\` — close it by hand if it is a container`;
129
166
  case 'unfiled-items':
130
167
  return `${n}: all ${c.total} sub-issue(s) closed, but ${c.unticked.length} unticked item(s) remain in its body — file them as sub-issues or tick them, then close`;
168
+ case 'done-when':
169
+ return `${n}: all ${c.total} sub-issue(s) closed, but its body states \`Done when\` — left open for the coordinator to check it`;
131
170
  case 'unknown':
132
171
  return `${n}: could not read the parent — container close skipped`;
133
172
  default:
@@ -173,7 +212,8 @@ function parentRelationFinding(rel) {
173
212
  }
174
213
 
175
214
  module.exports = {
176
- EPIC_LABEL, RELEASE_RECORD_RE,
215
+ EPIC_LABEL, RELEASE_RECORD_RE, DONE_WHEN_RE,
177
216
  issueRepoSlug, parentRelation, parentRelationFinding,
178
- untickedItems, classifyContainer, containerDeliveryLabels, containerCloseComment, containerFinding,
217
+ untickedItems, hasDoneWhen, classifyContainer, containerDeliveryLabels, containerCloseComment,
218
+ containerProposalComment, containerFinding,
179
219
  };