@intentius/chant 0.124.17 → 0.124.19

package/src/codegen/publish-order.test.ts

@@ -12,14 +12,20 @@
  * npm, after the tag.
  *
  * publish-packages.sh now derives the order instead of assuming one, as
- * dependency layers that pack and publish in parallel (#3857). This asserts
- * the derivation is actually topological, so the next lexicon that depends on
- * an alphabetically earlier one fails here rather than mid-release.
+ * dependency layers that pack in parallel (#3857). This asserts the
+ * derivation is actually topological, so the next lexicon that depends on an
+ * alphabetically earlier one fails here rather than mid-release.
+ *
+ * With CHANT_STAGED_PUBLISH=1 (#3903) every package publishes under `next`
+ * in one batch instead, and the order that reaches consumers is the order
+ * `latest` moves in, which `tag_layers` derives from peer and optional edges.
+ * Both modes are checked at the end of this file.
  */
 
 import { describe, expect, it } from "vitest";
 import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { chmodSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -147,3 +153,111 @@ describe("packages built even when their publish is skipped", () => {
     expect(built.has("lexicons/forgejo")).toBe(false);
   });
 });
+
+/**
+ * #3903: a release is staged under `next` and only becomes visible to range
+ * consumers when `latest` moves. The #3856 research found that when a
+ * lexicon's `latest` showed before core's, pnpm, bun and yarn installed the
+ * new lexicon against the old core with the peer unmet, and exited 0. So
+ * `latest` moves in waves, each package after everything it peers on.
+ */
+describe("latest tag order", () => {
+  const waves = new Map(
+    ask("tag_layers").map((line) => {
+      const [wave, dir] = line.split("\t");
+      return [dir, Number(wave)] as const;
+    }),
+  );
+  const order = publishOrder();
+
+  it("covers every package that publishes", () => {
+    expect([...waves.keys()].sort()).toEqual([...order].sort());
+  });
+
+  it("moves a package's latest after every package it peers on or optionally depends on", () => {
+    const owner = new Map(order.map((d) => [manifest(d).name as string, d]));
+    for (const dir of order) {
+      const pkg = manifest(dir);
+      for (const name of Object.keys({ ...pkg.peerDependencies, ...pkg.optionalDependencies })) {
+        const depDir = owner.get(name);
+        if (!depDir || depDir === dir) continue;
+        expect(
+          waves.get(depDir)!,
+          `${pkg.name} would move latest in wave ${waves.get(dir)}, no later than ${name} (wave ${waves.get(depDir)}), ` +
+            `so a consumer could get the new ${pkg.name} against the old ${name}`,
+        ).toBeLessThan(waves.get(dir)!);
+      }
+    }
+  });
+
+  it("moves core and k8s-client first, and no lexicon with them", () => {
+    expect(waves.get("packages/core")).toBe(0);
+    expect(waves.get("packages/k8s-client")).toBe(0);
+    for (const [dir, wave] of waves) {
+      if (dir.startsWith("lexicons/")) expect(wave, `${dir} moves latest with core`).toBeGreaterThan(0);
+    }
+  });
+
+  it("moves github before the two lexicons that peer on it", () => {
+    expect(waves.get("lexicons/github")).toBeLessThan(waves.get("lexicons/forgejo")!);
+    expect(waves.get("lexicons/github")).toBeLessThan(waves.get("lexicons/gitlab")!);
+  });
+
+});
+
+/**
+ * Staging is opt-in until every trusted-publisher record allows dist-tag
+ * moves (#3904). Off, the script must publish exactly as it did before
+ * #3903: straight to `latest`, layer by layer, with no tag moves.
+ */
+describe("publish modes (#3903)", () => {
+  const script = readFileSync(join(REPO, "scripts/publish-packages.sh"), "utf8");
+  const publishes = script
+    .split("\n")
+    .filter((line) => !line.trim().startsWith("#") && /\bnpm publish "\$tgz"/.test(line));
+
+  it("passes --tag next to npm publish only when CHANT_STAGED_PUBLISH is 1", () => {
+    expect(publishes.length).toBeGreaterThan(0);
+    for (const line of publishes) {
+      expect(line).not.toMatch(/--tag next/);
+      expect(line).toContain('${TAG_ARGS[@]+"${TAG_ARGS[@]}"}');
+    }
+    expect(script).toMatch(/^TAG_ARGS=\(\)$/m);
+    expect(script).toMatch(/^\[ -n "\$STAGED" \] && TAG_ARGS=\(--tag next\)$/m);
+    expect(script).toMatch(/^\[ "\$\{CHANT_STAGED_PUBLISH:-\}" = "1" \] && STAGED=1$/m);
+  });
+
+  it("moves latest with dist-tag only in the staged flow", () => {
+    const legacy = script.match(/^if \[ -z "\$STAGED" \]; then$.*?^fi$/ms);
+    expect(legacy, "the default publish block").not.toBeNull();
+    expect(legacy![0]).toMatch(/wait_visible/);
+    expect(legacy![0]).not.toMatch(/dist-tag|move_latest/);
+    expect(legacy![0]).toMatch(/^  exit 0$/m);
+    expect(script).toMatch(/dist-tag add "\$name@\$version" latest/);
+  });
+
+  // A stub npm whose every answer is an old version, so every package plans
+  // to publish. DRY_RUN=plan reads the registry and the graph, builds nothing.
+  function plan(env: Record<string, string>): string {
+    const bin = mkdtempSync(join(tmpdir(), "publish-plan-"));
+    writeFileSync(join(bin, "npm"), "#!/bin/sh\necho 0.0.1\n");
+    chmodSync(join(bin, "npm"), 0o755);
+    return execFileSync("bash", ["scripts/publish-packages.sh"], {
+      cwd: REPO,
+      encoding: "utf8",
+      env: { ...process.env, PATH: `${bin}:${process.env.PATH}`, DRY_RUN: "plan", RUNNER_TEMP: bin, ...env },
+    });
+  }
+
+  it("plans a layered publish to latest by default", () => {
+    const out = plan({ CHANT_STAGED_PUBLISH: "" });
+    expect(out).toMatch(/@intentius\/chant \S+: publish \(live: 0\.0\.1\)/);
+    expect(out).not.toMatch(/under next|wave \d/);
+  });
+
+  it("plans a staged publish and the tag waves with CHANT_STAGED_PUBLISH=1", () => {
+    const out = plan({ CHANT_STAGED_PUBLISH: "1" });
+    expect(out).toMatch(/@intentius\/chant \S+: publish under next \(latest: 0\.0\.1\)/);
+    expect(out).toMatch(/^  wave 0: @intentius\/chant @intentius\/chant-k8s-client$/m);
+  });
+});

package/src/components/fan-out-run.ts

@@ -31,9 +31,10 @@
  * ## Or one approval per wave
  *
  * `waveGate` (#3049) is the other mode. Each wave is planned once the waves
- * before it applied, and its gate binds that wave's set digest. Gate names,
- * the digest and the gate decision come from the wave engine
- * (`../wave-engine.ts`, #3766), which `chant run wave` uses too. See
+ * before it applied, and its gate binds that wave's set digest. The loop,
+ * gate names, the digest and the gate decision come from the wave engine
+ * (`../wave-engine.ts`, #3766), which `chant run wave` uses too; this module
+ * hands it the steps a fan-out plans, decides and applies a wave with. See
  * {@link runGatedWaves}.
  */
 
@@ -46,13 +47,13 @@ import {
 } from "./driver";
 import type { ReleaseIdentity } from "../telemetry-attribution";
 import { downstreamWithin, remainingFanOut, type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out";
-import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import { evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "../op/gate";
 import type { RunProgressEvent } from "./run-progress";
 import type { CapabilityRegistry } from "./capability";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { DeployContext } from "./capability";
 import { planWaveComponent, type WaveComponentPlan } from "./wave-plan";
-import { decideWaveGate, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
+import { decideWaveGate, runWaveLoop, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
 
 /**
  * One gate per wave (#3049), each bound to its wave's set digest. The other
@@ -392,137 +393,164 @@ async function runGatedWaves(
 
   options.onProgress?.({ type: "run-start", waves: plan.waves });
 
-  for (const [waveIndex, wave] of plan.waves.entries()) {
-    const waveNum = waveIndex + 1;
-    const runnable = wave.filter((name) => left.has(name) && !blockedBy.has(name));
-    if (waveGate.only !== undefined && waveNum < waveGate.only) {
-      if (runnable.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, runnable);
-      continue;
-    }
-    if (waveGate.only !== undefined && waveNum > waveGate.only) break;
-    if (runnable.length === 0) continue;
-
-    const gateName = waveGateName(waveGate.gate, waveNum);
-    const contexts = new Map(runnable.map((name) => [name, fanOutContext(options, name)]));
-    const planned = await Promise.all(
-      runnable.map((name) => planComponent(byName.get(name)!, contexts.get(name)!, componentOutputs)),
-    );
-
-    const members: WaveMember[] = [];
-    const plansFor = new Map<string, Record<string, unknown>>();
-    const waveFailures: Array<{ component: string; error?: string }> = [];
-    for (const p of planned) {
-      if ("error" in p) {
-        waveFailures.push({ component: p.component, error: p.error });
-        continue;
+  /** What planning one wave gave. */
+  interface Planned {
+    runnable: string[];
+    gateName: string;
+    contexts: Map<string, DeployContext>;
+    members: WaveMember[];
+    plansFor: Map<string, Record<string, unknown>>;
+    waveFailures: Array<{ component: string; error?: string }>;
+  }
+  /** `next`: go on to the next wave. `stop`: the run ends here. */
+  type Outcome = "next" | "stop";
+
+  await runWaveLoop<Planned, { check: Extract<GateCheck, { satisfied: true }>; record: WaveRecord; toRun: string[] }, Outcome>({
+    first: 1,
+    onward: (_k, outcome) => outcome === "next",
+
+    async plan({ k: waveNum }) {
+      const wave = plan.waves[waveNum - 1];
+      if (!wave) return { end: "stop" };
+      const runnable = wave.filter((name) => left.has(name) && !blockedBy.has(name));
+      if (waveGate.only !== undefined && waveNum < waveGate.only) {
+        if (runnable.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, runnable);
+        return { end: "next" };
       }
-      members.push(...p.members);
-      plansFor.set(p.component, p.plans);
-    }
-
-    let digest: string;
-    try {
-      // A wave where nothing planned has no set, and so no digest.
-      digest = members.length > 0 ? waveSetDigest(members) : "";
-    } catch (err) {
-      // Two components planning the same root: there is no one plan for it.
-      const error = err instanceof Error ? err.message : String(err);
-      for (const name of plansFor.keys()) waveFailures.push({ component: name, error });
-      plansFor.clear();
-      digest = "";
-    }
-    for (const f of waveFailures) {
-      failed.push(f.component);
-      results.push(planFailure(f.component, f.error ?? "plan failed"));
-      markBlocked(f.component);
-    }
+      if (waveGate.only !== undefined && waveNum > waveGate.only) return { end: "stop" };
+      if (runnable.length === 0) return { end: "next" };
+
+      const gateName = waveGateName(waveGate.gate, waveNum);
+      const contexts = new Map(runnable.map((name) => [name, fanOutContext(options, name)]));
+      const planned = await Promise.all(
+        runnable.map((name) => planComponent(byName.get(name)!, contexts.get(name)!, componentOutputs)),
+      );
+
+      const members: WaveMember[] = [];
+      const plansFor = new Map<string, Record<string, unknown>>();
+      const waveFailures: Array<{ component: string; error?: string }> = [];
+      for (const p of planned) {
+        if ("error" in p) {
+          waveFailures.push({ component: p.component, error: p.error });
+          continue;
+        }
+        members.push(...p.members);
+        plansFor.set(p.component, p.plans);
+      }
+      return { go: { runnable, gateName, contexts, members, plansFor, waveFailures } };
+    },
+
+    digest(_at, { members, plansFor, waveFailures }) {
+      try {
+        // A wave where nothing planned has no set, and so no digest.
+        return members.length > 0 ? waveSetDigest(members) : "";
+      } catch (err) {
+        // Two components planning the same root: there is no one plan for it.
+        const error = err instanceof Error ? err.message : String(err);
+        for (const name of plansFor.keys()) waveFailures.push({ component: name, error });
+        plansFor.clear();
+        return "";
+      }
+    },
 
-    const toRun = runnable.filter((name) => plansFor.has(name));
-    const record: WaveRecord = {
-      wave: waveNum,
-      op: waveGate.op,
-      gate: gateName,
-      components: [...runnable].sort(),
-      digest,
-      members: [...members].sort((a, b) => a.member.localeCompare(b.member)),
-      status: "failed",
-      ...(waveFailures.length > 0 ? { failed: waveFailures } : {}),
-    };
-    if (toRun.length === 0) {
-      waves.push(record);
-      options.onWaveSettled?.(record);
-      continue;
-    }
+    async decide({ k: waveNum }, { runnable, gateName, members, plansFor, waveFailures }, digest) {
+      for (const f of waveFailures) {
+        failed.push(f.component);
+        results.push(planFailure(f.component, f.error ?? "plan failed"));
+        markBlocked(f.component);
+      }
 
-    const check = await decideWaveGate(gates.port, {
-      op: waveGate.op,
-      gate: gateName,
-      digest,
-      description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
-      ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
-      ...(options.now ? { now: options.now } : {}),
-    });
-    if (!check.satisfied) {
-      // Nothing in this wave ran, and no later wave is planned: its plan
-      // would read outputs this wave has not written.
-      const stopped: WaveRecord = {
-        ...record,
-        status: "gated",
-        ...(check.mismatch?.approved ? { approved: check.mismatch.approved } : {}),
+      const toRun = runnable.filter((name) => plansFor.has(name));
+      const record: WaveRecord = {
+        wave: waveNum,
+        op: waveGate.op,
+        gate: gateName,
+        components: [...runnable].sort(),
+        digest,
+        members: [...members].sort((a, b) => a.member.localeCompare(b.member)),
+        status: "failed",
+        ...(waveFailures.length > 0 ? { failed: waveFailures } : {}),
       };
-      waves.push(stopped);
-      options.onWaveSettled?.(stopped);
-      gatedFact = check.pending;
-      break;
-    }
-
-    options.onProgress?.({ type: "wave-start", wave: waveNum, components: toRun });
-    const waveResults = await Promise.all(
-      toRun.map(async (name) => {
-        options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
-        const plans = plansFor.get(name)!;
-        const ctx = { ...contexts.get(name)!, ...(Object.keys(plans).length > 0 ? { plans } : {}) };
-        const result = await runComponentDeploy(byName.get(name)!, ctx, registry, componentOutputs, options.onProgress, gates);
-        options.onProgress?.({
-          type: "component-done",
-          wave: waveNum,
-          component: name,
-          status: result.status === "fail" ? "failed" : result.status,
-        });
-        options.onComponentSettled?.(result, componentOutputs[name]);
-        return result;
-      }),
-    );
-    results.push(...waveResults);
+      if (toRun.length === 0) {
+        waves.push(record);
+        options.onWaveSettled?.(record);
+        return { end: "next" };
+      }
 
-    for (const result of waveResults) {
-      if (result.status === "ok") {
-        completed.push(result.component);
-        continue;
+      const check = await decideWaveGate(gates.port, {
+        op: waveGate.op,
+        gate: gateName,
+        digest,
+        description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
+        ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
+        ...(options.now ? { now: options.now } : {}),
+      });
+      if (!check.satisfied) {
+        // Nothing in this wave ran, and no later wave is planned: its plan
+        // would read outputs this wave has not written.
+        const stopped: WaveRecord = {
+          ...record,
+          status: "gated",
+          ...(check.mismatch?.approved ? { approved: check.mismatch.approved } : {}),
+        };
+        waves.push(stopped);
+        options.onWaveSettled?.(stopped);
+        gatedFact = check.pending;
+        return { end: "stop" };
       }
-      if (result.status === "fail") {
-        failed.push(result.component);
-        waveFailures.push({ component: result.component });
-      } else {
-        gatedFact ??= result.gate;
+      return { go: { check, record, toRun } };
+    },
+
+    async apply({ k: waveNum }, { contexts, plansFor, waveFailures }, { check, record, toRun }) {
+      options.onProgress?.({ type: "wave-start", wave: waveNum, components: toRun });
+      const waveResults = await Promise.all(
+        toRun.map(async (name) => {
+          options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+          const plans = plansFor.get(name)!;
+          const ctx = { ...contexts.get(name)!, ...(Object.keys(plans).length > 0 ? { plans } : {}) };
+          const result = await runComponentDeploy(byName.get(name)!, ctx, registry, componentOutputs, options.onProgress, gates);
+          options.onProgress?.({
+            type: "component-done",
+            wave: waveNum,
+            component: name,
+            status: result.status === "fail" ? "failed" : result.status,
+          });
+          options.onComponentSettled?.(result, componentOutputs[name]);
+          return result;
+        }),
+      );
+      results.push(...waveResults);
+
+      for (const result of waveResults) {
+        if (result.status === "ok") {
+          completed.push(result.component);
+          continue;
+        }
+        if (result.status === "fail") {
+          failed.push(result.component);
+          waveFailures.push({ component: result.component });
+        } else {
+          gatedFact ??= result.gate;
+        }
+        markBlocked(result.component);
       }
-      markBlocked(result.component);
-    }
 
-    const settled: WaveRecord = {
-      ...record,
-      status: waveFailures.length > 0 ? "failed" : "applied",
-      approvedBy: check.resolution.resolvedBy,
-      ...(waveFailures.length > 0 ? { failed: waveFailures } : {}),
-    };
-    waves.push(settled);
-    options.onWaveSettled?.(settled);
-    options.onProgress?.({
-      type: "wave-done",
-      wave: waveNum,
-      status: waveFailures.length > 0 ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
-    });
-  }
+      const settled: WaveRecord = {
+        ...record,
+        status: waveFailures.length > 0 ? "failed" : "applied",
+        approvedBy: check.resolution.resolvedBy,
+        ...(waveFailures.length > 0 ? { failed: waveFailures } : {}),
+      };
+      waves.push(settled);
+      options.onWaveSettled?.(settled);
+      options.onProgress?.({
+        type: "wave-done",
+        wave: waveNum,
+        status: waveFailures.length > 0 ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
+      });
+      return "next";
+    },
+  });
 
   const blocked: FanOutSkip[] = [...blockedBy.entries()]
     .sort(([a], [b]) => a.localeCompare(b))

package/src/graph-ci-edges.test.ts

@@ -0,0 +1,97 @@
+import { describe, test, expect } from "vitest";
+import { applyLexiconGraphEdges, type GraphIR } from "./graph-ir";
+import { toMermaid } from "./graph-mermaid";
+import { toDot } from "./graph-dot";
+import { applyDetail } from "./graph-detail";
+import { applyLens, parseLens } from "./graph-lens";
+
+// #3910: CI lexicons report their dependency strings through `graphEdges`, and
+// core merges them, keeps the unresolved ones and draws both.
+
+const base: GraphIR = {
+  nodes: [
+    { id: "ci", kind: "GitHub::Actions::Workflow", lexicon: "github", attrs: {} },
+    { id: "build", kind: "GitHub::Actions::Job", lexicon: "github", attrs: {} },
+    { id: "test", kind: "GitHub::Actions::Job", lexicon: "github", attrs: {} },
+    { id: "shared", kind: "GitHub::Actions::Workflow", lexicon: "github", attrs: {} },
+  ],
+  // The core walk already found `test` holding the build Job under `needs`.
+  edges: [{ from: "test", to: "build", kind: "ref", viaAttr: "needs" }],
+  groups: { byLexicon: { github: ["build", "ci", "shared", "test"] } },
+};
+
+const merged = applyLexiconGraphEdges(base, [{
+  references: [
+    { from: "test", to: "build", kind: "needs", viaAttr: "needs" },
+    { from: "test", to: "shared", kind: "calls", viaAttr: "uses", crossPipeline: true },
+    { from: "test", to: "lint", kind: "needs", viaAttr: "needs", dangling: true },
+    { from: "build", to: "nowhere", kind: "needs", viaAttr: "needs" },
+    { from: "ghost", to: "build", kind: "needs" },
+  ],
+  pipelines: { ci: ["ci", "build", "test", "ghost"], shared: ["shared"] },
+}]);
+
+describe("applyLexiconGraphEdges (#3910)", () => {
+  test("a lexicon edge replaces the core ref edge on the same from/to/viaAttr", () => {
+    expect(merged.edges).toEqual([
+      { from: "test", to: "build", kind: "needs", viaAttr: "needs" },
+      { from: "test", to: "shared", kind: "calls", viaAttr: "uses", crossPipeline: true },
+    ]);
+  });
+
+  test("a dangling reference, or one whose target is not a node, is kept on ir.dangling", () => {
+    expect(merged.dangling).toEqual([
+      { from: "build", kind: "needs", path: "needs", value: "nowhere" },
+      { from: "test", kind: "needs", path: "needs", value: "lint" },
+    ]);
+  });
+
+  test("pipelines land on groups.byPipeline, restricted to nodes", () => {
+    expect(merged.groups.byPipeline).toEqual({ ci: ["build", "ci", "test"], shared: ["shared"] });
+  });
+
+  test("no report leaves the IR as it was", () => {
+    expect(applyLexiconGraphEdges(base, [])).toBe(base);
+    expect(applyLexiconGraphEdges(base, [{ references: [] }])).toBe(base);
+  });
+});
+
+describe("renderers draw CI edges (#3910)", () => {
+  test("mermaid: kind labels, dashed cross-pipeline edges, pipeline subgraphs, dangling stubs", () => {
+    const out = toMermaid(merged);
+    expect(out).toContain('test -->|"needs"| build');
+    expect(out).toContain('test -.->|"calls (uses)"| shared');
+    expect(out).toContain('subgraph pipe_github_ci["ci"]');
+    expect(out).toContain('subgraph pipe_github_shared["shared"]');
+    expect(out).toContain('dangling_lint(["lint<br/>(not declared)"])');
+    expect(out).toContain('test -.->|"needs"| dangling_lint');
+  });
+
+  test("dot: the same, as nested clusters and dashed edges", () => {
+    const out = toDot(merged);
+    expect(out).toContain('"test" -> "build" [label="needs"];');
+    expect(out).toContain('"test" -> "shared" [label="calls (uses)", style=dashed];');
+    expect(out).toContain('subgraph "cluster_github_pipeline_ci" {');
+    expect(out).toContain('"dangling:lint" [label="lint\\n(not declared)", shape=box, style="rounded,dashed"];');
+    expect(out).toContain('"test" -> "dangling:lint" [label="needs", style=dashed];');
+  });
+
+  test("a typed ref edge renders as before", () => {
+    const out = toMermaid({ ...base, edges: [{ from: "test", to: "build", kind: "ref", viaAttr: "needs" }] });
+    expect(out).toContain('test -->|"needs"| build');
+  });
+});
+
+describe("detail and lens keep CI edges (#3910)", () => {
+  test("the composite tier keeps the kind and the cross-pipeline mark, and the dangling list", () => {
+    const t1 = applyDetail(merged, 1);
+    expect(t1.edges).toContainEqual({ from: "test", to: "shared", kind: "calls", viaAttr: "uses", crossPipeline: true });
+    expect(t1.dangling).toHaveLength(2);
+  });
+
+  test("a lens keeps the dangling references and pipelines of the nodes it keeps", () => {
+    const focused = applyLens(merged, parseLens("blast:shared", { down: true }));
+    expect(focused.dangling).toEqual([{ from: "test", kind: "needs", path: "needs", value: "lint" }]);
+    expect(focused.groups.byPipeline).toEqual({ ci: ["test"], shared: ["shared"] });
+  });
+});

package/src/graph-detail.ts

@@ -159,10 +159,13 @@ function toComposites(ir: GraphIR): GraphIR {
     if (from === to) continue; // edge internal to a composite
     // A property label only makes sense when neither endpoint was collapsed.
     const collapsed = from !== e.from || to !== e.to;
+    // The kind survives the collapse (#3910): a job's `needs` into a
+    // collapsed composite is still a `needs`, not a typed reference.
+    const cross = e.crossPipeline ? { crossPipeline: true } : {};
     const edge: IREdge = collapsed
-      ? { from, to, kind: "ref" }
-      : { from, to, kind: "ref", viaAttr: e.viaAttr };
-    const key = `${from}\0${to}\0${edge.viaAttr ?? ""}`;
+      ? { from, to, kind: e.kind, ...cross }
+      : { from, to, kind: e.kind, viaAttr: e.viaAttr, ...cross };
+    const key = `${from}\0${to}\0${edge.viaAttr ?? ""}\0${collapsed ? e.kind : ""}`;
     if (!seen.has(key)) seen.set(key, edge);
   }
 
@@ -173,11 +176,14 @@ function toComposites(ir: GraphIR): GraphIR {
   // not just the base + ATTRIBUTES. Filter to handles whose node survived.
   const surviving = new Set(nodes.map((n) => n.id));
   const imports = ir.imports?.filter((i) => surviving.has(i.node));
+  // Unresolved references (#3910) stay with whichever node now holds them.
+  const dangling = ir.dangling?.map((d) => ({ ...d, from: idMap.get(d.from) ?? d.from }));
   return {
     nodes,
     edges: sortEdges([...seen.values()]),
     groups: { byLexicon: byLexiconOf(nodes) },
     ...(imports && imports.length ? { imports } : {}),
+    ...(dangling && dangling.length ? { dangling } : {}),
   };
 }
 

package/src/graph-dot.ts

@@ -1,4 +1,5 @@
 import type { GraphIR, IRNode, IREdge } from "./graph-ir";
+import { edgeLabel } from "./graph-mermaid";
 
 /**
  * Render the graph IR as Graphviz DOT. Pure text — no `dot` needed to produce
@@ -14,17 +15,36 @@ export function toDot(ir: GraphIR): string {
 
   // Cluster by wave (component graph) when present, else by lexicon (entity graph).
   const clusters = ir.groups.byWave ?? ir.groups.byLexicon;
+  // CI pipelines (#3910) nest as clusters inside their lexicon's cluster.
+  const pipelineOf = new Map<string, string>();
+  for (const [name, members] of Object.entries(ir.groups.byPipeline ?? {})) {
+    for (const id of members) if (!pipelineOf.has(id)) pipelineOf.set(id, name);
+  }
   const grouped = new Set<string>();
   if (clusters) {
     for (const [name, members] of Object.entries(clusters)) {
       lines.push(`  subgraph ${q(`cluster_${name}`)} {`);
       lines.push(`    label=${q(name)};`);
+      const nested = new Map<string, IRNode[]>();
       for (const id of members) {
         const node = ir.nodes.find((n) => n.id === id);
         if (!node) continue;
         grouped.add(id);
+        const pipeline = pipelineOf.get(id);
+        if (pipeline !== undefined) {
+          const arr = nested.get(pipeline) ?? [];
+          arr.push(node);
+          nested.set(pipeline, arr);
+          continue;
+        }
         lines.push(`    ${nodeLine(node)}`);
       }
+      for (const [pipeline, nodes] of [...nested].sort(([a], [b]) => a.localeCompare(b))) {
+        lines.push(`    subgraph ${q(`cluster_${name}_pipeline_${pipeline}`)} {`);
+        lines.push(`      label=${q(pipeline)};`);
+        for (const node of nodes) lines.push(`      ${nodeLine(node)}`);
+        lines.push("    }");
+      }
       lines.push("  }");
     }
   }
@@ -35,6 +55,17 @@ export function toDot(ir: GraphIR): string {
 
   for (const e of ir.edges) lines.push(`  ${edgeLine(e)}`);
 
+  // Unresolved references (#3910): a dashed edge to a dashed stub node.
+  const stubs = new Set<string>();
+  for (const d of ir.dangling ?? []) {
+    const stub = `dangling:${d.value}`;
+    if (!stubs.has(stub)) {
+      stubs.add(stub);
+      lines.push(`  ${q(stub)} [label=${q(`${d.value}\n(not declared)`)}, shape=box, style="rounded,dashed"];`);
+    }
+    lines.push(`  ${q(d.from)} -> ${q(stub)} [label=${q(d.kind)}, style=dashed];`);
+  }
+
   lines.push("}");
   return lines.join("\n") + "\n";
 }
@@ -47,8 +78,9 @@ function nodeLine(node: IRNode): string {
 function edgeLine(e: IREdge): string {
   const from = q(e.from);
   const to = q(e.to);
-  const label = [e.viaAttr, e.toAttr].filter(Boolean).join(" → ");
-  return label ? `${from} -> ${to} [label=${q(label)}];` : `${from} -> ${to};`;
+  const label = edgeLabel(e);
+  const attrs = [label ? `label=${q(label)}` : "", e.crossPipeline ? "style=dashed" : ""].filter(Boolean);
+  return attrs.length ? `${from} -> ${to} [${attrs.join(", ")}];` : `${from} -> ${to};`;
 }
 
 /** Quote a DOT identifier/label. Graphviz accepts any string in double quotes;