@intentius/chant 0.9.0 → 0.11.0

package/src/cli/handlers/graph.ts

@@ -2,8 +2,12 @@ import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph } from "../../build";
-import { buildGraphIr } from "../../graph-ir";
+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";
@@ -11,21 +15,29 @@ 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; `--format ir` emits the full entity-graph IR
- * (lint-gated) for diagram painters and the agentic diagrammer (#493).
+ * 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> {
-  if (ctx.args.format === "ir") return runGraphIr(ctx);
+  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` — emit the graph IR as JSON. Lint-gated: the IR is a
- * representation of valid infra, so we refuse to emit it for source that does
- * not pass lint (EVL + lexicon rules). Non-zero exit on discovery errors.
+ * `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 runGraphIr(ctx: CommandContext): Promise<number> {
+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;
@@ -34,13 +46,13 @@ async function runGraphIr(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  // Gate: only emit an IR for lint-clean source.
+  // 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 IR: source has lint errors. Run `chant lint` and fix them first.",
+          "Refusing to emit graph: source has lint errors. Run `chant lint` and fix them first.",
       }),
     );
     return 1;
@@ -52,9 +64,40 @@ async function runGraphIr(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  const ir = applyDetail(buildGraphIr(result.entities, projectPath), level as DetailLevel);
-  console.log(JSON.stringify(ir, null, 2));
-  return 0;
+  // 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> {

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

@@ -128,6 +128,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       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") {
@@ -193,8 +199,11 @@ Ops:
   run log <name>        Show run history for an Op
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
-                        --format ir for the lint-gated entity-graph IR;
-                        --detail 0..3: stacks|composites|declarables|attributes)
+                        --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

@@ -59,6 +59,12 @@ export interface ParsedArgs {
   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/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-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;
+}

package/src/graph-lens.test.ts

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "vitest";
+import { parseLens, applyLens } from "./graph-lens";
+import type { GraphIR } from "./graph-ir";
+
+// vpc <- subnet <- cluster (gcp), cluster <- pod (k8s). A linear dependency
+// chain crossing two lexicons.
+const ir: GraphIR = {
+  nodes: [
+    { id: "vpc", kind: "Vpc", lexicon: "gcp", attrs: {} },
+    { id: "subnet", kind: "Subnet", lexicon: "gcp", attrs: {} },
+    { id: "cluster", kind: "GkeCluster", lexicon: "gcp", attrs: {} },
+    { id: "pod", kind: "Pod", lexicon: "k8s", attrs: {} },
+  ],
+  edges: [
+    { from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" },
+    { from: "cluster", to: "subnet", kind: "ref", viaAttr: "subnetwork" },
+    { from: "pod", to: "cluster", kind: "ref", viaAttr: "cluster" },
+  ],
+  groups: { byLexicon: { gcp: ["cluster", "subnet", "vpc"], k8s: ["pod"] } },
+};
+
+describe("parseLens", () => {
+  test("parses kind:target", () => {
+    expect(parseLens("lexicon:gcp")).toMatchObject({ kind: "lexicon", target: "gcp" });
+  });
+  test("blast defaults to both directions", () => {
+    expect(parseLens("blast:cluster")).toMatchObject({ up: true, down: true });
+  });
+  test("blast honours --up / --down", () => {
+    expect(parseLens("blast:cluster", { up: true })).toMatchObject({ up: true, down: false });
+  });
+  test("rejects malformed and unknown lenses", () => {
+    expect(() => parseLens("gcp")).toThrow();
+    expect(() => parseLens("bogus:x")).toThrow();
+  });
+});
+
+describe("applyLens", () => {
+  test("lexicon: keeps only that lexicon's nodes and internal edges", () => {
+    const out = applyLens(ir, parseLens("lexicon:gcp"));
+    expect(out.nodes.map((n) => n.id).sort()).toEqual(["cluster", "subnet", "vpc"]);
+    // cross-lexicon pod→cluster edge dropped; gcp-internal edges kept
+    expect(out.edges.map((e) => `${e.from}->${e.to}`).sort()).toEqual([
+      "cluster->subnet",
+      "subnet->vpc",
+    ]);
+    expect(out.groups.byLexicon).toEqual({ gcp: ["cluster", "subnet", "vpc"] });
+  });
+
+  test("lexicon: count matches the byLexicon partition", () => {
+    const out = applyLens(ir, parseLens("lexicon:gcp"));
+    expect(out.nodes.length).toBe(ir.groups.byLexicon!.gcp.length);
+  });
+
+  test("blast --up returns the producer chain above a node", () => {
+    const out = applyLens(ir, parseLens("blast:cluster", { up: true }));
+    expect(out.nodes.map((n) => n.id).sort()).toEqual(["cluster", "subnet", "vpc"]);
+  });
+
+  test("blast --down returns the dependents below a node", () => {
+    const out = applyLens(ir, parseLens("blast:cluster", { down: true }));
+    expect(out.nodes.map((n) => n.id).sort()).toEqual(["cluster", "pod"]);
+  });
+
+  test("blast both returns the whole connected chain", () => {
+    const out = applyLens(ir, parseLens("blast:cluster"));
+    expect(out.nodes.map((n) => n.id).sort()).toEqual(["cluster", "pod", "subnet", "vpc"]);
+  });
+
+  test("blast on a leaf returns just its chain", () => {
+    const out = applyLens(ir, parseLens("blast:vpc", { up: true }));
+    expect(out.nodes.map((n) => n.id)).toEqual(["vpc"]); // vpc depends on nothing
+    expect(out.edges).toEqual([]);
+  });
+
+  test("throws when the target matches nothing", () => {
+    expect(() => applyLens(ir, parseLens("lexicon:aws"))).toThrow();
+    expect(() => applyLens(ir, parseLens("blast:ghost"))).toThrow();
+  });
+});

package/src/graph-lens.ts

@@ -0,0 +1,127 @@
+import type { GraphIR, IRNode, IREdge } from "./graph-ir";
+
+/**
+ * Lenses — focus the graph IR on a slice without touching the source. Pure
+ * IR → IR filters, composable with detail tiers (apply a lens, then view the
+ * result at any `--detail`). See issue #495 / epic #492.
+ *
+ * - `lexicon:<name>` — only nodes in a lexicon
+ * - `stack:<name>`   — only one stack's nodes (stacks map to lexicon partitions today)
+ * - `blast:<nodeId>` — the transitive neighbourhood of a node: what it depends
+ *   on (`--up`), what depends on it (`--down`), or both (default)
+ *
+ * Every lens drops edges that would dangle and rebuilds group metadata from the
+ * surviving nodes, so the result is always a self-consistent graph.
+ */
+export interface LensSpec {
+  kind: "lexicon" | "stack" | "blast";
+  target: string;
+  /** blast: include upstream producers (what the node depends on). */
+  up: boolean;
+  /** blast: include downstream dependents (what depends on the node). */
+  down: boolean;
+}
+
+const KINDS = new Set(["lexicon", "stack", "blast"]);
+
+/** Parse a `--lens` spec. Throws a descriptive Error on a malformed spec. */
+export function parseLens(spec: string, opts: { up?: boolean; down?: boolean } = {}): LensSpec {
+  const colon = spec.indexOf(":");
+  if (colon <= 0 || colon === spec.length - 1) {
+    throw new Error(`Invalid --lens "${spec}". Expected <kind>:<target>, e.g. lexicon:gcp or blast:vpc.`);
+  }
+  const kind = spec.slice(0, colon);
+  const target = spec.slice(colon + 1);
+  if (!KINDS.has(kind)) {
+    throw new Error(`Unknown lens "${kind}". Expected one of: ${[...KINDS].join(", ")}.`);
+  }
+  // For blast, default to both directions when neither flag is given.
+  const both = !opts.up && !opts.down;
+  return {
+    kind: kind as LensSpec["kind"],
+    target,
+    up: opts.up ?? both,
+    down: opts.down ?? both,
+  };
+}
+
+/** Apply a lens to the IR. Throws a descriptive Error when the target matches nothing. */
+export function applyLens(ir: GraphIR, lens: LensSpec): GraphIR {
+  const keep =
+    lens.kind === "blast" ? blastSet(ir, lens) : partitionSet(ir, lens);
+  return subgraph(ir, keep);
+}
+
+/** Node ids for a lexicon/stack lens. */
+function partitionSet(ir: GraphIR, lens: LensSpec): Set<string> {
+  if (lens.kind === "stack") {
+    const members = ir.groups.byStack?.[lens.target] ?? ir.groups.byLexicon?.[lens.target];
+    if (members && members.length) return new Set(members);
+    // Fall through to a direct scan if groups are absent.
+  }
+  const keep = new Set<string>();
+  for (const n of ir.nodes) if (n.lexicon === lens.target) keep.add(n.id);
+  if (keep.size === 0) {
+    throw new Error(`No nodes match lens ${lens.kind}:${lens.target}.`);
+  }
+  return keep;
+}
+
+/** Node ids in the transitive neighbourhood of a node. */
+function blastSet(ir: GraphIR, lens: LensSpec): Set<string> {
+  if (!ir.nodes.some((n) => n.id === lens.target)) {
+    throw new Error(`No node "${lens.target}" for lens blast:${lens.target}.`);
+  }
+  const out = new Map<string, string[]>(); // from -> [to]  (depends-on)
+  const inc = new Map<string, string[]>(); // to -> [from]  (depended-on-by)
+  const push = (m: Map<string, string[]>, k: string, v: string): void => {
+    const arr = m.get(k);
+    if (arr) arr.push(v);
+    else m.set(k, [v]);
+  };
+  for (const e of ir.edges) {
+    push(out, e.from, e.to);
+    push(inc, e.to, e.from);
+  }
+  const keep = new Set<string>([lens.target]);
+  if (lens.up) walk(lens.target, out, keep);
+  if (lens.down) walk(lens.target, inc, keep);
+  return keep;
+}
+
+function walk(start: string, adj: Map<string, string[]>, keep: Set<string>): void {
+  const stack = [start];
+  while (stack.length) {
+    const cur = stack.pop()!;
+    for (const next of adj.get(cur) ?? []) {
+      if (!keep.has(next)) {
+        keep.add(next);
+        stack.push(next);
+      }
+    }
+  }
+}
+
+/** Restrict the IR to a node set: keep internal edges, rebuild groups. */
+function subgraph(ir: GraphIR, keep: Set<string>): GraphIR {
+  const nodes: IRNode[] = ir.nodes.filter((n) => keep.has(n.id));
+  const edges: IREdge[] = ir.edges.filter((e) => keep.has(e.from) && keep.has(e.to));
+
+  const byLexicon: Record<string, string[]> = {};
+  const byComposite: Record<string, string[]> = {};
+  for (const n of nodes) {
+    (byLexicon[n.lexicon] ??= []).push(n.id);
+    if (n.compositeInstance) (byComposite[n.compositeInstance] ??= []).push(n.id);
+  }
+  const groups: GraphIR["groups"] = {};
+  if (Object.keys(byLexicon).length) groups.byLexicon = sortGroups(byLexicon);
+  if (Object.keys(byComposite).length) groups.byComposite = sortGroups(byComposite);
+
+  return { nodes, edges, groups };
+}
+
+function sortGroups(rec: Record<string, string[]>): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const k of Object.keys(rec).sort()) out[k] = rec[k].sort();
+  return out;
+}

package/src/graph-mermaid.test.ts

@@ -0,0 +1,61 @@
+import { describe, test, expect } from "vitest";
+import { toMermaid } from "./graph-mermaid";
+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("toMermaid", () => {
+  test("renders a flowchart with lexicon subgraphs, nodes, and labelled edges", () => {
+    const out = toMermaid(ir);
+    expect(out).toContain("flowchart TD");
+    expect(out).toContain('subgraph lex_gcp["gcp"]');
+    expect(out).toContain('subgraph lex_k8s["k8s"]');
+    // node label = name + kind on two lines
+    expect(out).toContain('vpc["vpc<br/>Vpc"]');
+    // edge with consumer-property label
+    expect(out).toContain("subnet -->|\"network\"| vpc");
+    // T3 edge shows consumer → producer attribute
+    expect(out).toContain('ns -->|"subnet → selfLink"| subnet');
+  });
+
+  test("is deterministic", () => {
+    expect(toMermaid(ir)).toEqual(toMermaid(ir));
+  });
+
+  test("sanitizes ids that aren't Mermaid-safe but keeps the human label", () => {
+    const dirty: GraphIR = {
+      nodes: [
+        { id: "east/db-0", kind: "StatefulSet", lexicon: "k8s", attrs: {} },
+        { id: "east/db-1", kind: "StatefulSet", lexicon: "k8s", attrs: {} },
+      ],
+      edges: [{ from: "east/db-1", to: "east/db-0", kind: "ref" }],
+      groups: {},
+    };
+    const out = toMermaid(dirty);
+    // ids are sanitized and unique
+    expect(out).toContain('east_db_0["east/db-0<br/>StatefulSet"]');
+    expect(out).toContain('east_db_1["east/db-1<br/>StatefulSet"]');
+    expect(out).toContain("east_db_1 --> east_db_0");
+  });
+
+  test("places ungrouped nodes at the top level", () => {
+    const out = toMermaid({
+      nodes: [{ id: "loner", kind: "Thing", lexicon: "x", attrs: {} }],
+      edges: [],
+      groups: {},
+    });
+    expect(out).toContain('loner["loner<br/>Thing"]');
+    expect(out).not.toContain("subgraph");
+  });
+});