@intentius/chant 0.124.32 → 0.124.34

package/src/components/promote-rounds.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Rounds and per-wave gates at promote (#4168 step 4): a dependent planned
+ * against its upstream's planned outputs is planned again once the upstream
+ * applied as another value, and `--wave-gate` checks each wave.
+ */
+
+import { describe, expect, test } from "vitest";
+import { composeChangeSet, type ChangeSetDocument } from "../change-set";
+import type { DriverComponent, DriverRunResult, ReleaseGateBinding } from "./driver";
+import { movedInputs, renameGates, runPromotionInRounds } from "./promote-rounds";
+
+const sha = (c: string) => `sha256:${c.repeat(64)}`;
+
+const net: DriverComponent = { name: "net", deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "tf", name: "net" }] }] };
+const svc: DriverComponent = {
+  name: "svc",
+  dependsOn: ["net"],
+  deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "tf", name: "svc", vpc: { stackOutput: { stack: "net", name: "id" } } }] }],
+};
+
+/** A change set of one planned member per name, each at the digest given; `writes` adds an update of that member's `vpc`. */
+const doc = (members: Record<string, string>, writes: Record<string, string> = {}): ChangeSetDocument =>
+  composeChangeSet(
+    Object.entries(members).map(([member, digest]) => ({
+      member: { member, lexicon: "terraform", planner: "terraform" as const, status: "planned" as const, planDigest: digest, holes: [] },
+      entries: writes[member]
+        ? [{ member, lexicon: "terraform", planner: "terraform" as const, address: `${member}.main`, type: "x", name: "main", action: "update" as const, attributes: [{ path: "vpc", after: writes[member] }] }]
+        : [],
+    })),
+  );
+
+const approved = doc({ net: sha("1"), svc: sha("2") }, { svc: "vpc-new" });
+const binding: ReleaseGateBinding = { op: "release", planDigest: approved.digest, releaseDigest: sha("r") };
+
+/** A run that applies every component and leaves `exposes` as its outputs, recording what it was handed. */
+function runner(exposes: Record<string, Record<string, unknown>>) {
+  const calls: Array<{ names: string[]; gates: string[]; binding: string; outputs: Record<string, Record<string, unknown>> }> = [];
+  const run = async (components: DriverComponent[], outputs: Record<string, Record<string, unknown>>, b: ReleaseGateBinding): Promise<DriverRunResult> => {
+    const gates = components.flatMap((c) => c.deploy.flatMap((p) => p.steps.filter((s) => (s as { kind?: string }).kind === "gate").map((s) => (s as { gate: string }).gate)));
+    calls.push({ names: components.map((c) => c.name), gates, binding: b.planDigest, outputs });
+    const out = { ...outputs };
+    for (const c of components) if (exposes[c.name]) out[c.name] = exposes[c.name];
+    return {
+      order: components.map((c) => c.name),
+      waves: [components.map((c) => c.name)],
+      results: components.map((c) => ({ component: c.name, ok: true, status: "ok" as const, records: [] })),
+      ok: true,
+      status: "ok",
+      componentOutputs: out,
+    };
+  };
+  return { run, calls };
+}
+
+const bindings: string[][] = [];
+const bind = async (d: ChangeSetDocument, gates: string[]): Promise<ReleaseGateBinding> => {
+  bindings.push(gates);
+  return { op: "release", planDigest: d.digest, releaseDigest: sha("r") };
+};
+
+describe("movedInputs", () => {
+  test("names each reference that resolves to another value than its plan read", () => {
+    expect(movedInputs(svc, { net: { id: "vpc-new" } }, { net: { id: "vpc-new" } })).toEqual([]);
+    expect(movedInputs(svc, { net: { id: "vpc-new" } }, { net: { id: "vpc-other" } })).toEqual(["net.id"]);
+    expect(movedInputs(svc, undefined, { net: { id: "x" } })).toEqual([]);
+  });
+});
+
+describe("renameGates", () => {
+  test("renames every gate, nested phases included, and drops the old key", () => {
+    const c: DriverComponent = { name: "x", deploy: [{ phase: "A", steps: [{ phase: "B", steps: [{ kind: "gate", signalName: "old" }] }, { kind: "gate", gate: "g" }] }] };
+    const renamed = renameGates(c, (g) => `${g}-round-2`);
+    expect(JSON.stringify(renamed)).toContain('"gate":"old-round-2"');
+    expect(JSON.stringify(renamed)).toContain('"gate":"g-round-2"');
+    expect(JSON.stringify(renamed)).not.toContain("signalName");
+  });
+});
+
+describe("runPromotionInRounds", () => {
+  test("an upstream that applies as its plan said leaves the dependent under the approval it has", async () => {
+    const { run, calls } = runner({ net: { id: "vpc-new" } });
+    const result = await runPromotionInRounds({
+      components: [svc, net],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      run,
+      replan: async () => { throw new Error("not planned again"); },
+      bind,
+    });
+    expect(result.run.status).toBe("ok");
+    expect(result.stages).toEqual([]);
+    expect(calls.map((c) => [c.names, c.binding])).toEqual([[["net"], approved.digest], [["svc"], approved.digest]]);
+    expect(calls[1].outputs).toEqual({ net: { id: "vpc-new" } });
+    expect(result.completed).toEqual(["net", "svc"]);
+  });
+
+  test("an upstream that applies as another value plans the dependent again; a covered plan applies under the approval", async () => {
+    const { run, calls } = runner({ net: { id: "vpc-other" } });
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      run,
+      replan: async () => doc({ svc: sha("2") }, { svc: "vpc-new" }),
+      bind,
+    });
+    expect(result.stages).toEqual([]);
+    expect(calls[1]).toMatchObject({ names: ["svc"], binding: approved.digest, gates: ["prod-release"] });
+  });
+
+  test("a moved plan the approval does not cover waits at <gate>-round-2, bound to the new digest", async () => {
+    const { run, calls } = runner({ net: { id: "vpc-other" } });
+    const fresh = doc({ svc: sha("9") }, { svc: "vpc-other" });
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      run,
+      replan: async (only, outputs) => {
+        expect([...only]).toEqual(["svc"]);
+        expect(outputs).toEqual({ net: { id: "vpc-other" } });
+        return fresh;
+      },
+      bind,
+    });
+    expect(result.stages).toHaveLength(1);
+    expect(result.stages[0]).toMatchObject({ kind: "round", number: 2, components: ["svc"], digest: fresh.digest, status: "applied" });
+    expect(result.stages[0].notCovered[0]).toMatch(/svc/);
+    expect(calls[1]).toMatchObject({ names: ["svc"], binding: fresh.digest, gates: ["prod-release-round-2"] });
+  });
+
+  test("--wave-gate checks every wave after the first and names one gate per wave", async () => {
+    const { run, calls } = runner({ net: { id: "vpc-new" } });
+    const fresh = doc({ svc: sha("8") }, { svc: "vpc-other" });
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      waveGate: "deploy",
+      run,
+      replan: async () => fresh,
+      bind,
+    });
+    expect(result.stages[0]).toMatchObject({ kind: "wave", number: 2, digest: fresh.digest });
+    expect(calls[1].gates).toEqual(["deploy-wave-2"]);
+  });
+
+  test("a stage whose components declare no gate stops with nothing more deployed", async () => {
+    const plain: DriverComponent = { ...svc, deploy: [{ phase: "Apply", steps: [{ kind: "tf", name: "svc", vpc: { stackOutput: { stack: "net", name: "id" } } }] }] };
+    const { run, calls } = runner({ net: { id: "vpc-other" } });
+    const result = await runPromotionInRounds({
+      components: [net, plain],
+      outputs: {},
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      run,
+      replan: async () => doc({ svc: sha("9") }, { svc: "vpc-other" }),
+      bind,
+    });
+    expect(result.run.status).toBe("fail");
+    expect(result.stages[0]).toMatchObject({ status: "failed" });
+    expect(result.stages[0].message).toMatch(/no gate/);
+    expect(calls.map((c) => c.names)).toEqual([["net"]]);
+  });
+
+  test("a resume skips what applied and starts from the outputs it kept", async () => {
+    const { run, calls } = runner({});
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: { net: { id: "vpc-new" } },
+      binding,
+      approved,
+      reads: { svc: { net: { id: "vpc-new" } } },
+      completed: ["net"],
+      run,
+      replan: async () => { throw new Error("not planned again"); },
+      bind,
+    });
+    expect(calls.map((c) => c.names)).toEqual([["svc"]]);
+    expect(result.completed).toEqual(["net", "svc"]);
+  });
+
+  test("a gated wave stops the run and leaves what applied", async () => {
+    const calls: string[][] = [];
+    const result = await runPromotionInRounds({
+      components: [net, svc],
+      outputs: {},
+      binding,
+      approved,
+      reads: {},
+      run: async (components, outputs) => {
+        calls.push(components.map((c) => c.name));
+        return {
+          order: ["net"],
+          waves: [["net"]],
+          results: [{ component: "net", ok: false, status: "gated", records: [] }],
+          ok: false,
+          status: "gated",
+          gatedComponent: "net",
+          componentOutputs: outputs,
+        };
+      },
+      replan: async () => approved,
+      bind,
+    });
+    expect(result.run.status).toBe("gated");
+    expect(result.run.gatedComponent).toBe("net");
+    expect(calls).toEqual([["net"]]);
+    expect(result.completed).toEqual([]);
+  });
+});

package/src/components/promote-rounds.ts

@@ -0,0 +1,232 @@
+/**
+ * A promote under a release that plans again once an upstream applied, and a
+ * gate per wave (#4168 step 4). Merging deploys nothing since step 1, so what
+ * `pr-apply` did on merge happens here, at promote:
+ *
+ * - **Rounds** (#3999's rule, `../pr-loop.ts`). The release gate approves a
+ *   change set in which each dependent was planned against its upstream's
+ *   planned outputs (`planReleaseSet` in ./release-gate.ts). The promote runs
+ *   a wave at a time. Before a wave runs, a component whose plan read an
+ *   upstream output that the run left as another value
+ *   (`movedWiringReferences`) is planned again against what stands. When the
+ *   approved change set covers the new plan (`waveNotCovered`, the test a
+ *   pull request's resume uses), it applies under the approval it has.
+ *   Otherwise its gates are decided as `<gate>-round-<n>` (`prRoundGate`),
+ *   bound to the new plan's digest.
+ * - **A gate per wave** (`--wave-gate <gate>`, #4157's rule). Every wave
+ *   after the first is planned again against what the waves before it left,
+ *   and a wave the approved change set does not cover waits at
+ *   `<gate>-wave-<k>` (`waveGateName`), one gate for the whole wave, bound to
+ *   that wave's digest.
+ *
+ * A stage whose components declare no gate has nowhere to wait, so the
+ * promote stops there with nothing more deployed.
+ *
+ * A promote that stops at a round's or a wave's gate writes a resume record
+ * ({@link PromoteResume}): the components that applied and the outputs they
+ * left. The same promote run again with it skips what applied and carries on
+ * from the wave it stopped at, so an approval of the round or wave it waits on
+ * is decided against the same plan.
+ */
+
+import { movedWiringReferences, type DriverComponent, type DriverGate, type DriverPhase, type DriverRunResult, type DriverStep, type ReleaseGateBinding } from "./driver";
+import { resolveComponentGraph } from "./driver";
+import { waveNotCovered } from "./pr-run";
+import { prRoundGate } from "../pr-loop";
+import { waveGateName } from "../gated-waves";
+import { capabilitySteps } from "./wave-plan";
+import type { ChangeSetDocument } from "../change-set";
+import type { ReleasePlan } from "./release-gate";
+
+export const PROMOTE_RESUME_SCHEMA = "chant-promote-resume/v1";
+
+/** What a promote that stopped at a round's or a wave's gate leaves for the next attempt. */
+export interface PromoteResume {
+  schema: typeof PROMOTE_RESUME_SCHEMA;
+  env: string;
+  releaseDigest: string;
+  /** The change set the release gate approved before anything applied. */
+  approvedDigest: string;
+  /** Components that applied, in run order. */
+  completed: string[];
+  /** The outputs standing after them. */
+  outputs: Record<string, Record<string, unknown>>;
+  /** ISO 8601. */
+  at: string;
+}
+
+/** One round or wave that needed its own approval. */
+export interface PromoteStage {
+  kind: "round" | "wave";
+  /** The round number (2 and up) or the wave number (1-based). */
+  number: number;
+  components: string[];
+  /** The plan the stage's gates bind. */
+  digest: string;
+  /** Why the approved change set did not cover it, one line per member. */
+  notCovered: string[];
+  status: "applied" | "waiting" | "failed";
+  /** With `failed` before anything ran: why. */
+  message?: string;
+}
+
+export interface PromoteRoundsOptions {
+  /** The promoted compositions, in no particular order. */
+  components: DriverComponent[];
+  /** Outputs standing before the run: the seeds, and on a resume the record's. */
+  outputs: Record<string, Record<string, unknown>>;
+  /** The release gate the change set was approved under. */
+  binding: ReleaseGateBinding;
+  /** The approved change set, and what each component's plan read. */
+  approved: ChangeSetDocument;
+  reads: ReleasePlan["reads"];
+  /** Components an earlier attempt applied. Skipped. */
+  completed?: readonly string[];
+  /** `--wave-gate <gate>`: check every wave after the first, not only the components whose inputs moved, and name a wave's gate `<gate>-wave-<k>`. */
+  waveGate?: string;
+  /** Run one subset of the components with `outputs` standing (`runPromotion` with the binding). */
+  run: (components: DriverComponent[], outputs: Record<string, Record<string, unknown>>, binding: ReleaseGateBinding) => Promise<DriverRunResult>;
+  /** Plan `only` again with `outputs` standing (`planReleaseSet`). */
+  replan: (only: ReadonlySet<string>, outputs: Record<string, Record<string, unknown>>) => Promise<ChangeSetDocument>;
+  /** Store a stage's plan and bind its gates (empty resolutions included). */
+  bind: (doc: ChangeSetDocument, gates: string[]) => Promise<ReleaseGateBinding>;
+}
+
+export interface PromoteRoundsResult {
+  run: DriverRunResult;
+  /** The rounds and waves that needed their own approval. */
+  stages: PromoteStage[];
+  /** Every component that applied, earlier attempts included, in run order. */
+  completed: string[];
+  outputs: Record<string, Record<string, unknown>>;
+}
+
+function isGate(step: DriverStep | DriverGate | DriverPhase): step is DriverGate {
+  return (step as { kind?: unknown }).kind === "gate";
+}
+
+function isPhase(step: DriverStep | DriverGate | DriverPhase): step is DriverPhase {
+  return typeof (step as { phase?: unknown }).phase === "string" && Array.isArray((step as DriverPhase).steps);
+}
+
+/** `component` with each gate renamed by `rename`, nested phases included. */
+export function renameGates(component: DriverComponent, rename: (gate: string) => string): DriverComponent {
+  const walk = (phase: DriverPhase): DriverPhase => ({
+    ...phase,
+    steps: phase.steps.map((step) => {
+      if (isPhase(step)) return walk(step);
+      if (!isGate(step)) return step;
+      const { signalName: _old, ...rest } = step;
+      return { ...rest, gate: rename(step.gate ?? step.signalName ?? "") };
+    }),
+  });
+  return { ...component, deploy: component.deploy.map(walk) };
+}
+
+/** The gate names `components` declare, sorted and distinct. */
+function gatesOf(components: readonly DriverComponent[]): string[] {
+  const names = new Set<string>();
+  const walk = (steps: DriverPhase["steps"]): void => {
+    for (const step of steps) {
+      if (isPhase(step)) walk(step.steps);
+      else if (isGate(step)) names.add(step.gate ?? step.signalName ?? "");
+    }
+  };
+  for (const c of components) for (const phase of c.deploy) walk(phase.steps);
+  return [...names].sort();
+}
+
+/** The references `component`'s steps make that resolve to another value now than when its plan read them. */
+export function movedInputs(component: DriverComponent, read: Record<string, Record<string, unknown>> | undefined, now: Record<string, Record<string, unknown>>): string[] {
+  if (!read) return [];
+  const moved = new Set<string>();
+  for (const step of capabilitySteps(component.deploy)) {
+    const { kind: _kind, ...rest } = step;
+    for (const r of movedWiringReferences(rest, read, now)) if (!r.publish) moved.add(r.ref);
+  }
+  return [...moved].sort();
+}
+
+function joinRuns(runs: DriverRunResult[], outputs: Record<string, Record<string, unknown>>): DriverRunResult {
+  const last = runs[runs.length - 1];
+  const base: DriverRunResult = {
+    order: runs.flatMap((r) => r.order),
+    waves: runs.flatMap((r) => r.waves),
+    results: runs.flatMap((r) => r.results),
+    ok: runs.every((r) => r.ok),
+    status: "ok",
+    componentOutputs: outputs,
+  };
+  if (!last || last.status === "ok") return base;
+  const { order: _o, waves: _w, results: _r, ok: _ok, componentOutputs: _c, ...stop } = last;
+  return { ...base, ...stop, ok: false };
+}
+
+/**
+ * Run the promote a wave at a time, planning again where an upstream applied
+ * as another value, and with `waveGate`, checking each wave. Stops at the
+ * first wave that fails or waits on a gate.
+ */
+export async function runPromotionInRounds(options: PromoteRoundsOptions): Promise<PromoteRoundsResult> {
+  const byName = new Map(options.components.map((c) => [c.name, c]));
+  const { waves } = resolveComponentGraph(options.components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+  const completed = [...(options.completed ?? [])];
+  const done = new Set(completed);
+  let outputs = { ...options.outputs };
+  const runs: DriverRunResult[] = [];
+  const stages: PromoteStage[] = [];
+  let round = 1;
+
+  for (const [index, wave] of waves.entries()) {
+    const waveNumber = index + 1;
+    const pending = wave.filter((name) => !done.has(name));
+    if (pending.length === 0) continue;
+    const check = options.waveGate !== undefined && waveNumber > 1
+      ? pending
+      : pending.filter((name) => movedInputs(byName.get(name)!, options.reads[name], outputs).length > 0);
+    const batches: Array<{ names: string[]; binding: ReleaseGateBinding; stage?: PromoteStage; rename?: (g: string) => string }> = [];
+    const rest = pending.filter((name) => !check.includes(name));
+    if (check.length > 0) {
+      const fresh = await options.replan(new Set(check), outputs);
+      const notCovered = waveNotCovered(options.approved, fresh);
+      if (notCovered.length === 0) {
+        rest.push(...check);
+      } else {
+        const kind: PromoteStage["kind"] = options.waveGate !== undefined ? "wave" : "round";
+        if (kind === "round") round += 1;
+        const number = kind === "wave" ? waveNumber : round;
+        const base = options.waveGate;
+        const rename = (g: string) => (base !== undefined ? waveGateName(base, number) : prRoundGate(g, number));
+        const renamed = check.map((name) => renameGates(byName.get(name)!, rename));
+        const gates = gatesOf(renamed);
+        const stage: PromoteStage = { kind, number, components: check, digest: fresh.digest, notCovered, status: "waiting" };
+        stages.push(stage);
+        if (gates.length === 0) {
+          stage.status = "failed";
+          stage.message = `${check.join(", ")} planned again past the approved change set and declare${check.length === 1 ? "s" : ""} no gate to approve the new plan on`;
+          const stop: DriverRunResult = { order: [], waves: [], results: [], ok: false, status: "fail", failedComponent: check[0], componentOutputs: outputs };
+          return { run: joinRuns([...runs, stop], outputs), stages, completed, outputs };
+        }
+        const binding = await options.bind(fresh, gates);
+        batches.push({ names: check, binding, stage, rename });
+      }
+    }
+    if (rest.length > 0) batches.unshift({ names: pending.filter((n) => rest.includes(n)), binding: options.binding });
+
+    for (const batch of batches) {
+      const components = batch.names.map((name) => (batch.rename ? renameGates(byName.get(name)!, batch.rename) : byName.get(name)!));
+      const run = await options.run(components, outputs, batch.binding);
+      runs.push(run);
+      outputs = { ...outputs, ...run.componentOutputs };
+      for (const r of run.results) {
+        if (r.status === "ok" && !done.has(r.component)) {
+          done.add(r.component);
+          completed.push(r.component);
+        }
+      }
+      if (batch.stage) batch.stage.status = run.status === "ok" ? "applied" : run.status === "gated" ? "waiting" : "failed";
+      if (run.status !== "ok") return { run: joinRuns(runs, outputs), stages, completed, outputs };
+    }
+  }
+  return { run: joinRuns(runs, outputs), stages, completed, outputs };
+}

package/src/components/release-compile.test.ts

@@ -13,6 +13,7 @@ import {
   buildReleaseArtifacts,
   buildStepsOf,
   compileEnvironment,
+  recordedInputRefs,
   ReleaseCompileError,
   templateRefs,
   withOnlyArchiveSteps,
@@ -49,6 +50,18 @@ describe("templateRefs", () => {
   });
 });
 
+describe("recordedInputRefs (#4155)", () => {
+  test("adds each kind's own fields to the template fields: a chart; a missing one need not exist", () => {
+    expect(recordedInputRefs(api).map((r) => [r.kind, r.field, r.path, r.required])).toEqual([
+      ["cfn-deploy", "template", "dist/api.template.json", true],
+      ["cfn-deploy", "template", "dist/edge.template.json", true],
+      ["helm-upgrade", "values", "values/base.yaml", true],
+      ["helm-upgrade", "chart", "charts/api", false],
+      ["kubectl-apply", "manifest", "k8s/api.yaml", true],
+    ]);
+  });
+});
+
 describe("withOnlyArchiveSteps", () => {
   test("keeps the archive steps alone, drops gates and every other step, and the dependencies", () => {
     expect(withOnlyArchiveSteps(api)).toEqual({
@@ -100,6 +113,27 @@ describe("compileEnvironment", () => {
     });
   });
 
+  test("records a chart directory file by file and names it in trees; a file that is not UTF-8 as base64 (#4155)", async () => {
+    await withTestDir(async (dir) => {
+      writeFileSync(
+        join(dir, "web.component.ts"),
+        `export const web = { name: "web", dependsOn: [], deploy: [{ phase: "Deploy", steps: [
+          { kind: "helm-upgrade", release: "web", chart: "chart" },
+          { kind: "helm-upgrade", release: "remote", chart: "bitnami/nginx", repo: "https://charts.example" },
+        ] }] };`,
+      );
+      mkdirSync(join(dir, "chart", "charts"), { recursive: true });
+      writeFileSync(join(dir, "chart", "Chart.yaml"), "name: web\n");
+      writeFileSync(join(dir, "chart", "charts", "dep.tgz"), Buffer.from([0x1f, 0x8b, 0xff, 0x00]));
+      const target = await compileEnvironment({ projectDir: dir }, "prod");
+      expect(target.trees).toEqual([{ component: "web", path: "chart" }]);
+      expect(target.templates).toEqual([
+        { component: "web", path: "chart/Chart.yaml", content: "name: web\n" },
+        { component: "web", path: "chart/charts/dep.tgz", content: Buffer.from([0x1f, 0x8b, 0xff, 0x00]).toString("base64"), encoding: "base64" },
+      ]);
+    });
+  });
+
   test("refuses when a template a deploy names does not exist after the build", async () => {
     await withTestDir(async (dir) => {
       project(dir);