@intentius/chant 0.8.2 → 0.10.0

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

@@ -1,11 +1,33 @@
 import { describe, test, expect, vi, beforeEach } from "vitest";
 import type { ParsedArgs } from "../registry";
+import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
+import { AttrRef } from "../../attrref";
 
 const discoverOpsMock = vi.fn();
 vi.mock("../../op/discover", () => ({
   discoverOps: () => discoverOpsMock(),
 }));
 
+const discoverMock = vi.fn();
+vi.mock("../../discovery/index", () => ({
+  discover: () => discoverMock(),
+}));
+
+const lintMock = vi.fn();
+vi.mock("../commands/lint", () => ({
+  lintCommand: () => lintMock(),
+}));
+
+// Avoid shelling out to graphviz in tests; the format dispatch is what matters.
+const layoutMock = vi.fn();
+vi.mock("../../graph-layout", () => ({
+  GraphvizLayout: class {
+    layout() {
+      return layoutMock();
+    }
+  },
+}));
+
 const { runGraph } = await import("./graph");
 
 function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
@@ -20,6 +42,18 @@ function makeOp(name: string, depends: string[] = []): [string, { config: { name
   return [name, { config: { name, depends } }];
 }
 
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+/** A small two-lexicon graph: vpc <- subnet (gcp), subnet <- pod (k8s). */
+function sampleEntities(): Map<string, Declarable> {
+  const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+  const subnet = decl({ lexicon: "gcp", entityType: "Subnet", props: { network: new AttrRef(vpc, "id") } });
+  const pod = decl({ lexicon: "k8s", entityType: "Pod", props: { net: new AttrRef(subnet, "id") } });
+  return new Map<string, Declarable>([["vpc", vpc], ["subnet", subnet], ["pod", pod]]);
+}
+
 describe("runGraph", () => {
   let stdoutBuf: string[];
   let stderrBuf: string[];
@@ -30,62 +64,146 @@ describe("runGraph", () => {
     vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
     vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
     discoverOpsMock.mockReset();
+    discoverMock.mockReset();
+    lintMock.mockReset();
+    layoutMock.mockReset();
   });
 
-  test("prints 'No Ops found' when discovery is empty", async () => {
-    discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: [] });
-    const exit = await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
-    expect(exit).toBe(0);
-    expect(stdoutBuf.join("\n")).toContain("No Ops found");
-  });
+  describe("Op graph (default)", () => {
+    test("prints 'No Ops found' when discovery is empty", async () => {
+      discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: [] });
+      const exit = await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("No Ops found");
+    });
 
-  test("prints 'No Op dependencies' when ops have no depends", async () => {
-    discoverOpsMock.mockResolvedValue({
-      ops: new Map([makeOp("solo")]),
-      errors: [],
+    test("prints 'No Op dependencies' when ops have no depends", async () => {
+      discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("solo")]), errors: [] });
+      const exit = await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("No Op dependencies");
     });
-    const exit = await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
-    expect(exit).toBe(0);
-    expect(stdoutBuf.join("\n")).toContain("No Op dependencies");
-  });
 
-  test("prints `dep -> name` edge per dependency", async () => {
-    discoverOpsMock.mockResolvedValue({
-      ops: new Map([
-        makeOp("infra"),
-        makeOp("app", ["infra"]),
-      ]),
-      errors: [],
-    });
-    const exit = await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
-    expect(exit).toBe(0);
-    const out = stdoutBuf.join("\n");
-    expect(out).toContain("infra → app");
-  });
+    test("prints `dep -> name` edge per dependency", async () => {
+      discoverOpsMock.mockResolvedValue({
+        ops: new Map([makeOp("infra"), makeOp("app", ["infra"])]),
+        errors: [],
+      });
+      const exit = await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("infra → app");
+    });
 
-  test("handles multi-edge graphs", async () => {
-    discoverOpsMock.mockResolvedValue({
-      ops: new Map([
-        makeOp("a"),
-        makeOp("b", ["a"]),
-        makeOp("c", ["a", "b"]),
-      ]),
-      errors: [],
-    });
-    await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
-    const out = stdoutBuf.join("\n");
-    expect(out).toContain("a → b");
-    expect(out).toContain("a → c");
-    expect(out).toContain("b → c");
+    test("handles multi-edge graphs", async () => {
+      discoverOpsMock.mockResolvedValue({
+        ops: new Map([makeOp("a"), makeOp("b", ["a"]), makeOp("c", ["a", "b"])]),
+        errors: [],
+      });
+      await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
+      const out = stdoutBuf.join("\n");
+      expect(out).toContain("a → b");
+      expect(out).toContain("a → c");
+      expect(out).toContain("b → c");
+    });
+
+    test("forwards discovery errors to stderr", async () => {
+      discoverOpsMock.mockResolvedValue({ ops: new Map(), errors: ["failed to parse ops/bad.op.ts"] });
+      const exit = await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(stderrBuf.join("\n")).toContain("failed to parse ops/bad.op.ts");
+    });
   });
 
-  test("forwards discovery errors to stderr", async () => {
-    discoverOpsMock.mockResolvedValue({
-      ops: new Map(),
-      errors: ["failed to parse ops/bad.op.ts"],
+  describe("graph IR views (--format ir|mermaid|dot|layout)", () => {
+    const lintClean = (): void => { lintMock.mockResolvedValue({ success: true }); };
+    const discovered = (): void => {
+      discoverMock.mockResolvedValue({ entities: sampleEntities(), errors: [], dependencies: new Map(), sourceFiles: [] });
+    };
+
+    test("--format ir emits the graph IR as JSON", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.nodes.map((n: { id: string }) => n.id).sort()).toEqual(["pod", "subnet", "vpc"]);
+      expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" });
+    });
+
+    test("lint gate: refuses to emit when source has lint errors", async () => {
+      lintMock.mockResolvedValue({ success: false });
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(stdoutBuf.join("\n")).toBe("");
+      expect(stderrBuf.join("\n")).toMatch(/lint errors/i);
+      expect(discoverMock).not.toHaveBeenCalled();
+    });
+
+    test("--format mermaid emits a flowchart", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "mermaid" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("flowchart TD");
+    });
+
+    test("--format dot emits a digraph", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "dot" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(stdoutBuf.join("\n")).toContain("digraph chant {");
+    });
+
+    test("--format layout emits positions from the layout engine", async () => {
+      lintClean(); discovered();
+      layoutMock.mockResolvedValue({ width: 100, height: 50, nodes: [{ id: "vpc", x: 1, y: 2 }] });
+      const exit = await runGraph({ args: makeArgs({ format: "layout" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(JSON.parse(stdoutBuf.join("\n"))).toMatchObject({ width: 100, nodes: [{ id: "vpc", x: 1, y: 2 }] });
+    });
+
+    test("--format layout reports a clear error when the engine fails (e.g. dot missing)", async () => {
+      lintClean(); discovered();
+      layoutMock.mockRejectedValue(new Error("could not run 'dot'"));
+      const exit = await runGraph({ args: makeArgs({ format: "layout" }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("could not run 'dot'");
+    });
+
+    test("--detail 0 collapses to one node per lexicon", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "ir", detail: 0 }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.nodes.map((n: { id: string }) => n.id).sort()).toEqual(["gcp", "k8s"]);
+    });
+
+    test("rejects an out-of-range --detail", async () => {
+      const exit = await runGraph({ args: makeArgs({ format: "ir", detail: 9 }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toMatch(/detail/i);
+      expect(lintMock).not.toHaveBeenCalled();
+    });
+
+    test("--lens lexicon:gcp filters to that lexicon", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "ir", lens: "lexicon:gcp" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.nodes.map((n: { id: string }) => n.id).sort()).toEqual(["subnet", "vpc"]);
+    });
+
+    test("--lens with a bad spec errors out", async () => {
+      lintClean(); discovered();
+      const exit = await runGraph({ args: makeArgs({ format: "ir", lens: "nope" }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toMatch(/lens/i);
+    });
+
+    test("--format ir forwards discovery errors and exits non-zero", async () => {
+      lintClean();
+      discoverMock.mockResolvedValue({ entities: new Map(), errors: [{ message: "boom" }], dependencies: new Map(), sourceFiles: [] });
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("boom");
     });
-    const exit = await runGraph({ args: makeArgs(), plugins: [], serializers: [] });
-    expect(exit).toBe(0);
-    expect(stderrBuf.join("\n")).toContain("failed to parse ops/bad.op.ts");
   });
 });

package/src/cli/handlers/graph.ts

@@ -2,19 +2,104 @@ import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph } from "../../build";
+import { buildGraphIr, type GraphIR } from "../../graph-ir";
+import { applyDetail, type DetailLevel } from "../../graph-detail";
+import { applyLens, parseLens } from "../../graph-lens";
+import { toMermaid } from "../../graph-mermaid";
+import { toDot } from "../../graph-dot";
+import { GraphvizLayout } from "../../graph-layout";
+import { lintCommand } from "../commands/lint";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
  * cross-stack apply-ordering graph (edges, order, waves) chant computes from
- * cross-lexicon references.
+ * cross-lexicon references; `--format ir|mermaid` emits the lint-gated
+ * entity-graph IR (or a Mermaid flowchart of it) for diagrams (#493/#496).
  */
 export async function runGraph(ctx: CommandContext): Promise<number> {
+  const viewFormats = ["ir", "mermaid", "dot", "layout"] as const;
+  if ((viewFormats as readonly string[]).includes(ctx.args.format)) {
+    return runGraphView(ctx, ctx.args.format as (typeof viewFormats)[number]);
+  }
   if (ctx.args.stacks) return runStackGraph(ctx);
   return runOpGraph();
 }
 
+/**
+ * `chant graph --format ir|mermaid|dot|layout` — build the graph IR (honouring
+ * `--detail`) and emit it as JSON, a Mermaid flowchart, Graphviz DOT, or node
+ * positions from a layout engine. Lint-gated: the IR represents valid infra, so
+ * we refuse to emit for source that does not pass lint. Non-zero on discovery
+ * errors, or on a missing `dot` for `--format layout`.
+ */
+async function runGraphView(
+  ctx: CommandContext,
+  format: "ir" | "mermaid" | "dot" | "layout",
+): Promise<number> {
+  const projectPath = resolve(ctx.args.path === "." ? "." : ctx.args.path);
+
+  const level = ctx.args.detail ?? 2;
+  if (![0, 1, 2, 3].includes(level)) {
+    console.error(formatError({ message: `Invalid --detail ${level}. Expected 0, 1, 2, or 3.` }));
+    return 1;
+  }
+
+  // Gate: only emit for lint-clean source.
+  const lint = await lintCommand({ path: ctx.args.path, format: "stylish" });
+  if (!lint.success) {
+    console.error(
+      formatError({
+        message:
+          "Refusing to emit graph: source has lint errors. Run `chant lint` and fix them first.",
+      }),
+    );
+    return 1;
+  }
+
+  const result = await discover(projectPath);
+  if (result.errors.length > 0) {
+    for (const e of result.errors) console.error(formatError({ message: e.message }));
+    return 1;
+  }
+
+  // Build the base IR, focus with a lens (declarable-level, most precise), then
+  // apply the detail tier — so e.g. blast:<resource> works before any collapse.
+  let ir: GraphIR = buildGraphIr(result.entities, projectPath);
+  if (ctx.args.lens) {
+    try {
+      ir = applyLens(ir, parseLens(ctx.args.lens, { up: ctx.args.up, down: ctx.args.down }));
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
+  ir = applyDetail(ir, level as DetailLevel);
+
+  switch (format) {
+    case "mermaid":
+      console.log(toMermaid(ir));
+      return 0;
+    case "dot":
+      console.log(toDot(ir));
+      return 0;
+    case "layout":
+      try {
+        const layout = await new GraphvizLayout().layout(toDot(ir));
+        console.log(JSON.stringify(layout, null, 2));
+        return 0;
+      } catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+      }
+    case "ir":
+    default:
+      console.log(JSON.stringify(ir, null, 2));
+      return 0;
+  }
+}
+
 async function runOpGraph(): Promise<number> {
   const { ops, errors } = await discoverOps();
   for (const err of errors) console.error(formatError({ message: err }));

package/src/cli/main.test.ts

@@ -72,6 +72,22 @@ describe("parseArgs", () => {
     expect(result.format).toBe("invalid"); // format is passed as-is to main
   });
 
+  test("parses graph --detail as a number", () => {
+    const result = parseArgs(["graph", "--format", "ir", "--detail", "1"]);
+    expect(result.detail).toBe(1);
+  });
+
+  test("parses graph --lens with a kind:target value", () => {
+    const result = parseArgs(["graph", "--format", "ir", "--lens", "blast:vpc"]);
+    expect(result.lens).toBe("blast:vpc");
+  });
+
+  test("parses graph --up and --down flags", () => {
+    const result = parseArgs(["graph", "--lens", "blast:vpc", "--up", "--down"]);
+    expect(result.up).toBe(true);
+    expect(result.down).toBe(true);
+  });
+
   test("combines multiple options", () => {
     const result = parseArgs([
       "build",

package/src/cli/main.ts

@@ -126,6 +126,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.theme = args[++i];
     } else if (arg === "--stacks") {
       result.stacks = true;
+    } else if (arg === "--detail") {
+      result.detail = Number(args[++i]);
+    } else if (arg === "--lens") {
+      result.lens = args[++i];
+    } else if (arg === "--up") {
+      result.up = true;
+    } else if (arg === "--down") {
+      result.down = true;
     } else if (arg === "--base") {
       result.base = args[++i];
     } else if (arg === "--head") {
@@ -190,7 +198,12 @@ Ops:
   run cancel <name>     Cancel the active workflow run (requires --force)
   run log <name>        Show run history for an Op
 
-  graph                 Show Op dependency graph (--stacks for cross-stack order)
+  graph                 Show Op dependency graph (--stacks for cross-stack order,
+                        --format ir|mermaid|dot|layout for the lint-gated graph IR,
+                        a Mermaid flowchart, Graphviz DOT, or node positions
+                        (layout needs graphviz);
+                        --detail 0..3: stacks|composites|declarables|attributes;
+                        --lens lexicon:<n>|stack:<n>|blast:<node> (--up/--down))
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch

package/src/cli/registry.ts

@@ -57,6 +57,14 @@ export interface ParsedArgs {
   env?: string;
   /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
   stacks?: boolean;
+  /** `chant graph --format ir --detail <0..3>` — graph IR detail tier */
+  detail?: number;
+  /** `chant graph --lens <kind>:<target>` — focus the graph IR on a slice */
+  lens?: string;
+  /** `chant graph --lens blast:<node> --up` — include upstream producers */
+  up?: boolean;
+  /** `chant graph --lens blast:<node> --down` — include downstream dependents */
+  down?: boolean;
   /** `chant lifecycle affected --base <ref>` — base git ref to diff against */
   base?: string;
   /** `chant lifecycle affected --head <ref>` — head git ref (default: working tree) */

package/src/discovery/collect.ts

@@ -58,7 +58,7 @@ export function collectEntities(
                   "resolution",
                 );
               }
-              setProvenance(entity, { sourceFile: file });
+              setProvenance(entity, { sourceFile: file, compositeInstance: indexedName });
               entities.set(expandedName, entity);
             }
           }
@@ -73,7 +73,7 @@ export function collectEntities(
               "resolution",
             );
           }
-          setProvenance(entity, { sourceFile: file });
+          setProvenance(entity, { sourceFile: file, compositeInstance: name });
           entities.set(expandedName, entity);
         }
       } else if (isLexiconOutput(value)) {

package/src/graph-detail.test.ts

@@ -0,0 +1,79 @@
+import { describe, test, expect } from "vitest";
+import { applyDetail, DETAIL } from "./graph-detail";
+import type { GraphIR } from "./graph-ir";
+
+// A small graph: a gcp vpc/subnet pair plus a k8s namespace and deployment that
+// came from one composite instance ("db"), with the deployment referencing the
+// subnet across lexicons.
+const base: GraphIR = {
+  nodes: [
+    { id: "vpc", kind: "Vpc", lexicon: "gcp", attrs: {} },
+    { id: "subnet", kind: "Subnet", lexicon: "gcp", attrs: { network: { $ref: "vpc.id" } } },
+    {
+      id: "dbNamespace",
+      kind: "Namespace",
+      lexicon: "k8s",
+      compositeParent: "DbStack",
+      compositeInstance: "db",
+      attrs: {},
+    },
+    {
+      id: "dbDeployment",
+      kind: "Deployment",
+      lexicon: "k8s",
+      compositeParent: "DbStack",
+      compositeInstance: "db",
+      attrs: { subnet: { $ref: "subnet.selfLink" } },
+    },
+  ],
+  edges: [
+    { from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" },
+    { from: "dbDeployment", to: "subnet", kind: "ref", viaAttr: "subnet" },
+  ],
+  groups: { byLexicon: { gcp: ["subnet", "vpc"], k8s: ["dbDeployment", "dbNamespace"] } },
+};
+
+describe("applyDetail", () => {
+  test("T2 (declarables) is the identity", () => {
+    expect(applyDetail(base, DETAIL.DECLARABLES)).toBe(base);
+  });
+
+  test("T0 (stacks) collapses to one node per lexicon with cross-lexicon edges", () => {
+    const ir = applyDetail(base, DETAIL.STACKS);
+    expect(ir.nodes.map((n) => n.id)).toEqual(["gcp", "k8s"]);
+    expect(ir.nodes.every((n) => n.kind === "stack")).toBe(true);
+    // subnet→vpc is intra-gcp (dropped); dbDeployment→subnet is k8s→gcp (kept).
+    expect(ir.edges).toEqual([{ from: "k8s", to: "gcp", kind: "ref" }]);
+  });
+
+  test("T1 (composites) collapses a composite instance to a single node", () => {
+    const ir = applyDetail(base, DETAIL.COMPOSITES);
+    expect(ir.nodes.map((n) => n.id).sort()).toEqual(["db", "subnet", "vpc"]);
+    const db = ir.nodes.find((n) => n.id === "db")!;
+    expect(db).toMatchObject({ kind: "DbStack", lexicon: "k8s", attrs: { members: 2 } });
+    // The composite's external ref is preserved, remapped to the composite node.
+    expect(ir.edges).toContainEqual({ from: "db", to: "subnet", kind: "ref" });
+    // The intra-gcp edge survives with its label.
+    expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" });
+  });
+
+  test("T1 node count is between T0 and T2", () => {
+    const t0 = applyDetail(base, DETAIL.STACKS).nodes.length;
+    const t1 = applyDetail(base, DETAIL.COMPOSITES).nodes.length;
+    const t2 = applyDetail(base, DETAIL.DECLARABLES).nodes.length;
+    expect(t0).toBeLessThan(t1);
+    expect(t1).toBeLessThan(t2);
+  });
+
+  test("T3 (attributes) annotates edges with the producer attribute", () => {
+    const ir = applyDetail(base, DETAIL.ATTRIBUTES);
+    expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network", toAttr: "id" });
+    expect(ir.edges).toContainEqual({
+      from: "dbDeployment",
+      to: "subnet",
+      kind: "ref",
+      viaAttr: "subnet",
+      toAttr: "selfLink",
+    });
+  });
+});

package/src/graph-detail.ts

@@ -0,0 +1,149 @@
+import type { GraphIR, IRNode, IREdge } from "./graph-ir";
+
+/**
+ * Detail tiers — the diagram "detail dial". Each level is a pure IR → IR
+ * transform over the base graph IR (no re-discovery), so every emitter and the
+ * painter get them for free. See issue #494 / epic #492.
+ *
+ * - 0 STACKS      — one node per lexicon; edges are cross-lexicon dependencies
+ * - 1 COMPOSITES  — composite instances collapsed to a single node each
+ * - 2 DECLARABLES — every resource (the base produced by buildGraphIr)
+ * - 3 ATTRIBUTES  — declarables plus the producer attribute on each edge
+ */
+export type DetailLevel = 0 | 1 | 2 | 3;
+
+export const DETAIL = {
+  STACKS: 0,
+  COMPOSITES: 1,
+  DECLARABLES: 2,
+  ATTRIBUTES: 3,
+} as const;
+
+/** Apply a detail tier to the base (declarable-level) IR. */
+export function applyDetail(ir: GraphIR, level: DetailLevel): GraphIR {
+  switch (level) {
+    case 0:
+      return toStacks(ir);
+    case 1:
+      return toComposites(ir);
+    case 3:
+      return toAttributes(ir);
+    case 2:
+    default:
+      return ir;
+  }
+}
+
+function edgeSortKey(e: IREdge): string {
+  return `${e.from}\0${e.to}\0${e.viaAttr ?? ""}`;
+}
+
+function sortEdges(edges: IREdge[]): IREdge[] {
+  return edges.sort((a, b) => edgeSortKey(a).localeCompare(edgeSortKey(b)));
+}
+
+function byLexiconOf(nodes: IRNode[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const n of nodes) (out[n.lexicon] ??= []).push(n.id);
+  const sorted: Record<string, string[]> = {};
+  for (const k of Object.keys(out).sort()) sorted[k] = out[k].sort();
+  return sorted;
+}
+
+/** T0 — collapse every resource to its lexicon; edges become cross-lexicon deps. */
+function toStacks(ir: GraphIR): GraphIR {
+  const lexOf = new Map(ir.nodes.map((n) => [n.id, n.lexicon]));
+  const lexicons = [...new Set(ir.nodes.map((n) => n.lexicon))].sort();
+  const nodes: IRNode[] = lexicons.map((l) => ({ id: l, kind: "stack", lexicon: l, attrs: {} }));
+
+  const seen = new Map<string, IREdge>();
+  for (const e of ir.edges) {
+    const from = lexOf.get(e.from);
+    const to = lexOf.get(e.to);
+    if (!from || !to || from === to) continue;
+    const key = `${from}\0${to}`;
+    if (!seen.has(key)) seen.set(key, { from, to, kind: "ref" });
+  }
+  return { nodes, edges: sortEdges([...seen.values()]), groups: {} };
+}
+
+/** T1 — collapse each composite instance to one node; internal edges disappear. */
+function toComposites(ir: GraphIR): GraphIR {
+  const idMap = new Map<string, string>();
+  for (const n of ir.nodes) idMap.set(n.id, n.compositeInstance ?? n.id);
+
+  const instances = new Map<string, IRNode[]>();
+  const plain: IRNode[] = [];
+  for (const n of ir.nodes) {
+    if (n.compositeInstance) {
+      const arr = instances.get(n.compositeInstance) ?? [];
+      arr.push(n);
+      instances.set(n.compositeInstance, arr);
+    } else {
+      plain.push({ ...n });
+    }
+  }
+
+  const nodes: IRNode[] = [...plain];
+  for (const [inst, members] of instances) {
+    const types = new Set(members.map((m) => m.compositeParent).filter(Boolean) as string[]);
+    const lexicons = new Set(members.map((m) => m.lexicon));
+    nodes.push({
+      id: inst,
+      kind: types.size === 1 ? [...types][0] : "Composite",
+      lexicon: lexicons.size === 1 ? [...lexicons][0] : "multi",
+      attrs: { members: members.length },
+    });
+  }
+
+  const seen = new Map<string, IREdge>();
+  for (const e of ir.edges) {
+    const from = idMap.get(e.from) ?? e.from;
+    const to = idMap.get(e.to) ?? e.to;
+    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;
+    const edge: IREdge = collapsed
+      ? { from, to, kind: "ref" }
+      : { from, to, kind: "ref", viaAttr: e.viaAttr };
+    const key = `${from}\0${to}\0${edge.viaAttr ?? ""}`;
+    if (!seen.has(key)) seen.set(key, edge);
+  }
+
+  nodes.sort((a, b) => a.id.localeCompare(b.id));
+  return { nodes, edges: sortEdges([...seen.values()]), groups: { byLexicon: byLexiconOf(nodes) } };
+}
+
+/** T3 — annotate each edge with the producer attribute it references. */
+function toAttributes(ir: GraphIR): GraphIR {
+  const nodeById = new Map(ir.nodes.map((n) => [n.id, n]));
+  const edges = ir.edges.map((e) => {
+    const node = nodeById.get(e.from);
+    const toAttr = node ? findRefAttr(node.attrs, e.to) : undefined;
+    return toAttr ? { ...e, toAttr } : { ...e };
+  });
+  return { ...ir, edges };
+}
+
+/** Find the attribute in a `{ $ref: "producer.attribute" }` envelope under attrs. */
+function findRefAttr(attrs: Record<string, unknown>, producer: string): string | undefined {
+  let found: string | undefined;
+  const visit = (v: unknown): void => {
+    if (found !== undefined || v === null || typeof v !== "object") return;
+    if (Array.isArray(v)) {
+      for (const item of v) visit(item);
+      return;
+    }
+    const ref = (v as { $ref?: unknown }).$ref;
+    if (typeof ref === "string") {
+      const dot = ref.indexOf(".");
+      if (dot > 0 && ref.slice(0, dot) === producer) {
+        found = ref.slice(dot + 1);
+        return;
+      }
+    }
+    for (const val of Object.values(v as Record<string, unknown>)) visit(val);
+  };
+  visit(attrs);
+  return found;
+}