@intentius/behold 0.29.40 → 0.29.42

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 (61) hide show
  1. package/AGENTS.md +180 -10
  2. package/README.md +6 -2
  3. package/dist/cli.js +16121 -13141
  4. package/example-writes/README.md +1 -1
  5. package/example-writes/chant.config.ts +0 -6
  6. package/package.json +5 -2
  7. package/web/app.js +327 -21
  8. package/web/carve-export.js +142 -0
  9. package/web/carve-narration.js +294 -0
  10. package/web/carve-narration.test.js +48 -0
  11. package/web/change-set-overlay.js +147 -0
  12. package/web/change-set-overlay.test.js +83 -0
  13. package/web/dots-border.js +66 -0
  14. package/web/dots-border.test.js +27 -0
  15. package/web/dots-kiosk.js +279 -0
  16. package/web/dots-kiosk.test.js +60 -0
  17. package/web/dots-layout.d.ts +10 -0
  18. package/web/dots-layout.js +201 -0
  19. package/web/dots-live.js +316 -0
  20. package/web/dots-live.test.js +220 -0
  21. package/web/dots-lod.js +122 -0
  22. package/web/dots-lod.test.js +78 -0
  23. package/web/dots-recording.d.ts +7 -0
  24. package/web/dots-recording.js +247 -0
  25. package/web/dots-recording.test.js +71 -0
  26. package/web/dots-scene.js +294 -0
  27. package/web/dots-scene.test.js +118 -0
  28. package/web/dots-timeline.js +128 -0
  29. package/web/dots-timeline.test.js +83 -0
  30. package/web/dots-tour.js +153 -0
  31. package/web/dots.js +2124 -0
  32. package/web/dots.test.js +15 -0
  33. package/web/event-help-modal.js +1 -1
  34. package/web/index.html +215 -121
  35. package/web/kiosk-carve.js +225 -0
  36. package/web/kiosk-carve.test.js +26 -0
  37. package/web/kiosk-event-help-ui.js +7 -1
  38. package/web/kiosk-link.js +68 -0
  39. package/web/kiosk-link.test.js +69 -0
  40. package/web/kiosk-metrics.js +2 -2
  41. package/web/kiosk-trace.js +1 -1
  42. package/web/kiosk.html +186 -135
  43. package/web/kiosk.js +65 -7
  44. package/web/motion.js +42 -0
  45. package/web/motion.test.js +64 -0
  46. package/web/operator.js +1 -1
  47. package/web/run-playhead.js +102 -19
  48. package/web/run-playhead.test.js +81 -11
  49. package/web/terralith.html +2 -2
  50. package/web/theme.js +99 -26
  51. package/web/theme.test.js +70 -6
  52. package/web/tooltip.js +212 -0
  53. package/web/tooltip.test.js +193 -0
  54. package/web/tour-player.js +204 -0
  55. package/web/tour-player.test.js +115 -0
  56. package/web/tours/behold.tour.v1.schema.json +182 -0
  57. package/web/tours/terralith.json +330 -0
  58. package/web/trunk-lane.js +406 -0
  59. package/web/trunk-lane.test.js +224 -0
  60. package/web/workspace-gates.js +29 -4
  61. package/web/workspace-gates.test.js +23 -2
@@ -0,0 +1,406 @@
1
+ // #680: the trunk lane. Pure words from /api/workspace/lane, and one render.
2
+ // First the trunk's recent commits, each green, revoked or undecided, with its
3
+ // work items and runs and where it is now. Then one lane per environment in
4
+ // the promotion order chant declares: what the environment runs, and the
5
+ // gates waiting there, each with the approve button the gate strip uses
6
+ // (approveAffordance, #690), and the change set it binds as the link that
7
+ // draws it on the graph (#681). Between the two, the releases cut from those
8
+ // commits (#692): each with its cut, a config-only mark, a revoked mark with
9
+ // the rollback line, where it runs and waits, and the environment it is
10
+ // promoted to next. Nothing here is behold's own state.
11
+
12
+ import { ago, clock } from "./terragucci.js";
13
+ import { approveAffordance, HOST_APPROVES, overrideCard } from "./workspace-gates.js";
14
+
15
+ const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
16
+ const sha7 = (s) => (s ? String(s).slice(0, 7) : "");
17
+ const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
18
+
19
+ /** The note under the legend: chant ci list reads local tags only. */
20
+ export const UNDECIDED_NOTE = "undecided: no ci tag yet. chant ci list reads local tags, so a commit that failed without ever going green also reads undecided.";
21
+
22
+ /** The lane's first line: what was read, or why it wasn't. */
23
+ export function laneLegend(a, now = new Date()) {
24
+ if (!a || a.error) return { text: `lane not read${a && a.error ? `: ${a.error}` : ""}`, title: "", tone: "refusal" };
25
+ if (a.refusal) return { text: `lane not read: ${a.refusal.error}`, title: a.refusal.remedy || "", tone: "refusal" };
26
+ const when = a.read ? ` · read ${ago(a.read.at, now)}` : "";
27
+ if (!a.trunk) return { text: `trunk not read: ${a.trunkRefusal ? a.trunkRefusal.error : "chant ci list gave no answer"}${when}`, title: (a.trunkRefusal && a.trunkRefusal.remedy) || "", tone: "refusal" };
28
+ const span = a.trunk.since ? `after ${sha7(a.trunk.since)}` : `within ${a.trunk.window}`;
29
+ return { text: `trunk ${a.trunk.branch} · ${plural(a.commits.length, "commit")} ${span}${when}`, title: UNDECIDED_NOTE, tone: "quiet" };
30
+ }
31
+
32
+ /** A commit's work items in words, as chant#4029 links them; null when chant said nothing. */
33
+ export function workWords(work) {
34
+ if (!work) return null;
35
+ if (work.state === "linked") return { text: `work ${work.ids.join(", ")}`, title: "" };
36
+ if (work.state === "unlinked") return { text: "no work item", title: "No Chant-Record or Chant-Lease trailer names one." };
37
+ if (work.state === "wrong") return { text: "names a work item that does not exist", title: work.problems.map((p) => `${p.trailer}: ${p.message}`).join("\n") };
38
+ if (work.state === "merge") return { text: "merge commit", title: "Its work is the commits it brings." };
39
+ return null;
40
+ }
41
+
42
+ /** Where a commit is, in words: "runs in staging, waits in prod". */
43
+ export function whereWords(where) {
44
+ return (where || []).map((w) => (w.what === "runs" ? `runs in ${w.env}` : `waits in ${w.env}`)).join(", ");
45
+ }
46
+
47
+ /** The runs behind a commit's state, each a link: every phase's runs, and the run a revoked tag names. */
48
+ export function commitRuns(c) {
49
+ const out = [];
50
+ const seen = new Set();
51
+ const add = (r) => {
52
+ if (!r || !r.url || seen.has(r.url)) return;
53
+ seen.add(r.url);
54
+ out.push({ text: r.name, href: r.url, title: r.conclusion ? `${r.name}: ${r.conclusion}` : r.name });
55
+ };
56
+ for (const p of c.phases || []) for (const r of p.runs) add(r);
57
+ if (c.revoked) add(c.revoked.run);
58
+ return out;
59
+ }
60
+
61
+ /** One trunk commit's row. */
62
+ export function commitRow(c, now = new Date()) {
63
+ const facts = [];
64
+ const work = workWords(c.work);
65
+ if (c.revoked) facts.push({ text: `revoked: ${c.revoked.phase || "a phase"} failed`, title: "" });
66
+ // #692: the releases cut from it.
67
+ if (c.cuts && c.cuts.length) facts.push({ text: `cut as ${c.cuts.map((x) => x.label || short(x.releaseDigest)).join(", ")}`, title: c.cuts.map((x) => `release ${x.releaseDigest} of ${x.member}`).join("\n") });
68
+ if (work) facts.push(work);
69
+ if (c.ignored && c.ignored.length) facts.push({ text: `${plural(c.ignored.length, "ci tag")} not counted`, title: c.ignored.map((t) => `${t.tag} (${t.status}): ${t.reason}`).join("\n") });
70
+ return {
71
+ sha: c.sha,
72
+ head: `${sha7(c.sha)} ${c.state}`,
73
+ state: c.state,
74
+ when: ago(c.committed, now),
75
+ title: `${c.sha}\ncommitted ${clock(c.committed, now)}${c.state === "undecided" ? `\n${UNDECIDED_NOTE}` : ""}`,
76
+ where: whereWords(c.where),
77
+ facts,
78
+ runs: commitRuns(c),
79
+ };
80
+ }
81
+
82
+ /** What one environment runs, line by line; `no deploy record` when chant has none. */
83
+ export function runsLines(e, now = new Date()) {
84
+ const lines = [];
85
+ for (const r of e.releases || []) {
86
+ const rollback = r.rollback || [];
87
+ lines.push({
88
+ text: `runs ${r.label || short(r.releaseDigest)}, cut from ${sha7(r.commit)}${r.listed ? "" : " (older than the trunk list)"} · ${r.components.join(", ")}${rollback.length ? " · revoked" : ""}`,
89
+ title: [
90
+ `release ${r.releaseDigest} of ${r.member}`,
91
+ r.cutBy ? `cut by ${r.cutBy}${r.cutAt ? ` ${clock(r.cutAt, now)}` : ""}` : "",
92
+ r.approver ? `deploy approved by ${r.approver}` : "",
93
+ ...rollback.map((l) => `roll back: ${l}`),
94
+ ]
95
+ .filter(Boolean)
96
+ .join("\n"),
97
+ ...(rollback.length ? { revoked: true } : {}),
98
+ });
99
+ }
100
+ for (const d of e.deploys || []) {
101
+ const from = d.release ? `release ${d.release.label || short(d.release.releaseDigest)}, ` : "";
102
+ lines.push({
103
+ text: `runs ${d.component} ${short(d.digest)} from ${from}${sha7(d.gitSha)}${d.listed ? "" : " (older than the trunk list)"}${d.rollback ? " · revoked" : ""}`,
104
+ title: `deploy record of ${d.member}, run ${d.runId}, by ${d.actor} ${ago(d.timestamp, now)}${d.approver ? `, approved by ${d.approver}` : ""}${d.rollback ? `\nroll back: ${d.rollback}` : ""}`,
105
+ ...(d.rollback ? { revoked: true } : {}),
106
+ });
107
+ }
108
+ if (!lines.length) lines.push({ text: "no deploy record", title: "chant has no deploy record for this environment, so behold does not say what runs here." });
109
+ return lines;
110
+ }
111
+
112
+ /** A release's name: its label, else its digest, short. */
113
+ const releaseName = (r) => (r ? r.label || short(r.releaseDigest) : "");
114
+
115
+ /** A cut's signature in words, from chant's own check of it (chant#4031). */
116
+ export function signatureWords(sig) {
117
+ if (!sig) return null;
118
+ if (sig.status === "verified") return { text: "signed", title: sig.reason || "chant verified the cut's signature." };
119
+ if (sig.status === "unsigned") return { text: "unsigned", title: sig.reason || "The cut carries no signature." };
120
+ return { text: "signature does not count", title: sig.reason || "" };
121
+ }
122
+
123
+ /** The note under the releases heading when the project's chant is below the column's floor. */
124
+ export function releaseColumnNote(a) {
125
+ if (!a || !a.releaseColumn || a.releaseColumn.full) return null;
126
+ return `chant ${a.chant || "(unknown version)"} does not say which releases are revoked; chant ${a.releaseColumn.floor} and newer does.`;
127
+ }
128
+
129
+ /**
130
+ * One release in the column (#692): its name and marks, its cut, where it is
131
+ * and where it goes next, and, when revoked, what failed and the line that
132
+ * rolls it back.
133
+ */
134
+ export function releaseRow(r, now = new Date()) {
135
+ const marks = [];
136
+ if (r.configOnly) marks.push({ text: "config-only", cls: "lane-config-only", title: `The same artifact digests as ${releaseName(r.previous)}: only configuration changed.` });
137
+ if (r.revoked) marks.push({ text: "revoked", cls: "lane-revoked", title: `${r.revoked.tag}${r.revoked.tagged ? `, tagged ${clock(r.revoked.tagged, now)}` : ""}. chant promotes no revoked release and counts no approval of it.` });
138
+ const facts = [];
139
+ if (r.cut) {
140
+ facts.push({ text: `cut by ${r.cut.by} ${ago(r.cut.at, now)}`, title: clock(r.cut.at, now) });
141
+ const sig = signatureWords(r.cut.signature);
142
+ if (sig) facts.push(sig);
143
+ } else facts.push({ text: "no cut recorded", title: "chant stores the release, but no cut names it." });
144
+ if (r.artifacts === 0) facts.push({ text: "no artifact digests", title: "The member builds no image or asset, so no release of it is config-only." });
145
+
146
+ const where = [];
147
+ for (const x of r.runs) where.push({ text: `runs in ${x.env}`, title: x.components.join(", ") });
148
+ for (const w of r.waits) where.push(w.state === "superseded" ? { text: `gate in ${w.env} superseded`, title: `${w.gate}: its release is revoked, so no approval of it counts.` } : { text: `waits in ${w.env}`, title: `at gate ${w.gate}` });
149
+ if (r.next && !r.waits.some((w) => w.env === r.next)) where.push({ text: `next: ${r.next}`, title: "The next environment in the promotion order chant declares." });
150
+ if (!r.runs.length && !r.waits.length && !r.next) where.push({ text: "runs nowhere", title: "" });
151
+
152
+ const revoked = r.revoked
153
+ ? {
154
+ text: `revoked: ${r.revoked.phase || "a required phase"} failed`,
155
+ run: r.revoked.run && r.revoked.run.url ? { text: r.revoked.run.name, href: r.revoked.run.url, title: r.revoked.run.conclusion ? `${r.revoked.run.name}: ${r.revoked.run.conclusion}` : r.revoked.run.name } : null,
156
+ rollback: r.revoked.rollback.map((l) => `roll back: ${l}`),
157
+ }
158
+ : null;
159
+ return {
160
+ key: r.releaseDigest,
161
+ head: `${releaseName(r)} · ${r.member}`,
162
+ cutFrom: `cut from ${sha7(r.commit)}${r.listed ? "" : " (older than the trunk list)"}`,
163
+ title: `release ${r.releaseDigest}\ncommit ${r.commit}${r.previous ? `\nprevious release ${releaseName(r.previous)}` : ""}`,
164
+ marks,
165
+ facts,
166
+ where,
167
+ revoked,
168
+ };
169
+ }
170
+
171
+ /** A release gate chant reads as superseded, as a line in its environment. */
172
+ export function supersededLine(g, a) {
173
+ const r = ((a && a.releases) || []).find((x) => x.releaseDigest === g.releaseDigest);
174
+ return {
175
+ text: `${g.key} superseded: release ${r ? releaseName(r) : short(g.releaseDigest)} is revoked (${g.revoked.phase || "a required phase"} failed)`,
176
+ title: `${g.revoked.tag}\nchant approve refuses this gate, and chant promotes no revoked release.${g.runId ? `\nrun ${g.runId}` : ""}`,
177
+ };
178
+ }
179
+
180
+ /** One waiting gate as a card, with the gate strip's approve button (or the note in its place). */
181
+ export function laneGateCard(g, answer, { embed = false } = {}) {
182
+ if (g.override) {
183
+ const o = overrideCard(g);
184
+ return { key: g.key, title: o.title, facts: o.facts, note: o.note, command: o.command };
185
+ }
186
+ const facts = [];
187
+ facts.push(g.gitSha ? `for ${sha7(g.gitSha)}${g.commitState ? ` (${g.commitState})` : ""}` : "commit unknown");
188
+ facts.push(`${g.approvals.length} of ${plural(g.needed, "approval")}`);
189
+ if (g.runId) facts.push(`run ${g.runId}`);
190
+ if (g.releaseDigest) facts.push(`release ${short(g.releaseDigest)}`);
191
+ if (g.approvals.length) facts.push(`approved by ${g.approvals.map((a) => a.principal).join(", ")}`);
192
+ const show = g.changeSet ? `chant change-set show ${g.changeSet} --member ${g.member}` : null;
193
+ const card = {
194
+ key: g.key,
195
+ title: `${g.member}: ${g.op} waits at gate ${g.gate}`,
196
+ facts: facts.join(" · "),
197
+ command: show ? `${g.approve}\n${show}` : g.approve,
198
+ };
199
+ // #681: the change set is a link that draws it on the graph.
200
+ if (g.changeSet) card.changeSet = { text: `change set ${short(g.changeSet)}`, title: `Draw this change set on the graph, as a preview.\n${show}` };
201
+ if (embed) card.note = HOST_APPROVES;
202
+ else Object.assign(card, approveAffordance(g, answer));
203
+ return card;
204
+ }
205
+
206
+ /** The whole lane as words: the legend, the commits, and a lane per environment. Pure. */
207
+ export function laneView(a, now = new Date(), opts = {}) {
208
+ const legend = laneLegend(a, now);
209
+ if (!a || a.error || a.refusal) return { legend, notes: [], commits: [], releases: null, environments: [] };
210
+ const notes = [];
211
+ if (a.order === "env" && a.environments.length) notes.push(`no member declares a promotion order, so this is ${a.environments[0].env} alone`);
212
+ for (const r of a.releaseRefusals || []) notes.push(`releases of ${r.member} not read: ${r.refusal.error}`);
213
+ return {
214
+ legend,
215
+ notes,
216
+ commits: (a.commits || []).map((c) => commitRow(c, now)),
217
+ empty: a.trunk && !(a.commits || []).length ? `no commits ${a.trunk.since ? `after ${sha7(a.trunk.since)}` : `within ${a.trunk.window}`}` : null,
218
+ // #692: null when the answer has no column (an older behold's export).
219
+ releases: a.releases
220
+ ? {
221
+ note: releaseColumnNote(a),
222
+ empty: !a.releases.length ? "no release cut yet" : null,
223
+ rows: a.releases.map((r) => releaseRow(r, now)),
224
+ }
225
+ : null,
226
+ environments: (a.environments || []).map((e) => ({
227
+ env: e.env,
228
+ heading: e.canary ? `${e.env} (canary)` : e.env,
229
+ refusal: e.refusal ? `not read: ${e.refusal.error}` : null,
230
+ runs: e.refusal ? [] : runsLines(e, now),
231
+ superseded: (e.superseded || []).map((g) => supersededLine(g, a)),
232
+ gates: (e.waiting || []).filter((g) => g.state === "pending" || g.override).map((g) => laneGateCard(g, a, opts)),
233
+ })),
234
+ };
235
+ }
236
+
237
+ /**
238
+ * Render into `host`. `ui.button(label, cls, onClick)` and `ui.link(text,
239
+ * href)` are app.js's; `ui.approve(key, env, button)` posts the approval;
240
+ * `ui.embed` and `ui.canApprove` say whether a button may be drawn;
241
+ * `ui.openChangeSet(key, env)` draws a gate's change set on the graph (#681).
242
+ */
243
+ export function renderTrunkLane(host, a, now, ui) {
244
+ host.replaceChildren();
245
+ const v = laneView(a, now, { embed: !!(ui && ui.embed) });
246
+ const line = (cls, text, title) => {
247
+ const d = document.createElement("div");
248
+ d.className = cls;
249
+ d.textContent = text;
250
+ if (title) d.title = title;
251
+ host.appendChild(d);
252
+ return d;
253
+ };
254
+ line(v.legend.tone === "refusal" ? "tg-refusal" : "tg-legend", v.legend.text, v.legend.title);
255
+ for (const n of v.notes) line("tg-legend", n);
256
+ if (!v.commits.length && !v.environments.length && !(v.releases && v.releases.rows.length)) return;
257
+
258
+ const h = document.createElement("h3");
259
+ h.textContent = "trunk";
260
+ host.appendChild(h);
261
+ if (v.empty) line("tg-legend", v.empty);
262
+ for (const c of v.commits) {
263
+ const row = document.createElement("div");
264
+ row.className = "lane-commit";
265
+ row.dataset.sha = c.sha;
266
+ row.title = c.title;
267
+ const head = document.createElement("div");
268
+ const state = document.createElement("span");
269
+ state.className = `lane-sha lane-${c.state}`;
270
+ state.textContent = c.head;
271
+ head.append(state, document.createTextNode(` · ${c.when}`));
272
+ if (c.where) {
273
+ const where = document.createElement("span");
274
+ where.className = "lane-where";
275
+ where.textContent = ` · ${c.where}`;
276
+ head.appendChild(where);
277
+ }
278
+ row.appendChild(head);
279
+ if (c.facts.length || c.runs.length) {
280
+ const facts = document.createElement("div");
281
+ facts.className = "lane-facts";
282
+ c.facts.forEach((f, i) => {
283
+ const s = document.createElement("span");
284
+ s.textContent = `${i ? " · " : ""}${f.text}`;
285
+ if (f.title) s.title = f.title;
286
+ facts.appendChild(s);
287
+ });
288
+ for (const r of c.runs) {
289
+ if (facts.childNodes.length) facts.appendChild(document.createTextNode(" · "));
290
+ const a = ui && ui.link ? ui.link(r.text, r.href) : document.createTextNode(r.text);
291
+ if (a.title !== undefined) a.title = r.title;
292
+ facts.appendChild(a);
293
+ }
294
+ row.appendChild(facts);
295
+ }
296
+ host.appendChild(row);
297
+ }
298
+
299
+ // #692: the release column, between the commits and the gates.
300
+ if (v.releases) {
301
+ const rh = document.createElement("h3");
302
+ rh.textContent = "releases";
303
+ host.appendChild(rh);
304
+ if (v.releases.note) line("tg-legend", v.releases.note);
305
+ if (v.releases.empty) line("tg-legend", v.releases.empty);
306
+ for (const r of v.releases.rows) {
307
+ const row = document.createElement("div");
308
+ row.className = "lane-release";
309
+ row.dataset.release = r.key;
310
+ row.title = r.title;
311
+ const head = document.createElement("div");
312
+ const name = document.createElement("span");
313
+ name.className = "lane-sha";
314
+ name.textContent = r.head;
315
+ head.append(name, document.createTextNode(` · ${r.cutFrom}`));
316
+ for (const m of r.marks) {
317
+ const mark = document.createElement("span");
318
+ mark.className = m.cls;
319
+ mark.textContent = ` · ${m.text}`;
320
+ mark.title = m.title;
321
+ head.appendChild(mark);
322
+ }
323
+ row.appendChild(head);
324
+ const parts = (cls, items) => {
325
+ const d = document.createElement("div");
326
+ d.className = cls;
327
+ items.forEach((f, i) => {
328
+ const sp = document.createElement("span");
329
+ sp.textContent = `${i ? " · " : ""}${f.text}`;
330
+ if (f.title) sp.title = f.title;
331
+ d.appendChild(sp);
332
+ });
333
+ row.appendChild(d);
334
+ return d;
335
+ };
336
+ parts("lane-facts", r.facts);
337
+ if (r.where.length) parts("lane-where", r.where);
338
+ if (r.revoked) {
339
+ const rv = parts("lane-revoked-why", [{ text: r.revoked.text }]);
340
+ if (r.revoked.run) {
341
+ rv.appendChild(document.createTextNode(" in "));
342
+ const a = ui && ui.link ? ui.link(r.revoked.run.text, r.revoked.run.href) : document.createTextNode(r.revoked.run.text);
343
+ if (a.title !== undefined) a.title = r.revoked.run.title;
344
+ rv.appendChild(a);
345
+ }
346
+ for (const l of r.revoked.rollback) {
347
+ const cmd = document.createElement("div");
348
+ cmd.className = "lane-rollback";
349
+ cmd.textContent = l;
350
+ row.appendChild(cmd);
351
+ }
352
+ }
353
+ host.appendChild(row);
354
+ }
355
+ }
356
+
357
+ for (const e of v.environments) {
358
+ const eh = document.createElement("h3");
359
+ eh.textContent = e.heading;
360
+ host.appendChild(eh);
361
+ if (e.refusal) line("tg-refusal", e.refusal);
362
+ for (const r of e.runs) line(r.revoked ? "lane-runs lane-runs-revoked" : "lane-runs", r.text, r.title);
363
+ for (const g of e.superseded) line("lane-superseded", g.text, g.title);
364
+ for (const g of e.gates) {
365
+ const box = document.createElement("div");
366
+ box.className = "ws-gate";
367
+ box.dataset.gate = g.key;
368
+ const title = document.createElement("div");
369
+ title.className = "ws-gate-title";
370
+ title.textContent = g.title;
371
+ const facts = document.createElement("div");
372
+ facts.className = "ws-gate-facts";
373
+ facts.textContent = g.facts;
374
+ facts.title = g.command;
375
+ // #681: the change set the gate binds, as the link that opens the overlay.
376
+ if (g.changeSet) {
377
+ facts.appendChild(document.createTextNode(" · "));
378
+ if (ui && ui.openChangeSet) {
379
+ const a = document.createElement("a");
380
+ a.href = "#";
381
+ a.className = "lane-change-set";
382
+ a.textContent = g.changeSet.text;
383
+ a.title = g.changeSet.title;
384
+ a.addEventListener("click", (ev) => {
385
+ ev.preventDefault();
386
+ ui.openChangeSet(g.key, e.env);
387
+ });
388
+ facts.appendChild(a);
389
+ } else facts.appendChild(document.createTextNode(g.changeSet.text));
390
+ }
391
+ box.append(title, facts);
392
+ if (g.note) {
393
+ const note = document.createElement("div");
394
+ note.className = "ws-gate-note";
395
+ note.textContent = g.note;
396
+ box.appendChild(note);
397
+ }
398
+ if (g.button && ui && ui.canApprove && ui.button && ui.approve) {
399
+ const b = ui.button(g.button.label, "approve", () => ui.approve(g.key, e.env, b));
400
+ b.title = g.button.title;
401
+ box.appendChild(b);
402
+ }
403
+ host.appendChild(box);
404
+ }
405
+ }
406
+ }
@@ -0,0 +1,224 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { commitRow, laneGateCard, laneLegend, laneView, releaseColumnNote, releaseRow, renderTrunkLane, runsLines, signatureWords, supersededLine, UNDECIDED_NOTE, whereWords, workWords } from "./trunk-lane.js";
3
+
4
+ const NOW = new Date("2026-10-05T10:00:00Z");
5
+ const C1 = "6828a7f5b398ea48543fe27c018ba302ce2aba14";
6
+ const C2 = "a14610e4f51778c969efcc77694a360412c34d88";
7
+ const C3 = "9c4250fa1ed203aa9c61eca708c8f0bbf4a06ddd";
8
+ const C4 = "0c7c85ae8cca01463f304a3bd69bc3e977899d5f";
9
+ const run = (id, conclusion) => ({ name: "test", url: `https://github.com/acme/app/actions/runs/${id}`, conclusion });
10
+
11
+ // The shape /api/workspace/lane answers for the #680 fixture workspace.
12
+ const gate = {
13
+ key: "web/web/promote",
14
+ member: "web",
15
+ op: "web",
16
+ gate: "promote",
17
+ env: "prod",
18
+ planDigest: "sha256:4b5e57f6eb2f42b9039b3d1e13929295f231749c510cbe341cd68036d9af97e2",
19
+ approvals: [],
20
+ needed: 1,
21
+ signed: false,
22
+ state: "pending",
23
+ approve: "chant approve web promote --env prod --plan sha256:4b5e57f6eb2f",
24
+ gitSha: C2,
25
+ runId: "run-9",
26
+ changeSet: "sha256:4b5e57f6eb2f42b9039b3d1e13929295f231749c510cbe341cd68036d9af97e2",
27
+ commitState: "green",
28
+ };
29
+ const answer = {
30
+ workspace: true,
31
+ chant: "0.124.28",
32
+ approver: "alex",
33
+ approverIdentity: { principal: "alex", source: "process", forge: false, signs: false },
34
+ read: { at: "2026-10-05T09:59:58Z" },
35
+ order: "promotion",
36
+ trunk: { branch: "main", ref: "refs/heads/main", window: "3650d", since: null, require: ["test"] },
37
+ commits: [
38
+ { sha: C4, committed: "2026-10-04T10:00:00Z", state: "undecided", phases: [{ phase: "test", result: "unrecorded", runs: [] }], revoked: null, work: { state: "linked", ids: ["task:12"], problems: [] }, ignored: [], where: [] },
39
+ { sha: C3, committed: "2026-10-03T10:00:00Z", state: "revoked", phases: [{ phase: "test", result: "fail", runs: [run(113, "failure")] }], revoked: { phase: "test", run: run(113, "failure") }, work: { state: "unlinked", ids: [], problems: [] }, ignored: [], where: [] },
40
+ { sha: C2, committed: "2026-10-02T10:00:00Z", state: "green", phases: [{ phase: "test", result: "pass", runs: [run(102, "success")] }], revoked: null, work: null, ignored: [], where: [{ env: "staging", what: "runs" }, { env: "prod", what: "waits", gate: "web/web/promote" }] },
41
+ { sha: C1, committed: "2026-10-01T10:00:00Z", state: "green", phases: [{ phase: "test", result: "pass", runs: [run(101, "success")] }], revoked: null, work: null, ignored: [], where: [{ env: "prod", what: "runs" }] },
42
+ ],
43
+ environments: [
44
+ { env: "staging", canary: false, members: ["web"], releases: [{ member: "web", label: "v2", releaseDigest: "jcs1-sha256:1a23268fa8b1fc419cffde4c1780f4387ff0346495f97bd9e22b0508bef99f9d", commit: C2, listed: true, components: ["web"], cutBy: "github:alice", cutAt: "2026-10-03T09:00:00Z", approver: null }], deploys: [], waiting: [] },
45
+ { env: "prod", canary: false, members: ["web"], releases: [{ member: "web", label: "v1", releaseDigest: "jcs1-sha256:e3956171ab72fcab2d812cbd3621ef18c04a46c96a9f1e1a8590dae0d9279185", commit: C1, listed: true, components: ["web"], cutBy: "github:alice", cutAt: "2026-10-02T09:00:00Z", approver: "github:alice" }], deploys: [], waiting: [gate] },
46
+ ],
47
+ releaseRefusals: [],
48
+ };
49
+
50
+ // #692: the release column of the same workspace (src/trunk-lane-fixture.ts):
51
+ // v1 from C1 running in prod, v2 from C2 with v1's image digest running in
52
+ // staging and waiting in prod, v3 from the revoked C3 with a new one.
53
+ const R1 = `jcs1-sha256:${"1".repeat(64)}`;
54
+ const R2 = `jcs1-sha256:${"2".repeat(64)}`;
55
+ const R3 = `jcs1-sha256:${"3".repeat(64)}`;
56
+ const revocation = { tag: `ci/revoked/${C3}`, tagged: "2026-10-05T00:00:00Z", phase: "test", run: run(113, "failure"), signer: null };
57
+ const ROLLBACK = "chant components rollback staging --component api";
58
+ const unsigned = { status: "unsigned", reason: "the cut carries no signature" };
59
+ const releases = [
60
+ { member: "web", releaseDigest: R3, label: "v3", commit: C3, listed: true, artifacts: 1, previous: { releaseDigest: R2, label: "v2" }, configOnly: false, cut: { by: "github:alice", at: "2026-10-04T09:00:00Z", signature: { status: "unverified", reason: "there is no signers file (.chant/allowed_signers) at base to check the cut's signature against" } }, revoked: { ...revocation, rollback: [ROLLBACK] }, runs: [{ env: "staging", components: ["api"] }], waits: [{ env: "prod", gate: "web/release/promote", state: "superseded" }], next: null },
61
+ { member: "web", releaseDigest: R2, label: "v2", commit: C2, listed: true, artifacts: 1, previous: { releaseDigest: R1, label: "v1" }, configOnly: true, cut: { by: "github:alice", at: "2026-10-03T09:00:00Z", signature: unsigned }, revoked: null, runs: [{ env: "staging", components: ["web"] }], waits: [{ env: "prod", gate: "web/web/promote", state: "pending" }], next: "prod" },
62
+ { member: "web", releaseDigest: R1, label: "v1", commit: C1, listed: true, artifacts: 1, previous: null, configOnly: null, cut: { by: "github:alice", at: "2026-10-02T09:00:00Z", signature: unsigned }, revoked: null, runs: [{ env: "prod", components: ["web"] }], waits: [], next: null },
63
+ ];
64
+ const superseded = { key: "web/release/promote", member: "web", op: "release", gate: "promote", env: "prod", releaseDigest: R3, gitSha: C3, runId: "run-12", revoked: revocation };
65
+ const column = {
66
+ ...answer,
67
+ chant: "0.124.29",
68
+ releases,
69
+ releaseColumn: { full: true, floor: "0.124.29" },
70
+ commits: answer.commits.map((c, i) => ({ ...c, cuts: [[], [{ member: "web", releaseDigest: R3, label: "v3" }], [{ member: "web", releaseDigest: R2, label: "v2" }], [{ member: "web", releaseDigest: R1, label: "v1" }]][i] })),
71
+ environments: [
72
+ { ...answer.environments[0], releases: [{ member: "web", label: "v3", releaseDigest: R3, commit: C3, listed: true, components: ["api"], cutBy: "github:alice", cutAt: "2026-10-04T09:00:00Z", approver: null, rollback: [ROLLBACK] }, { ...answer.environments[0].releases[0], rollback: [] }], superseded: [] },
73
+ { ...answer.environments[1], superseded: [superseded] },
74
+ ],
75
+ };
76
+
77
+ describe("laneLegend (#680)", () => {
78
+ it("names the branch, the count and the window, and carries the undecided caveat", () => {
79
+ expect(laneLegend(answer, NOW)).toEqual({ text: "trunk main · 4 commits within 3650d · read just now", title: UNDECIDED_NOTE, tone: "quiet" });
80
+ });
81
+ it("says why when the lane or the trunk wasn't read", () => {
82
+ const refusal = { error: "Trunk commits needs chant 0.124.28 or newer. This project has chant 0.124.24.", code: "chant-too-old", remedy: "Upgrade @intentius/chant to 0.124.28 or newer in the project." };
83
+ expect(laneLegend({ workspace: true, refusal }, NOW)).toEqual({ text: `lane not read: ${refusal.error}`, title: refusal.remedy, tone: "refusal" });
84
+ const noGreen = { ...answer, trunk: null, commits: [], trunkRefusal: { error: "chant ci list: the workspace declares no ci.green", code: "ci-green-undeclared", remedy: "Declare ci.green" } };
85
+ expect(laneLegend(noGreen, NOW)).toMatchObject({ text: "trunk not read: chant ci list: the workspace declares no ci.green · read just now", tone: "refusal" });
86
+ });
87
+ });
88
+
89
+ describe("a trunk commit (#680)", () => {
90
+ it("says its state, where it is, its work and its runs", () => {
91
+ const green = commitRow(answer.commits[2], NOW);
92
+ expect(green).toMatchObject({ head: "a14610e green", when: "3d ago", where: "runs in staging, waits in prod", facts: [] });
93
+ expect(green.runs).toEqual([{ text: "test", href: "https://github.com/acme/app/actions/runs/102", title: "test: success" }]);
94
+ const revoked = commitRow(answer.commits[1], NOW);
95
+ expect(revoked.facts.map((f) => f.text)).toEqual(["revoked: test failed", "no work item"]);
96
+ expect(revoked.runs).toHaveLength(1);
97
+ const undecided = commitRow(answer.commits[0], NOW);
98
+ expect(undecided.facts.map((f) => f.text)).toEqual(["work task:12"]);
99
+ expect(undecided.title).toContain(UNDECIDED_NOTE);
100
+ });
101
+ it("words each work state chant#4029 defines, and nothing when chant said nothing", () => {
102
+ expect(workWords(null)).toBeNull();
103
+ expect(workWords({ state: "merge", ids: [], problems: [] }).text).toBe("merge commit");
104
+ expect(workWords({ state: "wrong", ids: [], problems: [{ trailer: "Chant-Record: task:99", message: "no task record 99 exists" }] })).toEqual({ text: "names a work item that does not exist", title: "Chant-Record: task:99: no task record 99 exists" });
105
+ expect(whereWords([])).toBe("");
106
+ });
107
+ });
108
+
109
+ describe("an environment's lane (#680)", () => {
110
+ it("says what it runs and the commit it was cut from", () => {
111
+ expect(runsLines(answer.environments[0], NOW)).toEqual([{ text: "runs v2, cut from a14610e · web", title: expect.stringContaining("cut by github:alice") }]);
112
+ expect(runsLines(answer.environments[1], NOW)[0].title).toContain("deploy approved by github:alice");
113
+ });
114
+ it("says plainly when there is no deploy record, and names a deploy no release covers", () => {
115
+ expect(runsLines({ env: "dev", releases: [], deploys: [] }, NOW)).toEqual([{ text: "no deploy record", title: expect.any(String) }]);
116
+ const d = { member: "web", component: "api", digest: "sha256:0123456789abcdef", gitSha: C1, listed: false, timestamp: "2026-10-04T10:00:00Z", actor: "ci", approver: null, runId: "r" };
117
+ expect(runsLines({ env: "dev", releases: [], deploys: [d] }, NOW)[0].text).toBe("runs api 0123456789ab from 6828a7f (older than the trunk list)");
118
+ });
119
+ it("draws a waiting gate with its commit, run and change set, and the approve button that names the approver", () => {
120
+ const card = laneGateCard(gate, answer);
121
+ expect(card).toMatchObject({
122
+ title: "web: web waits at gate promote",
123
+ facts: "for a14610e (green) · 0 of 1 approval · run run-9",
124
+ changeSet: { text: "change set 4b5e57f6eb2f", title: expect.stringContaining("Draw this change set on the graph") },
125
+ button: { label: "Approve as alex" },
126
+ });
127
+ expect(card.command).toContain("chant change-set show sha256:4b5e57f6");
128
+ expect(card.changeSet.title).toContain("chant change-set show sha256:4b5e57f6eb2f42b9039b3d1e13929295f231749c510cbe341cd68036d9af97e2 --member web");
129
+ // #681: a release gate names the release its change set was planned for.
130
+ expect(laneGateCard({ ...gate, op: "release", releaseDigest: "jcs1-sha256:1a23268fa8b1fc419cffde4c1780f4387ff0346495f97bd9e22b0508bef99f9d" }, answer).facts).toBe("for a14610e (green) · 0 of 1 approval · run run-9 · release 1a23268fa8b1");
131
+ expect(laneGateCard({ ...gate, gitSha: undefined, commitState: null, changeSet: undefined }, answer)).toMatchObject({ facts: "commit unknown · 0 of 1 approval · run run-9" });
132
+ expect(laneGateCard({ ...gate, changeSet: undefined }, answer).changeSet).toBeUndefined();
133
+ expect(laneGateCard(gate, answer, { embed: true }).button).toBeUndefined();
134
+ });
135
+ it("lays the environments out in the order the answer gives", () => {
136
+ const v = laneView(answer, NOW);
137
+ expect(v.environments.map((e) => [e.heading, e.gates.length])).toEqual([
138
+ ["staging", 0],
139
+ ["prod", 1],
140
+ ]);
141
+ expect(v.notes).toEqual([]);
142
+ expect(laneView({ ...answer, order: "env", environments: [answer.environments[1]] }, NOW).notes).toEqual(["no member declares a promotion order, so this is prod alone"]);
143
+ });
144
+ });
145
+
146
+ describe("the release column (#692)", () => {
147
+ it("names each release with its commit, its cut and its signature check", () => {
148
+ const v2 = releaseRow(releases[1], NOW);
149
+ expect(v2).toMatchObject({ head: "v2 · web", cutFrom: "cut from a14610e" });
150
+ expect(v2.facts.map((f) => f.text)).toEqual(["cut by github:alice 2d ago", "unsigned"]);
151
+ expect(releaseRow(releases[0], NOW).facts.map((f) => f.text)).toEqual(["cut by github:alice 25h ago", "signature does not count"]);
152
+ expect(signatureWords({ status: "verified", reason: "" }).text).toBe("signed");
153
+ expect(signatureWords(null)).toBeNull();
154
+ expect(releaseRow({ ...releases[2], cut: null, artifacts: 0, listed: false }, NOW)).toMatchObject({ cutFrom: "cut from 6828a7f (older than the trunk list)", facts: [{ text: "no cut recorded" }, { text: "no artifact digests" }] });
155
+ });
156
+
157
+ it("marks a config-only release, and not one whose artifacts changed", () => {
158
+ expect(releaseRow(releases[1], NOW).marks).toEqual([{ text: "config-only", cls: "lane-config-only", title: "The same artifact digests as v1: only configuration changed." }]);
159
+ expect(releaseRow(releases[0], NOW).marks.map((m) => m.text)).toEqual(["revoked"]);
160
+ expect(releaseRow(releases[2], NOW).marks).toEqual([]);
161
+ });
162
+
163
+ it("says where a release runs and waits, and where promotion takes it next", () => {
164
+ expect(releaseRow(releases[1], NOW).where.map((w) => w.text)).toEqual(["runs in staging", "waits in prod"]);
165
+ expect(releaseRow({ ...releases[1], waits: [] }, NOW).where.map((w) => w.text)).toEqual(["runs in staging", "next: prod"]);
166
+ expect(releaseRow({ ...releases[1], runs: [], waits: [], next: "staging" }, NOW).where.map((w) => w.text)).toEqual(["next: staging"]);
167
+ expect(releaseRow(releases[2], NOW).where.map((w) => w.text)).toEqual(["runs in prod"]);
168
+ expect(releaseRow({ ...releases[2], runs: [] }, NOW).where.map((w) => w.text)).toEqual(["runs nowhere"]);
169
+ });
170
+
171
+ it("marks a revoked release with what failed and the line that rolls it back, and its gate as superseded", () => {
172
+ const v3 = releaseRow(releases[0], NOW);
173
+ expect(v3.revoked).toEqual({ text: "revoked: test failed", run: { text: "test", href: "https://github.com/acme/app/actions/runs/113", title: "test: failure" }, rollback: [`roll back: ${ROLLBACK}`] });
174
+ expect(v3.where.map((w) => w.text)).toEqual(["runs in staging", "gate in prod superseded"]);
175
+ expect(supersededLine(superseded, column).text).toBe("web/release/promote superseded: release v3 is revoked (test failed)");
176
+ expect(runsLines(column.environments[0], NOW)[0]).toMatchObject({ text: "runs v3, cut from 9c4250f · api · revoked", revoked: true, title: expect.stringContaining(`roll back: ${ROLLBACK}`) });
177
+ const d = { member: "web", component: "api", digest: "sha256:0123456789abcdef", gitSha: C3, listed: true, timestamp: "2026-10-04T10:00:00Z", actor: "ci", approver: null, runId: "r", release: { releaseDigest: R3, label: "v3" }, rollback: ROLLBACK };
178
+ expect(runsLines({ env: "staging", releases: [], deploys: [d] }, NOW)[0]).toMatchObject({ text: "runs api 0123456789ab from release v3, 9c4250f · revoked", revoked: true });
179
+ });
180
+
181
+ it("names the releases cut from each commit", () => {
182
+ expect(commitRow(column.commits[2], NOW).facts.map((f) => f.text)).toEqual(["cut as v2"]);
183
+ expect(commitRow(column.commits[0], NOW).facts.map((f) => f.text)).toEqual(["work task:12"]);
184
+ });
185
+
186
+ it("says when the project's chant is below the column's floor, and nothing at or above it", () => {
187
+ expect(releaseColumnNote(column)).toBeNull();
188
+ const old = { ...column, chant: "0.124.28", releaseColumn: { full: false, floor: "0.124.29" }, releases: releases.map((r) => ({ ...r, revoked: null })) };
189
+ expect(releaseColumnNote(old)).toBe("chant 0.124.28 does not say which releases are revoked; chant 0.124.29 and newer does.");
190
+ expect(laneView(old, NOW).releases.note).toBe(releaseColumnNote(old));
191
+ // An answer from before #692 has no column at all.
192
+ expect(laneView(answer, NOW).releases).toBeNull();
193
+ expect(laneView({ ...column, releases: [] }, NOW).releases.empty).toBe("no release cut yet");
194
+ });
195
+
196
+ it("draws the column between the trunk's commits and the environments' gates", () => {
197
+ const make = (tag) => {
198
+ const el = { tag, children: [], dataset: {}, className: "", textContent: "", title: "", listeners: {} };
199
+ Object.defineProperty(el, "childNodes", { get: () => el.children });
200
+ el.appendChild = (c) => (el.children.push(c), c);
201
+ el.append = (...cs) => cs.forEach((c) => el.children.push(c));
202
+ el.replaceChildren = () => (el.children = []);
203
+ el.addEventListener = (k, f) => (el.listeners[k] = f);
204
+ return el;
205
+ };
206
+ const saved = globalThis.document;
207
+ globalThis.document = { createElement: make, createTextNode: (t) => ({ tag: "#text", textContent: t, children: [] }) };
208
+ try {
209
+ const host = make("div");
210
+ renderTrunkLane(host, column, NOW, {});
211
+ const heads = host.children.filter((c) => c.tag === "h3").map((c) => c.textContent);
212
+ expect(heads).toEqual(["trunk", "releases", "staging", "prod"]);
213
+ const rows = host.children.filter((c) => c.className === "lane-release");
214
+ expect(rows.map((r) => r.dataset.release)).toEqual([R3, R2, R1]);
215
+ const text = (el) => (el.textContent || "") + el.children.map(text).join("");
216
+ expect(text(rows[1])).toBe("v2 · web · cut from a14610e · config-onlycut by github:alice 2d ago · unsignedruns in staging · waits in prod");
217
+ expect(text(rows[0])).toContain(`roll back: ${ROLLBACK}`);
218
+ expect(host.children.findIndex((c) => c.className === "lane-release")).toBeGreaterThan(host.children.findIndex((c) => c.className === "lane-commit"));
219
+ expect(host.children.find((c) => c.className === "lane-superseded").textContent).toBe("web/release/promote superseded: release v3 is revoked (test failed)");
220
+ } finally {
221
+ globalThis.document = saved;
222
+ }
223
+ });
224
+ });