@intentius/chant 0.124.18 → 0.124.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.124.18",
+  "version": "0.124.20",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/commands/import-live.test.ts

@@ -143,6 +143,30 @@ describe("liveImportFromPlugins (#114)", () => {
     expect(result.error).toContain("No resources exported");
   });
 
+  // #3911 — an exporter that refuses (the sql lexicon naming objects it cannot
+  // declare) is the import's error, not a warning behind "No resources exported".
+  test("an exporter's failure is the error when nothing else exported, and --skip-undeclarable reaches it", async () => {
+    let seen: unknown;
+    const refusing: LexiconPlugin = {
+      ...fakeExporter("sql", sampleIR),
+      async exportResources(opts: { skipUndeclarable?: boolean }) {
+        seen = opts.skipUndeclarable;
+        if (!opts.skipUndeclarable) throw new Error("the server has an object of a kind chant cannot declare:\n  - aggregate app.total(integer)");
+        return { ...sampleIR, warnings: ["aggregate app.total(integer) is left out (--skip-undeclarable)"] };
+      },
+    };
+    const failed = await liveImportFromPlugins([refusing], { environment: "prod", output: outputDir, force: true });
+    expect(failed.success).toBe(false);
+    expect(failed.error).toContain("sql: live export failed");
+    expect(failed.error).toContain("  - aggregate app.total(integer)");
+    expect(seen).toBeUndefined();
+
+    const skipped = await liveImportFromPlugins([refusing], { environment: "prod", output: outputDir, force: true, skipUndeclarable: true });
+    expect(skipped.success).toBe(true);
+    expect(seen).toBe(true);
+    expect(skipped.warnings).toContain("aggregate app.total(integer) is left out (--skip-undeclarable)");
+  });
+
   // #932 — a multi-stack reconcile imports each stack from its own live
   // CloudFormation stack; the `stack` option must reach `exportResources` so
   // the right stack is queried (not one env-named stack for all of them).

package/src/cli/commands/import.ts

@@ -645,6 +645,8 @@ export interface LiveImportOptions {
   owned?: boolean;
   /** Keep server-defaulted fields instead of stripping to declared shape. */
   verbatim?: boolean;
+  /** Import what can be declared, and warn about the live objects no declaration can hold instead of failing. */
+  skipUndeclarable?: boolean;
 }
 
 /**
@@ -745,6 +747,8 @@ export async function liveImportFromPlugins(
   // Collect IR from every exporter, tagging which lexicon produced output.
   let irParts: ExportedTemplate[] = [];
   let generatorLexicon: LexiconPlugin | undefined;
+  // An exporter that fails (an sql import refusing objects it cannot declare, #3911) is the error when nothing else exported.
+  const failures: string[] = [];
   for (const plugin of exporters) {
     let ir: ExportedTemplate;
     try {
@@ -754,9 +758,10 @@ export async function liveImportFromPlugins(
         selector: options.selector,
         owned: options.owned,
         verbatim: options.verbatim,
+        ...(options.skipUndeclarable ? { skipUndeclarable: true } : {}),
       });
     } catch (err) {
-      warnings.push(`${plugin.name}: live export failed — ${err instanceof Error ? err.message : String(err)}`);
+      failures.push(`${plugin.name}: live export failed — ${err instanceof Error ? err.message : String(err)}`);
       continue;
     }
     // What the exporter left out or could not carry (#3336).
@@ -771,9 +776,10 @@ export async function liveImportFromPlugins(
       success: false,
       generatedFiles: [],
       warnings,
-      error: `No resources exported from environment "${options.environment}".`,
+      error: failures.length > 0 ? failures.join("\n") : `No resources exported from environment "${options.environment}".`,
     };
   }
+  warnings.push(...failures);
 
   if (exporters.length > 1 && irParts.length > 1) {
     warnings.push("Multiple lexicons exported resources; generated with the first. Use --lexicon to target one.");

package/src/cli/handlers/graph.test.ts

@@ -249,6 +249,29 @@ describe("runGraph", () => {
       expect(JSON.parse(stdoutBuf.join("\n")).meta).toEqual({ collector: { pipelines: [] } });
     });
 
+    // #3910 — a lexicon's graphEdges answer becomes edges and dangling refs.
+    test("--format ir carries what a lexicon's graphEdges reports", async () => {
+      lintClean(); discovered();
+      loadPluginsMock.mockResolvedValue([{
+        name: "gitlab",
+        serializer: {},
+        graphEdges: () => ({
+          references: [
+            { from: "pod", to: "vpc", kind: "needs", viaAttr: "needs" },
+            { from: "pod", to: "group/other", kind: "triggers", viaAttr: "trigger", crossPipeline: true, dangling: true },
+          ],
+          pipelines: { ".gitlab-ci.yml": ["pod", "vpc"] },
+        }),
+      }, { name: "broken", serializer: {}, graphEdges: () => { throw new Error("boom"); } }]);
+      resolveLexMock.mockResolvedValue(["gitlab", "broken"]);
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.edges).toContainEqual({ from: "pod", to: "vpc", kind: "needs", viaAttr: "needs" });
+      expect(ir.dangling).toEqual([{ from: "pod", kind: "triggers", path: "trigger", value: "group/other", crossPipeline: true }]);
+      expect(ir.groups.byPipeline).toEqual({ ".gitlab-ci.yml": ["pod", "vpc"] });
+    });
+
     test("--format ir has no meta when no lexicon reports anything", async () => {
       lintClean(); discovered();
       loadPluginsMock.mockResolvedValue([{ name: "gcp", serializer: {}, graphMeta: () => undefined }, { name: "k8s", serializer: {} }]);

package/src/cli/handlers/graph.ts

@@ -2,7 +2,7 @@ import { dirname, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build";
-import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
+import { applyLexiconGraphEdges, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LexiconGraphEdges, type LiveObservation } from "../../graph-ir";
 import { behaviourOverlay } from "../../behaviour-overlay";
 import type { SerializerResult } from "../../serializer";
 import { applyBehaviourOverlay, behaviourRequestFromIr } from "../../behaviour-graph";
@@ -726,6 +726,26 @@ function withGraphMeta(ir: GraphIR, plugins: LexiconPlugin[], entities: Map<stri
   return Object.keys(added).length === 0 ? ir : { ...ir, meta: { ...(ir.meta ?? {}), ...added } };
 }
 
+/**
+ * Add the edges the lexicons' `graphEdges` hooks resolve (#3910): CI
+ * dependencies written as strings (`needs`, `uses:`, `trigger:`, `include:`,
+ * `extends`), which the AttrRef walk in `buildGraphIr` cannot see. A hook that
+ * throws costs its own edges and a warning, not the graph.
+ */
+function withLexiconEdges(ir: GraphIR, plugins: LexiconPlugin[], entities: Map<string, import("../../declarable").Declarable>): GraphIR {
+  const reports: LexiconGraphEdges[] = [];
+  for (const p of plugins) {
+    if (!p.graphEdges) continue;
+    try {
+      const report = p.graphEdges(entities);
+      if (report) reports.push(report);
+    } catch (err) {
+      console.error(formatWarning({ message: `the ${p.name} lexicon's graphEdges failed (${err instanceof Error ? err.message : String(err)}); its edges are left out` }));
+    }
+  }
+  return reports.length === 0 ? ir : applyLexiconGraphEdges(ir, reports);
+}
+
 /** Returned instead of a graph when the prediction cannot be attempted honestly. */
 const REFUSED = Symbol("behaviour-refused");
 
@@ -867,6 +887,7 @@ async function runGraphView(
     const plugins = ctx.plugins.length > 0
       ? ctx.plugins
       : await loadPlugins(await projectLexiconsOrNone(projectPath));
+    ir = withLexiconEdges(ir, plugins as LexiconPlugin[], result.entities);
     const predicted = await predictOntoIr(ir, plugins as LexiconPlugin[], ctx.args, {
       // No environment on the declared path: the file is not deployed anywhere
       // yet, and naming one would claim it was.

package/src/cli/handlers/misc.ts

@@ -349,7 +349,7 @@ export async function runImport(ctx: CommandContext): Promise<number> {
     const { config } = await loadChantConfig(resolve("."));
     if (config.stacks && config.stacks.length > 0) {
       const perStack = await importFromLiveStacks(
-        { environment: args.migrateFrom, lexicon: args.lexicon, force: args.force, selector, owned: args.owned, verbatim: args.verbatim },
+        { environment: args.migrateFrom, lexicon: args.lexicon, force: args.force, selector, owned: args.owned, verbatim: args.verbatim, skipUndeclarable: args.skipUndeclarable },
         config.stacks,
       );
       let anyFailure = false;
@@ -369,6 +369,7 @@ export async function runImport(ctx: CommandContext): Promise<number> {
       selector,
       owned: args.owned,
       verbatim: args.verbatim,
+      skipUndeclarable: args.skipUndeclarable,
     });
 
     printImportResult(result);

package/src/cli/main.test.ts

@@ -16,6 +16,11 @@ describe("parseArgs", () => {
     expect(() => parseArgs(["graph", "--traffic"])).toThrow(/--traffic needs a level/);
   });
 
+  test("--skip-undeclarable reaches live import (#3911)", () => {
+    expect(parseArgs(["import", "--from", "prod"]).skipUndeclarable).toBeUndefined();
+    expect(parseArgs(["import", "--from", "prod", "--skip-undeclarable"]).skipUndeclarable).toBe(true);
+  });
+
   test("--fold and --no-fold set the tri-state fold option (#1134)", () => {
     expect(parseArgs(["build", "src"]).fold).toBeUndefined();
     expect(parseArgs(["build", "src", "--fold"]).fold).toBe(true);

package/src/cli/parse-args.ts

@@ -33,6 +33,7 @@ const BOOLEAN_FLAGS = new Set([
   "--explain",
   "--owned",
   "--verbatim",
+  "--skip-undeclarable",
   "--apply-rewrites",
   "--write",
   "--strict",
@@ -216,6 +217,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.namespace || result.namespace.startsWith("-")) throw new Error("--namespace needs a namespace: --namespace <ns>");
     } else if (arg === "--verbatim") {
       result.verbatim = true;
+    } else if (arg === "--skip-undeclarable") {
+      result.skipUndeclarable = true;
     } else if (arg === "--state") {
       result.statePath = args[++i];
     } else if (arg === "--select") {

package/src/cli/registry.ts

@@ -158,6 +158,8 @@ export interface ParsedArgs {
   confirmProd?: boolean;
   /** `chant import --verbatim` — keep server-defaulted fields in live import */
   verbatim?: boolean;
+  /** `chant import --skip-undeclarable` — import what can be declared and warn about the live objects that cannot, instead of failing */
+  skipUndeclarable?: boolean;
   /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */
   src?: string;
   /** `--env <name>` — active environment: sets CHANT_ENV so env-aware source

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/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;