@intentius/chant 0.9.0 → 0.11.0

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";

package/src/reconcile.test.ts

@@ -222,3 +222,151 @@ describe("runGuardrailChecks", () => {
     expect(runGuardrailChecks(cs, [() => null])).toEqual({ ok: true });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Reconcile runner (fake provider — proves provider-agnosticism)
+// ---------------------------------------------------------------------------
+
+import { runReconcile, BudgetExhaustedError } from "./reconcile";
+import type { Cycle } from "./reconcile";
+
+interface FakeClient {
+  calls: string[];
+}
+interface FakeConfig {
+  create?: number;
+}
+type FakeLive = Record<string, never>;
+
+function fakeCycle(
+  name: string,
+  over: Partial<Cycle<FakeClient, FakeConfig, FakeLive>> = {},
+): Cycle<FakeClient, FakeConfig, FakeLive> {
+  return {
+    name,
+    async fetchLive(client, scopeId, _scope, budget) {
+      budget.use(1);
+      client.calls.push(`fetch:${name}@${scopeId}`);
+      return {};
+    },
+    buildDesired(config) {
+      return config;
+    },
+    async apply(client, entry, _scopeId, _scope, budget) {
+      budget.use(1);
+      client.calls.push(`apply:${entry.key}`);
+    },
+    ...over,
+  };
+}
+
+// Injected diff: emit N create entries from config.create.
+const fakeDiff = (scopeId: string, desired: FakeConfig): ChangeSet => ({
+  org: scopeId,
+  entries: Array.from({ length: desired.create ?? 0 }, (_, i) => ({
+    kind: "create" as const,
+    resourceType: "thing",
+    key: `k${i}`,
+  })),
+});
+
+describe("runReconcile (generic)", () => {
+  test("dry-run reports the plan and mutates nothing", async () => {
+    const client: FakeClient = { calls: [] };
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 3 } },
+      cycles: [fakeCycle("c1")],
+      diff: fakeDiff,
+      mode: "dry-run",
+    });
+    expect(result.mode).toBe("dry-run");
+    expect(result.completed).toBe(true);
+    expect(result.cycles[0]!.counts.create).toBe(3);
+    expect(result.cycles[0]!.applied).toHaveLength(0);
+    expect(client.calls.filter((c) => c.startsWith("apply:"))).toHaveLength(0);
+  });
+
+  test("apply applies each entry across multiple scopes", async () => {
+    const client: FakeClient = { calls: [] };
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 2 }, beta: { create: 1 } },
+      cycles: [fakeCycle("c1")],
+      diff: fakeDiff,
+      mode: "apply",
+    });
+    expect(result.completed).toBe(true);
+    expect(result.cycles.flatMap((c) => c.applied)).toHaveLength(3);
+    expect(client.calls.filter((c) => c.startsWith("apply:"))).toHaveLength(3);
+  });
+
+  test("guardrails block the apply unless overridden", async () => {
+    const client: FakeClient = { calls: [] };
+    const opts = {
+      client,
+      scopes: { acme: { create: 1 } },
+      cycles: [fakeCycle("c1")],
+      diff: fakeDiff,
+      mode: "apply" as const,
+      guardrails: () => ({ ok: false as const, diagnostics: [{ guardrail: "x", message: "no" }] }),
+    };
+    const blocked = await runReconcile<FakeClient, FakeConfig, FakeLive>(opts);
+    expect(blocked.cycles[0]!.guardrailBlocked).toBe(true);
+    expect(blocked.cycles[0]!.applied).toHaveLength(0);
+
+    const overridden = await runReconcile<FakeClient, FakeConfig, FakeLive>({ ...opts, allowGuardrailOverride: true });
+    expect(overridden.cycles[0]!.guardrailBlocked).toBe(false);
+    expect(overridden.cycles[0]!.applied).toHaveLength(1);
+  });
+
+  test("records deferred work when the budget is exhausted", async () => {
+    const client: FakeClient = { calls: [] };
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 0 }, beta: { create: 0 } },
+      cycles: [fakeCycle("c1"), fakeCycle("c2")],
+      diff: fakeDiff,
+      requestBudget: 1, // only the first fetchLive fits
+    });
+    expect(result.completed).toBe(false);
+    expect(result.deferred.skippedCycles.length).toBeGreaterThan(0);
+  });
+
+  test("an errored fetchLive is recorded and the run continues", async () => {
+    const client: FakeClient = { calls: [] };
+    const boom = fakeCycle("boom", {
+      async fetchLive() {
+        throw new Error("kaboom");
+      },
+    });
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 1 } },
+      cycles: [boom, fakeCycle("ok")],
+      diff: fakeDiff,
+    });
+    expect(result.errored).toHaveLength(1);
+    expect(result.errored[0]!.name).toBe("boom");
+    expect(result.cycles.some((c) => c.name === "ok")).toBe(true); // ran past the error
+  });
+
+  test("a budget-exhausted throw mid-fetch is deferred, not errored", async () => {
+    const client: FakeClient = { calls: [] };
+    const greedy = fakeCycle("greedy", {
+      async fetchLive(_c, _s, _scope, budget) {
+        budget.use(1);
+        throw new BudgetExhaustedError();
+      },
+    });
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 0 } },
+      cycles: [greedy],
+      diff: fakeDiff,
+      requestBudget: 5,
+    });
+    expect(result.errored).toHaveLength(0);
+    expect(result.deferred.skippedCycles).toContain("greedy@acme");
+  });
+});

package/src/reconcile.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).
  */
 
 // ---------------------------------------------------------------------------
@@ -344,3 +346,247 @@ export function runGuardrailChecks(changeSet: ChangeSet, checks: GuardrailCheck[
   }
   return diagnostics.length > 0 ? { ok: false, diagnostics } : { ok: true };
 }
+
+// ---------------------------------------------------------------------------
+// Reconcile runner (generic over provider client / config / live / scope)
+// ---------------------------------------------------------------------------
+
+/** 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 class BudgetExhaustedError extends Error {
+  constructor(message = "rate budget exhausted") {
+    super(message);
+    this.name = "BudgetExhaustedError";
+  }
+}
+
+class MutableRateBudget implements RateBudget {
+  private _remaining: number;
+  constructor(initial: number) {
+    this._remaining = initial;
+  }
+  get remaining(): number {
+    return this._remaining;
+  }
+  get exhausted(): boolean {
+    return this._remaining <= 0;
+  }
+  use(n = 1): void {
+    if (this.exhausted) throw new BudgetExhaustedError();
+    this._remaining = Math.max(0, this._remaining - n);
+  }
+}
+
+/**
+ * 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;
+}
+
+function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * 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 async function runReconcile<TClient, TConfig, TLive, TScope = unknown>(
+  opts: RunReconcileOptions<TClient, TConfig, TLive, TScope>,
+): Promise<ReconcileResult> {
+  const {
+    scopes,
+    client,
+    cycles,
+    scope,
+    mode = "dry-run",
+    diff: diffFn,
+    guardrails = (): GuardrailResult => ({ ok: true }),
+    diffOptions = {},
+    allowGuardrailOverride = false,
+    requestBudget = 1000,
+  } = opts;
+
+  const budget = new MutableRateBudget(requestBudget);
+  const cycleResults: CycleResult[] = [];
+  const erroredCycles: CycleError[] = [];
+  const deferred: DeferredWork = { skippedCycles: [], skippedEntries: [] };
+
+  const scopeEntries = Object.entries(scopes);
+
+  for (const cycle of cycles) {
+    for (const [scopeId, scopeConfig] of scopeEntries) {
+      if (budget.exhausted) {
+        deferred.skippedCycles.push(`${cycle.name}@${scopeId}`);
+        continue;
+      }
+
+      let live: TLive;
+      try {
+        live = await cycle.fetchLive(client, scopeId, scope as TScope, budget);
+      } catch (err) {
+        if (err instanceof BudgetExhaustedError) {
+          deferred.skippedCycles.push(`${cycle.name}@${scopeId}`);
+          continue;
+        }
+        erroredCycles.push({ name: cycle.name, org: scopeId, stage: "fetchLive", error: errMsg(err) });
+        continue;
+      }
+
+      let desired: TConfig;
+      try {
+        desired = cycle.buildDesired(scopeConfig, scopeId, scope as TScope);
+      } catch (err) {
+        erroredCycles.push({ name: cycle.name, org: scopeId, stage: "buildDesired", error: errMsg(err) });
+        continue;
+      }
+
+      const changeSet = diffFn(scopeId, desired, live, diffOptions);
+      const guardrailResult = guardrails(changeSet, live);
+
+      const counts = { create: 0, update: 0, delete: 0 };
+      for (const e of changeSet.entries) counts[e.kind]++;
+
+      const cycleResult: CycleResult = {
+        name: cycle.name,
+        org: scopeId,
+        counts,
+        guardrails: guardrailResult,
+        applied: [],
+        failed: [],
+        plan: renderChangeSet(changeSet),
+        guardrailBlocked: false,
+      };
+
+      if (mode === "dry-run") {
+        cycleResults.push(cycleResult);
+        continue;
+      }
+
+      if (!guardrailResult.ok && !allowGuardrailOverride) {
+        cycleResult.guardrailBlocked = true;
+        cycleResults.push(cycleResult);
+        continue;
+      }
+
+      for (const entry of changeSet.entries) {
+        if (budget.exhausted) {
+          deferred.skippedEntries.push({ cycleName: cycle.name, entry });
+          continue;
+        }
+        try {
+          await cycle.apply(client, entry, scopeId, scope as TScope, budget);
+          cycleResult.applied.push(entry);
+        } catch (err) {
+          if (err instanceof BudgetExhaustedError) {
+            deferred.skippedEntries.push({ cycleName: cycle.name, entry });
+            continue;
+          }
+          cycleResult.failed.push({ entry, error: errMsg(err) });
+        }
+      }
+
+      cycleResults.push(cycleResult);
+    }
+  }
+
+  const completed =
+    deferred.skippedCycles.length === 0 &&
+    deferred.skippedEntries.length === 0 &&
+    erroredCycles.length === 0;
+
+  return { mode, completed, cycles: cycleResults, errored: erroredCycles, deferred, budgetRemaining: budget.remaining };
+}