@intentius/chant 0.124.28 → 0.124.30

package/src/components/driver.test.ts

@@ -26,6 +26,7 @@ import {
   resolveWiring,
   runComponentDeploy,
   runInterpretDriver,
+  unresolvedWiringSources,
   type DriverComponent,
   type DriverStepRecord,
   type RunProgressEvent,
@@ -1149,3 +1150,26 @@ describe("the release a deploy step sees (#3061, ws-081)", () => {
     expect(deploy.calls[0]!.ctx.release).toEqual({ revision: "r0", version: "sha256:recorded" });
   });
 });
+
+describe("unresolvedWiringSources (#4084)", () => {
+  it("names each component whose cross-component output has no value yet, sorted and once", () => {
+    const input = {
+      template: "dist/a.json",
+      inputs: {
+        topic: { stackOutput: { stack: "network", name: "TopicArn" } },
+        queue: { stackOutput: { stack: "network", name: "QueueUrl" } },
+        table: { stackOutput: { stack: "cluster-a", name: "TableName" } },
+        image: "@api-image.publish.digest",
+        local: "@Publish.digest",
+      },
+    };
+    expect(unresolvedWiringSources(input, {})).toEqual(["api-image", "cluster-a", "network"]);
+    expect(
+      unresolvedWiringSources(input, {
+        network: { TopicArn: "t", QueueUrl: "q" },
+        "cluster-a": { TableName: "x" },
+        "api-image": { publish: { digest: "sha256:1" } },
+      }),
+    ).toEqual([]);
+  });
+});

package/src/components/driver.ts

@@ -345,6 +345,42 @@ export function resolveStepInput(
   return walk(input) as Record<string, unknown>;
 }
 
+/**
+ * The components (or stacks) whose outputs `input` reads through
+ * cross-component wiring, `stackOutput()` or `@<component>.publish.*`, and
+ * which have no value for it in `componentOutputs`, sorted and each once
+ * (#4084). {@link resolveStepInput} turns each such reference into
+ * `undefined`; a plan uses this to say whose outputs it is waiting on.
+ */
+export function unresolvedWiringSources(
+  input: Record<string, unknown>,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): string[] {
+  const found = new Set<string>();
+  const walk = (value: unknown): void => {
+    if (typeof value === "string") {
+      if (PRIOR_STEP_REF.test(value)) return;
+      const ref = value.match(COMPONENT_ARTIFACT_REF);
+      if (ref && resolvePath(componentOutputs[ref[1]]?.publish, ref[2]) === undefined) found.add(ref[1]);
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach(walk);
+      return;
+    }
+    if (value && typeof value === "object") {
+      if ("stackOutput" in value) {
+        const { stack, name } = (value as { stackOutput: { stack: string; name: string } }).stackOutput;
+        if (resolvePath(componentOutputs[stack], name) === undefined) found.add(stack);
+        return;
+      }
+      Object.values(value as Record<string, unknown>).forEach(walk);
+    }
+  };
+  walk(input);
+  return [...found].sort();
+}
+
 // ── Step + phase execution ───────────────────────────────────────────────
 
 /**

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

@@ -0,0 +1,85 @@
+/**
+ * What each component would apply, as a digest (#4081), and which of an
+ * earlier attempt's progress holds against it.
+ */
+
+import { describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { componentInputDigests, progressThatCarries } from "./fan-out-inputs";
+import type { DriverComponent } from "./driver";
+
+function project(): string {
+  const root = mkdtempSync(join(tmpdir(), "fan-out-inputs-"));
+  mkdirSync(join(root, "dist"));
+  for (const name of ["net", "cluster", "app"]) writeFileSync(join(root, "dist", `${name}.json`), `{"name":"${name}"}`);
+  return root;
+}
+
+const component = (name: string, dependsOn: string[] = [], extra: Record<string, unknown> = {}): DriverComponent => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: name, template: `dist/${name}.json`, ...extra }] }],
+});
+
+const estate = [component("net"), component("cluster", ["net"]), component("app", ["cluster"])];
+
+describe("componentInputDigests", () => {
+  test("is stable for the same project, environment and files", () => {
+    const root = project();
+    expect(componentInputDigests(estate, { projectRoot: root, env: "prod" })).toEqual(
+      componentInputDigests(estate, { projectRoot: root, env: "prod" }),
+    );
+  });
+
+  test("covers the bytes of a file a step input names, and everything downstream of it", () => {
+    const root = project();
+    const before = componentInputDigests(estate, { projectRoot: root, env: "prod" });
+    writeFileSync(join(root, "dist", "cluster.json"), `{"name":"cluster","queue":true}`);
+    const after = componentInputDigests(estate, { projectRoot: root, env: "prod" });
+    expect(after.net).toBe(before.net);
+    expect(after.cluster).not.toBe(before.cluster);
+    expect(after.app).not.toBe(before.app);
+  });
+
+  test("covers a directory a step names, by its files", () => {
+    const root = project();
+    const chart = [component("chart", [], { chart: "dist" })];
+    const before = componentInputDigests(chart, { projectRoot: root, env: "prod" });
+    writeFileSync(join(root, "dist", "app.json"), "{}");
+    expect(componentInputDigests(chart, { projectRoot: root, env: "prod" }).chart).not.toBe(before.chart);
+  });
+
+  test("covers the environment and the authored steps", () => {
+    const root = project();
+    const prod = componentInputDigests(estate, { projectRoot: root, env: "prod" });
+    expect(componentInputDigests(estate, { projectRoot: root, env: "staging" }).net).not.toBe(prod.net);
+    const moved = [component("net", [], { inputs: { size: 2 } }), ...estate.slice(1)];
+    expect(componentInputDigests(moved, { projectRoot: root, env: "prod" }).net).not.toBe(prod.net);
+  });
+
+  test("ignores a string that is not a file, a path outside the project, and the phase name", () => {
+    const root = project();
+    mkdirSync(join(root, "Apply"));
+    const before = componentInputDigests(estate, { projectRoot: root, env: "prod" });
+    writeFileSync(join(root, "Apply", "x"), "changes nothing");
+    expect(componentInputDigests(estate, { projectRoot: root, env: "prod" })).toEqual(before);
+    const outside = [component("net", [], { other: "../elsewhere.json" })];
+    expect(() => componentInputDigests(outside, { projectRoot: root, env: "prod" })).not.toThrow();
+  });
+});
+
+describe("progressThatCarries", () => {
+  test("carries a component only when its recorded input is the one it has now", () => {
+    const split = progressThatCarries(
+      { completed: ["net", "cluster", "app"], inputs: { net: "a", cluster: "b" } },
+      { net: "a", cluster: "B", app: "c" },
+    );
+    expect(split).toEqual({ carried: ["net"], changed: ["app", "cluster"], unrecorded: false });
+  });
+
+  test("a record with no input digests carries nothing", () => {
+    expect(progressThatCarries({ completed: ["net"] }, { net: "a" })).toEqual({ carried: [], changed: ["net"], unrecorded: true });
+  });
+});

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

@@ -0,0 +1,192 @@
+/**
+ * What each component of a fan-out would apply, as one digest per component
+ * (#4081), and which of an earlier attempt's progress still holds against it.
+ *
+ * A fan-out's plan digest identifies the derivation: who runs, in what order,
+ * off which edges. Two different changes that touch the same components in
+ * the same shape derive the same plan, so the plan digest alone cannot say
+ * whether "cluster-a already applied" is about the change in front of us.
+ * The attempt record therefore keeps, for each component it applied, the
+ * input digest computed here, and a resumed attempt carries a component as
+ * `already-applied` only when that digest is the one the component has now.
+ *
+ * ## What a component's input digest covers
+ *
+ * - The environment. Progress against `local` says nothing about `prod`.
+ * - The composition: every phase and step as authored, `rollback` included.
+ *   A `stackOutput` reference is hashed as the reference, not its value.
+ * - The bytes of every file a step input names. A string input that resolves,
+ *   relative to the project root, to a file or directory inside the root is
+ *   read and hashed, so `template: "dist/cluster-a.template.json"` covers the
+ *   built template and a rebuild that changes it changes the digest. A
+ *   directory is hashed by its files, skipping `.git`, `node_modules` and
+ *   `.chant`, the last because the attempt record itself lives there.
+ * - The input digests of the components it depends on. A parameter filled
+ *   from an upstream output gets its value from that upstream's apply, so a
+ *   change upstream changes the digest of everything downstream of it, the
+ *   same reach the fan-out's own walk has.
+ *
+ * Nothing decided during the run goes in: no run id, no time, no output an
+ * apply produced.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import { sha256Hex } from "../content-digest";
+import type { DriverComponent, DriverPhase } from "./driver";
+
+export interface ComponentInputOptions {
+  /** The root step inputs' file paths are read relative to, the project the fan-out runs in. */
+  projectRoot: string;
+  /** The environment the fan-out applies to. */
+  env: string;
+  /** Environment config resolved ahead of the run, when the caller has any. */
+  vars?: Record<string, unknown>;
+}
+
+const SKIPPED_DIRS = new Set([".git", "node_modules", ".chant"]);
+
+/** Inside `root`, and not `root` itself: a bare "." names the whole project, which is no one step's input. */
+function insideRoot(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/** Hash a file, or a directory by the relative path and bytes of each file under it. */
+function hashPath(path: string): string | undefined {
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    return undefined;
+  }
+  if (stat.isFile()) return `sha256:${sha256Hex(readFileSync(path))}`;
+  if (!stat.isDirectory()) return undefined;
+  const files: Record<string, string> = {};
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) files[relative(path, full).split(sep).join("/")] = sha256Hex(readFileSync(full));
+    }
+  };
+  walk(path);
+  return computePlanDigest("component-input-dir", files);
+}
+
+/** Every file or directory a component's steps name, keyed by the string the step wrote. */
+function referencedFiles(component: DriverComponent, root: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const visit = (value: unknown): void => {
+    if (typeof value === "string") {
+      if (value === "" || value.includes("\n") || value in out) return;
+      const path = resolve(root, value);
+      if (!insideRoot(root, path) || !existsSync(path)) return;
+      const digest = hashPath(path);
+      if (digest !== undefined) out[value] = digest;
+      return;
+    }
+    if (Array.isArray(value)) value.forEach(visit);
+    else if (value && typeof value === "object") Object.values(value).forEach(visit);
+  };
+  // Only a step's inputs name files. A phase name or a step's `kind` that
+  // happens to match a directory in the project is not one.
+  const visitPhases = (phases: DriverPhase[] | undefined): void => {
+    for (const phase of phases ?? []) {
+      for (const step of phase.steps) {
+        if (isPhase(step)) {
+          visitPhases([step]);
+          continue;
+        }
+        if (step.kind === "gate") continue;
+        const { kind: _kind, ...inputs } = step;
+        visit(inputs);
+      }
+      visitPhases(phase.onFailure);
+    }
+  };
+  visitPhases(component.deploy);
+  visitPhases(component.rollback);
+  return out;
+}
+
+function isPhase(step: DriverPhase["steps"][number]): step is DriverPhase {
+  return typeof (step as { phase?: unknown }).phase === "string" && Array.isArray((step as DriverPhase).steps);
+}
+
+/**
+ * One input digest per component in `components`, keyed by name. Each folds
+ * in the digests of the components it depends on, so `components` should be
+ * the whole project: a dependency it does not contain is hashed by name only.
+ */
+export function componentInputDigests(
+  components: DriverComponent[],
+  options: ComponentInputOptions,
+): Record<string, string> {
+  const root = resolve(options.projectRoot);
+  const byName = new Map(components.map((c) => [c.name, c]));
+  const digests = new Map<string, string>();
+  const visiting = new Set<string>();
+
+  const digestOf = (name: string): string | null => {
+    const known = digests.get(name);
+    if (known !== undefined) return known;
+    const component = byName.get(name);
+    // An unknown dependency or a cycle is refused by the fan-out's derivation
+    // before this runs; here it only has to not loop.
+    if (!component || visiting.has(name)) return null;
+    visiting.add(name);
+    const upstream = [...(component.dependsOn ?? [])].sort().map((dep) => ({ component: dep, digest: digestOf(dep) }));
+    visiting.delete(name);
+    const digest = computePlanDigest("component-input", {
+      environment: options.env,
+      component: name,
+      deploy: component.deploy,
+      rollback: component.rollback ?? null,
+      vars: options.vars ?? null,
+      files: referencedFiles(component, root),
+      upstream,
+    });
+    digests.set(name, digest);
+    return digest;
+  };
+
+  for (const c of components) digestOf(c.name);
+  return Object.fromEntries([...digests.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/** What of an earlier attempt's progress holds against the inputs the components have now. */
+export interface CarriedProgress {
+  /** Components the attempt applied whose input is the same now. These stay `already-applied`. */
+  carried: string[];
+  /** Components the attempt applied whose input moved since. These run again. */
+  changed: string[];
+  /**
+   * True when the record has no input digests at all, as one written before
+   * #4081 has. Nothing carries from such a record, since nothing in it says
+   * what was applied.
+   */
+  unrecorded: boolean;
+}
+
+/**
+ * Split an attempt's `completed` by whether each component's input is the
+ * same as now. A component the record holds no digest for counts as changed:
+ * a claim that it applied is only worth keeping for the input it applied.
+ */
+export function progressThatCarries(
+  attempt: { completed: string[]; inputs?: Record<string, string> },
+  now: Record<string, string>,
+): CarriedProgress {
+  const recorded = attempt.inputs;
+  const carried: string[] = [];
+  const changed: string[] = [];
+  for (const name of [...attempt.completed].sort()) {
+    const then = recorded?.[name];
+    if (then !== undefined && now[name] !== undefined && then === now[name]) carried.push(name);
+    else changed.push(name);
+  }
+  return { carried, changed, unrecorded: recorded === undefined };
+}

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

@@ -70,3 +70,13 @@ describe("prApply (#3464)", () => {
     for (const name of ["a.json", "b.json", "c.json"]) expect(readFanOutAttempt(join(dir, name))?.prApply).toBeUndefined();
   });
 });
+
+describe("inputs (#4081)", () => {
+  test("round-trips, and a record without them reads as none", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fan-out-record-"));
+    writeFanOutAttempt(join(dir, "a.json"), { digest: "d", completed: ["net"], failed: [], outputs: {}, inputs: { net: "jcs1-sha256:x" } });
+    expect(readFanOutAttempt(join(dir, "a.json"))?.inputs).toEqual({ net: "jcs1-sha256:x" });
+    writeFileSync(join(dir, "b.json"), JSON.stringify({ digest: "d", completed: ["net"], failed: [], outputs: {} }));
+    expect(readFanOutAttempt(join(dir, "b.json"))?.inputs).toBeUndefined();
+  });
+});

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

@@ -25,6 +25,14 @@
  * `carried` holds what a step asked to keep for its member (#3459). It rides
  * in the record rather than beside it because the record is the one file a
  * per-wave CI job hands to the next.
+ *
+ * `inputs` holds, for each component in `completed`, the input digest it
+ * applied (#4081, ./fan-out-inputs.ts). The plan digest only identifies the
+ * derivation, and two different changes with the same shape derive the same
+ * one, so the digest alone would carry "cluster-a already applied" into a
+ * change that never applied it. A resumed attempt carries a component only
+ * when its input digest is the same now. A record written before #4081 has
+ * no `inputs`, and none of its progress carries.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -68,6 +76,11 @@ export interface FanOutAttempt {
   carried?: Record<string, unknown>;
   /** A pull request's apply only (#3464). */
   prApply?: PrApplyRecord;
+  /**
+   * The input digest each completed component applied (#4081), keyed by
+   * name. Absent on a record written before it, which then carries nothing.
+   */
+  inputs?: Record<string, string>;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -109,6 +122,11 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
   }
   const waves = readWaveRecords(parsed.waves);
   const prApply = readPrApplyRecord(parsed.prApply);
+  let inputs: Record<string, string> | undefined;
+  if (isRecord(parsed.inputs)) {
+    inputs = {};
+    for (const [name, value] of Object.entries(parsed.inputs)) if (typeof value === "string") inputs[name] = value;
+  }
   return {
     digest: typeof parsed.digest === "string" ? parsed.digest : "",
     completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n): n is string => typeof n === "string") : [],
@@ -117,6 +135,7 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
     ...(waves.length > 0 ? { waves } : {}),
     ...(isRecord(parsed.carried) && Object.keys(parsed.carried).length > 0 ? { carried: parsed.carried } : {}),
     ...(prApply ? { prApply } : {}),
+    ...(inputs ? { inputs } : {}),
   };
 }
 

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

@@ -61,6 +61,46 @@ function fanOutSink(options: FanOutRunOptions): RunEventSink | undefined {
   return joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
 }
 
+/** The 1-based wave of each component in `waves`. */
+function waveNumbers(waves: string[][]): Map<string, number> {
+  const out = new Map<string, number>();
+  waves.forEach((wave, i) => wave.forEach((name) => out.set(name, i + 1)));
+  return out;
+}
+
+/**
+ * The settles of components a fan-out does not start (#4007): `blocked`
+ * when a dependency failed or stopped at a gate, `already-applied` when an
+ * earlier attempt applied it. Each is said once, with no `component-start`
+ * before it, so a reader of the stream sees every component of the plan.
+ */
+function skipSettles(emit: RunEventSink | undefined, waveOf: Map<string, number>) {
+  const said = new Set<string>();
+  const say = (component: string, wave: number | undefined, body: { status: "blocked"; blockedBy: string } | { status: "already-applied" }): void => {
+    if (!emit || wave === undefined || said.has(component)) return;
+    said.add(component);
+    emit({ type: "component-settle", wave, component, ...body });
+  };
+  return {
+    /** Each component in `blockedBy` not yet said, in wave order then by name. */
+    blocked(blockedBy: Map<string, string>): void {
+      const order = [...blockedBy.keys()].sort((a, b) => (waveOf.get(a) ?? 0) - (waveOf.get(b) ?? 0) || a.localeCompare(b));
+      for (const component of order) say(component, waveOf.get(component), { status: "blocked", blockedBy: blockedBy.get(component)! });
+    },
+    /**
+     * What an earlier attempt left (`remainingFanOut`'s skips): the components
+     * it applied, and the ones its failures blocked. Their wave is the one
+     * they have in the derivation, `derived`, which a resumed run re-layers.
+     */
+    carried(skipped: FanOutSkip[], derived: Map<string, number>): void {
+      for (const skip of skipped) {
+        if (skip.reason === "already-applied") say(skip.component, derived.get(skip.component), { status: "already-applied" });
+        else if (skip.reason === "blocked" && skip.blockedBy) say(skip.component, derived.get(skip.component), { status: "blocked", blockedBy: skip.blockedBy });
+      }
+    },
+  };
+}
+
 /**
  * One gate per wave (#3049), each bound to its wave's set digest. The other
  * mode beside {@link FanOutGate}: that one approves the whole set once, this
@@ -220,6 +260,8 @@ export async function runFanOut(
 
   const emit = fanOutSink(options);
   emit?.({ type: "run-start", waves: active.waves });
+  const skips = skipSettles(emit, waveNumbers(active.waves));
+  skips.carried(active.skipped, waveNumbers(plan.waves));
 
   if (options.gate) {
     const gate = options.gate;
@@ -320,6 +362,8 @@ export async function runFanOut(
       wave: waveNum,
       status: waveFailed ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
     });
+    // What this wave's failures and gates hold back settles now, before the next wave starts.
+    skips.blocked(blockedBy);
   }
 
   const blocked: FanOutSkip[] = [...blockedBy.entries()]
@@ -411,6 +455,8 @@ async function runGatedWaves(
 
   const emit = fanOutSink(options);
   emit?.({ type: "run-start", waves: plan.waves });
+  const skips = skipSettles(emit, waveNumbers(plan.waves));
+  skips.carried(active.skipped, waveNumbers(plan.waves));
 
   /** What planning one wave gave. */
   interface Planned {
@@ -478,6 +524,7 @@ async function runGatedWaves(
         results.push(planFailure(f.component, f.error ?? "plan failed"));
         markBlocked(f.component);
       }
+      skips.blocked(blockedBy);
 
       const toRun = runnable.filter((name) => plansFor.has(name));
       const record: WaveRecord = {
@@ -569,6 +616,7 @@ async function runGatedWaves(
         wave: waveNum,
         status: waveFailures.length > 0 ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
       });
+      skips.blocked(blockedBy);
       return "next";
     },
   });

package/src/components/fan-out.ts

@@ -89,6 +89,10 @@ export interface FanOutRequest {
    * {@link FanOutPlan.digest} so an approval is bound to *what* would be
    * applied and not only to who would run. Absent, the digest still identifies
    * the derivation — the selection, the order and the edges it came from.
+   *
+   * `chant components fan-out` does not pass it: its approval stays bound to
+   * the derivation, and it binds a resumed attempt's progress to each
+   * component's input instead (./fan-out-inputs.ts, #4081).
    */
   inputDigests?: Record<string, string>;
   /**

package/src/components/pr-pipeline.ts

@@ -29,6 +29,19 @@
  * squash merges and rebase merges alike, and every job measures from the
  * merge base of that commit and its own head (`resolveMergeBase`).
  *
+ * With `events` (#4007) both commands pass `--events-json`, so the job log
+ * carries the run-event stream, and keep a copy of it under the report
+ * directory through `CHANT_RUN_EVENTS_DIR`, so the report artifact carries
+ * it too. With `reportUrl` both pass `--report-url`, which copies the report,
+ * the change set and the events where a reader outside CI can fetch them;
+ * the job's own environment brings the credentials an `s3://` URL needs.
+ *
+ * With `build` (#4088) both jobs run the project's build and `chant lint`
+ * before their command, and fail on an error. A `cfn-deploy` member's plan
+ * and apply read the built template, so a project with one needs it. The
+ * build is `chant build --env <env>`, or `buildCommand` when the templates
+ * come from several builds (`npm run build`).
+ *
  * 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
@@ -68,6 +81,13 @@ export function prLoopSetup(image: string): string[] {
   return image === PR_LOOP_IMAGE ? PR_LOOP_SETUP : [];
 }
 
+/**
+ * Where the jobs keep their run-event files with `events` (#4007), as
+ * `CHANT_RUN_EVENTS_DIR`: inside the report directory, so the report
+ * artifact carries them.
+ */
+export const PR_LOOP_EVENTS_DIR = `${PR_LOOP_REPORT_DIR}/run-events`;
+
 /** The `prLoop` generator option (`ComponentPipelineOptions.prLoop`). */
 export interface PrLoopPipelineOptions {
   /** The gate the apply waits on. Default `pr-apply`. */
@@ -79,6 +99,32 @@ export interface PrLoopPipelineOptions {
   branch?: string;
   /** Count an approval only from someone who approved the pull request on the forge. Default true. */
   requireReview?: boolean;
+  /**
+   * Stream each job's run events (#4007): `--events-json` on both commands,
+   * and `CHANT_RUN_EVENTS_DIR` set to {@link PR_LOOP_EVENTS_DIR}. Default false.
+   */
+  events?: boolean;
+  /**
+   * Copy each job's report, change set and events to this `s3://` or
+   * `file://` URL (#4007, `--report-url`), under `<pr>/<commit>/`. It is
+   * passed in double quotes, so it may name a variable the job expands,
+   * such as `$CHANT_REPORT_URL`.
+   */
+  reportUrl?: string;
+  /**
+   * Build and lint before `pr-plan` and before `pr-apply` (#4088): the build
+   * line, then `chant lint`, each failing the job on an error. A `cfn-deploy`
+   * member reads the built template, so a project with one sets this. The
+   * build line is `chant build --env <env>` unless `buildCommand` names
+   * another. Default false.
+   */
+  build?: boolean;
+  /**
+   * The shell line that builds the project in place of `chant build --env
+   * <env>`, for a project whose templates come from several builds, such as
+   * `npm run build`. Setting it turns `build` on.
+   */
+  buildCommand?: string;
   /**
    * Which GitHub-shaped forge the workflow is for. Set by the forgejo
    * generator, which reuses the github one; a caller never needs to.
@@ -100,6 +146,14 @@ export interface PrLoopJob {
   env: Record<string, string>;
   /** Shell lines to run before the command, to settle values the forge may leave unusable. */
   setup?: string[];
+  /** With `build` (#4088): the build line and the lint line, run in this order before the command. */
+  build?: string[];
+}
+
+/** The lines `build` (#4088) runs before a job's command: the build, then the lint. Empty without the option. */
+export function prLoopBuildLines(env: string, options: PrLoopPipelineOptions = {}): string[] {
+  if (!options.build && !options.buildCommand) return [];
+  return [options.buildCommand ?? `chant build --env ${env}`, "chant lint"];
 }
 
 /**
@@ -112,16 +166,24 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
   const common = [
     "--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
     ...(member ? ["--member", member] : []),
+    ...(options.events ? ["--events-json"] : []),
+    ...(options.reportUrl ? ["--report-url", JSON.stringify(options.reportUrl)] : []),
   ];
   const github = forge !== "gitlab";
-  const token: Record<string, string> = github ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {};
+  const buildLines = prLoopBuildLines(env, options);
+  const build = buildLines.length > 0 ? { build: buildLines } : {};
+  const jobEnv: Record<string, string> = {
+    ...(github ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {}),
+    ...(options.events ? { CHANT_RUN_EVENTS_DIR: PR_LOOP_EVENTS_DIR } : {}),
+  };
   return [
     {
       jobName: "plan",
       command: ["chant", "components", "pr-plan", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common].join(" "),
       env: github
-        ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...token }
-        : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID" },
+        ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...jobEnv }
+        : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID", ...jobEnv },
+      ...build,
     },
     {
       jobName: "apply",
@@ -130,8 +192,9 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
         ...(options.requireReview === false ? [] : ["--require-review"]),
         "--resume", PR_APPLY_RECORD,
       ].join(" "),
-      env: github ? { BASE_SHA: "${{ github.event.before }}", ...token } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA" },
+      env: github ? { BASE_SHA: "${{ github.event.before }}", ...jobEnv } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA", ...jobEnv },
       ...(github ? {} : { setup: [gitlabBaseFallback(options.branch)] }),
+      ...build,
     },
   ];
 }