@intentius/behold 0.29.3 → 0.29.4

package/web/terragucci-components-live.js

@@ -0,0 +1,166 @@
+// #571: the live marks on a terragucci repo's components zoom, the roots drawn
+// one card per root in wave boxes titled with the job that applies the wave
+// (behold#597). The same marks the resources zoom carries (#568, #569), for
+// the run the view is pinned to: each card in its wave's state, the waiting
+// wave's plan digest on its box, the box's title with its job's status from
+// the pipeline's runs (`/api/terragucci/runs`, terragucci#1038), and the reads
+// between the roots. app.js draws what these return; nothing here touches
+// the DOM.
+//
+// The marks are the reports' and the runs', read when they were written: a
+// wave that failed says the waves before it stay applied, and nothing here is
+// all-or-nothing.
+
+import { pinsCommit, rootStates } from "./terragucci-change.js";
+
+/** A job's status as its wave box says it. A job held at a terragucci gate is never a failure. */
+export const JOB_WORDS = {
+  queued: "queued",
+  running: "running",
+  waiting: "held at the gate",
+  success: "succeeded",
+  failure: "failed",
+  cancelled: "cancelled",
+  skipped: "skipped",
+};
+
+/** The tone a job's status is drawn in, on the same channels as a root's state. */
+export const JOB_TONE = { queued: "idle", running: "busy", waiting: "wait", success: "ok", failure: "bad", cancelled: "idle", skipped: "idle" };
+
+/** A card's state in one or two words, when the full words don't fit the card. */
+export const SHORT_WORDS = {
+  planned: "planned",
+  "not-started": "not started",
+  waiting: "waiting",
+  applying: "applying",
+  applied: "applied",
+  refused: "refused",
+  failed: "failed",
+  unchanged: "no changes",
+  outside: "not in this run",
+};
+
+const sameSha = (a, b) => !!a && !!b && (a.startsWith(b) || b.startsWith(a));
+
+/**
+ * The commit whose pipeline runs the wave boxes report: the pinned one, or
+ * with no pin, the run view's. None when the pin holds the view off every run
+ * (`base`, `none`, a pull request's plan): the boxes then carry no job status.
+ */
+export function runsCommit(pin, progress) {
+  if (pin) return pinsCommit(pin) ? pin : null;
+  const run = progress && !progress.error && progress.run && progress.run.present ? progress.run : null;
+  return run && run.commit ? run.commit : null;
+}
+
+/**
+ * A wave job's status on a commit: of the runs on that commit (the index is
+ * newest first), the newest in which the job ran or waits, so a resume's run
+ * of `apply-wave-2` follows the merge's run that held it. A job every such
+ * run skipped is `skipped`. Null when no run on the commit has the job.
+ */
+export function jobStatus(index, commit, jobName) {
+  const runs = index && index.doc && Array.isArray(index.doc.runs) ? index.doc.runs : [];
+  let skipped = null;
+  for (const run of runs) {
+    if (!sameSha(run.commit, commit)) continue;
+    const job = (run.jobs || []).find((j) => j.name === jobName);
+    if (!job) continue;
+    if (job.status !== "skipped") return { status: job.status, words: JOB_WORDS[job.status] || job.status, tone: JOB_TONE[job.status] || "idle", run: run.id };
+    skipped = skipped || { status: "skipped", words: JOB_WORDS.skipped, tone: "idle", run: run.id };
+  }
+  return skipped;
+}
+
+/** "apply-wave-2 · held at the gate", or the job alone without a status. */
+export function waveTitle(jobName, status) {
+  return status ? `${jobName} · ${status.words}` : jobName;
+}
+
+/** The wave a `groups.byWave` key names: `wave-2` is 2. Null for any other key. */
+export function waveOfKey(key) {
+  const m = /^wave-(\d+)$/.exec(String(key || ""));
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Each component's marks and each wave box's, for the run the view draws:
+ *
+ * - `cards[component]`: its root, wave and state (`rootStates`' words and
+ *   tone; `words` without the "wave N ·" its box already says, `short` for a
+ *   card the words don't fit), and the facts for its tooltip;
+ * - `waves[n]`: the wave's state, its job and the job's status on the run's
+ *   commit, the box's title, and the facts drawn on the box (a waiting
+ *   wave's plan digest first).
+ *
+ * `facets` is the components graph's `meta.terragucciComponents`: its jobs
+ * (component -> job and wave) and `roots` (component -> the root it applies;
+ * a component without one is taken to be its root's name).
+ */
+export function componentMarks(answer, progress, facets, { runs = null, pin = null } = {}) {
+  const jobs = facets && Array.isArray(facets.jobs) ? facets.jobs : [];
+  const rootOf = (c) => (facets && facets.roots && facets.roots[c]) || c;
+  const states = rootStates(answer, progress);
+  const stage = states.stage;
+  const commit = runsCommit(pin, progress);
+  const cards = {};
+  for (const j of jobs) {
+    const root = rootOf(j.component);
+    const st = states.roots[root];
+    if (!st) continue;
+    cards[j.component] = {
+      root,
+      wave: j.wave ?? st.wave,
+      state: st.state,
+      tone: st.tone,
+      words: st.words.replace(/^wave \d+ · /, ""),
+      short: SHORT_WORDS[st.state] || st.state,
+      facts: st.facts,
+    };
+  }
+  const waves = {};
+  const waveNumbers = [...new Set(jobs.map((j) => j.wave).filter((n) => typeof n === "number"))].sort((a, b) => a - b);
+  for (const n of waveNumbers) {
+    const jobName = jobs.find((j) => j.wave === n).jobName;
+    const status = commit ? jobStatus(runs, commit, jobName) : null;
+    const members = jobs.filter((j) => j.wave === n).map((j) => cards[j.component]).filter(Boolean);
+    const w = waveState(answer, progress, stage, n);
+    const facts = [];
+    for (const m of members) for (const f of m.facts) if (!facts.includes(f)) facts.push(f);
+    // The plan a waiting wave is approved for first, as it's what the approval
+    // names; then, for a wave that failed, the waves before it that stay applied.
+    const rank = (f) => (/^approve plan /.test(f) ? 0 : / stays applied$/.test(f) ? 1 : 2);
+    facts.sort((a, b) => rank(a) - rank(b));
+    waves[n] = {
+      number: n,
+      job: jobName,
+      state: w,
+      tone: w ? toneOf(w) : status ? status.tone : "idle",
+      status,
+      title: waveTitle(jobName, status),
+      facts,
+    };
+  }
+  return { stage, cards, waves, commit };
+}
+
+const toneOf = (state) => ({ planned: "plan", waiting: "wait", applying: "busy", applied: "ok", failed: "bad", refused: "bad" })[state] || "idle";
+
+/** A wave's own state: the run view's once merged, `planned` while a pull request plans it. */
+function waveState(answer, progress, stage, n) {
+  if (stage === "apply") {
+    const w = progress.states.find((x) => x.number === n);
+    return w ? w.state : null;
+  }
+  if (stage === "pull-request") {
+    const w = answer.pull_request.waves.find((x) => x.number === n);
+    return w ? w.state || "planned" : null;
+  }
+  return null;
+}
+
+/** The words for a card: the full state when it fits in `room` (a width), else the short form. */
+export function cardWords(mark, fits) {
+  return fits(mark.words) ? mark.words : mark.short;
+}
+

package/web/terragucci-components-live.test.js

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import { JOB_WORDS, componentMarks, jobStatus, runsCommit, waveOfKey, waveTitle } from "./terragucci-components-live.js";
+
+// #571: the live marks on a terragucci repo's components zoom. The facets are
+// the components graph's (src/__fixtures__/terragucci-components: network and
+// other in wave 1, app in 2, edge in 3), the run view and the runs shaped as
+// the kiosk's demo fixtures have them.
+const MERGE = "f0e1d2c3b4a5968778695a4b3c2d1e0f12345678";
+const facets = {
+  jobs: [
+    { component: "network", jobName: "apply-wave-1", needs: ["check"], wave: 1 },
+    { component: "other", jobName: "apply-wave-1", needs: ["check"], wave: 1 },
+    { component: "app", jobName: "apply-wave-2", needs: ["apply-wave-1"], wave: 2 },
+    { component: "edge", jobName: "apply-wave-3", needs: ["apply-wave-2"], wave: 3 },
+  ],
+  roots: { network: "network", other: "other", app: "app", edge: "edge" },
+};
+const answer = {
+  roots: ["app", "edge", "network", "other"].map((name) => ({ member: "demo", name, path: name })),
+  pull_request: {
+    run: { pull_request: "41", commit: "a1b2c3d4", finished: "2026-10-20T10:01:40.000Z" },
+    roots: ["network", "app", "edge"],
+    reads: [{ root: "app", upstream: "network", data: "network", outputs: "planned", unknown: ["subnet_id"] }],
+    waves: [
+      { number: 1, roots: ["network"], set_digest: "jcs1-sha256:aaaaaaaaaaaaaaaa" },
+      { number: 2, roots: ["app"], replans_after: [1], waits: true },
+      { number: 3, roots: ["edge"], set_digest: "jcs1-sha256:bbbbbbbbbbbbbbbb" },
+    ],
+    blast: { roots: ["network", "app", "edge"], downstream: [] },
+  },
+};
+const progress = (wave2) => ({
+  run: { present: true, commit: MERGE, updated: "2026-10-20T10:05:00.000Z" },
+  states: [
+    { number: 1, state: "applied", roots: ["network"], reads: [], digest: "jcs1-sha256:4444", totals: { create: 1 }, changed: ["network"] },
+    { number: 2, state: wave2, roots: ["app"], reads: [1], digest: "jcs1-sha256:555555555555555555", totals: { create: 4 }, changed: ["app"] },
+    { number: 3, state: "not-started", roots: ["edge"], reads: [2] },
+  ],
+  reads: [
+    { root: "app", wave: 2, reads: ["network"] },
+    { root: "edge", wave: 3, reads: ["app"] },
+  ],
+});
+const job = (name, status) => ({ name, status });
+const runs = (...list) => ({ doc: { runs: list } });
+const run = (id, commit, jobs) => ({ id, commit, jobs });
+
+describe("a wave job's status from the pipeline's runs (#571)", () => {
+  it("takes the newest run on the commit in which the job ran or waits", () => {
+    const index = runs(
+      run(12, MERGE, [job("apply-wave-1", "skipped"), job("apply-wave-2", "running")]), // the resume
+      run(11, MERGE, [job("apply-wave-1", "success"), job("apply-wave-2", "waiting")]), // the merge, held at the gate
+      run(10, "0000000", [job("apply-wave-2", "failure")]),
+    );
+    expect(jobStatus(index, MERGE, "apply-wave-2")).toEqual({ status: "running", words: "running", tone: "busy", run: 12 });
+    // The resume skipped wave 1: the merge's run says how it went.
+    expect(jobStatus(index, MERGE, "apply-wave-1")).toEqual({ status: "success", words: "succeeded", tone: "ok", run: 11 });
+    // A short sha names the same commit.
+    expect(jobStatus(index, MERGE.slice(0, 8), "apply-wave-2").run).toBe(12);
+  });
+
+  it("says skipped when every run on the commit skipped the job, and nothing without one", () => {
+    const index = runs(run(12, MERGE, [job("apply-wave-3", "skipped")]));
+    expect(jobStatus(index, MERGE, "apply-wave-3")).toMatchObject({ status: "skipped", words: "skipped" });
+    expect(jobStatus(index, MERGE, "apply-wave-9")).toBe(null);
+    expect(jobStatus(index, "1234567", "apply-wave-3")).toBe(null);
+    expect(jobStatus(null, MERGE, "apply-wave-3")).toBe(null);
+    expect(jobStatus({ error: "no runs" }, MERGE, "apply-wave-3")).toBe(null);
+  });
+
+  it("calls a job held at the gate that, never a failure", () => {
+    expect(JOB_WORDS.waiting).toBe("held at the gate");
+    expect(waveTitle("apply-wave-2", { words: JOB_WORDS.waiting })).toBe("apply-wave-2 · held at the gate");
+    expect(waveTitle("apply-wave-2", null)).toBe("apply-wave-2");
+  });
+
+  it("reads the runs of the pinned commit, of the run view's without a pin, and of none under a pin off every run", () => {
+    expect(runsCommit(MERGE, null)).toBe(MERGE);
+    expect(runsCommit(null, progress("waiting"))).toBe(MERGE);
+    expect(runsCommit(null, null)).toBe(null);
+    for (const pin of ["base", "none", "pull", "pull-41", `pull-41-${MERGE}`]) expect(runsCommit(pin, progress("waiting"))).toBe(null);
+  });
+
+  it("reads a wave from chant's box key", () => {
+    expect(waveOfKey("wave-2")).toBe(2);
+    expect(waveOfKey("wave-12")).toBe(12);
+    expect(waveOfKey("network")).toBe(null);
+    expect(waveOfKey(undefined)).toBe(null);
+  });
+});
+
+describe("the component marks (#571)", () => {
+  it("colours each card by its wave's state, and puts the waiting wave's digest and its job's status on its box", () => {
+    const index = runs(run(11, MERGE, [job("apply-wave-1", "success"), job("apply-wave-2", "waiting"), job("apply-wave-3", "queued")]));
+    const m = componentMarks(answer, progress("waiting"), facets, { runs: index, pin: MERGE });
+    expect(m.stage).toBe("apply");
+    expect(Object.fromEntries(Object.entries(m.cards).map(([c, x]) => [c, [x.state, x.tone, x.words]]))).toEqual({
+      network: ["applied", "ok", "applied"],
+      other: ["outside", "idle", "not in this run"],
+      app: ["waiting", "wait", "waiting for an approval"],
+      edge: ["not-started", "idle", "not started"],
+    });
+    expect(m.cards.app.short).toBe("waiting");
+    expect(m.waves[2]).toMatchObject({ job: "apply-wave-2", state: "waiting", tone: "wait", title: "apply-wave-2 · held at the gate" });
+    expect(m.waves[2].facts[0]).toBe("approve plan 555555555555");
+    expect(m.waves[1].title).toBe("apply-wave-1 · succeeded");
+    expect(m.waves[3]).toMatchObject({ state: "not-started", title: "apply-wave-3 · queued", facts: [] });
+  });
+
+  it("says first on a failed wave's box that the waves before it stay applied", () => {
+    const index = runs(run(11, MERGE, [job("apply-wave-1", "success"), job("apply-wave-2", "failure"), job("apply-wave-3", "skipped")]));
+    const m = componentMarks(answer, progress("failed"), facets, { runs: index, pin: MERGE });
+    expect(m.cards.app).toMatchObject({ state: "failed", tone: "bad" });
+    expect(m.waves[2].facts[0]).toBe("wave 1 stays applied");
+    expect(m.waves[2].title).toBe("apply-wave-2 · failed");
+    expect(m.waves[3].title).toBe("apply-wave-3 · skipped");
+  });
+
+  it("draws the pull request's plan before the merge, with no job status", () => {
+    const m = componentMarks(answer, null, facets, { runs: runs(run(11, MERGE, [job("apply-wave-2", "waiting")])), pin: `pull-41-a1b2c3d4` });
+    expect(m.stage).toBe("pull-request");
+    expect(m.cards.network).toMatchObject({ state: "planned", words: "planned" });
+    expect(m.cards.other).toMatchObject({ state: "outside", words: "not in this change" });
+    expect(m.waves[2]).toMatchObject({ state: "planned", status: null, title: "apply-wave-2" });
+    expect(m.waves[1].facts).toEqual(["plan aaaaaaaaaaaa"]);
+  });
+
+  it("marks nothing at rest", () => {
+    const m = componentMarks({ ...answer, pull_request: null }, null, facets, { runs: null, pin: "base" });
+    expect(m.stage).toBe("none");
+    expect(m.cards).toEqual({});
+    expect(Object.values(m.waves).map((w) => [w.title, w.state])).toEqual([
+      ["apply-wave-1", null],
+      ["apply-wave-2", null],
+      ["apply-wave-3", null],
+    ]);
+  });
+
+  it("joins a component to the root it applies, and to its own name without one", () => {
+    const renamed = { jobs: [{ component: "net", jobName: "apply-wave-1", wave: 1 }, { component: "app", jobName: "apply-wave-2", wave: 2 }], roots: { net: "network" } };
+    const m = componentMarks(answer, progress("applying"), renamed, { runs: null, pin: MERGE });
+    expect(m.cards.net).toMatchObject({ root: "network", state: "applied" });
+    expect(m.cards.app).toMatchObject({ root: "app", state: "applying", tone: "busy" });
+  });
+});

package/web/view-url.js

@@ -14,8 +14,9 @@
  * `focus` (#569) names the boxes the view brings forward, comma-separated
  * (a terragucci repo's roots): the rest are drawn dimmed, nothing is hidden.
  * `run` (#569) pins which terragucci run the view draws: a commit's run view,
- * `none` (no run view: the pull request's plan) or `base` (nothing in
- * flight); absent, the newest. */
+ * `none` (no run view: the newest pull request's plan), `pull-<n>[-<sha>]`
+ * (no run view, and only that pull request's plan, of that commit) or `base`
+ * (nothing in flight); absent, the newest. */
 export const VIEW_KEYS = ["member", "zoom", "env", "tier", "lens", "node", "radial", "gates", "focus", "run"];
 
 /** An env name as the server takes one (src/workspace-gates.ts isEnvName). */
@@ -131,8 +132,8 @@ export function settleView(want, offer) {
   }
   if ("run" in want) {
     // null: the newest run, as without the key.
-    if (want.run === null || /^([0-9a-f]{7,40}|none|base)$/.test(String(want.run))) apply.run = want.run;
-    else refused.push({ key: "run", value: want.run, reason: "run is a commit sha, none or base" });
+    if (want.run === null || /^([0-9a-f]{7,40}|none|base|pull(-\d+(-[0-9a-f]{7,40})?)?)$/.test(String(want.run))) apply.run = want.run;
+    else refused.push({ key: "run", value: want.run, reason: "run is a commit sha, none, base or pull-<number>[-<sha>]" });
   }
   if (want.member) apply.member = want.member;
   if (want.node) apply.node = want.node;

package/web/view-url.test.js

@@ -127,6 +127,10 @@ describe("run (#569)", () => {
     expect(settleView({ run: "base" }, {}).apply).toEqual({ run: "base" });
     expect(settleView({ run: null }, {}).apply).toEqual({ run: null });
     expect(settleView({ run: "main" }, {}).refused[0].key).toBe("run");
+    expect(settleView({ run: "pull-989-659dee43" }, {}).apply).toEqual({ run: "pull-989-659dee43" });
+    expect(settleView({ run: "pull-989" }, {}).apply).toEqual({ run: "pull-989" });
+    expect(settleView({ run: "pull" }, {}).apply).toEqual({ run: "pull" });
+    expect(settleView({ run: "pull-x" }, {}).refused[0].key).toBe("run");
     expect(writeViewQuery("", { run: "none" })).toBe("?run=none");
   });
 });