@intentius/chant 0.8.1 → 0.9.0

package/src/reconcile.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Tests for the provider-agnostic reconcile primitive.
+ *
+ * Pure unit tests over the generic primitives — no provider types, no I/O.
+ */
+
+import { describe, expect, test } from "vitest";
+import {
+  deepEqual,
+  diffFields,
+  diffCollection,
+  summarizeChangeSet,
+  renderChangeSet,
+  resolveRenames,
+  removalDeltaCap,
+  runGuardrailChecks,
+} from "./reconcile";
+import type { ChangeSet, ChangeSetEntry, DiffOptions, GuardrailCheck } from "./reconcile";
+
+const noOpts: DiffOptions = {};
+
+// ---------------------------------------------------------------------------
+// deepEqual / diffFields
+// ---------------------------------------------------------------------------
+
+describe("deepEqual", () => {
+  test("compares primitives and nested structures", () => {
+    expect(deepEqual(1, 1)).toBe(true);
+    expect(deepEqual("a", "b")).toBe(false);
+    expect(deepEqual({ a: [1, 2] }, { a: [1, 2] })).toBe(true);
+    expect(deepEqual({ a: 1 }, { a: 2 })).toBe(false);
+    expect(deepEqual(null, undefined)).toBe(false);
+  });
+});
+
+describe("diffFields", () => {
+  test("compares every key of desired when no key list is given", () => {
+    expect(diffFields({ a: 1, b: 2 }, { a: 1, b: 9 })).toEqual([{ field: "b", before: 9, after: 2 }]);
+  });
+
+  test("compares only listed keys present in desired", () => {
+    expect(diffFields({ a: 1, b: 2 }, { a: 9, b: 9 }, ["a"])).toEqual([{ field: "a", before: 9, after: 1 }]);
+  });
+
+  test("ignores listed keys absent from desired (selective-by-omission)", () => {
+    expect(diffFields({ a: 1 }, { a: 1, b: 2 }, ["a", "b"])).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// diffCollection
+// ---------------------------------------------------------------------------
+
+interface D {
+  name: string;
+  v?: number;
+}
+interface L {
+  name: string;
+  v?: number;
+}
+
+function runCollection(desired: D[], live: L[], opts: DiffOptions = noOpts): ChangeSetEntry[] {
+  const out: ChangeSetEntry[] = [];
+  diffCollection<D, L>({
+    resourceType: "thing",
+    keyPrefix: "p/",
+    desired: new Map(desired.map((d) => [d.name, d])),
+    live: new Map(live.map((l) => [l.name, l])),
+    compareFields: (d, l) => (d.v !== l.v ? [{ field: "v", before: l.v, after: d.v }] : []),
+    opts,
+    out,
+  });
+  return out;
+}
+
+describe("diffCollection", () => {
+  test("creates entries for desired-not-live (with key prefix)", () => {
+    const out = runCollection([{ name: "a", v: 1 }], []);
+    expect(out).toEqual([{ kind: "create", resourceType: "thing", key: "p/a", after: { name: "a", v: 1 } }]);
+  });
+
+  test("updates when compareFields reports differences", () => {
+    const out = runCollection([{ name: "a", v: 2 }], [{ name: "a", v: 1 }]);
+    expect(out[0]!.kind).toBe("update");
+    expect(out[0]!.fields).toEqual([{ field: "v", before: 1, after: 2 }]);
+  });
+
+  test("emits no entry when live matches desired", () => {
+    expect(runCollection([{ name: "a", v: 1 }], [{ name: "a", v: 1 }])).toEqual([]);
+  });
+
+  test("only deletes live-not-desired when ownership-gated", () => {
+    const live = [
+      { name: "a", v: 1 },
+      { name: "stray", v: 9 },
+    ];
+    expect(runCollection([{ name: "a", v: 1 }], live)).toEqual([]); // no predicate
+    const owned = runCollection([{ name: "a", v: 1 }], live, { isOwned: (_t, k) => k === "p/stray" });
+    expect(owned).toEqual([
+      { kind: "delete", resourceType: "thing", key: "p/stray", before: { name: "stray", v: 9 } },
+    ]);
+  });
+
+  test("honours createAfter / updateAfter mappers", () => {
+    const out: ChangeSetEntry[] = [];
+    diffCollection<D, L>({
+      resourceType: "thing",
+      desired: new Map([["a", { name: "a", v: 5 }]]),
+      live: new Map(),
+      compareFields: () => [],
+      createAfter: (key, d) => ({ normalized: key, v: d.v }),
+      opts: noOpts,
+      out,
+    });
+    expect(out[0]!.after).toEqual({ normalized: "a", v: 5 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// summarize / render
+// ---------------------------------------------------------------------------
+
+describe("summarizeChangeSet / renderChangeSet", () => {
+  const cs: ChangeSet = {
+    org: "acme",
+    entries: [
+      { kind: "create", resourceType: "thing", key: "a" },
+      { kind: "update", resourceType: "thing", key: "b", fields: [{ field: "v", before: 1, after: 2 }] },
+      { kind: "delete", resourceType: "thing", key: "c" },
+    ],
+  };
+
+  test("counts entries by kind", () => {
+    expect(summarizeChangeSet(cs)).toEqual({ create: 1, update: 1, delete: 1 });
+  });
+
+  test("renders a readable plan with the scope id and field changes", () => {
+    const out = renderChangeSet(cs);
+    expect(out).toContain("Plan for acme: 1 to create, 1 to update, 1 to delete");
+    expect(out).toContain("[thing] b");
+    expect(out).toContain("v: 1 → 2");
+  });
+
+  test("renders 'No changes.' for an empty set", () => {
+    expect(renderChangeSet({ org: "acme", entries: [] })).toContain("No changes.");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Guardrail framework
+// ---------------------------------------------------------------------------
+
+describe("resolveRenames", () => {
+  test("collapses delete(previously)+create(key) into one update", () => {
+    const cs: ChangeSet = {
+      org: "acme",
+      entries: [
+        { kind: "delete", resourceType: "team", key: "old", before: { slug: "old" } },
+        { kind: "create", resourceType: "team", key: "new", after: { previously: "old" } },
+      ],
+    };
+    const resolved = resolveRenames(cs);
+    expect(resolved.entries.some((e) => e.kind === "delete")).toBe(false);
+    const update = resolved.entries.find((e) => e.kind === "update")!;
+    expect(update.key).toBe("new");
+    expect(update.before).toEqual({ slug: "old" });
+  });
+
+  test("is a no-op without a matching previously alias", () => {
+    const cs: ChangeSet = { org: "acme", entries: [{ kind: "delete", resourceType: "team", key: "old" }] };
+    expect(resolveRenames(cs)).toBe(cs);
+  });
+});
+
+describe("removalDeltaCap", () => {
+  test("trips when deletes exceed the fraction of pre-existing entries", () => {
+    const cs: ChangeSet = {
+      org: "acme",
+      entries: Array.from({ length: 4 }, (_, i) => ({
+        kind: "delete" as const,
+        resourceType: "x",
+        key: `k${i}`,
+      })),
+    };
+    expect(removalDeltaCap(cs)!.guardrail).toBe("removalDeltaCap");
+  });
+
+  test("excludes creates from the denominator and passes under the cap", () => {
+    const cs: ChangeSet = {
+      org: "acme",
+      entries: [
+        { kind: "delete", resourceType: "x", key: "d" },
+        { kind: "update", resourceType: "x", key: "u1" },
+        { kind: "update", resourceType: "x", key: "u2" },
+        { kind: "update", resourceType: "x", key: "u3" },
+        { kind: "create", resourceType: "x", key: "c" },
+      ],
+    };
+    expect(removalDeltaCap(cs)).toBeNull(); // 1/4 = 25%, not > 25%
+  });
+});
+
+describe("runGuardrailChecks", () => {
+  test("resolves renames once and aggregates failing checks", () => {
+    const cs: ChangeSet = {
+      org: "acme",
+      entries: [
+        { kind: "delete", resourceType: "x", key: "a" },
+        { kind: "delete", resourceType: "x", key: "b" },
+      ],
+    };
+    const failing: GuardrailCheck = (resolved) => removalDeltaCap(resolved);
+    const passing: GuardrailCheck = () => null;
+    const result = runGuardrailChecks(cs, [failing, passing]);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.diagnostics).toHaveLength(1);
+  });
+
+  test("returns ok when every check passes", () => {
+    const cs: ChangeSet = { org: "acme", entries: [{ kind: "create", resourceType: "x", key: "a" }] };
+    expect(runGuardrailChecks(cs, [() => null])).toEqual({ ok: true });
+  });
+});

package/src/reconcile.ts

@@ -0,0 +1,346 @@
+/**
+ * Provider-agnostic reconcile primitive.
+ *
+ * The reusable machinery behind a declarative reconcile loop, with NO knowledge
+ * of any specific provider (GitHub, GitLab, a cloud, …): the change-set model,
+ * the generic collection diff (selective-by-omission + ownership-gated deletes),
+ * the plan renderer, and the guardrail framework (rename resolution + a removal
+ * 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
+ * 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.
+ */
+
+// ---------------------------------------------------------------------------
+// Change-set model
+// ---------------------------------------------------------------------------
+
+/** A single field-level change: what the old value was and what it will become. */
+export interface FieldChange {
+  field: string;
+  before: unknown;
+  after: unknown;
+}
+
+/** The kind of operation this change represents. */
+export type ChangeKind = "create" | "update" | "delete";
+
+/** A single entry in the change set. */
+export interface ChangeSetEntry {
+  kind: ChangeKind;
+  /** High-level resource category (e.g. "team", "member", "branch-protection"). */
+  resourceType: string;
+  /**
+   * Unique key identifying this resource within its type.
+   * - For top-level resources: a single name (team slug, member login, …).
+   * - For nested resources: "<parent>/<child>" (e.g. "backend/alice").
+   */
+  key: string;
+  /** The live value before the change (absent for creates). */
+  before?: unknown;
+  /** The desired value after the change (absent for deletes). */
+  after?: unknown;
+  /** Field-level diff, populated for `update` entries. */
+  fields?: FieldChange[];
+}
+
+/** The full set of changes to reconcile for one scope (e.g. one org). */
+export interface ChangeSet {
+  /** Scope identifier this change set applies to (e.g. a GitHub org login). */
+  org: string;
+  /** All proposed changes, in stable order. */
+  entries: ChangeSetEntry[];
+}
+
+/** Options controlling diff behaviour. */
+export interface DiffOptions {
+  /**
+   * Ownership predicate for collection entries. The diff only emits a `delete`
+   * for a live entry absent from desired when this returns `true`. Omitted →
+   * deletes are never emitted ("assume nothing is owned").
+   */
+  isOwned?: (resourceType: string, key: string) => boolean;
+
+  /**
+   * Reference "now" in epoch milliseconds, used by time-based diffs. Callers
+   * inject `Date.now()` when unset; tests pass an explicit value.
+   */
+  nowMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Generic field/value diffing
+// ---------------------------------------------------------------------------
+
+/** Deep value equality via JSON for plain data (config/live snapshots). */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== "object" || typeof b !== "object") return false;
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Diff fields of `desired` against `live`, returning one `FieldChange` per
+ * differing field. When `keys` is given, only those keys are compared (and only
+ * when present in `desired`); otherwise every key in `desired` is compared.
+ * Selective-by-omission: keys absent from `desired` are never compared.
+ */
+export function diffFields(
+  desired: Record<string, unknown>,
+  live: Record<string, unknown>,
+  keys?: string[],
+): FieldChange[] {
+  const fields: FieldChange[] = [];
+  const compareKeys = keys ?? Object.keys(desired);
+  for (const key of compareKeys) {
+    if (keys && !Object.prototype.hasOwnProperty.call(desired, key)) continue;
+    const dv = desired[key];
+    const lv = live[key];
+    if (!deepEqual(dv, lv)) fields.push({ field: key, before: lv, after: dv });
+  }
+  return fields;
+}
+
+// ---------------------------------------------------------------------------
+// Generic collection diff
+// ---------------------------------------------------------------------------
+
+/** Parameters for {@link diffCollection}. */
+export interface DiffCollectionParams<D, L> {
+  /** Resource type stamped on emitted entries. */
+  resourceType: string;
+  /** Prefix prepended to each entry key (e.g. "<parent>/"). Default "". */
+  keyPrefix?: string;
+  /** Desired entries, keyed by logical key. */
+  desired: Map<string, D>;
+  /** Live entries, keyed by logical key. */
+  live: Map<string, L>;
+  /** Fields that differ → an update. Return `[]` for "no change". */
+  compareFields: (desired: D, live: L) => FieldChange[];
+  /** `after` value for a create entry. Defaults to the desired value. */
+  createAfter?: (key: string, desired: D) => unknown;
+  /** `after` value for an update entry. Defaults to the desired value. */
+  updateAfter?: (key: string, desired: D, live: L) => unknown;
+  opts: DiffOptions;
+  out: ChangeSetEntry[];
+}
+
+/**
+ * The generic managed-collection diff: creates for desired-not-live, updates
+ * when `compareFields` reports differences, and ownership-gated deletes for
+ * live-not-desired. This is the selective-by-omission + ownership-gated-delete
+ * pattern shared by every keyed-collection diff.
+ */
+export function diffCollection<D, L>(params: DiffCollectionParams<D, L>): void {
+  const {
+    resourceType,
+    keyPrefix = "",
+    desired,
+    live,
+    compareFields,
+    createAfter,
+    updateAfter,
+    opts,
+    out,
+  } = params;
+
+  for (const [key, d] of desired) {
+    const entryKey = `${keyPrefix}${key}`;
+    const l = live.get(key);
+    if (l === undefined) {
+      out.push({
+        kind: "create",
+        resourceType,
+        key: entryKey,
+        after: createAfter ? createAfter(key, d) : d,
+      });
+      continue;
+    }
+    const fields = compareFields(d, l);
+    if (fields.length > 0) {
+      out.push({
+        kind: "update",
+        resourceType,
+        key: entryKey,
+        before: l,
+        after: updateAfter ? updateAfter(key, d, l) : d,
+        fields,
+      });
+    }
+  }
+
+  for (const [key, l] of live) {
+    if (desired.has(key)) continue;
+    const entryKey = `${keyPrefix}${key}`;
+    if (opts.isOwned?.(resourceType, entryKey)) {
+      out.push({ kind: "delete", resourceType, key: entryKey, before: l });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Summary / rendering
+// ---------------------------------------------------------------------------
+
+/** Count entries per change kind. */
+export function summarizeChangeSet(cs: ChangeSet): Record<ChangeKind, number> {
+  const counts: Record<ChangeKind, number> = { create: 0, update: 0, delete: 0 };
+  for (const e of cs.entries) counts[e.kind]++;
+  return counts;
+}
+
+/** Human-readable plan summary for dry-run output. Pure. */
+export function renderChangeSet(cs: ChangeSet): string {
+  const counts = summarizeChangeSet(cs);
+  const header = `Plan for ${cs.org}: ${counts.create} to create, ${counts.update} to update, ${counts.delete} to delete`;
+
+  if (cs.entries.length === 0) return `${header}\nNo changes.`;
+
+  const lines: string[] = [header];
+  const byKind: Record<ChangeKind, ChangeSetEntry[]> = { create: [], update: [], delete: [] };
+  for (const e of cs.entries) byKind[e.kind].push(e);
+
+  const ORDER: ChangeKind[] = ["create", "update", "delete"];
+  for (const kind of ORDER) {
+    const group = byKind[kind];
+    if (group.length === 0) continue;
+    lines.push(`\n${kind.toUpperCase()}:`);
+    for (const e of group) {
+      lines.push(`  [${e.resourceType}] ${e.key}`);
+      for (const f of e.fields ?? []) {
+        lines.push(`    ${f.field}: ${fmt(f.before)} → ${fmt(f.after)}`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
+function fmt(v: unknown): string {
+  if (v === undefined) return "<unset>";
+  if (typeof v === "string") return v.length > 60 ? `${v.slice(0, 57)}...` : v;
+  const json = JSON.stringify(v);
+  return json.length > 60 ? `${json.slice(0, 57)}...` : json;
+}
+
+// ---------------------------------------------------------------------------
+// Guardrail framework
+// ---------------------------------------------------------------------------
+
+/** A single tripped guardrail with a human-readable message. */
+export interface GuardrailDiagnostic {
+  /** Short identifier, e.g. "removalDeltaCap". */
+  guardrail: string;
+  /** Clear, actionable description of why the apply was refused. */
+  message: string;
+}
+
+/** Aggregated guardrail result. */
+export type GuardrailResult = { ok: true } | { ok: false; diagnostics: GuardrailDiagnostic[] };
+
+/** A guardrail check over a (rename-resolved) change set. Returns null when it passes. */
+export type GuardrailCheck = (resolved: ChangeSet) => GuardrailDiagnostic | null;
+
+/** Config for `removalDeltaCap`. */
+export interface RemovalDeltaCapOptions {
+  /** Max fraction of pre-existing entries that may be deleted. Must be in (0,1]. Default 0.25. */
+  maxFraction?: number;
+}
+
+/**
+ * Resolve rename aliases. A create entry carrying a `previously` key matching a
+ * delete entry's key is collapsed into an update, removing the delete. Returns a
+ * new ChangeSet with renames resolved. Provider-agnostic — works on any entry
+ * whose `after.previously` is a string.
+ */
+export function resolveRenames(changeSet: ChangeSet): ChangeSet {
+  const deleteEntries = new Map<string, ChangeSetEntry>();
+  for (const e of changeSet.entries) {
+    if (e.kind === "delete") deleteEntries.set(e.key, e);
+  }
+
+  const resolvedDeletes = new Set<string>();
+  const resolvedCreates = new Set<string>();
+  const syntheticUpdates: ChangeSetEntry[] = [];
+
+  for (const e of changeSet.entries) {
+    if (e.kind !== "create") continue;
+    const after = e.after as Record<string, unknown> | undefined;
+    if (!after) continue;
+    const previously = after["previously"];
+    if (typeof previously !== "string") continue;
+
+    const deleted = deleteEntries.get(previously);
+    if (!deleted) continue;
+
+    resolvedDeletes.add(previously);
+    resolvedCreates.add(e.key);
+    syntheticUpdates.push({
+      kind: "update",
+      resourceType: e.resourceType,
+      key: e.key,
+      before: deleted.before,
+      after: e.after,
+      fields: [{ field: "key", before: previously, after: e.key }],
+    });
+  }
+
+  if (resolvedDeletes.size === 0) return changeSet;
+
+  const filteredEntries = changeSet.entries.filter(
+    (e) =>
+      !(e.kind === "delete" && resolvedDeletes.has(e.key)) &&
+      !(e.kind === "create" && resolvedCreates.has(e.key)),
+  );
+
+  return { org: changeSet.org, entries: [...filteredEntries, ...syntheticUpdates] };
+}
+
+/**
+ * Refuse if deletes exceed `maxFraction` of the pre-existing managed entries
+ * (deletes + updates; creates excluded so a flood of new entries can't dilute
+ * the delete fraction). Guards against a typo wiping the config in one apply.
+ *
+ * CONTRACT: pass a RENAME-RESOLVED change set (see {@link resolveRenames}).
+ */
+export function removalDeltaCap(
+  changeSet: ChangeSet,
+  opts: RemovalDeltaCapOptions = {},
+): GuardrailDiagnostic | null {
+  const maxFraction = opts.maxFraction ?? 0.25;
+  const total = changeSet.entries.filter((e) => e.kind !== "create").length;
+  if (total === 0) return null;
+  const deletes = changeSet.entries.filter((e) => e.kind === "delete").length;
+  const fraction = deletes / total;
+  if (fraction > maxFraction) {
+    return {
+      guardrail: "removalDeltaCap",
+      message:
+        `${deletes} of ${total} managed entries (${Math.round(fraction * 100)}%) would be deleted, ` +
+        `exceeding the ${Math.round(maxFraction * 100)}% threshold. ` +
+        `Check for typos in config or raise maxFraction to proceed.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Run a set of guardrail checks against a change set. Resolves renames ONCE,
+ * then runs every check on the resolved set, aggregating any diagnostics. The
+ * caller composes provider-specific checks (e.g. an admin floor) as closures.
+ */
+export function runGuardrailChecks(changeSet: ChangeSet, checks: GuardrailCheck[]): GuardrailResult {
+  const resolved = resolveRenames(changeSet);
+  const diagnostics: GuardrailDiagnostic[] = [];
+  for (const check of checks) {
+    const d = check(resolved);
+    if (d) diagnostics.push(d);
+  }
+  return diagnostics.length > 0 ? { ok: false, diagnostics } : { ok: true };
+}