@intentius/chant 0.124.39 → 0.124.41

package/src/cli/handlers/lock.test.ts

@@ -0,0 +1,98 @@
+/**
+ * #4293: `chant lock` and `chant unlock` take, list and release target locks
+ * on `chant/lifecycle`, and exit 3 when another pull request holds a target.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { commandRegistry, parseArgs } from "../main";
+import { resolveCommand } from "../registry";
+
+const dirs: string[] = [];
+const home = process.cwd();
+afterAll(() => {
+  process.chdir(home);
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function initRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-lock-cli-")));
+  dirs.push(dir);
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "test@chant.dev");
+  git(dir, "config", "user.name", "Test");
+  git(dir, "config", "commit.gpgsign", "false");
+  writeFileSync(join(dir, "README.md"), "# t\n");
+  git(dir, "add", "README.md");
+  git(dir, "commit", "-q", "-m", "init");
+  return dir;
+}
+
+async function run(argv: string[]): Promise<{ code: number; out: string; err: string }> {
+  let out = "";
+  let err = "";
+  vi.spyOn(console, "log").mockImplementation((s) => void (out += String(s) + "\n"));
+  vi.spyOn(console, "error").mockImplementation((s) => void (err += String(s) + "\n"));
+  const args = parseArgs(argv);
+  const match = resolveCommand(args, commandRegistry);
+  expect(match?.def.name).toBe(argv[0]);
+  const code = await match!.def.handler({ args, plugins: [], serializers: [] });
+  vi.restoreAllMocks();
+  return { code: code ?? 0, out, err };
+}
+
+let repo: string;
+beforeEach(() => {
+  repo = initRepo();
+  process.chdir(repo);
+});
+afterEach(() => {
+  process.chdir(home);
+  vi.restoreAllMocks();
+});
+
+describe("chant lock and chant unlock", () => {
+  test("lock takes named targets, a second pull request exits 3 naming the holder, unlock frees them", async () => {
+    const taken = await run(["lock", "web", "api", "--pr", "1", "--by", "alice", "--json"]);
+    expect(taken.code).toBe(0);
+    expect(JSON.parse(taken.out)).toMatchObject({ gate: "pr-apply", pr: 1, ok: true, stage: "lock", taken: ["api", "web"] });
+
+    const held = await run(["lock", "web", "--pr", "2", "--by", "bob"]);
+    expect(held.code).toBe(3);
+    expect(held.err).toContain("web is locked by pull request 1 (locked with chant lock by alice), so pull request 2 is not locked");
+
+    const listed = await run(["lock", "--list", "--json"]);
+    expect(Object.keys(JSON.parse(listed.out).locks)).toEqual(["api", "web"]);
+
+    const released = await run(["unlock", "--pr", "1", "--json"]);
+    expect(JSON.parse(released.out)).toMatchObject({ released: ["api", "web"] });
+    expect((await run(["lock", "web", "--pr", "2", "--by", "bob"])).code).toBe(0);
+  });
+
+  test("--from-report locks the components a pr-plan.json selected, as plan locks, and refuses another pull request's report", async () => {
+    const report = join(repo, "pr-plan.json");
+    writeFileSync(report, JSON.stringify({ pr: 4, head: "b".repeat(40), selection: { waves: [["db"], ["api", "web"]] } }));
+    const taken = await run(["lock", "--from-report", report, "--pr", "4", "--stage", "plan", "--json"]);
+    expect(JSON.parse(taken.out)).toMatchObject({ ok: true, stage: "plan", taken: ["api", "db", "web"] });
+    const file = JSON.parse(git(repo, "show", "chant/lifecycle:_locks/pr-apply.json"));
+    expect(file.locks.db).toMatchObject({ pr: 4, stage: "plan", head: "b".repeat(40) });
+
+    const wrong = await run(["lock", "--from-report", report, "--pr", "5"]);
+    expect(wrong.code).toBe(1);
+    expect(wrong.err).toContain("is the report of pull request 4, not 5");
+  });
+
+  test("refuses without --pr or targets, an unknown stage, and a gate that is not a file name", async () => {
+    expect((await run(["lock", "web"])).err).toContain("--pr <n>");
+    expect((await run(["lock", "--pr", "1"])).err).toContain("needs the targets");
+    expect((await run(["lock", "web", "--pr", "1", "--stage", "merge"])).err).toContain("--stage merge is not one of plan, apply, lock");
+    expect((await run(["lock", "web", "--pr", "1", "--gate", "../x"])).code).toBe(1);
+    expect((await run(["unlock"])).err).toContain("--pr <n>");
+  });
+});

package/src/cli/handlers/lock.ts

@@ -0,0 +1,202 @@
+/**
+ * `chant lock` and `chant unlock` (#4293): take, list and release the target
+ * locks a pull request holds (../../lifecycle/target-lock.ts).
+ *
+ * ```
+ * chant lock <target>... --pr <n> [--stage plan|apply|lock] [--head <sha>] [--by <who>] [--gate <name>] [--forge <kind>] [--json]
+ * chant lock --from-report <pr-plan.json> --pr <n> [--stage plan] [--forge <kind>] [--json]
+ * chant lock --list [--gate <name>] [--json]
+ * chant unlock --pr <n> [<target>...] [--gate <name>] [--json]
+ * ```
+ *
+ * The targets are names: the components `chant components pr-plan` selects,
+ * which are what `pr-apply` checks under `ci.locks`, or any other name a
+ * pipeline locks by. `--from-report` reads them from a pull-request report
+ * (`selection.waves`), so a lock job that runs the target branch's code can
+ * lock what the plan job, which ran the pull request's code, selected.
+ *
+ * `--forge` reads which holders are still open, so a lock whose pull
+ * request merged or closed is taken over, and, with `--head`, posts the
+ * `chant/lock` status on that commit. Without it every lock counts as held.
+ *
+ * Exit 0 when the locks are taken or released, 3 when another open pull
+ * request holds a target (nothing is locked), 1 on an error.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { CommandContext } from "../registry";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
+import { FORGE_KINDS, forgeFromEnv, type ForgeKind, type PrForge } from "../../pr-forge";
+import { PR_APPLY_GATE } from "../../pr-loop";
+import {
+  describeHeldTargetLocks,
+  readTargetLocks,
+  releaseTargetLocks,
+  takeTargetLocks,
+  targetLockGateProblem,
+  targetLockPathAt,
+  TARGET_LOCK_STAGES,
+  type TargetLockStage,
+} from "../../lifecycle/target-lock";
+
+/** The exit for a target another open pull request holds: 3, as a run stopped at a gate exits (`GATED_EXIT_CODE` in ./run.ts). */
+const HELD_EXIT_CODE = 3;
+
+/** The status `chant lock --head <sha> --forge <kind>` posts. */
+export const LOCK_STATUS_CONTEXT = "chant/lock";
+
+const fail = (message: string, hint?: string): number => {
+  console.error(formatError({ message, ...(hint ? { hint } : {}) }));
+  return 1;
+};
+
+/** The targets named after the command word. */
+function targetsOf(ctx: CommandContext): string[] {
+  return (ctx.args.positionals ?? []).filter((t) => t !== "");
+}
+
+function gateOf(ctx: CommandContext): string | { error: string } {
+  const gate = ctx.args.gate ?? PR_APPLY_GATE;
+  const problem = targetLockGateProblem(gate);
+  return problem ? { error: problem } : gate;
+}
+
+function forgeOf(ctx: CommandContext): PrForge | undefined | { error: string } {
+  const kind = ctx.args.forge;
+  if (kind === undefined) return undefined;
+  if (!(FORGE_KINDS as readonly string[]).includes(kind)) return { error: `--forge ${kind} is not one of ${FORGE_KINDS.join(", ")}` };
+  try {
+    return forgeFromEnv(kind as ForgeKind);
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+const prName = (forge: PrForge | undefined) => (n: number) => (forge?.kind === "gitlab" ? `merge request !${n}` : `pull request ${n}`);
+
+/** The components a `pr-plan.json` selected, and the head it planned, checked against `--pr`. */
+function fromReport(file: string, pr: number): { targets: string[]; head?: string } | { error: string } {
+  let doc: { pr?: unknown; head?: unknown; selection?: { waves?: unknown } };
+  try {
+    doc = JSON.parse(readFileSync(resolve(file), "utf8"));
+  } catch (err) {
+    return { error: `--from-report: could not read "${file}": ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (doc.pr !== pr) return { error: `--from-report: "${file}" is the report of ${doc.pr === null || doc.pr === undefined ? "no pull request" : `pull request ${String(doc.pr)}`}, not ${pr}` };
+  const waves = doc.selection?.waves;
+  if (!Array.isArray(waves) || !waves.every((w) => Array.isArray(w) && w.every((n) => typeof n === "string"))) {
+    return { error: `--from-report: "${file}" has no selection.waves; pass a pr-plan.json that chant components pr-plan wrote` };
+  }
+  return { targets: (waves as string[][]).flat(), ...(typeof doc.head === "string" ? { head: doc.head } : {}) };
+}
+
+async function postStatus(forge: PrForge | undefined, head: string | undefined, state: "success" | "failure", description: string): Promise<void> {
+  if (!forge || !head) return;
+  try {
+    await forge.setStatus(head, { context: LOCK_STATUS_CONTEXT, state, description: description.length > 140 ? `${description.slice(0, 137)}...` : description, ...(forge.runUrl ? { url: forge.runUrl } : {}) });
+  } catch (err) {
+    console.error(formatWarning({ message: `could not post ${LOCK_STATUS_CONTEXT} on ${head}: ${err instanceof Error ? err.message : String(err)}` }));
+  }
+}
+
+/** chant lock */
+export async function runLock(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const gate = gateOf(ctx);
+  if (typeof gate !== "string") return fail(gate.error);
+
+  if (args.list) {
+    if (targetsOf(ctx).length > 0 || args.pr !== undefined) return fail("--list prints every lock; drop the targets and --pr");
+    let file;
+    try {
+      file = await readTargetLocks(gate);
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+    const rows = Object.entries(file.locks).sort(([a], [b]) => a.localeCompare(b));
+    if (args.json) {
+      console.log(JSON.stringify({ gate, path: await targetLockPathAt(gate), locks: Object.fromEntries(rows) }, null, 2));
+      return 0;
+    }
+    if (rows.length === 0) console.error(formatInfo(`no target locks on ${gate}`));
+    for (const [target, l] of rows) console.log(`${target}\tpull request ${l.pr}\t${l.stage}\t${l.by}\t${l.at}`);
+    return 0;
+  }
+
+  if (args.pr === undefined) return fail("chant lock needs the pull or merge request that holds the locks: --pr <n>", "chant lock --list prints the locks held now.");
+  const stage = (args.lockStage ?? "lock") as TargetLockStage;
+  if (!(TARGET_LOCK_STAGES as readonly string[]).includes(stage)) return fail(`--stage ${args.lockStage} is not one of ${TARGET_LOCK_STAGES.join(", ")}`);
+
+  let targets = targetsOf(ctx);
+  let head = args.head;
+  if (args.fromReport) {
+    if (targets.length > 0) return fail("--from-report reads the targets from the report; drop the names");
+    const read = fromReport(args.fromReport, args.pr);
+    if ("error" in read) return fail(read.error);
+    targets = read.targets;
+    head ??= read.head;
+  } else if (targets.length === 0 && stage !== "plan") {
+    return fail("chant lock needs the targets to lock: chant lock <target>... --pr <n>", "Or --from-report <pr-plan.json> to lock what a plan selected.");
+  }
+
+  const forge = forgeOf(ctx);
+  if (forge && "error" in forge) return fail(forge.error);
+  const isOpen = forge?.pullRequestOpen?.bind(forge);
+  const by = args.by ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+  const name = prName(forge);
+
+  let result;
+  try {
+    result = await takeTargetLocks(
+      gate,
+      targets,
+      { pr: args.pr, by, at: new Date().toISOString(), stage, ...(head ? { head } : {}) },
+      { ...(isOpen ? { isOpen } : {}), releaseStalePlan: stage === "plan" },
+    );
+  } catch (err) {
+    return fail(`could not take the locks of ${gate}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!result.ok) {
+    const holders = [...new Set(result.held.map((h) => h.pr))].sort((a, b) => a - b);
+    const text = `${describeHeldTargetLocks(result.held, name)}, so ${name(args.pr)} is not locked`;
+    await postStatus(forge, head, "failure", `locked by ${holders.map(name).join(", ")}: ${result.held.map((h) => h.target).join(", ")}`);
+    if (args.json) console.log(JSON.stringify({ gate, pr: args.pr, ok: false, held: result.held }, null, 2));
+    console.error(formatError({ message: text, hint: `Lock again once ${holders.length === 1 ? "it merges or closes" : "they merge or close"}, or after chant unlock --pr ${holders[0]}.${isOpen ? "" : " Without --forge every lock counts as held."}` }));
+    return HELD_EXIT_CODE;
+  }
+
+  const holds = result.taken.length > 0 ? `holds ${result.taken.join(", ")}` : "reaches no target";
+  await postStatus(forge, head, "success", holds);
+  if (args.json) {
+    console.log(JSON.stringify({ gate, pr: args.pr, ok: true, stage, taken: result.taken, released: result.released, expired: result.expired, pushed: result.pushed }, null, 2));
+    return 0;
+  }
+  console.error(formatSuccess(`${name(args.pr)} ${holds} on ${gate}`));
+  if (result.released.length > 0) console.error(formatInfo(`released ${result.released.join(", ")}, which it no longer reaches`));
+  if (result.expired.length > 0) console.error(formatInfo(`took over ${result.expired.join(", ")} from pull requests that merged or closed`));
+  if (!result.pushed && (result.taken.length > 0 || result.released.length > 0)) console.error(formatInfo("chant/lifecycle was not pushed: this repository has no remote, or recording is off"));
+  return 0;
+}
+
+/** chant unlock */
+export async function runUnlock(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const gate = gateOf(ctx);
+  if (typeof gate !== "string") return fail(gate.error);
+  if (args.pr === undefined) return fail("chant unlock needs the pull or merge request whose locks it releases: --pr <n>");
+  const targets = targetsOf(ctx);
+  let result;
+  try {
+    result = await releaseTargetLocks(gate, args.pr, targets.length > 0 ? { targets } : {});
+  } catch (err) {
+    return fail(`could not release the locks of ${gate}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (args.json) {
+    console.log(JSON.stringify({ gate, pr: args.pr, released: result.released, pushed: result.pushed }, null, 2));
+    return 0;
+  }
+  if (result.released.length === 0) console.error(formatInfo(`pull request ${args.pr} holds no lock${targets.length > 0 ? ` on ${targets.join(", ")}` : ""} on ${gate}`));
+  else console.error(formatSuccess(`released the locks pull request ${args.pr} held on ${result.released.join(", ")}`));
+  return 0;
+}

package/src/cli/handlers/operator.test.ts

@@ -1278,7 +1278,9 @@ describe("runApprove — a gate with an approval policy (#2508)", () => {
     }));
     const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
     expect(out).toContain("log-only mode, so the decision is recorded and does not change the outcome");
-    expect(out).toContain("Quorum: 1 of 2 human approval(s) with role maintainer for this plan (alex)");
+    // #4290: a claimed role is recorded for the policy, and the quorum never counts it.
+    expect(out).toContain("Quorum: 0 of 2 human approval(s) with role maintainer for this plan (none yet)");
+    expect(out).toContain("its roles are read from .chant/trust.json at base");
     errSpy.mockRestore();
   });
 

package/src/cli/handlers/pr-endpoint.test.ts

@@ -0,0 +1,169 @@
+/**
+ * `chant components pr-plan` for an environment that declares an endpoint
+ * (#4281): every request a capability's plan sends goes to that endpoint and
+ * no other host, the way a `--live` read does (`../../live-endpoint.ts`).
+ *
+ * The capability stands in for azure's `arm-deploy`, gcp's `gcp-apply` and
+ * aws's `cfn-deploy`: its plan reads the endpoint from its lexicon's ambient
+ * var, else the real cloud's host, and sends a request through `fetch`, which
+ * is replaced here and only records. Nothing leaves the process. Git, the
+ * change signal, the derivation and the gate ledger are fakes, and the
+ * lifecycle branch can't be pushed.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { DriverComponent } from "../../components/driver";
+import type { DeployContext } from "../../components/capability";
+import type { EmulatorCapability } from "../../op/emulator-lifecycle";
+import type { ParsedArgs } from "../registry";
+
+const HEAD = "a".repeat(40);
+const BASE = "b".repeat(40);
+const EMULATOR = "http://localhost:4566";
+const REAL_CLOUD = "https://management.fakecloud.example";
+const ENDPOINT_VAR = "FAKECLOUD_ENDPOINT_URL";
+
+vi.mock("../../components/changed-files", () => ({
+  resolveCommit: async () => HEAD,
+  resolveMergeBase: async () => BASE,
+}));
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return {
+    ...actual,
+    loadChantConfig: async () => ({
+      config: { environments: [{ name: "floci", endpoint: EMULATOR }, { name: "prod" }] },
+    }),
+  };
+});
+
+vi.mock("./fan-out", () => ({
+  resolveChangedUnits: async () => ({ units: { changed: ["net"], indeterminate: [] } }),
+}));
+
+vi.mock("../../lifecycle/gate-change-set", () => ({
+  storeGateChangeSet: async () => ({ written: false }),
+  readGraphIds: async () => ({ ids: [] }),
+  setGraphIdReader: () => {},
+  gateGraphReader: () => async () => ({ ids: [] }),
+}));
+vi.mock("../../lifecycle/git", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
+  return { ...actual, pushLifecycleReport: async () => { throw new Error("pr-endpoint.test must not push chant/lifecycle"); } };
+});
+
+vi.mock("./run", () => ({
+  GATED_EXIT_CODE: 3,
+  autoReleaseRun: (id: string) => ({ runId: id, runOrigin: { forge: "local" } }),
+  recordAutoReleasesForRun: async () => [],
+}));
+
+vi.mock("../../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
+  return { ...actual, gitGateLedgerPort: () => actual.memoryGateLedgerPort(), gateIsSealed: async () => false };
+});
+
+vi.mock("../../components/fan-out-support", async () => {
+  const { CapabilityRegistry } = await import("../../components/capability");
+  const { planFanOut } = await import("../../components/fan-out");
+  const { computePlanDigest } = await import("../../lifecycle/plan-digest");
+  const registry = new CapabilityRegistry();
+  registry.register({
+    kind: "fakecloud-deploy",
+    async plan(_ctx: DeployContext, input: { root: string }) {
+      // What arm-deploy, gcp-apply and cfn-deploy do: the ambient var, else the real host.
+      const base = process.env[ENDPOINT_VAR] ?? REAL_CLOUD;
+      await fetch(`${base}/deployments/${input.root}`);
+      const planDigest = computePlanDigest("fakecloud-deploy", { root: input.root });
+      return {
+        member: input.root,
+        planDigest,
+        artifact: { planDigest },
+        changeSet: { member: { member: input.root, lexicon: "fakecloud", planner: "fakecloud", status: "planned", planDigest, holes: [] }, entries: [] },
+      };
+    },
+    async outputs() {
+      return {};
+    },
+    async run() {
+      throw new Error("pr-plan must not apply");
+    },
+  } as never);
+  const component = (name: string, dependsOn: string[] = []): DriverComponent => ({
+    name,
+    dependsOn,
+    deploy: [{ phase: "Apply", steps: [{ kind: "fakecloud-deploy", root: name }] }],
+  });
+  const estate = [component("net"), component("app", ["net"])];
+  return {
+    fanOutRegistry: async () => registry,
+    deriveFanOut: async () => ({
+      success: true,
+      components: estate,
+      plan: planFanOut({ components: estate, changed: ["net"] }),
+      signal: { changed: ["net"], indeterminate: [], unclaimed: [] },
+    }),
+  };
+});
+
+/** The lexicon plugin, declaring its endpoint var through its emulator as aws, azure and gcp do. */
+const emulator: EmulatorCapability = {
+  spec: { name: "chant-fakecloud", image: "fakecloud:0", containerPort: 4566, healthPath: "/health" },
+  env: (endpoint) => ({ [ENDPOINT_VAR]: endpoint, FAKECLOUD_ACCESS_KEY: "test" }),
+};
+const plugins = [{ name: "fakecloud", emulator }];
+
+const { runComponentsPrPlan } = await import("./pr");
+
+let dir: string;
+let hosts: string[];
+
+const ctx = (env: string) =>
+  ({
+    args: { command: "components", path: "pr-plan", format: "", fix: false, watch: false, verbose: false, help: false, live: false, base: "main", env, output: dir, pr: 7 } as ParsedArgs,
+    plugins,
+  }) as never;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "pr-endpoint-"));
+  hosts = [];
+  delete process.env[ENDPOINT_VAR];
+  vi.stubGlobal("fetch", vi.fn(async (url: string | URL) => {
+    hosts.push(new URL(String(url)).host);
+    return new Response("{}", { status: 200 });
+  }));
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(async () => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  delete process.env[ENDPOINT_VAR];
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe("pr-plan against an environment that declares an endpoint (#4281)", () => {
+  test("every plan request goes to the declared endpoint and no other host, and the var is restored after", async () => {
+    expect(await runComponentsPrPlan(ctx("floci"))).toBe(0);
+    expect(hosts.length).toBe(2);
+    expect(new Set(hosts)).toEqual(new Set(["localhost:4566"]));
+    expect(process.env[ENDPOINT_VAR]).toBeUndefined();
+  });
+
+  test("an environment with no endpoint is left to the capability's own default", async () => {
+    expect(await runComponentsPrPlan(ctx("prod"))).toBe(0);
+    expect(new Set(hosts)).toEqual(new Set([new URL(REAL_CLOUD).host]));
+  });
+
+  test("an ambient var already set wins over the declared endpoint", async () => {
+    process.env[ENDPOINT_VAR] = "http://127.0.0.1:9999";
+    expect(await runComponentsPrPlan(ctx("floci"))).toBe(0);
+    expect(new Set(hosts)).toEqual(new Set(["127.0.0.1:9999"]));
+    expect(process.env[ENDPOINT_VAR]).toBe("http://127.0.0.1:9999");
+  });
+});