@intentius/chant 0.105.1 → 0.106.3

package/src/cli/registry.ts

@@ -282,6 +282,9 @@ export interface ParsedArgs {
    * the identical command finishes what an interrupted attempt left, because
    * the plan is narrowed by this file before the gate is decided and the
    * digest is carried rather than recomputed, so the approval still stands.
+   * `chant components pr-apply --resume <file>` (#3464) keeps the same record
+   * with the approved change set in it, and finishes an apply that failed
+   * partway under that approval.
    */
   resume?: string;
   /** `chant audit --tier merge-worthy|all` */
@@ -446,6 +449,8 @@ export interface ParsedArgs {
   /**
    * `chant workspace build|lint|audit|graph --member <name>` (#2537): run only
    * the named members or example groups. Repeatable, and a comma list works too.
+   * `chant components pr-plan|pr-apply --member <name>` (#3465) takes exactly
+   * one: the workspace member whose pull-request loop runs.
    */
   members?: string[];
   /**
@@ -524,6 +529,8 @@ export interface ParsedArgs {
   foldRankCollapsedFile?: string;
   /** `chant build --param name=value` (#1064) — repeatable. Bound to `params.<name>` (`@intentius/chant/params`) for source to reference, after validation against `chant.config.ts`'s declared `buildParams`. Highest precedence over `--params-file`/a declared `env` mapping/the declared `default`. */
   param?: string[];
+  /** `chant build --lexicon-output <lexicon>=<path>` — repeatable. Writes that lexicon's output to its own file, so one project can declare several lexicons (otel and prometheus) without their outputs sharing a file. Lexicons not named are built into `--output` when given, and skipped otherwise. */
+  lexiconOutput?: string[];
   /** `chant build --params-file <path>` (#1064) — a JSON file of `{ "name": value }` build-time parameter values. Second precedence, after `--param`. */
   paramsFile?: string;
   /** `chant graph --components --format ir --projection <lexicon>` (#989) — add

package/src/components/changed-files.test.ts

@@ -0,0 +1,58 @@
+/**
+ * The files a change touched (#3183), as a project in a workspace member
+ * sees them (#3465): every changed file in the repository, relative to the
+ * member's directory, so one outside it reads `../...`.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { changedFilesBetween } from "./changed-files";
+
+const repo = mkdtempSync(join(tmpdir(), "chant-changed-files-"));
+afterAll(() => rmSync(repo, { recursive: true, force: true }));
+
+const git = (...args: string[]): string =>
+  execFileSync("git", args, {
+    cwd: repo,
+    encoding: "utf8",
+    env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@example.com", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@example.com" },
+  }).trim();
+
+function put(path: string, text: string): void {
+  mkdirSync(dirname(join(repo, path)), { recursive: true });
+  writeFileSync(join(repo, path), text);
+}
+
+git("init", "-q", "-b", "main");
+put("infra/network/roots/vpc/main.tf", "");
+put("shared/modules/base/main.tf", "");
+put("apps/web/main.tf", "");
+git("add", "-A");
+git("commit", "-q", "-m", "base");
+const base = git("rev-parse", "HEAD");
+put("infra/network/roots/vpc/main.tf", "# changed\n");
+put("shared/modules/base/main.tf", "# changed\n");
+put("apps/web/main.tf", "# changed\n");
+git("add", "-A");
+git("commit", "-q", "-m", "change");
+
+describe("changedFilesBetween", () => {
+  test("at the repository root, every file by its repository path", async () => {
+    expect(await changedFilesBetween(repo, base)).toEqual([
+      "apps/web/main.tf",
+      "infra/network/roots/vpc/main.tf",
+      "shared/modules/base/main.tf",
+    ]);
+  });
+
+  test("in a member's directory, every file relative to the member, outside ones included", async () => {
+    expect(await changedFilesBetween(join(repo, "infra/network"), base)).toEqual([
+      "../../apps/web/main.tf",
+      "../../shared/modules/base/main.tf",
+      "roots/vpc/main.tf",
+    ]);
+  });
+});

package/src/components/changed-files.ts

@@ -9,6 +9,7 @@
  */
 
 import { execFile } from "node:child_process";
+import { posix } from "node:path";
 import { promisify } from "node:util";
 import type { LexiconPlugin } from "../lexicon";
 
@@ -43,12 +44,26 @@ export async function resolveCommit(cwd: string, ref: string): Promise<string> {
 }
 
 /**
- * Files changed between `base` and `head`, relative to `cwd` and limited to
- * it, with `/` separators. A rename counts as its old and its new path.
+ * Files changed between `base` and `head`, relative to `cwd`, with `/`
+ * separators. A rename counts as its old and its new path.
+ *
+ * Every changed file in the repository is listed, not only those under
+ * `cwd`: one outside it reads `../...`. A project in a workspace member
+ * (#3465) can call a module that lives in another member or beside the
+ * members, and a change there reaches it; `changedUnits` decides which of
+ * these paths matter.
  */
 export async function changedFilesBetween(cwd: string, base: string, head = "HEAD"): Promise<string[]> {
-  const out = await git(cwd, ["diff", "--name-only", "-z", "--no-renames", "--relative", base, head]);
-  return out.split("\0").filter(Boolean).sort();
+  const prefix = (await git(cwd, ["rev-parse", "--show-prefix"])).trim().replace(/\/+$/, "");
+  const out = await git(cwd, ["diff", "--name-only", "-z", "--no-renames", "--no-relative", base, head]);
+  return out
+    .split("\0")
+    .filter(Boolean)
+    .map((file) => {
+      const rel = posix.relative(prefix, file);
+      return rel === "" ? "." : rel;
+    })
+    .sort();
 }
 
 /** The union of every plugin's `changedUnits` answer, sorted. */

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

@@ -1,13 +1,16 @@
 /**
  * The attempt record keeps what steps carried per member (#3459), so the
- * next attempt, in this process or in the next CI job, hands it back.
+ * next attempt, in this process or in the next CI job, hands it back. It
+ * also keeps the change set a pull request's apply approved (#3464), so a
+ * re-run finishes it under that approval.
  */
 
 import { describe, expect, test } from "vitest";
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { readFanOutAttempt, writeFanOutAttempt } from "./fan-out-record";
+import { readFanOutAttempt, writeFanOutAttempt, type PrApplyRecord } from "./fan-out-record";
+import { composeChangeSet } from "../change-set";
 
 describe("carried", () => {
   test("round-trips through the record", () => {
@@ -25,3 +28,45 @@ describe("carried", () => {
     expect(readFanOutAttempt(join(dir, "b.json"))?.carried).toBeUndefined();
   });
 });
+
+describe("prApply (#3464)", () => {
+  const changeSet = composeChangeSet([
+    {
+      member: { member: "net", lexicon: "terraform", planner: "tofu", status: "planned", planDigest: `jcs1-sha256:${"1".repeat(64)}`, holes: [] },
+      entries: [],
+    },
+  ]);
+  const prApply: PrApplyRecord = {
+    op: "pr-12",
+    gate: "pr-apply",
+    head: "2".repeat(40),
+    digest: changeSet.digest,
+    approvedBy: ["github:alice"],
+    members: [
+      {
+        member: "net",
+        component: "net",
+        planDigest: `jcs1-sha256:${"1".repeat(64)}`,
+        status: "planned",
+        counts: { create: 0, update: 0, replace: 0, delete: 0 },
+      },
+    ],
+    changeSet,
+    planOutputs: { net: { cidr: "10.0.0.0/16" } },
+  };
+
+  test("round-trips through the record", () => {
+    const path = join(mkdtempSync(join(tmpdir(), "fan-out-record-")), "pr-apply.json");
+    writeFanOutAttempt(path, { digest: "d", completed: ["net"], failed: [], outputs: { net: { cidr: "10.0.0.0/16" } }, prApply });
+    expect(readFanOutAttempt(path)?.prApply).toEqual(prApply);
+  });
+
+  test("an entry whose change set does not carry its digest, or that misses a field, reads as none", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fan-out-record-"));
+    const base = { digest: "d", completed: [], failed: [], outputs: {} };
+    writeFileSync(join(dir, "a.json"), JSON.stringify({ ...base, prApply: { ...prApply, digest: `jcs1-sha256:${"9".repeat(64)}` } }));
+    writeFileSync(join(dir, "b.json"), JSON.stringify({ ...base, prApply: { ...prApply, head: undefined } }));
+    writeFileSync(join(dir, "c.json"), JSON.stringify({ ...base, prApply: "pr-12" }));
+    for (const name of ["a.json", "b.json", "c.json"]) expect(readFanOutAttempt(join(dir, name))?.prApply).toBeUndefined();
+  });
+});

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

@@ -30,6 +30,29 @@
 import { dirname } from "node:path";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { readWaveRecords, type WaveRecord } from "../gated-waves";
+import type { ChangeSetDocument } from "../change-set";
+import type { PrMember } from "../pr-loop";
+
+/** What a pull request's apply approved, kept so a re-run can finish it (#3464). */
+export interface PrApplyRecord {
+  /** The gate's op and name: `pr-<n>` and `pr-apply` unless the pipeline names another. */
+  op: string;
+  gate: string;
+  /** The commit the apply ran on. A record from another commit does not carry. */
+  head: string;
+  /** The change-set digest the approval stands for. */
+  digest: string;
+  approvedBy: string[];
+  /** Every member of the approved set, as planned. */
+  members: PrMember[];
+  /** The approved change-set document. Its entries are what a re-planned member is checked against. */
+  changeSet: ChangeSetDocument;
+  /**
+   * The outputs the approved plans read. The members left are planned
+   * against them again, so an unchanged member plans to the same digest.
+   */
+  planOutputs: Record<string, Record<string, unknown>>;
+}
 
 export interface FanOutAttempt {
   digest: string;
@@ -44,11 +67,39 @@ export interface FanOutAttempt {
    * root, choudoufu's wave resume file.
    */
   carried?: Record<string, unknown>;
+  /** A pull request's apply only (#3464). */
+  prApply?: PrApplyRecord;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((v) => typeof v === "string");
+
+/** The `prApply` entry, when it has every field a resume needs. Anything else reads as no entry. */
+function readPrApplyRecord(value: unknown): PrApplyRecord | undefined {
+  if (!isRecord(value)) return undefined;
+  const { op, gate, head, digest, approvedBy, members, changeSet, planOutputs } = value;
+  if (typeof op !== "string" || typeof gate !== "string" || typeof head !== "string" || typeof digest !== "string") return undefined;
+  if (!isStringArray(approvedBy) || !Array.isArray(members) || !members.every(isRecord)) return undefined;
+  if (!isRecord(changeSet) || changeSet.digest !== digest || !Array.isArray(changeSet.members) || !Array.isArray(changeSet.entries)) return undefined;
+  const outputs: Record<string, Record<string, unknown>> = {};
+  if (isRecord(planOutputs)) {
+    for (const [name, v] of Object.entries(planOutputs)) if (isRecord(v)) outputs[name] = v;
+  }
+  return {
+    op,
+    gate,
+    head,
+    digest,
+    approvedBy,
+    members: members as unknown as PrMember[],
+    changeSet: changeSet as unknown as ChangeSetDocument,
+    planOutputs: outputs,
+  };
+}
+
 /** Read an attempt record, or `undefined` when there is none yet. Throws on a file that is not JSON. */
 export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
   if (!existsSync(path)) return undefined;
@@ -58,6 +109,7 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
     for (const [name, value] of Object.entries(parsed.outputs)) if (isRecord(value)) outputs[name] = value;
   }
   const waves = readWaveRecords(parsed.waves);
+  const prApply = readPrApplyRecord(parsed.prApply);
   return {
     digest: typeof parsed.digest === "string" ? parsed.digest : "",
     completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n): n is string => typeof n === "string") : [],
@@ -65,6 +117,7 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
     outputs,
     ...(waves.length > 0 ? { waves } : {}),
     ...(isRecord(parsed.carried) && Object.keys(parsed.carried).length > 0 ? { carried: parsed.carried } : {}),
+    ...(prApply ? { prApply } : {}),
   };
 }
 

package/src/components/pr-pipeline.ts

@@ -17,9 +17,23 @@
  *   to `chant/lifecycle`, to record the pending fact when the gate stops it.
  *   One apply runs at a time per environment.
  *
+ * The apply job passes `--resume` (#3543) with a record path outside the
+ * report directory, and each forge keeps that file in its CI cache under a
+ * key that names the environment, the member and the pushed commit
+ * (`prApplyRecordKey`). A re-run of a failed apply job restores it and
+ * finishes the approved set under the same approval; the record itself is
+ * checked against the pull request's gate, the commit, the selection and
+ * the ledger before it counts (`pr-apply --resume`, #3464).
+ *
  * Measuring the push from the commit it replaced works for merge commits,
  * squash merges and rebase merges alike, and every job measures from the
  * merge base of that commit and its own head (`resolveMergeBase`).
+ *
+ * In a workspace member (#3465) both commands run in the member's directory
+ * and pass `--member <name>`, so the member's gate (`pr-<number>-<member>`),
+ * note and statuses stay apart from every other member's on the same pull
+ * request. They still measure the whole change: a file outside the member
+ * that one of its units reaches selects that unit.
  */
 
 import type { ForgeKind } from "../pr-forge";
@@ -28,6 +42,31 @@ import { PR_APPLY_GATE } from "../pr-loop";
 /** Where both jobs write their reports, kept as a CI artifact. */
 export const PR_LOOP_REPORT_DIR = ".chant/pr";
 
+/**
+ * The attempt record the apply job resumes from (#3543), relative to the
+ * directory the job runs in. It sits outside `PR_LOOP_REPORT_DIR`, so the
+ * report artifact never carries it: it holds the outputs the members read.
+ */
+export const PR_APPLY_RECORD = ".chant/pr-resume/pr-apply.json";
+
+/**
+ * The image the pull-request pipeline runs in when the caller sets none. The
+ * full `node` image has git, which both jobs measure the change with;
+ * `PR_LOOP_SETUP` adds OpenTofu on top of it. A caller who sets `image`
+ * brings both and gets no setup lines.
+ */
+export const PR_LOOP_IMAGE = "node:22";
+
+/** Installs OpenTofu into `PR_LOOP_IMAGE`. */
+export const PR_LOOP_SETUP = [
+  "command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)",
+];
+
+/** The setup lines for a pipeline running in `image`: the install when it is the default image, none otherwise. */
+export function prLoopSetup(image: string): string[] {
+  return image === PR_LOOP_IMAGE ? PR_LOOP_SETUP : [];
+}
+
 /** The `prLoop` generator option (`ComponentPipelineOptions.prLoop`). */
 export interface PrLoopPipelineOptions {
   /** The gate the apply waits on. Default `pr-apply`. */
@@ -58,12 +97,21 @@ export interface PrLoopJob {
    * variables on GitLab.
    */
   env: Record<string, string>;
+  /** Shell lines to run before the command, to settle values the forge may leave unusable. */
+  setup?: string[];
 }
 
-/** The two jobs for `forge`. */
-export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}): PrLoopJob[] {
+/**
+ * The two jobs for `forge`. `member` is the workspace member the pipeline is
+ * generated for; the commands then run in its directory, so `--output` is
+ * relative to it.
+ */
+export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}, member?: string): PrLoopJob[] {
   const gate = options.gate ?? PR_APPLY_GATE;
-  const common = ["--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge];
+  const common = [
+    "--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
+    ...(member ? ["--member", member] : []),
+  ];
   const github = forge !== "gitlab";
   const token: Record<string, string> = github ? { GITHUB_TOKEN: "${{ github.token }}" } : {};
   return [
@@ -79,13 +127,55 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       command: [
         "chant", "components", "pr-apply", "--base", '"$BASE_SHA"', ...common,
         ...(options.requireReview === false ? [] : ["--require-review"]),
+        "--resume", PR_APPLY_RECORD,
       ].join(" "),
       env: github ? { BASE_SHA: "${{ github.event.before }}", ...token } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA" },
+      ...(github ? {} : { setup: [gitlabBaseFallback(options.branch)] }),
     },
   ];
 }
 
-/** The concurrency group (GitHub, Forgejo) or resource group (GitLab) that keeps one apply at a time per environment. */
-export function prApplyGroup(env: string): string {
-  return `chant-apply-${env}`;
+/**
+ * The concurrency group (GitHub, Forgejo) or resource group (GitLab) that
+ * keeps one apply at a time per environment, and per member in a workspace.
+ *
+ * A member's group is `chant-apply.<member>.<env>`. Member names hold only
+ * lower-case letters, digits and `-`, so the first `.` ends the member and no
+ * two member and environment pairs share a group: member `a` with environment
+ * `b-c` is `chant-apply.a.b-c`, and member `a-b` with environment `c` is
+ * `chant-apply.a-b.c`. The `.` after `chant-apply` keeps a member's groups
+ * apart from a single project's `chant-apply-<env>`.
+ */
+export function prApplyGroup(env: string, member?: string): string {
+  return member ? `chant-apply.${member}.${env}` : `chant-apply-${env}`;
+}
+
+/**
+ * The cache key the apply job keeps its attempt record under (#3543), with
+ * `commit` the forge's expression for the pushed commit. A push of another
+ * commit never restores a record, and the environment and member keep each
+ * pipeline's record apart. The pull request and the gate digest are not in
+ * the key, since neither is known before the job runs; `pr-apply --resume`
+ * refuses a record made for another pull request, gate or digest.
+ */
+export function prApplyRecordKey(env: string, commit: string, member?: string): string {
+  return `${prApplyGroup(env, member)}-${commit}`;
+}
+
+/**
+ * GitLab sets `CI_COMMIT_BEFORE_SHA` to forty zeros on a branch's first push.
+ * The line replaces it with the merge request's diff base when the pipeline
+ * has one, and otherwise with the merge base of the target branch and the
+ * pushed commit, or the pushed commit's parent when that is the commit itself.
+ */
+export function gitlabBaseFallback(branch?: string): string {
+  const target = branch ? JSON.stringify(branch) : "$CI_DEFAULT_BRANCH";
+  return (
+    'if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then ' +
+    'BASE_SHA="${CI_MERGE_REQUEST_DIFF_BASE_SHA:-}"; ' +
+    'if [ -z "$BASE_SHA" ]; then ' +
+    `git fetch origin ${target} && BASE_SHA="$(git merge-base FETCH_HEAD "$CI_COMMIT_SHA")"; ` +
+    'if [ "$BASE_SHA" = "$CI_COMMIT_SHA" ]; then BASE_SHA="$(git rev-parse "$CI_COMMIT_SHA^")"; fi; ' +
+    "fi; fi; export BASE_SHA"
+  );
 }