@intentius/chant 0.8.2 → 0.10.0

package/src/graph-dot.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect } from "vitest";
+import { toDot } from "./graph-dot";
+import { parseDotJson } from "./graph-layout";
+import type { GraphIR } from "./graph-ir";
+
+const ir: GraphIR = {
+  nodes: [
+    { id: "vpc", kind: "Vpc", lexicon: "gcp", attrs: {} },
+    { id: "subnet", kind: "Subnet", lexicon: "gcp", attrs: {} },
+    { id: "ns", kind: "Namespace", lexicon: "k8s", attrs: {} },
+  ],
+  edges: [
+    { from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" },
+    { from: "ns", to: "subnet", kind: "ref", viaAttr: "subnet", toAttr: "selfLink" },
+  ],
+  groups: { byLexicon: { gcp: ["subnet", "vpc"], k8s: ["ns"] } },
+};
+
+describe("toDot", () => {
+  test("emits a digraph with lexicon clusters, nodes, and labelled edges", () => {
+    const dot = toDot(ir);
+    expect(dot).toContain("digraph chant {");
+    expect(dot).toContain('subgraph "cluster_gcp" {');
+    expect(dot).toContain('label="gcp";');
+    expect(dot).toContain('"vpc" [label="vpc\\nVpc"];');
+    expect(dot).toContain('"subnet" -> "vpc" [label="network"];');
+    expect(dot).toContain('"ns" -> "subnet" [label="subnet → selfLink"];');
+  });
+
+  test("is deterministic", () => {
+    expect(toDot(ir)).toEqual(toDot(ir));
+  });
+
+  test("places ungrouped nodes at the top level", () => {
+    const dot = toDot({
+      nodes: [{ id: "loner", kind: "Thing", lexicon: "x", attrs: {} }],
+      edges: [],
+      groups: {},
+    });
+    expect(dot).toContain('"loner" [label="loner\\nThing"];');
+    expect(dot).not.toContain("subgraph");
+  });
+});
+
+describe("parseDotJson", () => {
+  test("parses bounding box and node positions, sorted by id", () => {
+    const json = JSON.stringify({
+      bb: "0,0,200,300",
+      objects: [
+        { name: "vpc", pos: "100,280" },
+        { name: "subnet", pos: "100,20" },
+      ],
+    });
+    const layout = parseDotJson(json);
+    expect(layout).toEqual({
+      width: 200,
+      height: 300,
+      nodes: [
+        { id: "subnet", x: 100, y: 20 },
+        { id: "vpc", x: 100, y: 280 },
+      ],
+    });
+  });
+
+  test("throws on a malformed bounding box", () => {
+    expect(() => parseDotJson(JSON.stringify({ bb: "0,0", objects: [] }))).toThrow();
+  });
+});

package/src/graph-dot.ts

@@ -0,0 +1,58 @@
+import type { GraphIR, IRNode, IREdge } from "./graph-ir";
+
+/**
+ * Render the graph IR as Graphviz DOT. Pure text — no `dot` needed to produce
+ * it. Two consumers: render directly with `dot -Tsvg` (mingrammer-style), or
+ * feed it to a layout engine for node positions that a custom painter draws
+ * (the rackattack pattern; see {@link toLayout}). See issue #497 / epic #492.
+ *
+ * Consumes whatever IR it is given, so `--detail` (and future `--lens`) flow
+ * through for free.
+ */
+export function toDot(ir: GraphIR): string {
+  const lines: string[] = ["digraph chant {", "  rankdir=TB;", '  node [shape=box];'];
+
+  const byLexicon = ir.groups.byLexicon;
+  const grouped = new Set<string>();
+  if (byLexicon) {
+    for (const [lexicon, members] of Object.entries(byLexicon)) {
+      lines.push(`  subgraph ${q(`cluster_${lexicon}`)} {`);
+      lines.push(`    label=${q(lexicon)};`);
+      for (const id of members) {
+        const node = ir.nodes.find((n) => n.id === id);
+        if (!node) continue;
+        grouped.add(id);
+        lines.push(`    ${nodeLine(node)}`);
+      }
+      lines.push("  }");
+    }
+  }
+  for (const node of ir.nodes) {
+    if (grouped.has(node.id)) continue;
+    lines.push(`  ${nodeLine(node)}`);
+  }
+
+  for (const e of ir.edges) lines.push(`  ${edgeLine(e)}`);
+
+  lines.push("}");
+  return lines.join("\n") + "\n";
+}
+
+function nodeLine(node: IRNode): string {
+  const label = node.kind && node.kind !== node.id ? `${node.id}\n${node.kind}` : node.id;
+  return `${q(node.id)} [label=${q(label)}];`;
+}
+
+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};`;
+}
+
+/** Quote a DOT identifier/label. Graphviz accepts any string in double quotes;
+ * a real newline becomes the DOT line-break escape. */
+function q(s: string): string {
+  const esc = s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+  return `"${esc}"`;
+}

package/src/graph-ir.test.ts

@@ -0,0 +1,122 @@
+import { describe, test, expect } from "vitest";
+import { buildGraphIr } from "./graph-ir";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import { AttrRef } from "./attrref";
+import { resolveAttrRefs } from "./discovery/resolve";
+import { setProvenance } from "./provenance";
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+describe("buildGraphIr", () => {
+  test("emits a node per resource with kind, lexicon, and scrubbed attrs", () => {
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc", props: { autoCreateSubnetworks: false } });
+    const entities = new Map<string, Declarable>([["vpc", vpc]]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.nodes).toHaveLength(1);
+    expect(ir.nodes[0]).toMatchObject({ id: "vpc", kind: "Vpc", lexicon: "gcp" });
+    // `props` is flattened into attrs (field reads as the property, not props.x).
+    expect(ir.nodes[0].attrs).toEqual({ autoCreateSubnetworks: false });
+    // Framework fields are scrubbed out of attrs.
+    expect(ir.nodes[0].attrs).not.toHaveProperty("lexicon");
+    expect(ir.nodes[0].attrs).not.toHaveProperty("entityType");
+  });
+
+  test("derives ref edges labelled with the consumer property", () => {
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const subnet = decl({ lexicon: "gcp", entityType: "Subnet", props: { network: new AttrRef(vpc, "id") } });
+    const entities = new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.edges).toEqual([{ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" }]);
+    // The ref also appears in the consumer's attrs as an auditable envelope.
+    expect(ir.nodes.find((n) => n.id === "subnet")!.attrs).toEqual({
+      network: { $ref: "vpc.id" },
+    });
+  });
+
+  test("excludes property-kind declarables and keeps resources", () => {
+    const resource = decl({ lexicon: "k8s", entityType: "Deployment" });
+    const prop = decl({ lexicon: "k8s", entityType: "Probe", kind: "property" as const });
+    const entities = new Map<string, Declarable>([
+      ["dep", resource],
+      ["probe", prop],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.nodes.map((n) => n.id)).toEqual(["dep"]);
+  });
+
+  test("populates compositeParent and byComposite from provenance", () => {
+    const sts = decl({ lexicon: "k8s", entityType: "StatefulSet" });
+    const svc = decl({ lexicon: "k8s", entityType: "Service" });
+    setProvenance(sts, { composite: "CockroachDbCluster", sourceFile: "/proj/src/db.ts" });
+    setProvenance(svc, { composite: "CockroachDbCluster", sourceFile: "/proj/src/db.ts" });
+    const entities = new Map<string, Declarable>([
+      ["dbSts", sts],
+      ["dbSvc", svc],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities, "/proj");
+    expect(ir.nodes.every((n) => n.compositeParent === "CockroachDbCluster")).toBe(true);
+    expect(ir.groups.byComposite).toEqual({ CockroachDbCluster: ["dbSts", "dbSvc"] });
+    // Source file is relativized to the project root.
+    expect(ir.nodes[0].sourceLoc).toEqual({ file: "src/db.ts" });
+  });
+
+  test("reads non-enumerable props like real lexicon entities", () => {
+    // Real lexicon resources define lexicon/entityType/props as non-enumerable,
+    // so Object.entries(entity) is empty — attrs and edges must come from props.
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const subnet = { [DECLARABLE_MARKER]: true } as Declarable & { props: unknown };
+    Object.defineProperties(subnet, {
+      lexicon: { value: "gcp", enumerable: false },
+      entityType: { value: "Subnet", enumerable: false },
+      props: { value: { cidr: "10.0.0.0/16", network: new AttrRef(vpc, "id") }, enumerable: false },
+    });
+    const entities = new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    const subnetNode = ir.nodes.find((n) => n.id === "subnet")!;
+    expect(subnetNode.attrs).toEqual({ cidr: "10.0.0.0/16", network: { $ref: "vpc.id" } });
+    expect(ir.edges).toEqual([{ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" }]);
+  });
+
+  test("groups nodes by lexicon and is deterministic", () => {
+    const a = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const b = decl({ lexicon: "k8s", entityType: "Namespace" });
+    const c = decl({ lexicon: "gcp", entityType: "Subnet" });
+    const entities = new Map<string, Declarable>([
+      ["zeta", c],
+      ["alpha", a],
+      ["mid", b],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.nodes.map((n) => n.id)).toEqual(["alpha", "mid", "zeta"]); // sorted
+    expect(ir.groups.byLexicon).toEqual({ gcp: ["alpha", "zeta"], k8s: ["mid"] });
+
+    // Same input (different insertion order) yields identical IR.
+    const reordered = new Map<string, Declarable>([
+      ["alpha", a],
+      ["mid", b],
+      ["zeta", c],
+    ]);
+    resolveAttrRefs(reordered);
+    expect(JSON.stringify(buildGraphIr(reordered))).toEqual(JSON.stringify(ir));
+  });
+});

package/src/graph-ir.ts

@@ -0,0 +1,285 @@
+import { relative, isAbsolute } from "node:path";
+import { AttrRef } from "./attrref";
+import { type Declarable, isDeclarable } from "./declarable";
+import { isLexiconOutput } from "./lexicon-output";
+import { getProvenance } from "./provenance";
+import { INTRINSIC_MARKER } from "./intrinsic";
+
+/**
+ * Graph IR — the engine-neutral, lint-gated representation of a project's
+ * resolved infrastructure graph. Painters (mermaid, graphviz, custom SVG) and
+ * the agentic diagrammer consume this; it is a pure function of lint-clean
+ * source. Every node traces to the file that declared it; every edge is a real
+ * cross-resource reference (AttrRef).
+ *
+ * Emitted by `chant graph --format ir`. See issue #493 / epic #492.
+ */
+
+/** Where in the source a node came from. Entity-level (file), not a line map. */
+export interface SourceLoc {
+  /** Path of the declaring file, relative to the project root when possible. */
+  file: string;
+  /**
+   * Line number, when available. Provenance is entity-level today, so this is
+   * usually absent — reserved for a future source map.
+   */
+  line?: number;
+}
+
+/** A reference in an attribute projection: `<producer>.<attribute>`. */
+export interface AttrRefEnvelope {
+  $ref: string;
+}
+
+/** One resource in the graph. */
+export interface IRNode {
+  /** Logical name (the export name, or composite-expanded name). */
+  id: string;
+  /** Resource type, e.g. "GkeCluster". */
+  kind: string;
+  /** Lexicon the resource belongs to, e.g. "gcp". */
+  lexicon: string;
+  /**
+   * Name of the composite *type* that expanded this node, when it came from one
+   * (e.g. "CockroachDbCluster").
+   */
+  compositeParent?: string;
+  /**
+   * The composite *instance* (export name) this node belongs to — shared by every
+   * node from the same composite call. Detail tiers collapse on this (#494).
+   */
+  compositeInstance?: string;
+  /** Literal/const/ref-resolved props. References appear as `{ $ref }`. */
+  attrs: Record<string, unknown>;
+  /** Where the node was declared. */
+  sourceLoc?: SourceLoc;
+}
+
+/** A directed dependency: `from` references an attribute of `to`. */
+export interface IREdge {
+  from: string;
+  to: string;
+  /** "ref" for an AttrRef-derived edge. */
+  kind: "ref";
+  /** The consumer-side property the reference flows through, when derivable. */
+  viaAttr?: string;
+  /** The producer-side attribute referenced (e.g. "id"). Added at detail T3. */
+  toAttr?: string;
+}
+
+/** Grouping metadata for cluster/subgraph rendering. Maps group name -> node ids. */
+export interface IRGroups {
+  byLexicon?: Record<string, string[]>;
+  byComposite?: Record<string, string[]>;
+  /** Reserved for stack grouping (#494). */
+  byStack?: Record<string, string[]>;
+}
+
+/** The full graph IR for a project at the default (declarable) detail level. */
+export interface GraphIR {
+  nodes: IRNode[];
+  edges: IREdge[];
+  groups: IRGroups;
+}
+
+/** A node is anything that serializes to a resource — not a property or output. */
+function isNodeEntity(entity: Declarable): boolean {
+  if (isLexiconOutput(entity)) return false;
+  if (entity.kind === "property") return false;
+  return true;
+}
+
+function relFile(file: string | undefined, projectPath?: string): string | undefined {
+  if (!file) return undefined;
+  if (projectPath && isAbsolute(file)) {
+    const rel = relative(projectPath, file);
+    return rel.startsWith("..") ? file : rel;
+  }
+  return file;
+}
+
+/** Resolve the producer (logical name) an AttrRef points at. */
+function refTarget(ref: AttrRef, reverse: Map<object, string>): string | undefined {
+  // Nested refs (under `props`) aren't assigned a logical name by resolveAttrRefs,
+  // which only resolves top-level own props — so fall back to the parent's name.
+  const parent = ref.parent.deref();
+  return ref.getLogicalName() ?? (parent ? reverse.get(parent) : undefined);
+}
+
+/** Project a value into a JSON-safe, scrubbed form. References become `{ $ref }`. */
+function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string>): unknown {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") return value;
+  if (t !== "object") return undefined; // functions, symbols, undefined
+
+  if (value instanceof AttrRef) {
+    const to = refTarget(value, reverse);
+    return { $ref: to ? `${to}.${value.attribute}` : value.attribute } satisfies AttrRefEnvelope;
+  }
+  // Other intrinsics (interpolations, pseudo-parameters): mark, don't inline.
+  if ((value as Record<symbol, unknown>)[INTRINSIC_MARKER] === true) {
+    return { $intrinsic: true };
+  }
+
+  if (seen.has(value)) return undefined; // break cycles
+  seen.add(value);
+
+  // Nested declarables (e.g. an inlined property-kind resource) keep their
+  // config in a non-enumerable `props` bag, like top-level nodes — project that.
+  if (isDeclarable(value)) {
+    const out = projectConfig(value, seen, reverse);
+    seen.delete(value);
+    return out;
+  }
+
+  if (Array.isArray(value)) {
+    const out = value.map((v) => project(v, seen, reverse)).filter((v) => v !== undefined);
+    seen.delete(value);
+    return out;
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    const p = project(v, seen, reverse);
+    if (p !== undefined) out[k] = p;
+  }
+  seen.delete(value);
+  return out;
+}
+
+const SKIP_KEYS = new Set(["lexicon", "entityType", "kind", "attributes", "Ref"]);
+
+/** The config bag of a node, paired with each key. Lexicon entities keep their
+ * declared props in a (usually non-enumerable) `props` object; simpler entities
+ * carry config as enumerable own properties. We surface both, flattening `props`
+ * so a field reads as e.g. `network`, not `props.network`. */
+function configRoots(entity: Declarable): Array<[string, unknown]> {
+  const out: Array<[string, unknown]> = [];
+  for (const [k, v] of Object.entries(entity)) {
+    if (SKIP_KEYS.has(k) || k === "props") continue;
+    out.push([k, v]);
+  }
+  const props = (entity as unknown as { props?: unknown }).props;
+  if (props && typeof props === "object" && !Array.isArray(props)) {
+    for (const [k, v] of Object.entries(props as Record<string, unknown>)) out.push([k, v]);
+  }
+  return out;
+}
+
+/** Project a declarable's config bag (flattened props + enumerable own props). */
+function projectConfig(
+  entity: Declarable,
+  seen: Set<unknown>,
+  reverse: Map<object, string>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of configRoots(entity)) {
+    const p = project(v, seen, reverse);
+    if (p !== undefined) out[k] = p;
+  }
+  return out;
+}
+
+/** Collect ref edges from one node, labelling each with its consumer property. */
+function collectEdges(
+  entity: Declarable,
+  from: string,
+  nodeIds: Set<string>,
+  reverse: Map<object, string>,
+): IREdge[] {
+  const edges: IREdge[] = [];
+  const seen = new Set<unknown>();
+  const visit = (value: unknown, viaAttr: string): void => {
+    if (value === null || typeof value !== "object") return;
+    if (value instanceof AttrRef) {
+      const to = refTarget(value, reverse);
+      if (to && to !== from && nodeIds.has(to)) {
+        edges.push({ from, to, kind: "ref", viaAttr });
+      }
+      return;
+    }
+    if ((value as Record<symbol, unknown>)[INTRINSIC_MARKER] === true) return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item, viaAttr);
+      return;
+    }
+    for (const v of Object.values(value as Record<string, unknown>)) visit(v, viaAttr);
+  };
+  for (const [k, v] of configRoots(entity)) visit(v, k);
+  return edges;
+}
+
+/** Stable key for deduping and sorting an edge. */
+function edgeKey(e: IREdge): string {
+  return `${e.from}\0${e.to}\0${e.viaAttr ?? ""}`;
+}
+
+/**
+ * Build the graph IR from resolved entities (the output of `discover`). Pure and
+ * deterministic: nodes and edges are sorted, so the same source yields identical
+ * IR. `projectPath` relativizes source-file paths for portable output.
+ */
+export function buildGraphIr(
+  entities: Map<string, Declarable>,
+  projectPath?: string,
+): GraphIR {
+  // Reverse lookup for producers whose AttrRef logical name wasn't resolved.
+  const reverse = new Map<object, string>();
+  for (const [name, entity] of entities) reverse.set(entity, name);
+
+  const nodeIds = new Set<string>();
+  for (const [name, entity] of entities) {
+    if (isNodeEntity(entity)) nodeIds.add(name);
+  }
+
+  const nodes: IRNode[] = [];
+  const byLexicon: Record<string, string[]> = {};
+  const byComposite: Record<string, string[]> = {};
+
+  for (const [name, entity] of entities) {
+    if (!nodeIds.has(name)) continue;
+    const prov = getProvenance(entity);
+    const node: IRNode = {
+      id: name,
+      kind: entity.entityType,
+      lexicon: entity.lexicon,
+      attrs: projectConfig(entity, new Set(), reverse),
+    };
+    if (prov?.composite) node.compositeParent = prov.composite;
+    if (prov?.compositeInstance) node.compositeInstance = prov.compositeInstance;
+    const file = relFile(prov?.sourceFile, projectPath);
+    if (file) node.sourceLoc = { file };
+    nodes.push(node);
+
+    (byLexicon[entity.lexicon] ??= []).push(name);
+    if (prov?.composite) (byComposite[prov.composite] ??= []).push(name);
+  }
+
+  const edgeMap = new Map<string, IREdge>();
+  for (const [name, entity] of entities) {
+    if (!nodeIds.has(name)) continue;
+    for (const e of collectEdges(entity, name, nodeIds, reverse)) {
+      edgeMap.set(edgeKey(e), e);
+    }
+  }
+
+  nodes.sort((a, b) => a.id.localeCompare(b.id));
+  const edges = [...edgeMap.values()].sort((a, b) => edgeKey(a).localeCompare(edgeKey(b)));
+  for (const ids of Object.values(byLexicon)) ids.sort();
+  for (const ids of Object.values(byComposite)) ids.sort();
+
+  const groups: IRGroups = {};
+  if (Object.keys(byLexicon).length) groups.byLexicon = sortKeys(byLexicon);
+  if (Object.keys(byComposite).length) groups.byComposite = sortKeys(byComposite);
+
+  return { nodes, edges, groups };
+}
+
+function sortKeys(rec: Record<string, string[]>): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const k of Object.keys(rec).sort()) out[k] = rec[k];
+  return out;
+}

package/src/graph-layout.ts

@@ -0,0 +1,104 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Layout-position export — node coordinates a custom painter consumes (the
+ * rackattack pattern: Graphviz lays out, the painter draws). Graphviz is used
+ * for LAYOUT ONLY; its rendering is discarded. See issue #497 / epic #492.
+ *
+ * The {@link LayoutEngine} interface exists so a pure-JS engine (elkjs/dagre)
+ * can drop in later for a zero-native-dependency path — closing the install gap
+ * so a painter can run without `dot`.
+ */
+
+/** A laid-out position in the engine's coordinate space. */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/** Node positions plus the overall canvas size a painter needs. */
+export interface Layout {
+  /** Canvas width in the engine's coordinate space. */
+  width: number;
+  /** Canvas height in the engine's coordinate space. */
+  height: number;
+  /** Each node's centre position, ordered by id for deterministic output. */
+  nodes: Array<{ id: string } & Point>;
+}
+
+/** Turns DOT into node positions. The painter consumes the result; it never
+ * asks the engine to paint. */
+export interface LayoutEngine {
+  readonly name: string;
+  layout(dot: string): Promise<Layout>;
+}
+
+/** Layout via `dot -Tjson`. Requires Graphviz (`brew install graphviz`). */
+export class GraphvizLayout implements LayoutEngine {
+  readonly name = "graphviz";
+
+  async layout(dot: string): Promise<Layout> {
+    return parseDotJson(await runDot(dot));
+  }
+}
+
+function runDot(dot: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let proc;
+    try {
+      proc = spawn("dot", ["-Tjson"], { stdio: ["pipe", "pipe", "pipe"] });
+    } catch (err) {
+      reject(installHint(err));
+      return;
+    }
+    let out = "";
+    let errOut = "";
+    proc.stdout.on("data", (d) => (out += d));
+    proc.stderr.on("data", (d) => (errOut += d));
+    proc.on("error", (err) => reject(installHint(err)));
+    proc.on("close", (code) => {
+      if (code !== 0) reject(new Error(`dot exited ${code}: ${errOut.trim()}`));
+      else resolve(out);
+    });
+    proc.stdin.write(dot);
+    proc.stdin.end();
+  });
+}
+
+function installHint(err: unknown): Error {
+  const msg = err instanceof Error ? err.message : String(err);
+  return new Error(
+    `could not run 'dot' (${msg}). Graphviz is required for --format layout — ` +
+      `install it with 'brew install graphviz', or use --format mermaid, which needs no native dependency.`,
+  );
+}
+
+interface DotJson {
+  bb?: string;
+  objects?: Array<{ name?: string; pos?: string }>;
+}
+
+/** Parse `dot -Tjson` output into a {@link Layout}. Pure; exported for testing. */
+export function parseDotJson(json: string): Layout {
+  const parsed = JSON.parse(json) as DotJson;
+  const bb = (parsed.bb ?? "").split(",");
+  if (bb.length !== 4) throw new Error(`bad bounding box ${parsed.bb}`);
+  const width = num(bb[2]);
+  const height = num(bb[3]);
+  if (width === 0 || height === 0) throw new Error("zero graph bounds");
+
+  const nodes: Array<{ id: string } & Point> = [];
+  for (const o of parsed.objects ?? []) {
+    if (!o.name || !o.pos) continue;
+    const p = o.pos.split(",");
+    if (p.length !== 2) continue;
+    nodes.push({ id: o.name, x: num(p[0]), y: num(p[1]) });
+  }
+  nodes.sort((a, b) => a.id.localeCompare(b.id));
+  return { width, height, nodes };
+}
+
+function num(s: string): number {
+  const f = Number.parseFloat(s.trim());
+  return Number.isFinite(f) ? f : 0;
+}