@intentius/chant 0.9.0 → 0.10.0

package/dist/cli/handlers/graph.d.ts

@@ -2,8 +2,8 @@ import type { CommandContext } from "../registry.js";
 /**
  * `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 declare function runGraph(ctx: CommandContext): Promise<number>;
 //# sourceMappingURL=graph.d.ts.map

package/dist/cli/handlers/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAInE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAKA,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAe9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuIpD"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAKA,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAe9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA6IpD"}

package/dist/cli/registry.d.ts

@@ -58,6 +58,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/dist/cli/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/cli/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/cli/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,UAAU,CAAC;IAChB,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAC;CACnB;AAWD,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,eAAe,GAAG,IAAI,CAiB/F"}

package/dist/graph-dot.d.ts

@@ -0,0 +1,12 @@
+import type { GraphIR } from "./graph-ir.js";
+/**
+ * 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 declare function toDot(ir: GraphIR): string;
+//# sourceMappingURL=graph-dot.d.ts.map

package/dist/graph-dot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-dot.d.ts","sourceRoot":"","sources":["../src/graph-dot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAE1D;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CA2BzC"}

package/dist/graph-layout.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare class GraphvizLayout implements LayoutEngine {
+    readonly name = "graphviz";
+    layout(dot: string): Promise<Layout>;
+}
+/** Parse `dot -Tjson` output into a {@link Layout}. Pure; exported for testing. */
+export declare function parseDotJson(json: string): Layout;
+//# sourceMappingURL=graph-layout.d.ts.map

package/dist/graph-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-layout.d.ts","sourceRoot":"","sources":["../src/graph-layout.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,mEAAmE;AACnE,MAAM,WAAW,MAAM;IACrB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC,CAAC;CACtC;AAED;+BAC+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtC;AAED,4EAA4E;AAC5E,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,cAAc;IAErB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAG3C;AAsCD,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiBjD"}

package/dist/graph-lens.d.ts

@@ -0,0 +1,30 @@
+import type { GraphIR } from "./graph-ir.js";
+/**
+ * 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;
+}
+/** Parse a `--lens` spec. Throws a descriptive Error on a malformed spec. */
+export declare function parseLens(spec: string, opts?: {
+    up?: boolean;
+    down?: boolean;
+}): LensSpec;
+/** Apply a lens to the IR. Throws a descriptive Error when the target matches nothing. */
+export declare function applyLens(ir: GraphIR, lens: LensSpec): GraphIR;
+//# sourceMappingURL=graph-lens.d.ts.map

package/dist/graph-lens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-lens.d.ts","sourceRoot":"","sources":["../src/graph-lens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,IAAI,EAAE,OAAO,CAAC;CACf;AAID,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,QAAQ,CAkB7F;AAED,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAI9D"}

package/dist/graph-mermaid.d.ts

@@ -0,0 +1,17 @@
+import type { GraphIR } from "./graph-ir.js";
+/**
+ * Render the graph IR as a Mermaid `flowchart`. Mermaid is the zero-install
+ * default — it renders in GitHub, docs, and browsers with no native dependency,
+ * so `chant graph --format mermaid` gives a diagram out of the box without the
+ * standalone painter. Lower fidelity than a custom painter, but portable.
+ *
+ * Consumes whatever IR it is given, so it honours `--detail` and `--lens` for
+ * free (those are IR → IR transforms). See issue #496 / epic #492.
+ *
+ * Known limits: Mermaid owns layout, so there is little control over node
+ * placement, and very large graphs get hard to read — that is the trade-off for
+ * zero-install portability. Reach for the graphviz/custom-painter path (#497,
+ * pinhole) when fidelity matters.
+ */
+export declare function toMermaid(ir: GraphIR): string;
+//# sourceMappingURL=graph-mermaid.d.ts.map

package/dist/graph-mermaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-mermaid.d.ts","sourceRoot":"","sources":["../src/graph-mermaid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAgC7C"}

package/dist/index.d.ts

@@ -26,6 +26,10 @@ export * from "./discovery/cache.js";
 export * from "./build.js";
 export * from "./graph-ir.js";
 export * from "./graph-detail.js";
+export * from "./graph-mermaid.js";
+export * from "./graph-dot.js";
+export * from "./graph-layout.js";
+export * from "./graph-lens.js";
 export * from "./detectLexicon.js";
 export * from "./lint/parser.js";
 export * from "./lint/rule.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,QAAQ,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAClE,cAAc,EAAE,iBAAiB,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,QAAQ,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAClE,cAAc,EAAE,iBAAiB,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/package.json

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

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,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");
+  });
+});

package/src/graph-mermaid.ts

@@ -0,0 +1,85 @@
+import type { GraphIR, IRNode, IREdge } from "./graph-ir";
+
+/**
+ * Render the graph IR as a Mermaid `flowchart`. Mermaid is the zero-install
+ * default — it renders in GitHub, docs, and browsers with no native dependency,
+ * so `chant graph --format mermaid` gives a diagram out of the box without the
+ * standalone painter. Lower fidelity than a custom painter, but portable.
+ *
+ * Consumes whatever IR it is given, so it honours `--detail` and `--lens` for
+ * free (those are IR → IR transforms). See issue #496 / epic #492.
+ *
+ * Known limits: Mermaid owns layout, so there is little control over node
+ * placement, and very large graphs get hard to read — that is the trade-off for
+ * zero-install portability. Reach for the graphviz/custom-painter path (#497,
+ * pinhole) when fidelity matters.
+ */
+export function toMermaid(ir: GraphIR): string {
+  const ids = new Map<string, string>(); // logical name -> mermaid-safe id
+  for (const n of ir.nodes) safeId(n.id, ids);
+
+  const lines: string[] = ["flowchart TD"];
+
+  // Cluster by lexicon when grouping is available; nodes outside any group fall
+  // through to the top level. byLexicon is sorted, so output is deterministic.
+  const byLexicon = ir.groups.byLexicon;
+  const grouped = new Set<string>();
+  if (byLexicon) {
+    for (const [lexicon, members] of Object.entries(byLexicon)) {
+      lines.push(`  subgraph ${safeId(`lex_${lexicon}`, ids)}[${quote(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, ids)}`);
+      }
+      lines.push("  end");
+    }
+  }
+  for (const node of ir.nodes) {
+    if (grouped.has(node.id)) continue;
+    lines.push(`  ${nodeLine(node, ids)}`);
+  }
+
+  for (const e of ir.edges) {
+    lines.push(`  ${edgeLine(e, ids)}`);
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+function nodeLine(node: IRNode, ids: Map<string, string>): string {
+  const id = safeId(node.id, ids);
+  const parts = [node.id];
+  if (node.kind && node.kind !== node.id) parts.push(node.kind);
+  return `${id}[${quote(parts.join("\n"))}]`;
+}
+
+function edgeLine(e: IREdge, ids: Map<string, string>): string {
+  const from = safeId(e.from, ids);
+  const to = safeId(e.to, ids);
+  const label = [e.viaAttr, e.toAttr].filter(Boolean).join(" → ");
+  return label ? `${from} -->|${quote(label)}| ${to}` : `${from} --> ${to}`;
+}
+
+/** Map an arbitrary logical name to a stable, unique Mermaid-safe node id. */
+function safeId(raw: string, ids: Map<string, string>): string {
+  const existing = ids.get(raw);
+  if (existing) return existing;
+  let base = raw.replace(/[^A-Za-z0-9_]/g, "_");
+  if (base === "" || /^[0-9]/.test(base)) base = `n_${base}`;
+  const taken = new Set(ids.values());
+  let candidate = base;
+  let i = 1;
+  while (taken.has(candidate)) candidate = `${base}_${i++}`;
+  ids.set(raw, candidate);
+  return candidate;
+}
+
+/** Quote a Mermaid label, escaping markup and turning newlines into <br/>. */
+function quote(text: string): string {
+  const esc = (s: string): string =>
+    s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const body = text.split("\n").map(esc).join("<br/>");
+  return `"${body}"`;
+}

package/src/index.ts

@@ -27,6 +27,10 @@ export * from "./discovery/cache";
 export * from "./build";
 export * from "./graph-ir";
 export * from "./graph-detail";
+export * from "./graph-mermaid";
+export * from "./graph-dot";
+export * from "./graph-layout";
+export * from "./graph-lens";
 export * from "./detectLexicon";
 export * from "./lint/parser";
 export * from "./lint/rule";