@intentius/chant 0.9.0 → 0.11.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":"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"}

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/dist/reconcile.d.ts

@@ -8,13 +8,15 @@
  * cap + a pluggable check runner).
  *
  * A "warden" (e.g. github-warden) builds its provider-specific resource diffing,
- * live-state types, and domain guardrails on top of this. It complements
+ * live-state types, and domain guardrails on top of this, and drives them with
+ * the generic `runReconcile` loop + `Cycle` interface (below). It complements
  * chant's `ownership.ts` marker contract: ownership markers make a `delete`
  * precise; this module decides *which* entries are creates / updates / deletes
  * in the first place.
  *
- * Consumed as `@intentius/chant/reconcile`. Pure and deterministic: no I/O,
- * no clock.
+ * Consumed as `@intentius/chant/reconcile`. The diff and guardrail primitives
+ * are pure and clock-free; `runReconcile` is the orchestration loop and is the
+ * only part that drives I/O (through the provider's `Cycle` implementations).
  */
 /** A single field-level change: what the old value was and what it will become. */
 export interface FieldChange {
@@ -144,4 +146,110 @@ export declare function removalDeltaCap(changeSet: ChangeSet, opts?: RemovalDelt
  * caller composes provider-specific checks (e.g. an admin floor) as closures.
  */
 export declare function runGuardrailChecks(changeSet: ChangeSet, checks: GuardrailCheck[]): GuardrailResult;
+/** Controls how a cycle tracks its API usage against a shared request budget. */
+export interface RateBudget {
+    /** Remaining request capacity for this run. */
+    readonly remaining: number;
+    /** True once `remaining` has reached zero. */
+    readonly exhausted: boolean;
+    /** Decrement by `n` (default 1). Throws `BudgetExhaustedError` if exhausted. */
+    use(n?: number): void;
+}
+/** Thrown when a cycle or apply step attempts to use an exhausted budget. */
+export declare class BudgetExhaustedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * A reconcile cycle: fetch live state for one resource domain, build desired
+ * state from config, and apply a single `ChangeSetEntry` back to the provider.
+ * Generic over the provider client (`TClient`), the per-scope config slice
+ * (`TConfig`), the live snapshot (`TLive`), and caller-supplied scope (`TScope`).
+ *
+ * `scopeId` is the current scope being iterated (e.g. an org login or group
+ * path); cycles use it — not `TScope` — for provider API paths, so a multi-scope
+ * config targets the right scope. Every network call must charge `budget`.
+ */
+export interface Cycle<TClient, TConfig, TLive, TScope = unknown> {
+    /** Human-readable name, e.g. "branch-protection". */
+    name: string;
+    fetchLive(client: TClient, scopeId: string, scope: TScope, budget: RateBudget): Promise<TLive>;
+    buildDesired(config: TConfig, scopeId: string, scope: TScope): TConfig;
+    apply(client: TClient, entry: ChangeSetEntry, scopeId: string, scope: TScope, budget: RateBudget): Promise<void>;
+}
+/** Per-cycle outcome recorded in the run result. */
+export interface CycleResult {
+    name: string;
+    /** Scope id this result is for (e.g. an org login). */
+    org: string;
+    counts: {
+        create: number;
+        update: number;
+        delete: number;
+    };
+    guardrails: GuardrailResult;
+    applied: ChangeSetEntry[];
+    failed: Array<{
+        entry: ChangeSetEntry;
+        error: string;
+    }>;
+    plan: string;
+    guardrailBlocked: boolean;
+}
+/** A cycle that errored during `fetchLive`/`buildDesired` (non-budget error). */
+export interface CycleError {
+    name: string;
+    org: string;
+    stage: "fetchLive" | "buildDesired";
+    error: string;
+}
+/** Work that could not complete due to budget exhaustion. */
+export interface DeferredWork {
+    skippedCycles: string[];
+    skippedEntries: Array<{
+        cycleName: string;
+        entry: ChangeSetEntry;
+    }>;
+}
+/** Structured result from a single `runReconcile` call. */
+export interface ReconcileResult {
+    mode: "dry-run" | "apply";
+    completed: boolean;
+    cycles: CycleResult[];
+    errored: CycleError[];
+    deferred: DeferredWork;
+    budgetRemaining: number;
+}
+/** Options for `runReconcile`. */
+export interface RunReconcileOptions<TClient, TConfig, TLive, TScope = unknown> {
+    /** Per-scope configs to reconcile, keyed by scope id (e.g. org login). */
+    scopes: Record<string, TConfig>;
+    /** Authed provider client, passed to every cycle. */
+    client: TClient;
+    /** Cycles to run; each runs against every scope in `scopes`. */
+    cycles: Array<Cycle<TClient, TConfig, TLive, TScope>>;
+    /** Scope forwarded to each cycle (filter/cursor); does not vary by scopeId. */
+    scope?: TScope;
+    /** "dry-run" (default) computes + reports; "apply" mutates after guardrails. */
+    mode?: "dry-run" | "apply";
+    /** Provider diff: turn (desired, live) into a ChangeSet for one scope. */
+    diff: (scopeId: string, desired: TConfig, live: TLive, opts: DiffOptions) => ChangeSet;
+    /** Guardrail check over the change set + live. Defaults to always-ok. */
+    guardrails?: (changeSet: ChangeSet, live: TLive) => GuardrailResult;
+    /** Diff options forwarded to `diff`. */
+    diffOptions?: DiffOptions;
+    /** Apply even when guardrails trip. Default false. */
+    allowGuardrailOverride?: boolean;
+    /** Max requests for the run (across all cycles). Default 1000. */
+    requestBudget?: number;
+}
+/**
+ * Run the reconcile loop. For each scope in `scopes` and each cycle:
+ *   1. fetchLive  2. buildDesired  3. diff  4. guardrails
+ *   5a. dry-run: record the plan  5b. apply: apply each entry (if guardrails pass)
+ *
+ * Budget-aware (stops cleanly + records deferred work on exhaustion) and
+ * fault-tolerant (a cycle that errors is recorded and the run continues).
+ * Returns a structured `ReconcileResult`.
+ */
+export declare function runReconcile<TClient, TConfig, TLive, TScope = unknown>(opts: RunReconcileOptions<TClient, TConfig, TLive, TScope>): Promise<ReconcileResult>;
 //# sourceMappingURL=reconcile.d.ts.map

package/dist/reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.9.0",
+  "version": "0.11.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");
   });
 });