@intentius/behold 0.29.42 → 0.29.44

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 (68) hide show
  1. package/AGENTS.md +77 -0
  2. package/dist/cli.js +3969 -1918
  3. package/package.json +1 -1
  4. package/web/app.js +1463 -80
  5. package/web/carve-narration.js +33 -1
  6. package/web/chant-live-pace.js +138 -0
  7. package/web/chant-live-pace.test.js +116 -0
  8. package/web/chant-pr-marks.js +417 -39
  9. package/web/chant-pr-marks.test.js +208 -4
  10. package/web/collision-marks.js +124 -0
  11. package/web/collision-marks.test.js +89 -0
  12. package/web/cone.js +269 -0
  13. package/web/cone.test.js +213 -0
  14. package/web/dots-cards.js +362 -0
  15. package/web/dots-cards.test.js +303 -0
  16. package/web/dots-live.test.js +151 -1
  17. package/web/dots-lod.js +20 -0
  18. package/web/dots-lod.test.js +19 -1
  19. package/web/dots-scene.js +110 -10
  20. package/web/dots.js +489 -87
  21. package/web/embed.js +17 -1
  22. package/web/embed.test.js +19 -1
  23. package/web/event-help-modal.js +85 -3
  24. package/web/event-help-modal.test.js +85 -1
  25. package/web/feature-flags.js +143 -0
  26. package/web/feature-flags.test.js +96 -0
  27. package/web/index.html +33 -0
  28. package/web/kiosk-carve.js +59 -6
  29. package/web/kiosk-event-help-ui.js +150 -19
  30. package/web/kiosk-event-help.js +102 -15
  31. package/web/kiosk-event-help.test.js +58 -1
  32. package/web/kiosk-metrics.js +4 -3
  33. package/web/kiosk-runs.js +8 -5
  34. package/web/kiosk-shot.js +157 -3
  35. package/web/kiosk-shot.test.js +223 -1
  36. package/web/kiosk-source.js +43 -0
  37. package/web/kiosk-source.test.js +39 -0
  38. package/web/kiosk-story-gate.test.js +44 -0
  39. package/web/kiosk-track.js +312 -0
  40. package/web/kiosk-track.test.js +148 -0
  41. package/web/kiosk-unknown-step.test.js +58 -0
  42. package/web/kiosk-vendor.js +71 -4
  43. package/web/kiosk-vendor.test.js +103 -3
  44. package/web/kiosk-watch.js +154 -1
  45. package/web/kiosk-watch.test.js +53 -1
  46. package/web/kiosk.html +57 -22
  47. package/web/kiosk.js +566 -53
  48. package/web/kiosk.test.js +2 -1
  49. package/web/small-stage.test.js +150 -0
  50. package/web/terragucci-blocked.test.js +192 -0
  51. package/web/terragucci-change.js +197 -17
  52. package/web/terragucci-components-live.js +189 -13
  53. package/web/terragucci-live-pace.js +92 -0
  54. package/web/terragucci-wave-results.test.js +125 -0
  55. package/web/terralith.html +7 -7
  56. package/web/tg-outside.js +124 -0
  57. package/web/tg-outside.test.js +100 -0
  58. package/web/tg-read-pills.js +122 -0
  59. package/web/tg-read-pills.test.js +117 -0
  60. package/web/theme.js +13 -1
  61. package/web/theme.test.js +21 -1
  62. package/web/tooltip.js +19 -7
  63. package/web/tooltip.test.js +15 -0
  64. package/web/tours/terralith.json +4 -4
  65. package/web/trunk-lane.test.js +1 -1
  66. package/web/view-url.js +8 -2
  67. package/web/why.js +129 -1
  68. package/web/why.test.js +113 -1
@@ -1,5 +1,5 @@
1
1
  import { describe, expect, it } from "vitest";
2
- import { chantApprovalModel, chantComponentMarks, countWords } from "./chant-pr-marks.js";
2
+ import { CHANT_PANEL_STEPS, chantApprovalModel, chantComponentMarks, chantLiveWaves, chantResultModel, countWords, graphWaves, shortReason } from "./chant-pr-marks.js";
3
3
 
4
4
  // behold#631: the marks on a chant repo's components view, from /api/chant/pr's
5
5
  // answer, shaped as it answered for cycle 767 of terragucci's demo (scenario
@@ -30,6 +30,24 @@ describe("a chant repo's components, marked from its pull-request loop (behold#6
30
30
  expect(m.source).toBe("(from chant pr-plan's summary in run #3843)");
31
31
  });
32
32
 
33
+ it("on a kiosk: the plan by its short id, the box's words at the right of its title line, and no approve command on the card", () => {
34
+ const m = chantComponentMarks(answer({ plan, gate: waiting }), facets, { kiosk: true });
35
+ // The approval card names the plan; the boxes don't repeat it on a kiosk.
36
+ expect(m.waves[1].facts).toEqual([]);
37
+ expect(m).toMatchObject({ statusRight: true, cardFont: 15, waveFont: 18 });
38
+ const panel = chantApprovalModel({ demo: { step: "waiting", pull: 13 }, answer: answer({ plan, gate: waiting }), kiosk: true });
39
+ expect(panel.rows[0].command).toBeUndefined();
40
+ // No run numbers and plain words for what comes next.
41
+ expect(panel.run).toBeNull();
42
+ expect(panel.rows.every((r) => !r.runId)).toBe(true);
43
+ expect(panel.rows.map((r) => r.text).slice(1)).toEqual(["A reviewer approves this exact plan.", "The merge applies it only if it still matches."]);
44
+ // An answer read for the cycle's first pull request is not the fix's.
45
+ expect(chantApprovalModel({ demo: { step: "waiting", pull: 14 }, answer: answer({ plan, gate: waiting }), kiosk: true })).toBeNull();
46
+ // Inspect keeps both.
47
+ expect(chantComponentMarks(answer({ plan, gate: waiting }), facets).statusRight).toBeUndefined();
48
+ expect(chantApprovalModel({ demo: { step: "waiting", pull: 13 }, answer: answer({ plan, gate: waiting }) }).rows[0].command).toBe(waiting.approveCommand);
49
+ });
50
+
33
51
  it("approved: the waves planned, and who approved", () => {
34
52
  const m = chantComponentMarks(answer({ plan, gate: approved }), facets);
35
53
  expect(m.waves[2]).toMatchObject({ state: "planned", facts: ["approved by demo-reviewer"] });
@@ -52,13 +70,17 @@ describe("a chant repo's components, marked from its pull-request loop (behold#6
52
70
  expect(m.cards.cache.state).toBe("unchanged");
53
71
  });
54
72
 
55
- it("a failed wave fails, and the waves after it are held back", () => {
73
+ it("a failed wave fails, and what depends on it is blocked by it", () => {
56
74
  const apply = { ...plan, stage: "apply", run: 3844, status: "failed", members: [member("network", "applied"), { ...member("app", "failed"), error: "exit 1" }, member("edge", "blocked")] };
57
75
  const m = chantComponentMarks(answer({ plan, apply, gate: approved }), facets);
58
76
  expect(m.waves[1].state).toBe("applied");
59
- expect(m.cards.app).toMatchObject({ state: "failed", tone: "bad", words: "apply failed" });
77
+ expect(m.cards.app).toMatchObject({ state: "failed", tone: "bad", words: "failed: exit 1", short: "failed" });
60
78
  expect(m.cards.app.facts).toContain("exit 1");
61
- expect(m.cards.edge).toMatchObject({ state: "not-started", short: "held back" });
79
+ // No edges in the facets: blocked, the blocker unnamed.
80
+ expect(m.cards.edge).toMatchObject({ state: "blocked", short: "blocked", words: "blocked by an earlier failure" });
81
+ // With the graph's edges, the blocker by name.
82
+ const named = chantComponentMarks(answer({ plan, apply, gate: approved }), { ...facets, needs: { edge: ["app"], app: ["network"] } });
83
+ expect(named.cards.edge).toMatchObject({ state: "blocked", words: "blocked by app", blockedBy: "app" });
62
84
  });
63
85
 
64
86
  it("sums a plan's changes as Terraform does", () => {
@@ -88,3 +110,185 @@ describe("how chant's gate ends, the hold panel (behold#631)", () => {
88
110
  expect(chantApprovalModel({ demo: demo("waiting"), answer: null })).toBeNull();
89
111
  });
90
112
  });
113
+
114
+ // behold#631, chant#4007: terragucci's fan-out scenario on demo-chant-fanout, chant's examples/fan-out-estate.
115
+ describe("a chant repo's apply, live from its run events", () => {
116
+ const appsA = ["app-01", "app-02", "app-03", "app-04", "app-05", "app-06"];
117
+ const appsB = ["app-07", "app-08", "app-09", "app-10", "app-11", "app-12"];
118
+ const all = ["network", "cluster-a", "cluster-b", ...appsA, ...appsB];
119
+ const fan = {
120
+ ...facets,
121
+ waves: Object.fromEntries(all.map((c) => [c, c === "network" ? 1 : c.startsWith("cluster") ? 2 : 3])),
122
+ members: Object.fromEntries(all.map((c) => [c, c])),
123
+ needs: { "cluster-a": ["network"], "cluster-b": ["network"], ...Object.fromEntries(appsA.map((a) => [a, ["cluster-a"]])), ...Object.fromEntries(appsB.map((a) => [a, ["cluster-b"]])) },
124
+ };
125
+ const fanPlan = { ...plan, pr: 14, op: "pr-14", members: all.map((c) => member(c, "planned")) };
126
+ const FIFO = "Resource handler returned message: The name of a FIFO queue can only end with '.fifo'.";
127
+ const comps = (states) => Object.fromEntries(Object.entries(states).map(([c, s]) => [c, { component: c, wave: fan.waves[c], ...(typeof s === "string" ? { state: s } : s) }]));
128
+ const wave = (n, state, counts = {}) => ({ wave: n, state, components: all.filter((c) => fan.waves[c] === n), counts: { applied: 0, failed: 0, blocked: 0, alreadyApplied: 0, running: 0, waiting: 0, ...counts } });
129
+ const running = { stage: "apply", run: 3901, job: "apply", status: "running", started_at: null };
130
+
131
+ it("while wave 2 applies: wave 1 done, wave 2 applying, the apps waiting for wave 3, and no progress issue", () => {
132
+ const live = { stage: "apply", settled: false, status: null, waves: [wave(1, "applied", { applied: 1 }), wave(2, "running", { running: 2 }), wave(3, "waiting", { waiting: 12 })], components: comps({ network: "applied", "cluster-a": "running", "cluster-b": "running", ...Object.fromEntries([...appsA, ...appsB].map((a) => [a, "planned"])) }) };
133
+ const m = chantComponentMarks(answer({ pull: 14, plan: fanPlan, gate: approved, running, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: live } }), fan);
134
+ expect(m.waves[1]).toMatchObject({ state: "applied", status: { words: "done" } });
135
+ expect(m.waves[2]).toMatchObject({ state: "applying", tone: "busy", status: { status: "running", words: "applying" } });
136
+ // A wave the run has not reached is waiting, never "held".
137
+ expect(m.waves[3].status).toMatchObject({ status: "queued", words: "waiting" });
138
+ expect(m.cards["cluster-a"]).toMatchObject({ state: "applying", words: "applying", tone: "busy" });
139
+ expect(m.cards["app-01"]).toMatchObject({ state: "queued", words: "waiting for wave 3" });
140
+ expect(JSON.stringify(m)).not.toContain("chant#4007");
141
+ });
142
+
143
+ it("after the merge: cluster-a failed with its reason, cluster-b's apps applied, cluster-a's blocked by it", () => {
144
+ const live = {
145
+ stage: "apply",
146
+ settled: true,
147
+ status: "failed",
148
+ waves: [wave(1, "applied", { applied: 1 }), wave(2, "failed", { applied: 1, failed: 1 }), wave(3, "applied", { applied: 6, blocked: 6 })],
149
+ components: comps({ network: "applied", "cluster-a": { state: "failed", error: FIFO, failedIn: "apply" }, "cluster-b": "applied", ...Object.fromEntries(appsA.map((a) => [a, { state: "blocked", blockedBy: "cluster-a" }])), ...Object.fromEntries(appsB.map((a) => [a, "applied"])) }),
150
+ };
151
+ const a = answer({ pull: 14, plan: fanPlan, gate: approved, running, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: live } });
152
+ const m = chantComponentMarks(a, fan);
153
+ expect(m.cards["cluster-a"]).toMatchObject({ state: "failed", tone: "bad", short: "failed", reason: "The name of a FIFO queue can only end with '.fifo'" });
154
+ expect(m.cards["cluster-a"].words).toBe("failed: The name of a FIFO queue can only end with '.fifo'");
155
+ expect(m.cards["cluster-a"].mid).toMatch(/^failed: The name of a…$/);
156
+ expect(m.cards["app-03"]).toMatchObject({ state: "blocked", words: "blocked by cluster-a", tone: "wait" });
157
+ expect(m.cards["app-03"].facts).toContain("did not run: cluster-a failed, and this depends on it");
158
+ expect(m.cards["app-09"].state).toBe("applied");
159
+ expect(m.waves[2]).toMatchObject({ state: "failed", status: { words: "1 failed, 1 applied" } });
160
+ expect(m.waves[2].facts[0]).toBe("cluster-a failed: The name of a FIFO queue can only end with '.fifo'");
161
+ expect(m.waves[3]).toMatchObject({ state: "blocked", status: { words: "6 applied, 6 blocked by cluster-a" } });
162
+ expect(m.source).toMatch(/run events/);
163
+ // The gate's panel stays up on the failed step, and says how far the apply got.
164
+ expect(CHANT_PANEL_STEPS).toContain("failed");
165
+ const panel = chantApprovalModel({ demo: { step: "failed", pull: 14 }, answer: a });
166
+ expect(panel.rows[2]).toMatchObject({ id: "spent", state: "dim", text: "The merge applied part of this digest: 8 applied, 1 failed, 6 blocked. The rest waits for a fix." });
167
+ expect(panel.chantWaves[1]).toMatchObject({ wave: 2, state: "failed", failed: [{ component: "cluster-a", reason: "The name of a FIFO queue can only end with '.fifo'" }] });
168
+ expect(chantLiveWaves(a)[2]).toMatchObject({ applied: 6, blocked: 6, blockedBy: ["cluster-a"] });
169
+ });
170
+
171
+ it("a blocked card names its blocker from the graph when chant's events don't", () => {
172
+ const live = { stage: "apply", settled: true, status: "failed", waves: [wave(1, "applied"), wave(2, "failed"), wave(3, "applied")], components: comps({ network: "applied", "cluster-a": "failed", "cluster-b": "applied", ...Object.fromEntries(appsA.map((a) => [a, "blocked"])), ...Object.fromEntries(appsB.map((a) => [a, "applied"])) }) };
173
+ const m = chantComponentMarks(answer({ pull: 14, plan: fanPlan, gate: approved, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: live } }), fan);
174
+ expect(m.cards["app-01"]).toMatchObject({ state: "blocked", blockedBy: "cluster-a", words: "blocked by cluster-a" });
175
+ });
176
+
177
+ it("a resume's boxes follow the graph's waves by name, not run-start's re-layered numbers", () => {
178
+ // run-start re-layered what was left: cluster-a is its wave 1, cluster-a's apps its wave 2.
179
+ const live = {
180
+ stage: "apply",
181
+ settled: false,
182
+ status: null,
183
+ waves: [{ ...wave(1, "running", { running: 1 }), components: ["cluster-a"] }, { ...wave(2, "waiting", { waiting: 6 }), components: appsA }],
184
+ components: comps({
185
+ network: { state: "already-applied", wave: 1, waveFrom: "graph" },
186
+ "cluster-b": { state: "already-applied", wave: 2, waveFrom: "graph" },
187
+ ...Object.fromEntries(appsB.map((a) => [a, { state: "already-applied", wave: 3, waveFrom: "graph" }])),
188
+ "cluster-a": { state: "running", wave: 1 },
189
+ ...Object.fromEntries(appsA.map((a) => [a, { state: "planned", wave: 2 }])),
190
+ }),
191
+ };
192
+ const m = chantComponentMarks(answer({ pull: 15, plan: fanPlan, gate: approved, running, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: live } }), fan);
193
+ expect(m.cards.network).toMatchObject({ state: "already-applied", words: "applied before", tone: "ok" });
194
+ // The graph's wave 1 (network) is done though run-start's wave 1 (cluster-a) runs.
195
+ expect(m.waves[1]).toMatchObject({ state: "applied", status: { words: "done" } });
196
+ expect(m.waves[2]).toMatchObject({ state: "applying", status: { words: "applying" } });
197
+ // Wave 3: cluster-b's apps applied before, cluster-a's wait their turn.
198
+ expect(m.waves[3]).toMatchObject({ state: "planned", status: { words: "waiting" } });
199
+ expect(m.cards["app-01"]).toMatchObject({ state: "queued", words: "waiting for wave 3" });
200
+ });
201
+
202
+ it("the fix's apply: what the cycle's first apply landed reads applied earlier, and every card has landed at the end", () => {
203
+ const live = {
204
+ stage: "apply",
205
+ settled: true,
206
+ status: "ok",
207
+ waves: [{ ...wave(1, "applied", { applied: 1 }), components: ["cluster-a"] }, { ...wave(2, "applied", { applied: 6 }), components: appsA }],
208
+ components: comps({ "cluster-a": { state: "applied", wave: 1, graphWave: 2 }, ...Object.fromEntries(appsA.map((a) => [a, { state: "applied", wave: 2, graphWave: 3 }])) }),
209
+ };
210
+ const fixPlan = { ...plan, pr: 15, op: "pr-15", members: ["cluster-a", ...appsA].map((c) => member(c, "planned")) };
211
+ const earlier = { runs: [3901], applied: ["app-07", "app-08", "app-09", "app-10", "app-11", "app-12", "cluster-b", "network"] };
212
+ const a = answer({ pull: 15, plan: fixPlan, gate: approved, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: live, earlier } });
213
+ const m = chantComponentMarks(a, fan);
214
+ expect(m.cards.network).toMatchObject({ state: "applied-earlier", words: "applied earlier", tone: "ok" });
215
+ expect(m.cards["app-09"].state).toBe("applied-earlier");
216
+ expect(m.cards["cluster-a"].state).toBe("applied");
217
+ expect(Object.values(m.cards).every((c) => c.state === "applied" || c.state === "applied-earlier")).toBe(true);
218
+ expect(m.waves[1]).toMatchObject({ state: "applied", status: { words: "applied earlier" } });
219
+ // Network landed in the first apply: its box claims none of this run's plan.
220
+ expect(m.waves[1].facts.some((f) => /^applied plan/.test(f))).toBe(false);
221
+ // The run's waves numbered as the graph's boxes are.
222
+ expect(graphWaves(live).map((w) => w.wave)).toEqual([2, 3]);
223
+ // The result card, the one terragucci's scenarios get.
224
+ const r = chantResultModel({ step: "applied", label: "Done." }, a);
225
+ expect(r).toMatchObject({ head: "Applied", line: "Done.", counts: ["7 applied this run", "8 applied earlier", "the fix ran 2 waves"] });
226
+ expect(r.waves).toEqual([{ wave: 2, words: "1 applied" }, { wave: 3, words: "6 applied" }]);
227
+ expect(chantResultModel({ step: "applying" }, a)).toBeNull();
228
+ // The plan of the same fix, before it applies: the eight read as landed there too.
229
+ const planned = chantComponentMarks(answer({ pull: 15, plan: fixPlan, gate: waiting, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: null, earlier } }), fan);
230
+ expect(planned.cards.network.state).toBe("applied-earlier");
231
+ expect(planned.cards["cluster-a"].state).toBe("planned");
232
+ });
233
+
234
+ it("says starting… while the apply runs and its events have not landed, and never an issue number on a kiosk", () => {
235
+ const run = { stage: "apply", run: 3901, job: "apply", status: "running", started_at: null };
236
+ const m = chantComponentMarks(answer({ pull: 14, plan: fanPlan, gate: approved, running: run, eventsExpected: true }), fan);
237
+ // Only the wave the apply starts with says so; the ones after it wait.
238
+ expect(m.waves[1].status).toMatchObject({ words: "starting…", tone: "busy" });
239
+ expect(m.waves[2].status).toMatchObject({ status: "queued", words: "waiting" });
240
+ expect(m.waves[3].status).toMatchObject({ status: "queued", words: "waiting" });
241
+ expect(JSON.stringify(m)).not.toContain("chant#4007");
242
+ const kiosk = chantComponentMarks(answer({ pull: 14, plan: fanPlan, gate: approved, running: run }), fan, { kiosk: true });
243
+ expect(JSON.stringify(kiosk)).not.toContain("chant#4007");
244
+ // Inspect, with no events at all, still says which issue asks for them.
245
+ const inspect = chantComponentMarks(answer({ pull: 14, plan: fanPlan, gate: approved, running: run }), fan);
246
+ expect(inspect.waves[2].facts[0]).toBe("per-wave progress: chant#4007");
247
+ });
248
+
249
+ it("names the specific part of a tool's error, not its prefix or its advice", () => {
250
+ expect(shortReason('cfn-deploy "cluster-a": stack reached ROLLBACK_COMPLETE — the deploy failed and was rolled back. Inspect the stack events for the resource that failed to create/update.')).toBe("stack reached ROLLBACK_COMPLETE");
251
+ });
252
+
253
+ it("a fix just opened, with no plan yet: what landed reads applied earlier, a failed or blocked card keeps its state, nothing blank", () => {
254
+ const run = { stage: "plan", run: 3950, job: "plan", status: "queued", started_at: null };
255
+ const lastStates = { "cluster-a": "failed", ...Object.fromEntries(appsA.map((a) => [a, "blocked"])) };
256
+ const earlier = { runs: [], applied: ["network", "cluster-b", ...appsB] };
257
+ const m = chantComponentMarks(answer({ pull: 15, plan: null, gate: null, running: run, lastStates, live: { reportUrl: null, via: "pipeline", plan: null, apply: null, earlier } }), fan, { kiosk: true });
258
+ expect(m.cards.network.state).toBe("applied-earlier");
259
+ expect(m.cards["cluster-a"].state).toBe("failed");
260
+ expect(m.cards["app-02"]).toMatchObject({ state: "blocked", blockedBy: "cluster-a" });
261
+ expect(Object.values(m.cards).every((c) => c.state !== "unchanged")).toBe(true);
262
+ // Network's box is not part of the fix: it says applied earlier, never the plan job.
263
+ expect(m.waves[1].status.words).toBe("applied earlier");
264
+ expect(JSON.stringify(m)).not.toContain("plan queued");
265
+ });
266
+
267
+ it("draws what a change reaches: the plan from network over all fifteen, the failure from cluster-a over its six apps, the fix over its seven", () => {
268
+ const planned = chantComponentMarks(answer({ pull: 14, plan: fanPlan, gate: waiting }), fan);
269
+ expect(planned.reach).toMatchObject({ roots: ["network"], tone: "plan", label: "reaches 15 stacks" });
270
+ expect(planned.reach.covered).toHaveLength(15);
271
+ const live = {
272
+ stage: "apply",
273
+ settled: true,
274
+ status: "failed",
275
+ waves: [wave(1, "applied"), wave(2, "failed"), wave(3, "applied")],
276
+ components: comps({ network: "applied", "cluster-a": "failed", "cluster-b": "applied", ...Object.fromEntries(appsA.map((a) => [a, { state: "blocked", blockedBy: "cluster-a" }])), ...Object.fromEntries(appsB.map((a) => [a, "applied"])) }),
277
+ };
278
+ const failed = chantComponentMarks(answer({ pull: 14, plan: fanPlan, gate: approved, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: live } }), fan);
279
+ expect(failed.reach).toMatchObject({ roots: ["cluster-a"], covered: appsA, tone: "bad", label: "6 apps blocked" });
280
+ const fixPlan = { ...plan, pr: 15, op: "pr-15", members: ["cluster-a", ...appsA].map((c) => member(c, "planned")) };
281
+ const earlier = { runs: [3901], applied: ["network", "cluster-b", ...appsB] };
282
+ const fix = chantComponentMarks(answer({ pull: 15, plan: fixPlan, gate: waiting, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: null, earlier } }), fan);
283
+ expect(fix.reach).toMatchObject({ roots: ["cluster-a"], label: "the fix reaches 7" });
284
+ expect(fix.reach.covered).toEqual(["app-01", "app-02", "app-03", "app-04", "app-05", "app-06", "cluster-a"]);
285
+ // Once the apply has started a wave, and at the end, nothing.
286
+ const going = { stage: "apply", settled: false, status: null, waves: [wave(1, "running")], components: comps({ network: "running" }) };
287
+ expect(chantComponentMarks(answer({ pull: 14, plan: fanPlan, gate: approved, live: { reportUrl: "s3://r", via: "pipeline", plan: null, apply: going } }), fan).reach).toBeUndefined();
288
+ });
289
+
290
+ it("cuts a long reason at a word", () => {
291
+ expect(shortReason("error: one two three four five six seven", 20)).toBe("one two three four…");
292
+ expect(shortReason("")).toBeNull();
293
+ });
294
+ });
@@ -0,0 +1,124 @@
1
+ // #684: collision marks. Pure words and colours from
2
+ // /api/workspace/collisions; app.js draws them.
3
+ //
4
+ // A graph node is marked when two or more in-flight work items reach it: both
5
+ // have a commit that changed the file declaring it, and a waiting gate's
6
+ // change set has an entry on it (chant#4025). The mark is a ring round the
7
+ // card and a tag under it that names the items; the tooltip lists the items
8
+ // and the entries behind it. Files two items both changed have no node, so
9
+ // the Collisions tab lists them on the side. The filter keeps only colliding
10
+ // work: the colliding nodes on the graph (the rest are hidden, with the edges
11
+ // that touch them) and the colliding items in the tab.
12
+ //
13
+ // behold records and locks nothing. chant reports, and the people on the two
14
+ // items sort the overlap out.
15
+
16
+ const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
17
+ const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
18
+ const sha7 = (s) => (s ? String(s).slice(0, 7) : "");
19
+ const id = (item) => String(item).replace(/^[^:]*:/, "");
20
+
21
+ /** The colour of the ring and the tag. */
22
+ export const COLLISION_COLOR = "var(--degraded)";
23
+ /** The note on what a collision is. */
24
+ export const COLLISION_NOTE = "Two in-flight work items changed the file that declares this resource, and a waiting gate's change set has an entry on it. behold only reports it; nothing is locked.";
25
+ /** The note on the side list. */
26
+ export const FILES_NOTE = "These files have no graph node, so they are listed here and not marked on the graph.";
27
+ /** The filter's button, by whether it is on. */
28
+ export const FILTER_ON = "Show all work";
29
+ export const FILTER_OFF = "Show only colliding work";
30
+
31
+ /** The tab's first line: what was read, or why it wasn't. */
32
+ export function collisionHeader(a) {
33
+ if (!a || a.error) return { text: `collisions not read${a && a.error ? `: ${a.error}` : ""}`, title: "", tone: "refusal" };
34
+ if (a.refusal) return { text: `collisions not read: ${a.refusal.error}`, title: [a.refusal.remedy, a.degraded ? `Without it, ${a.degraded}.` : ""].filter(Boolean).join("\n"), tone: "refusal" };
35
+ const colliding = a.items.filter((i) => i.with.length).length;
36
+ const n = a.nodes.length;
37
+ if (!colliding) return { text: `no work items collide (${plural(a.items.length, "work item")} in flight)`, title: COLLISION_NOTE, tone: "quiet" };
38
+ return { text: `${plural(colliding, "work item")} collide, ${plural(n, "node")} marked`, title: COLLISION_NOTE, tone: "quiet" };
39
+ }
40
+
41
+ /** The marks to draw: per node id in `ids` that a collision names, a tag, the items and a tooltip. */
42
+ export function collisionMarks(a, ids) {
43
+ const out = {};
44
+ if (!a || a.error || a.refusal || !a.nodes) return out;
45
+ const want = new Set(ids);
46
+ for (const n of a.nodes) {
47
+ if (!want.has(n.node)) continue;
48
+ const lines = n.entries.map((e) => `${e.address} in change set ${short(e.changeSet)}, declared in ${e.source}: ${e.items.join(" and ")}`);
49
+ out[n.node] = {
50
+ color: COLLISION_COLOR,
51
+ items: n.items,
52
+ tag: `collision: ${n.items.map(id).join(", ")}`,
53
+ title: [`${n.node} is touched by ${plural(n.items.length, "in-flight work item")}:`, ...n.items, "", ...lines, "", COLLISION_NOTE].join("\n"),
54
+ };
55
+ }
56
+ return out;
57
+ }
58
+
59
+ /** Whether a node id stays on the graph with the filter on. */
60
+ export function keepNode(a, nodeId) {
61
+ return !!a && !a.error && !a.refusal && !!a.nodes && a.nodes.some((n) => n.node === nodeId);
62
+ }
63
+
64
+ /**
65
+ * What the filter leaves: the ids of `ids` to hide on the graph, and the items
66
+ * and files the tab lists. With the filter off nothing is hidden and every
67
+ * in-flight item is listed; with it on, only the colliding nodes (and the
68
+ * edges between them) and the items that collide.
69
+ */
70
+ export function collisionFilter(a, ids, on) {
71
+ if (!a || a.error || a.refusal || !a.items) return { hide: [], items: [], nodes: [], files: [] };
72
+ const nodes = a.nodes;
73
+ if (!on) return { hide: [], items: a.items, nodes, files: a.files };
74
+ const keep = new Set(nodes.map((n) => n.node));
75
+ return { hide: ids.filter((i) => !keep.has(i)), items: a.items.filter((i) => i.with.length), nodes, files: a.files };
76
+ }
77
+
78
+ /** Whether an edge between two node ids is hidden with the filter on: when either end is. */
79
+ export function hideEdge(a, from, to, on) {
80
+ return !!on && !(keepNode(a, from) && keepNode(a, to));
81
+ }
82
+
83
+ /** One item's row in the tab. */
84
+ export function itemRow(i) {
85
+ const facts = [i.state || "no state", i.path, `${plural(i.commits.length, "commit")}${i.commits.length ? ` (${i.commits.map(sha7).join(", ")})` : ""}`];
86
+ return {
87
+ key: i.item,
88
+ title: i.item,
89
+ facts: facts.filter(Boolean).join(" · "),
90
+ with: i.with.length ? `collides with ${i.with.join(", ")}` : "collides with none",
91
+ colliding: i.with.length > 0,
92
+ };
93
+ }
94
+
95
+ /** One marked node's row: the node and the items there. */
96
+ export function nodeRow(n) {
97
+ return {
98
+ node: n.node,
99
+ text: `${n.node}: ${n.items.join(" and ")}`,
100
+ title: n.entries.map((e) => `${e.address} in change set ${short(e.changeSet)}, declared in ${e.source}`).join("\n"),
101
+ };
102
+ }
103
+
104
+ /** The side list: files two items both changed, and shared entries chant mapped to no node. */
105
+ export function sideLines(a) {
106
+ if (!a || a.error || a.refusal) return [];
107
+ return [
108
+ ...a.files.map((f) => ({ text: `${f.items.join(" and ")}: ${f.files.join(", ")}`, title: FILES_NOTE })),
109
+ ...a.unplaced.map((u) => ({ text: `${u.items.join(" and ")}: ${u.address} of ${u.member} in change set ${short(u.changeSet)}, declared in ${u.source}`, title: "chant maps this entry to no graph node, so it is listed here and not marked on the graph." })),
110
+ ];
111
+ }
112
+
113
+ /** The items colliding on one card, for the inspect pane. */
114
+ export function collisionsFor(a, nodeId) {
115
+ if (!a || a.error || a.refusal || !a.nodes) return [];
116
+ const n = a.nodes.find((x) => x.node === nodeId);
117
+ return n ? n.items.map((item) => ({ text: item, color: COLLISION_COLOR, title: n.entries.map((e) => `${e.address} in change set ${short(e.changeSet)}, declared in ${e.source}`).join("\n") })) : [];
118
+ }
119
+
120
+ /** Lines for what the answer leaves out, when it says so. */
121
+ export function gapLines(a) {
122
+ if (!a || a.error || a.refusal) return [];
123
+ return a.unattributed ? [{ text: `${plural(a.unattributed, "change-set entry", "change-set entries")} could not be attributed to a work item`, title: "chant attributes an entry through the file that declares its node. An entry stored by an older chant, or on a node with no source file, goes to no item." }] : [];
124
+ }
@@ -0,0 +1,89 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { describe, expect, it } from "vitest";
4
+ import { collisionsFrom } from "../src/collision-marks.ts";
5
+ import { COLLISION_COLOR, COLLISION_NOTE, collisionFilter, collisionHeader, collisionMarks, collisionsFor, FILTER_OFF, FILTER_ON, gapLines, hideEdge, itemRow, nodeRow, sideLines } from "./collision-marks.js";
6
+
7
+ // #684: the marks drawn from what chant printed for the fixture workspace
8
+ // (src/__fixtures__/collision-marks): W-001 and W-002 both change
9
+ // web/queue.ts, and a waiting gate's change set has an entry on web/Queue.
10
+ const fixture = JSON.parse(readFileSync(join(import.meta.dirname, "..", "src", "__fixtures__", "collision-marks", "status-staging.json"), "utf8"));
11
+ const base = { workspace: true, chant: "0.124.29", ...collisionsFrom(fixture, new Date("2026-10-17T00:00:00Z")) };
12
+ // The fixture plus a third in-flight item that collides with none, and a second node only one item reaches (not marked).
13
+ const answer = { ...base, items: [...base.items, { item: "work:W-003", path: "work/W-003.md", state: "open", commits: ["abcdef1234567"], with: [] }] };
14
+ const IDS = ["web/Queue", "web/Topic", "api/Fn"];
15
+
16
+ describe("collision marks on the graph (#684)", () => {
17
+ it("marks the node two work items touch and lists them, and leaves other cards alone", () => {
18
+ const m = collisionMarks(answer, IDS);
19
+ expect(Object.keys(m)).toEqual(["web/Queue"]);
20
+ expect(m["web/Queue"]).toMatchObject({ tag: "collision: W-001, W-002", color: COLLISION_COLOR, items: ["work:W-001", "work:W-002"] });
21
+ expect(m["web/Queue"].title).toContain("work:W-001\nwork:W-002");
22
+ expect(m["web/Queue"].title).toContain("declared in web/queue.ts");
23
+ expect(m["web/Queue"].title).toContain(COLLISION_NOTE);
24
+ });
25
+ it("marks nothing for a node not on the graph, or for a refusal", () => {
26
+ expect(collisionMarks(answer, ["api/Fn"])).toEqual({});
27
+ expect(collisionMarks({ refusal: { error: "x" } }, IDS)).toEqual({});
28
+ });
29
+ it("lists a card's colliding items in the inspect pane", () => {
30
+ expect(collisionsFor(answer, "web/Queue").map((r) => r.text)).toEqual(["work:W-001", "work:W-002"]);
31
+ expect(collisionsFor(answer, "web/Topic")).toEqual([]);
32
+ });
33
+ });
34
+
35
+ describe("the filter shows only colliding work (#684)", () => {
36
+ it("off, hides nothing and lists every in-flight item", () => {
37
+ const f = collisionFilter(answer, IDS, false);
38
+ expect(f.hide).toEqual([]);
39
+ expect(f.items.map((i) => i.item)).toEqual(["work:W-001", "work:W-002", "work:W-003"]);
40
+ });
41
+ it("on, hides every card but the colliding node, and lists only the items that collide", () => {
42
+ const f = collisionFilter(answer, IDS, true);
43
+ expect(f.hide).toEqual(["web/Topic", "api/Fn"]);
44
+ expect(f.nodes.map((n) => n.node)).toEqual(["web/Queue"]);
45
+ expect(f.items.map((i) => i.item)).toEqual(["work:W-001", "work:W-002"]);
46
+ });
47
+ it("on, hides an edge unless both of its ends are colliding nodes", () => {
48
+ expect(hideEdge(answer, "web/Queue", "web/Topic", true)).toBe(true);
49
+ expect(hideEdge(answer, "web/Queue", "web/Queue", true)).toBe(false);
50
+ expect(hideEdge(answer, "web/Queue", "web/Topic", false)).toBe(false);
51
+ });
52
+ it("on, with nothing colliding, shows nothing", () => {
53
+ const none = { ...answer, nodes: [], items: answer.items.map((i) => ({ ...i, with: [] })), files: [] };
54
+ const f = collisionFilter(none, IDS, true);
55
+ expect(f.hide).toEqual(IDS);
56
+ expect(f.items).toEqual([]);
57
+ });
58
+ it("says what the button does", () => {
59
+ expect([FILTER_OFF, FILTER_ON]).toEqual(["Show only colliding work", "Show all work"]);
60
+ });
61
+ });
62
+
63
+ describe("the Collisions tab (#684)", () => {
64
+ it("counts the colliding items and the marked nodes", () => {
65
+ expect(collisionHeader(answer)).toMatchObject({ text: "2 work items collide, 1 node marked", tone: "quiet" });
66
+ expect(collisionHeader({ ...answer, nodes: [], items: base.items.map((i) => ({ ...i, with: [] })) }).text).toBe("no work items collide (2 work items in flight)");
67
+ });
68
+ it("shows each item with its state, record, commits and who it collides with", () => {
69
+ const r = itemRow(answer.items[0]);
70
+ expect(r).toMatchObject({ title: "work:W-001", with: "collides with work:W-002", colliding: true });
71
+ expect(r.facts).toMatch(/^in-progress · work\/W-001-the-queue\.md · 1 commit \([0-9a-f]{7}\)$/);
72
+ expect(itemRow(answer.items[2])).toMatchObject({ with: "collides with none", colliding: false });
73
+ });
74
+ it("lists the marked node, and the shared file on the side with no node", () => {
75
+ expect(nodeRow(answer.nodes[0])).toMatchObject({ node: "web/Queue", text: "web/Queue: work:W-001 and work:W-002" });
76
+ expect(sideLines(answer).map((s) => s.text)).toEqual(["work:W-001 and work:W-002: web/queue.ts"]);
77
+ });
78
+ it("lists a shared entry chant mapped to no node on the side", () => {
79
+ const unplaced = { ...answer, unplaced: [{ items: ["work:W-001", "work:W-002"], changeSet: "jcs1-sha256:" + "ab".repeat(32), member: "web", address: "web", source: "web/queue.ts" }] };
80
+ expect(sideLines(unplaced).map((s) => s.text)).toContain("work:W-001 and work:W-002: web of web in change set abababababab, declared in web/queue.ts");
81
+ });
82
+ it("says why nothing was read, and what is missing below the floor", () => {
83
+ const h = collisionHeader({ refusal: { error: "Work overlap needs chant 0.124.29 or newer.", remedy: "Upgrade." }, degraded: "the graph draws no collision marks" });
84
+ expect(h).toMatchObject({ tone: "refusal", text: "collisions not read: Work overlap needs chant 0.124.29 or newer." });
85
+ expect(h.title).toContain("Without it, the graph draws no collision marks.");
86
+ expect(gapLines({ ...answer, unattributed: 3 }).map((g) => g.text)).toEqual(["3 change-set entries could not be attributed to a work item"]);
87
+ expect(gapLines(answer)).toEqual([]);
88
+ });
89
+ });