@intentius/chant 0.124.34 → 0.124.35

package/src/lifecycle/release-compose.ts

@@ -0,0 +1,312 @@
+/**
+ * `chant release compose` (#4168 4.3, mode b): a release of chosen changes
+ * on a base, when trunk carries work that is not ready to ship.
+ *
+ * The changes are named by pull request (`--pr <n>`) or work item
+ * (`--work <id>`) and found on trunk's first-parent line after the base:
+ * a pull request by the merge record `_merges/<sha>.json` on
+ * `chant/lifecycle` (./merge-record.ts) or the squash subject `... (#n)`,
+ * a work item by the commit's `Chant-Record: work:<id>` trailers or a merge
+ * record that names it. Each commit is cherry-picked in trunk order onto the
+ * base, in a temporary detached worktree, with a `Chant-Composed-From: <sha>`
+ * trailer, and the result goes on the branch `chant/compose/<name>`, pushed
+ * so the forge's CI builds it (decision 6).
+ *
+ * It only appends. A branch that exists is composed onto from its tip, with
+ * the base it already has; a change it already carries is skipped. On a
+ * conflict it stops, names the change and the files, and writes nothing: a
+ * person resolves it in a pull request to the compose branch.
+ *
+ * Without `yes` it is a dry run: the picks are made in the temporary
+ * worktree, so a conflict shows now, and no ref is moved or pushed.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { COMPOSE_BRANCH_PREFIX, COMPOSED_FROM_TRAILER, compositionOnTrunk } from "./compose-refs";
+
+export type ComposeCode =
+  | "not-a-git-repository"
+  | "compose-name-invalid"
+  | "compose-nothing-chosen"
+  | "compose-base-unknown"
+  | "compose-base-differs"
+  | "compose-branch-diverged"
+  | "compose-source-unknown"
+  | "compose-conflict"
+  | "compose-push-refused";
+
+export class ComposeError extends Error {
+  constructor(
+    readonly code: ComposeCode,
+    message: string,
+    readonly fix?: string,
+    /** With `compose-conflict`: the change that did not apply and the files it conflicts in. */
+    readonly conflict?: { commit: string; subject: string; files: string[] },
+  ) {
+    super(message);
+    this.name = "ComposeError";
+  }
+}
+
+export interface ComposeRequest {
+  cwd: string;
+  name: string;
+  /** A release label or digest, or a commit. Required when the branch does not exist yet. */
+  base?: string;
+  prs: readonly number[];
+  works: readonly string[];
+  /** Move the branch and push it. Otherwise a dry run. */
+  yes: boolean;
+  /** The trunk branch, `ci.green.branch` as the cut resolves it. */
+  trunk: { remote: string; branch: string };
+  /** Push the branch to the trunk's remote with `yes`. Default true. */
+  push?: boolean;
+}
+
+/** One trunk commit a compose picks, and why. */
+export interface ComposeSource {
+  commit: string;
+  subject: string;
+  pr: number | null;
+  work: string[];
+  /** The `--pr` and `--work` values that chose it. */
+  chosenBy: string[];
+}
+
+export interface ComposeResult {
+  name: string;
+  branch: string;
+  base: string;
+  /** The branch's tip before the compose, or null when it is new. */
+  from: string | null;
+  /** The commits picked now, in trunk order. */
+  picked: ComposeSource[];
+  /** Chosen commits the branch already carries. */
+  already: ComposeSource[];
+  /** The branch's tip after the picks. Under a dry run, the tip it would have. */
+  tip: string;
+  /** Whether the branch was moved here. False under a dry run. */
+  written: boolean;
+  /** Whether it was pushed. */
+  pushed: boolean;
+}
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PR_IN_SUBJECT = /\(#(\d+)\)\s*$/;
+
+function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024, ...(env ? { env } : {}) }).trim();
+}
+
+function tryGit(cwd: string, args: string[]): string | null {
+  try {
+    return git(cwd, args);
+  } catch {
+    return null;
+  }
+}
+
+const isAncestor = (top: string, a: string, b: string): boolean => spawnSync("git", ["merge-base", "--is-ancestor", a, b], { cwd: top, stdio: "ignore" }).status === 0;
+
+/** The branch a compose name lives on. */
+export function composeBranchName(name: string): string {
+  return `${COMPOSE_BRANCH_PREFIX}${name}`;
+}
+
+async function resolveBase(top: string, cwd: string, ref: string): Promise<string> {
+  const { resolveRelease } = await import("./release-store");
+  const found = await resolveRelease(ref, { cwd }).catch(() => null);
+  if (found) return found.release.commit;
+  const sha = tryGit(top, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  if (!sha) {
+    throw new ComposeError("compose-base-unknown", `--base ${ref} names no release of this member and no commit this clone has`, "Name a release label (chant release list) or a commit, after fetching it.");
+  }
+  return sha;
+}
+
+/** The merge record of `sha`, as stored, or null. */
+async function mergeRecordOf(cwd: string, sha: string): Promise<Record<string, unknown> | null> {
+  const { readBlobFromPath } = await import("./git");
+  const text = await readBlobFromPath("_merges", `${sha}.json`, { cwd }).catch(() => null);
+  if (text === null) return null;
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The pull request and work items a merge record names. */
+function fromMergeRecord(merge: Record<string, unknown> | null): { pr: number | null; work: string[] } {
+  if (!merge) return { pr: null, work: [] };
+  const source = merge.source as { kind?: unknown; pr?: unknown; records?: unknown } | undefined;
+  const pr = source?.kind === "pull-request" && typeof source.pr === "number" ? source.pr : typeof merge.pr === "number" ? merge.pr : null;
+  const work =
+    source?.kind === "work-item" && Array.isArray(source.records)
+      ? source.records.filter((r): r is { kind: string; id: string } => !!r && typeof r === "object" && (r as { kind?: unknown }).kind === "work").map((r) => r.id)
+      : [];
+  return { pr, work };
+}
+
+/**
+ * Compose the chosen changes onto the base, on `chant/compose/<name>`.
+ * Throws {@link ComposeError} before any ref moves.
+ */
+export async function composeRelease(req: ComposeRequest): Promise<ComposeResult> {
+  const top = tryGit(req.cwd, ["rev-parse", "--show-toplevel"]);
+  if (!top) throw new ComposeError("not-a-git-repository", "a compose picks commits, and this directory is not in a git repository");
+  if (!NAME.test(req.name)) {
+    throw new ComposeError("compose-name-invalid", `"${req.name}" can't name a compose branch: use letters, digits, dots, dashes and underscores, starting with a letter or digit`);
+  }
+  if (req.prs.length === 0 && req.works.length === 0) {
+    throw new ComposeError("compose-nothing-chosen", "a compose needs the changes it carries", "Name them: --pr <n> or --work <id>, each as often as needed.");
+  }
+  const { remote } = req.trunk;
+  const branch = composeBranchName(req.name);
+  const remoteRef = `refs/remotes/${remote}/${branch}`;
+  const localRef = `refs/heads/${branch}`;
+  // The branch as the remote has it, when the remote is reachable; a new branch is absent there.
+  if (tryGit(top, ["remote", "get-url", remote]) !== null) tryGit(top, ["fetch", "--quiet", "--no-tags", remote, `+${localRef}:${remoteRef}`]);
+  const remoteTip = tryGit(top, ["rev-parse", "--verify", "--quiet", `${remoteRef}^{commit}`]);
+  const localTip = tryGit(top, ["rev-parse", "--verify", "--quiet", `${localRef}^{commit}`]);
+  if (remoteTip && localTip && !isAncestor(top, localTip, remoteTip) && !isAncestor(top, remoteTip, localTip)) {
+    throw new ComposeError(
+      "compose-branch-diverged",
+      `${branch} here and on ${remote} have diverged, and a compose only appends`,
+      `Keep the remote's: git branch -f ${branch} ${remote}/${branch}`,
+    );
+  }
+  const from = remoteTip && localTip ? (isAncestor(top, localTip, remoteTip) ? remoteTip : localTip) : (remoteTip ?? localTip);
+  const trunkRef =
+    tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${remote}/${req.trunk.branch}^{commit}`]) ??
+    tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${req.trunk.branch}^{commit}`]);
+  if (!trunkRef) throw new ComposeError("compose-source-unknown", `this clone has neither ${remote}/${req.trunk.branch} nor ${req.trunk.branch}, so there is no trunk to pick from`);
+  // What the branch carries: back to trunk, past a commit a person made on it, such as a resolved conflict.
+  const existing = from ? compositionOnTrunk(top, from, trunkRef, branch) : null;
+
+  let base: string;
+  if (from) {
+    base = existing?.base ?? from;
+    if (req.base !== undefined) {
+      const asked = await resolveBase(top, req.cwd, req.base);
+      if (asked !== base) {
+        throw new ComposeError(
+          "compose-base-differs",
+          `${branch} is composed on ${base.slice(0, 12)}, and --base names ${asked.slice(0, 12)}; a compose only appends to its branch`,
+          `Drop --base to add to ${branch}, or compose under another name.`,
+        );
+      }
+    }
+  } else {
+    if (req.base === undefined) throw new ComposeError("compose-base-unknown", `${branch} does not exist yet, so the compose needs --base`, "Name the release or commit to compose on: --base <label|sha>");
+    base = await resolveBase(top, req.cwd, req.base);
+  }
+
+  // Trunk's first-parent commits after the base, oldest first.
+  const line = (tryGit(top, ["rev-list", "--first-parent", "--reverse", trunkRef, `^${base}`]) ?? "").split("\n").filter(Boolean);
+  const { commitDetails } = await import("../workspace/intent");
+  const { recordTrailers } = await import("../workspace/release-candidates");
+  const details = commitDetails(top, line);
+
+  const chosen = new Map<string, ComposeSource>();
+  const choose = (sha: string, by: string, pr: number | null, work: string[]) => {
+    const entry = chosen.get(sha) ?? { commit: sha, subject: details.get(sha)?.subject ?? "", pr, work, chosenBy: [] };
+    if (!entry.chosenBy.includes(by)) entry.chosenBy.push(by);
+    chosen.set(sha, entry);
+  };
+  const unmatched = new Set<string>([...req.prs.map((n) => `--pr ${n}`), ...req.works.map((w) => `--work ${w}`)]);
+  for (const sha of line) {
+    const d = details.get(sha);
+    const merge = fromMergeRecord(await mergeRecordOf(req.cwd, sha));
+    const subjectPr = PR_IN_SUBJECT.exec(d?.subject ?? "");
+    const pr = merge.pr ?? (subjectPr ? Number(subjectPr[1]) : null);
+    const work = [...new Set([...recordTrailers(d?.trailers ?? {}).work, ...merge.work])];
+    for (const n of req.prs) {
+      if (pr === n) {
+        choose(sha, `--pr ${n}`, pr, work);
+        unmatched.delete(`--pr ${n}`);
+      }
+    }
+    for (const w of req.works) {
+      if (work.includes(w)) {
+        choose(sha, `--work ${w}`, pr, work);
+        unmatched.delete(`--work ${w}`);
+      }
+    }
+  }
+  if (unmatched.size > 0) {
+    throw new ComposeError(
+      "compose-source-unknown",
+      `${[...unmatched].join(", ")} names no commit on ${remote}/${req.trunk.branch} after ${base.slice(0, 12)}`,
+      "A pull request is found by its merge record or its squash subject (#n), and a work item by a Chant-Record: work:<id> trailer. Fetch trunk and chant/lifecycle if it merged elsewhere.",
+    );
+  }
+
+  // Trunk order, and what the branch already carries.
+  const carried = new Set(existing?.sources ?? []);
+  const ordered = line.filter((sha) => chosen.has(sha)).map((sha) => chosen.get(sha)!);
+  const already = ordered.filter((s) => carried.has(s.commit));
+  const picked = ordered.filter((s) => !carried.has(s.commit));
+
+  const tip = picked.length === 0 ? (from ?? base) : pickOnto(top, from ?? base, picked);
+  let written = false;
+  let pushed = false;
+  if (req.yes && picked.length > 0) {
+    git(top, ["update-ref", "-m", `chant release compose ${req.name}`, localRef, tip, localTip ?? ""]);
+    written = true;
+  }
+  if (req.yes && (req.push ?? true) && tryGit(top, ["remote", "get-url", remote]) !== null && tip !== remoteTip) {
+    try {
+      git(top, ["push", "--quiet", remote, `${tip}:${localRef}`]);
+      tryGit(top, ["update-ref", remoteRef, tip]);
+      pushed = true;
+    } catch (err) {
+      const stderr = (err as { stderr?: Buffer | string }).stderr?.toString().trim() ?? String(err);
+      throw new ComposeError("compose-push-refused", `${branch} was composed here at ${tip.slice(0, 12)} and ${remote} refused the push: ${stderr}`, `Push it by hand once the remote allows it: git push ${remote} ${branch}`);
+    }
+  }
+  return { name: req.name, branch, base, from, picked, already, tip, written, pushed };
+}
+
+/**
+ * Cherry-pick `sources` in order onto `start` in a temporary detached
+ * worktree, each with its trailer, and return the last commit. Throws
+ * `compose-conflict` naming the change and its files when one does not
+ * apply. The worktree is removed either way.
+ */
+function pickOnto(top: string, start: string, sources: readonly ComposeSource[]): string {
+  const realTop = realpathSync(top);
+  const dir = mkdtempSync(join(tmpdir(), "chant-compose-"));
+  git(realTop, ["worktree", "add", "--detach", "--quiet", dir, start]);
+  try {
+    for (const s of sources) {
+      const parents = (tryGit(dir, ["rev-list", "--parents", "-n", "1", s.commit]) ?? "").split(" ").length - 1;
+      const args = ["cherry-pick", "--allow-empty", "--keep-redundant-commits", ...(parents > 1 ? ["-m", "1"] : []), s.commit];
+      const run = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+      if (run.status !== 0) {
+        const files = (tryGit(dir, ["diff", "--name-only", "--diff-filter=U"]) ?? "").split("\n").filter(Boolean);
+        tryGit(dir, ["cherry-pick", "--abort"]);
+        const what = [s.pr !== null ? `#${s.pr}` : null, ...s.work.map((w) => `work:${w}`)].filter(Boolean).join(", ");
+        throw new ComposeError(
+          "compose-conflict",
+          `${s.commit.slice(0, 12)} (${s.subject}${what ? `; ${what}` : ""}) does not apply on the composed commits${files.length > 0 ? `: it conflicts in ${files.join(", ")}` : `: ${(run.stderr || run.stdout).trim()}`}. Nothing was written`,
+          "Resolve it by hand in a pull request to the compose branch, or compose without that change.",
+          { commit: s.commit, subject: s.subject, files },
+        );
+      }
+      git(dir, ["commit", "--quiet", "--amend", "--no-edit", "--allow-empty", "--no-verify", "--trailer", `${COMPOSED_FROM_TRAILER}: ${s.commit}`]);
+    }
+    return git(dir, ["rev-parse", "HEAD"]);
+  } finally {
+    try {
+      git(realTop, ["worktree", "remove", "--force", dir]);
+    } catch {
+      rmSync(dir, { recursive: true, force: true });
+      tryGit(realTop, ["worktree", "prune"]);
+    }
+  }
+}

package/src/lifecycle/release-cut.ts

@@ -102,6 +102,10 @@ export interface CutRequest {
    * must be the principal the signers file lists the key for.
    */
   sign?: string | true;
+  /** The composition of a composed commit (#4168 4.3), recorded on the cut. */
+  composed?: { branch: string; base: string; sources: string[] };
+  /** The publish channel recorded on the cut (#4168 4.3), in place of `latest`. */
+  channel?: string;
 }
 
 export interface CutResult {
@@ -501,6 +505,8 @@ export async function cutRelease(req: CutRequest): Promise<CutResult> {
       runId: ci?.runId ?? `local-${Date.parse(timestamp)}`,
       runOrigin: ci?.runOrigin ?? { forge: "local" },
       signature,
+      ...(req.composed ? { composed: req.composed } : {}),
+      ...(req.channel ? { channel: req.channel } : {}),
     },
     { cwd },
   );

package/src/lifecycle/release-publish.ts

@@ -278,6 +278,8 @@ export interface PublishPlan {
   redactor: Redactor;
   /** Whether a target with no SBOM source is refused (`publish-sbom-missing`): the workspace opts into `supply-chain` (#4168). Otherwise it publishes without one. */
   requireSbom: boolean;
+  /** The channel a cut of the release names (#4168 4.3), the tag moved in place of `latest`, or null. */
+  channel: string | null;
 }
 
 /**
@@ -399,7 +401,8 @@ export async function preparePublish(req: {
   const member = ledger.members.length > 0 ? ledger.members.join("/") : null;
   const releaseTag = label !== null ? releaseTagName(member, label) : null;
   const redactor = createRedactor(env, targets.flatMap((t) => t.credentialEnv));
-  return { release, label, signature, provenance, warning, signatureWarning, cut, releaseTag, targets, redactor, requireSbom: groups.has("supply-chain") };
+  const channel = [...cuts].reverse().find((c) => c.channel)?.channel ?? null;
+  return { release, label, signature, provenance, warning, signatureWarning, cut, releaseTag, targets, redactor, requireSbom: groups.has("supply-chain"), channel };
 }
 
 /**

package/src/lifecycle/release-store.ts

@@ -149,6 +149,17 @@ export interface ReleaseCut {
    * unsigned cut, and on every cut written before 0.124.28.
    */
   signature: string | null;
+  /**
+   * A cut of a composed commit (#4168 4.3): its compose branch, the base it
+   * was composed on, and the trunk commits picked onto the base, oldest
+   * first. Absent on a cut of a trunk commit.
+   */
+  composed?: { branch: string; base: string; sources: string[] };
+  /**
+   * The channel the release publishes to (#4168 4.3): the npm dist-tag or
+   * image tag a publish moves in place of `latest`. Absent for `latest`.
+   */
+  channel?: string;
 }
 
 /** The parts of a release a digest is computed from. */
@@ -364,7 +375,9 @@ export function parseCuts(text: string | null): { cuts: ReleaseCut[]; malformed:
         typeof c.timestamp === "string" &&
         (c.runOrigin === null || (typeof c.runOrigin === "object" && typeof c.runOrigin?.forge === "string")) &&
         (c.signature === null || c.signature === undefined || typeof c.signature === "string") &&
-        (c.runId === null || c.runId === undefined || typeof c.runId === "string");
+        (c.runId === null || c.runId === undefined || typeof c.runId === "string") &&
+        (c.channel === undefined || typeof c.channel === "string") &&
+        (c.composed === undefined || (typeof c.composed === "object" && c.composed !== null && typeof c.composed.base === "string" && Array.isArray(c.composed.sources)));
       if (!ok) {
         malformed++;
         continue;
@@ -444,6 +457,8 @@ export async function appendCut(
       runId: input.runId ?? null,
       runOrigin: input.runOrigin,
       signature: input.signature ?? null,
+      ...(input.composed ? { composed: input.composed } : {}),
+      ...(input.channel ? { channel: input.channel } : {}),
     };
     const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${JSON.stringify(cut, sortedJsonReplacer)}\n`;
     try {

package/src/workspace/checks/ci-workflow.test.ts

@@ -47,6 +47,8 @@ const PIPELINE = [
   "      - run: chant ci run record --in-place --env prod --gate pr-apply --forge github",
   "",
 ].join("\n");
+/** #4168 step 9: under apply on merge a merge is recorded, and the apply applies the newest green commit, with no push base. */
+const APPLY_PIPELINE = `${PIPELINE}  apply:\n    steps:\n      - run: chant ci run apply --in-place --env prod --gate pr-apply --forge github\n`;
 const TICK = "jobs:\n  tick:\n    steps:\n      - run: npx --yes @intentius/chant@0.124.33 ci tick\n";
 const PUBLISH = "jobs:\n  publish:\n    steps:\n      - run: npx chant release publish \"$LABEL\"\n";
 
@@ -100,14 +102,22 @@ describe("ci.workflow (WSP151)", () => {
   });
 
   test("trunk-curated with an apply job on merge differs", async () => {
-    const root = repo(complete({ ".github/workflows/chant-pr.yml": PIPELINE.replace("ci run record", "ci run apply") }));
+    const root = repo(complete({ ".github/workflows/chant-pr.yml": APPLY_PIPELINE }));
     expect(await found(root)).toEqual([["ci-workflow-pipeline-differs", null]]);
   });
 
   test("trunk-curated+apply-on-merge with only a record job differs, and with an apply job passes", async () => {
     const decl = declaration({ ci: { workflow: "trunk-curated+apply-on-merge", green: green() } });
     expect(await found(repo(complete({ "chant.workspace.json": decl })))).toEqual([["ci-workflow-pipeline-differs", null]]);
-    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": PIPELINE.replace("ci run record", "ci run apply") })))).toEqual([]);
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": APPLY_PIPELINE })))).toEqual([]);
+  });
+
+  test("trunk-curated+apply-on-merge: an apply of each merge differs, and a pipeline with no record job is missing it (#4168 step 9)", async () => {
+    const decl = declaration({ ci: { workflow: "trunk-curated+apply-on-merge", green: green() } });
+    const perMerge = APPLY_PIPELINE.replace("ci run apply --in-place", 'ci run apply --in-place --base "$BASE_SHA"');
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": perMerge })))).toEqual([["ci-workflow-pipeline-differs", null]]);
+    const noRecord = PIPELINE.replace("ci run record", "ci run apply");
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": noRecord })))).toEqual([["ci-workflow-pipeline-missing", null]]);
   });
 
   test("a member's own workflow wins, and a top-level workflow skips members that don't build with chant", async () => {

package/src/workspace/checks/ci-workflow.ts

@@ -106,7 +106,8 @@ export const CI_WORKFLOW_CHECKS: readonly WorkspaceCheck[] = [
       const applyOnMerge = under.some((u) => appliesOnMerge(u.workflow)) || (d.ci?.workflow ? appliesOnMerge(d.ci.workflow) : false);
       const missing = [
         ...(has(PLAN) ? [] : ["a plan job (ci run plan)"]),
-        ...(has(RECORD) || has(APPLY) ? [] : [applyOnMerge ? "an apply job (ci run apply)" : "a record job (ci run record)"]),
+        // #4168 step 9: every merge is recorded, apply on merge or not, since the apply reads the merge records.
+        ...(has(RECORD) ? [] : ["a record job (ci run record)"]),
         ...(has(TICK) ? [] : ["chant ci tick"]),
       ];
       if (missing.length > 0) {
@@ -119,6 +120,11 @@ export const CI_WORKFLOW_CHECKS: readonly WorkspaceCheck[] = [
       } else if (!has(APPLY) && has(RECORD)) {
         const l = commandLines(ctx, RECORD)[0]!;
         finding("ci-workflow-pipeline-differs", `${l.path} records on merge, and the workflow is trunk-curated+apply-on-merge; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
+      } else {
+        // #4168 step 9: an apply measured from a push's base applies each merge; the workflow applies green commits.
+        for (const l of commandLines(ctx, APPLY).filter((c) => /--base\b/.test(c.text) || (/\bcomponents\s+pr-apply\b/.test(c.text) && !/--green\b/.test(c.text)))) {
+          finding("ci-workflow-pipeline-differs", `${l.path} applies each merge, and under trunk-curated+apply-on-merge the apply applies the newest green commit; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
+        }
       }
       if (!has(PUBLISH)) {
         finding("ci-workflow-publish-missing", "no pipeline file runs chant release publish, so a cut release is never published; generate one with chant release workflow");

package/src/workspace/ci-green-cli.ts

@@ -154,7 +154,9 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     const sources = readWorkflowSources(repoRoot, fromRepo);
     const scan = workflowsHolding(green, sources);
     // #4169: the triggers and concurrency of the workflows holding a phase that sets build. Refused before anything is written.
-    const edits = buildTriggerEdits(green, sources);
+    // #4220: under a ci.workflow, composed releases' branches run the phases and tick too.
+    const compose = declaration.ci?.workflow !== undefined || declaration.members.some((m) => m.ciWorkflow !== null);
+    const edits = buildTriggerEdits(green, sources, { compose });
     const extra = ctx.args.ciWorkflows ?? [];
     const workflows = [...new Set([...scan.workflows, ...extra])].sort();
     for (const f of scan.unreadable) console.error(`warning: ${f} is not valid YAML, so its jobs were not read`);
@@ -180,10 +182,10 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
     // The install runs in the workspace root, so its lockfile there keys setup-node's npm cache.
     const npmLock = ctx.args.ciInstall && existsSync(join(root, "package-lock.json")) ? (workspaceRoot === "." ? "package-lock.json" : `${workspaceRoot}/package-lock.json`) : undefined;
-    const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push, ...(runnerKeySecret ? { runnerKeySecret } : {}) });
+    const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push, ...(runnerKeySecret ? { runnerKeySecret } : {}), ...(compose ? { compose } : {}) });
     const written = writeWorkflowFile(target, ciGreenHeader(command, member ? "member" : "root") + yaml);
     if (member) recordGeneratedFiles(member.memberRoot, [{ path: fromRepo, command }]);
-    console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}, and every 15 minutes.`);
+    console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}${compose ? " or a chant/compose/ branch" : ""}, and every 15 minutes.`);
     for (const e of edits) {
       if (!e.changed) continue;
       const path = writeWorkflowFile(join(repoRoot, e.path), e.text);

package/src/workspace/ci-green-workflow.test.ts

@@ -381,6 +381,58 @@ describe("the triggers of a phase that sets build (#4169)", () => {
     expect(before.on.workflow_run.branches).toEqual(["main"]);
   });
 
+  test("under a ci.workflow, both builds run on chant/compose/** pushes, a compose branch's every runs are keyed by commit, and the tick ticks on them (#4220)", () => {
+    const sources = [
+      { path: ".github/workflows/ci.yml", text: LINT_WF },
+      { path: ".github/workflows/suites.yml", text: SUITES_WF },
+    ];
+    const edits = buildTriggerEdits(green(), sources, { compose: true });
+    const ci = parseYAMLDocument(edits[0].text) as Yaml;
+    expect(ci.on).toEqual({ push: { branches: ["main", "chant/compose/**"] }, pull_request: null });
+    expect(ci.concurrency).toEqual({
+      group: "chant-build-lint-${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/chant/compose/')) && github.sha || github.ref }}",
+      "cancel-in-progress": "${{ !(github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/chant/compose/')) }}",
+    });
+    const suites = parseYAMLDocument(edits[1].text) as Yaml;
+    expect(suites.on).toEqual({ push: { branches: ["main", "chant/compose/**"] }, workflow_dispatch: {} });
+    // Writing again changes nothing.
+    expect(buildTriggerEdits(green(), edits.map((e) => ({ path: e.path, text: e.text })), { compose: true }).map((e) => e.changed)).toEqual([false, false]);
+    // A push with no branch list already runs on every branch, so its triggers stay.
+    const anyBranch = LINT_WF.replace("  push:\n    branches: [main]\n", "  push:\n");
+    expect((parseYAMLDocument(buildTriggerEdits(green(), [{ path: ".github/workflows/ci.yml", text: anyBranch }], { compose: true })[0].text) as Yaml).on).toEqual({ push: null, pull_request: null });
+    // Without compose the bytes are what #4169 wrote.
+    expect(buildTriggerEdits(green(), sources).map((e) => e.text)).toEqual(buildTriggerEdits(green(), sources, { compose: false }).map((e) => e.text));
+    const tick = parseYAMLDocument(renderCiGreenWorkflow({ green: green(), workflows: ["ci"], chantVersion: "0.124.33", workspaceRoot: ".", compose: true })) as Yaml;
+    expect(tick.on.workflow_run.branches).toEqual(["main", "ci/build/**", "chant/compose/**"]);
+  });
+
+  test("chant ci workflow writes the compose triggers only when the declaration names a ci.workflow (#4220)", async () => {
+    const run = async (ci: Record<string, unknown>) => {
+      const root = scratchDir();
+      git(root, "init", "-q");
+      writeFiles(root, {
+        "chant.workspace.json": declaration([{ name: "root", dir: ".", kind: "other", because: "x" }], { ci }),
+        ".github/workflows/ci.yml": LINT_WF,
+      });
+      const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+      const log = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        expect(await runCiWorkflow({ args: {} } as unknown as CommandContext)).toBe(0);
+        return { tick: readFileSync(join(root, CI_GREEN_WORKFLOW_FILE), "utf-8"), ci: readFileSync(join(root, ".github/workflows/ci.yml"), "utf-8") };
+      } finally {
+        cwd.mockRestore();
+        log.mockRestore();
+      }
+    };
+    const lint = { branch: "main", phases: { lint: { runs: ["lint"], build: "every" } }, require: ["lint"] };
+    const without = await run({ green: lint });
+    expect(without.tick).not.toContain("chant/compose");
+    expect(without.ci).not.toContain("chant/compose");
+    const curated = await run({ green: lint, workflow: "trunk-curated" });
+    expect(curated.tick).toContain("chant/compose/**");
+    expect(curated.ci).toContain("chant/compose/**");
+  });
+
   test("the workflows a build request can start are the ones holding its phases with workflow_dispatch", () => {
     expect(dispatchableWorkflows(green(), ["lint", "suites"], [{ path: ".github/workflows/ci.yml", text: LINT_WF }, { path: ".github/workflows/suites.yml", text: SUITES_WF }])).toEqual({ dispatchable: ["suites.yml"], without: ["ci.yml"] });
   });

package/src/workspace/ci-green-workflow.ts

@@ -52,6 +52,7 @@ import { emitYAMLEntry, parseYAMLDocument } from "../yaml";
 import type { CiBuild, CiGreen } from "./declaration";
 import { matchesCheckRun } from "./ci-green";
 import { githubSecretOrJobToken } from "../ci-jobs";
+import { COMPOSE_BRANCH_PREFIX } from "../lifecycle/compose-refs";
 
 /** Where the workflow goes, relative to the repository root. */
 export const CI_GREEN_WORKFLOW_FILE = ".github/workflows/chant-ci-green.yml";
@@ -194,8 +195,17 @@ export interface WorkflowInput {
    * The key's principal needs the `runner` role in `.chant/trust.json`.
    */
   runnerKeySecret?: string;
+  /**
+   * The workspace declares a `ci.workflow` (#4220), so composed releases
+   * live on `chant/compose/<name>` branches (#4168 4.3): the tick also runs
+   * when a phase workflow completes on one of them.
+   */
+  compose?: boolean;
 }
 
+/** The branch filter for composed releases' branches (#4220). */
+export const COMPOSE_BRANCHES = `${COMPOSE_BRANCH_PREFIX}**`;
+
 /**
  * A token the checkout persists for the tick's `git push`: a repository
  * secret, or a GitHub App's installation token minted from its id (an
@@ -240,6 +250,8 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
     `      - ${q(green.branch)}`,
     // #4169: a build the tick asked for runs at a ci/build/<sha> tag, and its completion ticks too.
     ...(newestPhases(green) ? [`      - ${q("ci/build/**")}`] : []),
+    // #4220: a composed commit's phases run on its chant/compose/<name> branch, and their completion ticks too.
+    ...(input.compose ? [`      - ${q(COMPOSE_BRANCHES)}`] : []),
     "  schedule:",
     "    - cron: \"*/15 * * * *\"",
     "  workflow_dispatch: {}",
@@ -319,12 +331,19 @@ export interface BuildTriggerEdit {
  *   branch, so no push cancels or replaces another's run; elsewhere, such as
  *   a pull request, a new push cancels the run it supersedes.
  *
- * Only the top-level `on:` (for `newest`) and `concurrency:` blocks change,
+ * With `compose` (#4220, a workspace declaring `ci.workflow`), both builds
+ * also run on pushes to `chant/compose/**`: `newest` adds the filter to the
+ * branches it writes, `every` adds it to an existing `push.branches` list,
+ * and `every`'s group keys a compose branch's runs by commit, as the trunk
+ * branch's.
+ *
+ * Only the top-level `on:` (for `newest`, or `every` with `compose`) and `concurrency:` blocks change,
  * each under {@link BUILD_BLOCK_MARKER}; the rest of the file is kept as it
  * is. Throws when one workflow holds a phase of each build, which no one
  * concurrency group can serve.
  */
-export function buildTriggerEdits(green: CiGreen, sources: readonly WorkflowSource[]): BuildTriggerEdit[] {
+export function buildTriggerEdits(green: CiGreen, sources: readonly WorkflowSource[], options: { compose?: boolean } = {}): BuildTriggerEdit[] {
+  const compose = options.compose === true;
   const out: BuildTriggerEdit[] = [];
   for (const s of sources) {
     let doc: unknown;
@@ -349,17 +368,27 @@ export function buildTriggerEdits(green: CiGreen, sources: readonly WorkflowSour
       delete on.schedule;
       const push = isObject(on.push) ? { ...on.push } : {};
       const branches = Array.isArray(push.branches) ? push.branches.filter((b): b is string => typeof b === "string") : [];
-      push.branches = branches.includes(green.branch) ? branches : [...branches, green.branch];
+      const withBranch = branches.includes(green.branch) ? branches : [...branches, green.branch];
+      push.branches = compose && !withBranch.includes(COMPOSE_BRANCHES) ? [...withBranch, COMPOSE_BRANCHES] : withBranch;
       const { push: _push, workflow_dispatch: dispatch, ...rest } = on;
       text = writeTopLevel(text, "on", { push, workflow_dispatch: dispatch ?? {}, ...rest });
       text = writeTopLevel(text, "concurrency", { group: `chant-build-${tag}-\${{ github.ref }}`, "cancel-in-progress": false });
     } else {
       const main = `refs/heads/${green.branch}`;
+      // A push filter that lists branches gains the compose branches; one with no list already runs on every branch.
+      const on = isObject(doc) && isObject(doc.on) ? doc.on : undefined;
+      const pushOn = on && isObject(on.push) ? on.push : undefined;
+      if (compose && on && pushOn && Array.isArray(pushOn.branches) && !pushOn.branches.includes(COMPOSE_BRANCHES)) {
+        text = writeTopLevel(text, "on", { ...on, push: { ...pushOn, branches: [...pushOn.branches, COMPOSE_BRANCHES] } });
+      }
+      // #4220: a compose branch's commits each get a verdict, so its runs are keyed by commit, as the trunk branch's are.
+      const keyed = compose ? `(github.ref == '${main}' || startsWith(github.ref, 'refs/heads/${COMPOSE_BRANCH_PREFIX}'))` : `github.ref == '${main}'`;
+      const unkeyed = compose ? `!${keyed}` : `github.ref != '${main}'`;
       // Written as lines: the emitter would quote the expression, and GitHub reads it the same either way.
       text = writeTopLevel(text, "concurrency", [
         "concurrency:",
-        `  group: chant-build-${tag}-\${{ github.ref == '${main}' && github.sha || github.ref }}`,
-        `  cancel-in-progress: \${{ github.ref != '${main}' }}`,
+        `  group: chant-build-${tag}-\${{ ${keyed} && github.sha || github.ref }}`,
+        `  cancel-in-progress: \${{ ${unkeyed} }}`,
       ]);
     }
     out.push({ path: s.path, build, phases, text, changed: text !== s.text });