@intentius/chant 0.70.1 → 0.71.0

package/src/components/fan-out-run.ts

@@ -0,0 +1,221 @@
+/**
+ * Run a derived fan-out (#2417).
+ *
+ * `./fan-out.ts` decides who runs and in what order; this dispatches it. The
+ * two are separate because the deciding is worth testing without a cloud, and
+ * because the same plan is what one approval is bound to.
+ *
+ * ## Why not `runInterpretDriver`
+ *
+ * That runner stops the whole run at the first failed component, which is the
+ * right default for `chant run --components all`: there, the user asked for
+ * everything, and a failure means the estate is in a state nobody described.
+ *
+ * A fan-out is the case where that default throws away the point. The order was
+ * derived from the source, so a branch sharing no edge with the failure is
+ * *known* to be independent rather than assumed to be. Stopping it buys nothing
+ * and costs a second approval to finish. So this runner skips the failed
+ * component's subtree and lets the rest of the wave plan proceed.
+ *
+ * Neither runner's behaviour changes the other's: `runInterpretDriver` is
+ * untouched.
+ *
+ * ## One approval, not one per component
+ *
+ * The gate is evaluated once, before the first wave, bound to the plan's digest
+ * through the same `planDigest` mechanism #2300 gave gates. Twenty components
+ * behind one fan-out is one approval, and re-deriving the same fan-out does not
+ * expire it. A component's *own* authored gates still decide per component —
+ * this adds a gate over the set, it does not remove the ones inside it.
+ */
+
+import {
+  runComponentDeploy,
+  type DriverComponent,
+  type DriverComponentResult,
+  type GateContext,
+} from "./driver";
+import { downstreamWithin, remainingFanOut, type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out";
+import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import type { RunProgressEvent } from "./run-progress";
+import type { CapabilityRegistry } from "./capability";
+import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+
+/** The single gate over a whole fan-out. Omit it to run without one. */
+export interface FanOutGate {
+  /** The name `chant approve <op> <gate>` takes — the fan-out's name, not a component's. */
+  op: string;
+  gate: string;
+  description?: string;
+  timeout?: string;
+}
+
+export interface FanOutRunOptions {
+  env: string;
+  vars?: Record<string, unknown>;
+  /** Outputs of components this run is not running: the ones the plan lists in `seeds`. */
+  componentOutputs?: Record<string, Record<string, unknown>>;
+  onProgress?: (event: RunProgressEvent) => void;
+  gates?: GateLedgerPort;
+  now?: string;
+  /** One approval over the ordered set, bound to `plan.digest`. */
+  gate?: FanOutGate;
+  /** What an earlier attempt at this same plan already did. */
+  progress?: FanOutProgress;
+}
+
+export interface FanOutRunResult {
+  /** The plan actually dispatched — `plan` narrowed by `options.progress`. */
+  plan: FanOutPlan;
+  status: "ok" | "fail" | "gated";
+  results: DriverComponentResult[];
+  /** Reached `ok` this attempt. Feed back as `progress.completed` to resume. */
+  completed: string[];
+  /** Failed this attempt. Feed back as `progress.failed`. */
+  failed: string[];
+  /** Never dispatched because something upstream failed, each naming the failure. */
+  blocked: FanOutSkip[];
+  componentOutputs: Record<string, Record<string, unknown>>;
+  /** Present when `status === "gated"`: the pending fact to approve. */
+  gate?: PendingGateRecord;
+}
+
+/**
+ * Dispatch a fan-out plan.
+ *
+ * Resolves rather than throws on a failed component: a fan-out's partial
+ * outcome is the interesting one, and the caller needs `completed` to resume.
+ */
+export async function runFanOut(
+  plan: FanOutPlan,
+  components: DriverComponent[],
+  registry: CapabilityRegistry,
+  options: FanOutRunOptions,
+): Promise<FanOutRunResult> {
+  const byName = new Map(components.map((c) => [c.name, c]));
+  const gates: GateContext = {
+    port: options.gates ?? gitGateLedgerPort(),
+    ...(options.now ? { now: options.now } : {}),
+  };
+  const componentOutputs: Record<string, Record<string, unknown>> = { ...(options.componentOutputs ?? {}) };
+
+  // Resume first, so the gate is decided against the work that is actually left
+  // and a re-run does not re-approve. The digest is carried, not recomputed.
+  const active = options.progress ? remainingFanOut(plan, components, options.progress) : plan;
+
+  if (options.gate) {
+    const check = await evaluateGate(gates.port, {
+      op: options.gate.op,
+      gate: options.gate.gate,
+      planDigest: active.digest,
+      ...(options.gate.description ? { description: options.gate.description } : {}),
+      ...(options.gate.timeout ? { timeout: options.gate.timeout } : {}),
+      ...(options.now ? { now: options.now } : {}),
+    });
+    if (!check.satisfied) {
+      // Nothing ran, so nothing is half-applied and there is nothing to
+      // compensate. A gate is a fact, not a failure.
+      return {
+        plan: active,
+        status: "gated",
+        results: [],
+        completed: [],
+        failed: [],
+        blocked: [],
+        componentOutputs,
+        gate: check.pending,
+      };
+    }
+  }
+
+  const results: DriverComponentResult[] = [];
+  const completed: string[] = [];
+  const failed: string[] = [];
+  const blockedBy = new Map<string, string>();
+  let gatedFact: PendingGateRecord | undefined;
+
+  const inPlan = new Set(active.order);
+  /** Skip everything downstream of `root`, blaming `root` rather than the nearest edge. */
+  const markBlocked = (root: string): void => {
+    for (const [component, by] of downstreamWithin(components, inPlan, [root])) {
+      if (blockedBy.has(component) || failed.includes(component)) continue;
+      blockedBy.set(component, by);
+    }
+  };
+
+  options.onProgress?.({ type: "run-start", waves: active.waves });
+
+  for (const [waveIndex, wave] of active.waves.entries()) {
+    const waveNum = waveIndex + 1;
+    // A component whose upstream failed in an earlier wave is not dispatched.
+    const runnable = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name));
+    if (runnable.length === 0) continue;
+
+    options.onProgress?.({ type: "wave-start", wave: waveNum, components: runnable });
+    const waveResults = await Promise.all(
+      runnable.map(async (name) => {
+        options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+        const result = await runComponentDeploy(
+          byName.get(name)!,
+          { env: options.env, component: name, vars: options.vars },
+          registry,
+          componentOutputs,
+          options.onProgress,
+          gates,
+        );
+        options.onProgress?.({
+          type: "component-done",
+          wave: waveNum,
+          component: name,
+          status: result.status === "fail" ? "failed" : result.status,
+        });
+        return result;
+      }),
+    );
+    results.push(...waveResults);
+
+    for (const result of waveResults) {
+      if (result.status === "ok") {
+        completed.push(result.component);
+        continue;
+      }
+      if (result.status === "fail") {
+        failed.push(result.component);
+        markBlocked(result.component);
+        continue;
+      }
+      // A component of its own stopped at one of its authored gates. Its
+      // dependents cannot run either, for the same reason a failure's cannot:
+      // the value they would read has not landed.
+      gatedFact ??= result.gate;
+      markBlocked(result.component);
+    }
+
+    const waveFailed = waveResults.some((r) => r.status === "fail");
+    options.onProgress?.({
+      type: "wave-done",
+      wave: waveNum,
+      status: waveFailed ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
+    });
+  }
+
+  const blocked: FanOutSkip[] = [...blockedBy.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([component, by]) => ({ component, reason: "blocked" as const, blockedBy: by }));
+
+  // A failure outranks a gate: something is actually broken, and reporting the
+  // run as "waiting on a human" would hide it. Same precedence the driver uses.
+  const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
+  options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+
+  return {
+    plan: active,
+    status,
+    results,
+    completed: [...completed].sort(),
+    failed: [...failed].sort(),
+    blocked,
+    componentOutputs,
+    ...(gatedFact ? { gate: gatedFact } : {}),
+  };
+}

package/src/components/fan-out-support.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Discovery to plan (#2420).
+ *
+ * The join is the part that had no caller: `componentsForUnits` turns a
+ * stack-level change signal into components, and `planFanOut` needs the whole
+ * component set to order a subset of it. These tests hold that seam to the
+ * selection semantics `chant run --components all` already has, so the two
+ * commands cannot disagree about which components exist.
+ */
+
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import type { Component } from "./component";
+
+const discoverComponentsMock = vi.fn();
+const loadChantConfigMock = vi.fn();
+
+vi.mock("./discover", () => ({
+  discoverComponents: (...args: unknown[]) => discoverComponentsMock(...args),
+}));
+
+vi.mock("../config", async () => {
+  const actual = await vi.importActual<typeof import("../config")>("../config");
+  return { ...actual, loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args) };
+});
+
+const { deriveFanOut } = await import("./fan-out-support");
+
+function component(name: string, dependsOn: string[] = [], over: Partial<Component> = {}): Component {
+  return {
+    name,
+    dependsOn,
+    deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: `${name}-stack` }] }],
+    ...over,
+  };
+}
+
+const ESTATE = [
+  component("network"),
+  component("cluster-a", ["network"]),
+  component("cluster-b", ["network"]),
+  component("app-one", ["cluster-a"]),
+  component("app-two", ["cluster-b"]),
+  component("billing"),
+];
+
+function discovers(components: Component[]): void {
+  discoverComponentsMock.mockResolvedValue({
+    components: new Map(components.map((c) => [c.name, { component: c, exportName: c.name, filePath: `${c.name}.component.ts` }])),
+    sourceFiles: [],
+    errors: [],
+  });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["aws"] } });
+  discovers(ESTATE);
+});
+
+describe("joining a stack-level signal to components", () => {
+  test("a changed stack selects the component that deploys it, and everything downstream", async () => {
+    const derived = await deriveFanOut({ path: "/project", units: { changed: ["network-stack"] } });
+
+    expect(derived.success).toBe(true);
+    expect(derived.signal.changed).toEqual(["network"]);
+    expect(derived.plan.order).toEqual(["network", "cluster-a", "cluster-b", "app-one", "app-two"]);
+    expect(derived.plan.waves).toEqual([["network"], ["cluster-a", "cluster-b"], ["app-one", "app-two"]]);
+    expect(derived.plan.skipped).toEqual([{ component: "billing", reason: "unaffected" }]);
+  });
+
+  test("ordering a subset works, and the dependency outside it is seeded rather than run", async () => {
+    const derived = await deriveFanOut({ path: "/project", units: { changed: ["cluster-a-stack"] } });
+
+    expect(derived.plan.order).toEqual(["cluster-a", "app-one"]);
+    expect(derived.plan.seeds).toEqual(["network"]);
+  });
+
+  test("a changed stack no component deploys is reported, never dropped", async () => {
+    const derived = await deriveFanOut({
+      path: "/project",
+      units: { changed: ["network-stack", "legacy-stack"] },
+    });
+
+    expect(derived.signal.unclaimed).toEqual(["legacy-stack"]);
+    expect(derived.signal.changed).toEqual(["network"]);
+  });
+
+  test("an indeterminate stack the walk does not reach stays the third outcome", async () => {
+    const derived = await deriveFanOut({
+      path: "/project",
+      units: { changed: ["app-one-stack"], indeterminate: ["billing-stack"] },
+    });
+
+    expect(derived.plan.order).toEqual(["app-one"]);
+    expect(derived.plan.indeterminate).toEqual(["billing"]);
+    expect(derived.plan.skipped).toContainEqual({ component: "billing", reason: "indeterminate" });
+  });
+
+  test("a component a build parameter turned off sits out, exactly as it does under `run --components all`", async () => {
+    discovers([...ESTATE.filter((c) => c.name !== "app-two"), component("app-two", ["cluster-b"], { enabled: false })]);
+
+    const derived = await deriveFanOut({ path: "/project", units: { changed: ["network-stack"] } });
+
+    expect(derived.components.map((c) => c.name)).not.toContain("app-two");
+    expect(derived.plan.order).not.toContain("app-two");
+  });
+
+  test("the whole graph is refused by name before anything is selected", async () => {
+    discovers([component("a", ["b"]), component("b", ["a"]), component("network")]);
+
+    await expect(deriveFanOut({ path: "/project", units: { changed: ["network-stack"] } })).rejects.toThrow(/cycle/i);
+  });
+
+  test("a discovery failure comes back as an error rather than an empty fan-out", async () => {
+    discoverComponentsMock.mockResolvedValue({
+      components: new Map(),
+      sourceFiles: [],
+      errors: [{ message: "app-one.component.ts failed to import" }],
+    });
+
+    const derived = await deriveFanOut({ path: "/project", units: { changed: ["network-stack"] } });
+    expect(derived.success).toBe(false);
+    expect(derived.error).toContain("failed to import");
+  });
+});

package/src/components/fan-out-support.ts

@@ -0,0 +1,95 @@
+/**
+ * Discovery-to-plan wiring for `chant components fan-out` (#2420).
+ *
+ * `./cli-support.ts` does this for `chant run --components`: the CLI handler
+ * stays a thin dispatcher and the component-specific work lives beside the
+ * rest of the component subsystem. This is the same seam for the fan-out, and
+ * it exists mostly so the join can be tested against a real discovery result
+ * without a CLI, a git repo or a cloud.
+ *
+ * Nothing here decides anything. `componentsForUnits` joins the stack-level
+ * change signal to components, `planFanOut` derives the order, and both live
+ * in ./fan-out.ts. This finds the components those two need and hands them
+ * over.
+ */
+
+import { resolveComponentTargets } from "./cli-support";
+import { applyConfigDefaults } from "./config-defaults";
+import { buildCapabilityRegistry } from "./capability-plugin-loader";
+import { componentsForUnits, planFanOut, type ChangedUnits, type ComponentChangeSignal, type FanOutPlan } from "./fan-out";
+import type { CapabilityRegistry } from "./capability";
+import type { DriverComponent } from "./driver";
+import type { BuildParamProvenance } from "../provenance";
+import { loadChantConfig, type ChantConfig } from "../config";
+
+export interface DeriveFanOutOptions {
+  /** Project root to discover `*.component.ts` under. */
+  path: string;
+  /** The stack-level change signal, from `lifecycle affected` or from a caller who already had one. */
+  units: ChangedUnits;
+  sandbox?: boolean;
+  /** chant #1108 — this invocation's resolved build-time parameters, so a `params.*` reference in a component file resolves. */
+  buildParams?: BuildParamProvenance[];
+  /** Already-loaded project config, when the caller read it for its own reasons. */
+  config?: ChantConfig;
+}
+
+export interface DerivedFanOut {
+  success: boolean;
+  /**
+   * Every component in the project, config defaults applied. The full set, not
+   * the selection: ordering a subset is only possible against the whole graph
+   * (./fan-out.ts), and the runner needs the unselected ones to work out what
+   * a failure blocks.
+   */
+  components: DriverComponent[];
+  /** What the stack-level signal meant in component terms, `unclaimed` included. */
+  signal: ComponentChangeSignal;
+  plan: FanOutPlan;
+  error?: string;
+}
+
+const EMPTY_PLAN: FanOutPlan = { order: [], waves: [], skipped: [], seeds: [], indeterminate: [], digest: "" };
+const EMPTY_SIGNAL: ComponentChangeSignal = { changed: [], indeterminate: [], unclaimed: [] };
+
+/**
+ * Discover the project's components and derive the fan-out for `units`.
+ *
+ * Selection is `"all"`'s, borrowed wholesale from `resolveComponentTargets`, so
+ * a component a build parameter turned off (`enabled: false`, chant #1522) sits
+ * out of a fan-out exactly as it sits out of `chant run --components all`. Two
+ * commands disagreeing about which components exist would be worse than either
+ * answer on its own.
+ *
+ * Resolves with `success: false` and an `error` rather than throwing on a
+ * discovery failure; a cycle or an unknown `dependsOn` still throws out of
+ * `planFanOut`, which is #2417's "refuse by name, before anything is selected".
+ */
+export async function deriveFanOut(options: DeriveFanOutOptions): Promise<DerivedFanOut> {
+  const resolved = await resolveComponentTargets(options.path, "all", options.sandbox, options.buildParams);
+  if (!resolved.success) {
+    return { success: false, components: [], signal: EMPTY_SIGNAL, plan: EMPTY_PLAN, error: resolved.error };
+  }
+
+  const { config } = options.config ? { config: options.config } : await loadChantConfig(options.path);
+  const components = resolved.targets.map((component) => applyConfigDefaults(component, config));
+
+  const signal = componentsForUnits(components, options.units);
+  const plan = planFanOut({
+    components,
+    changed: signal.changed,
+    ...(signal.indeterminate.length > 0 ? { indeterminate: signal.indeterminate } : {}),
+  });
+
+  return { success: true, components, signal, plan };
+}
+
+/**
+ * The capability registry a fan-out dispatches through — the project's own,
+ * built exactly the way `runComponents` builds it, so a fan-out and a
+ * `chant run --components` of the same component reach the same leaves.
+ */
+export async function fanOutRegistry(path: string, config?: ChantConfig): Promise<CapabilityRegistry> {
+  const resolved = config ?? (await loadChantConfig(path)).config;
+  return buildCapabilityRegistry({ plugins: resolved.capabilities, lexicons: resolved.lexicons });
+}