@intentius/chant 0.124.33 → 0.124.35

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

@@ -0,0 +1,135 @@
+/**
+ * WSP151 (#4168 step 6): what a member under `ci.workflow` still lacks.
+ *
+ * A declaration that names no workflow gets no finding from this file. The
+ * requirements and their codes are {@link CI_WORKFLOW_REQUIREMENTS}
+ * (../ci-workflow.ts). Like the security checklists (./security.ts), the
+ * check reads files and never runs them: `chant.config.ts` for the
+ * environments (its literal `environments`, as `workspace status` reads it),
+ * `*.component.ts` for components and gates, and the forge pipeline files for
+ * the jobs. A generated file that differs from what its generator writes is
+ * WSP101 to WSP106's to report; this check asks only whether the jobs the
+ * workflow needs are there.
+ */
+
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+import type { CiWorkflow, Member } from "../declaration";
+import { appliesOnMerge, STUB_MARKER, workflowOf, type CiWorkflowCode } from "../ci-workflow";
+import { matchesCheckRun } from "../ci-green";
+import { staticPromotionOrder } from "../promotion-order";
+import { joinPath } from "../tree";
+import { allPipelineFiles, commandLines, componentFiles, read } from "./security";
+
+export const WSP_CI_WORKFLOW = "WSP151";
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+const PLAN = /\bci\s+run\s+plan\b|\bcomponents\s+pr-plan\b/;
+const RECORD = /\bci\s+run\s+record\b|\bcomponents\s+pr-record\b/;
+const APPLY = /\bci\s+run\s+apply\b|\bcomponents\s+pr-apply\b/;
+const TICK = /\bci\s+tick\b/;
+const PUBLISH = /\brelease\s+publish\b/;
+
+/** The apply job names a required phase could match. */
+const APPLY_JOB_NAMES = ["apply", "pr-apply"];
+
+export const CI_WORKFLOW_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_CI_WORKFLOW,
+    name: "ci-workflow",
+    description: "Under ci.workflow: ci.green with pre-merge phases and no apply job required, each member with a component, environments and a gate on each component, and pipeline files that plan, record (or apply under apply on merge), tick and publish.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      const d = ctx.declaration;
+      const under = d.members
+        .map((m) => ({ member: m, workflow: workflowOf(d, m) }))
+        .filter((u): u is { member: Member; workflow: CiWorkflow } => u.workflow !== null)
+        // The top level's workflow covers the members that build with chant; a member that names one itself is held to it.
+        .filter((u) => u.member.ciWorkflow !== null || ctx.tree.stat(joinPath(memberDir(u.member.dir), "chant.config.ts")) === "file");
+      if (under.length === 0 && !d.ci?.workflow) return [];
+      const pointer = d.ci?.workflow ? "/ci/workflow" : `${under[0]!.member.pointer}/ci/workflow`;
+      const out: WorkspaceDiagnostic[] = [];
+      const finding = (code: CiWorkflowCode, message: string, at: { pointer?: string; entity?: string; treeFile?: string; line?: number } = {}): void => {
+        out.push({
+          checkId: this.id,
+          severity: this.severity,
+          code,
+          message: `${code}: ${message}`,
+          pointer: at.pointer ?? pointer,
+          ...(at.entity !== undefined ? { entity: at.entity } : {}),
+          ...(at.treeFile !== undefined ? { treeFile: at.treeFile, line: at.line ?? 1, column: 1 } : {}),
+        });
+      };
+
+      const green = d.ci?.green ?? null;
+      if (!green) {
+        finding("ci-workflow-green-undeclared", "the workspace follows a ci.workflow and declares no ci.green, so no commit gets a verdict and no release can be cut; run chant ci init or add a ci.green block");
+      } else {
+        if ((green.preMerge ?? []).length === 0) {
+          finding("ci-workflow-no-pre-merge", "ci.green.preMerge names no phase, so nothing says which checks run before the branch moves; name the quick ones", { pointer: green.pointer });
+        }
+        for (const name of green.require) {
+          const phase = green.phases.find((p) => p.name === name);
+          const hit = phase?.runs.find((pattern) => APPLY_JOB_NAMES.some((job) => matchesCheckRun(pattern, job)));
+          if (phase && hit) {
+            finding("ci-workflow-apply-in-green", `the required phase ${name} matches the apply job with ${JSON.stringify(hit)}, so an apply that waits for a green commit would wait on itself; drop the pattern`, { pointer: phase.pointer });
+          }
+        }
+      }
+
+      for (const { member } of under) {
+        const dir = memberDir(member.dir);
+        const components = componentFiles(ctx.tree, dir);
+        if (components.length === 0) {
+          finding("ci-workflow-no-components", `member ${member.name} declares no component, so nothing of it can be cut or promoted; chant ci init writes a stub`, { pointer: member.pointer, entity: member.name });
+        } else if (components.every((f) => (read(ctx.tree, f) ?? "").includes(STUB_MARKER))) {
+          finding("ci-workflow-no-components", `member ${member.name}'s only component is the stub chant ci init wrote (${components[0]}); say how it is built and deployed, then delete its ${STUB_MARKER} line`, { pointer: member.pointer, entity: member.name, treeFile: components[0] });
+        }
+        const configPath = joinPath(dir, "chant.config.ts");
+        const config = read(ctx.tree, configPath);
+        // A config whose environments aren't literals can't be read without running it; say nothing rather than guess.
+        const order = config === null ? [] : staticPromotionOrder(config);
+        if (order !== undefined && order.length === 0) {
+          finding("ci-workflow-no-environments", `member ${member.name}'s chant.config.ts declares no environments, so a release has nowhere to be promoted to`, { pointer: member.pointer, entity: member.name, ...(config !== null ? { treeFile: configPath } : {}) });
+        }
+        for (const file of components) {
+          const text = read(ctx.tree, file) ?? "";
+          if (/\bgate\s*\(|kind\s*:\s*["']gate["']/.test(text)) continue;
+          const last = order && order.length > 0 ? order[order.length - 1]!.name : "the last environment";
+          finding("ci-workflow-ungated-env", `${file} has no gate, so a promote to ${last} waits on no approval; add a gate() step`, { pointer: member.pointer, entity: member.name, treeFile: file });
+        }
+      }
+
+      const files = allPipelineFiles(ctx);
+      const has = (re: RegExp) => files.some((f) => f.lines.some((l) => re.test(l)));
+      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)"]),
+        // #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) {
+        finding("ci-workflow-pipeline-missing", `no pipeline file runs ${missing.join(", ")}; generate them with chant build --components --generate <forge> --pr-loop and chant ci workflow`);
+      }
+      if (!applyOnMerge) {
+        for (const l of commandLines(ctx, APPLY)) {
+          finding("ci-workflow-pipeline-differs", `${l.path} applies on merge, and the workflow is trunk-curated, where a merge records the plan and deploys nothing; regenerate without --apply-on-merge, or set ci.workflow to trunk-curated+apply-on-merge`, { treeFile: l.path, line: l.line });
+        }
+      } 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");
+      }
+      return out;
+    },
+  },
+];

package/src/workspace/checks/security.ts

@@ -83,7 +83,7 @@ function groupPointer(declaration: Declaration, group: SecurityGroup): string {
   return m ? `${m.pointer}/security/${m.security.indexOf(group)}` : "/security";
 }
 
-function read(tree: WorkspaceTree, path: string): string | null {
+export function read(tree: WorkspaceTree, path: string): string | null {
   if (tree.stat(path) !== "file") return null;
   try {
     return tree.read(path);
@@ -109,18 +109,18 @@ function pipelineFiles(tree: WorkspaceTree, dir: string): { path: string; lines:
 }
 
 /** Every pipeline file of the workspace: its root's, and each member's. */
-function allPipelineFiles(ctx: WorkspaceCheckContext): { path: string; lines: string[] }[] {
+export function allPipelineFiles(ctx: WorkspaceCheckContext): { path: string; lines: string[] }[] {
   const dirs = new Set(["", ...ctx.declaration.members.map((m) => memberDir(m.dir))]);
   return [...dirs].flatMap((d) => pipelineFiles(ctx.tree, d));
 }
 
 /** The lines of the pipeline files that run a chant command, `command` naming it, such as `release publish`. */
-function commandLines(ctx: WorkspaceCheckContext, command: RegExp): { path: string; line: number; text: string }[] {
+export function commandLines(ctx: WorkspaceCheckContext, command: RegExp): { path: string; line: number; text: string }[] {
   return allPipelineFiles(ctx).flatMap((f) => f.lines.flatMap((text, i) => (command.test(text) ? [{ path: f.path, line: i + 1, text }] : [])));
 }
 
 /** The member's `*.component.ts` files, walked a few levels down, past node_modules and build output. */
-function componentFiles(tree: WorkspaceTree, dir: string, depth = 4): string[] {
+export function componentFiles(tree: WorkspaceTree, dir: string, depth = 4): string[] {
   const out: string[] = [];
   for (const e of tree.list(dir) ?? []) {
     if (e.type === "dir") {

package/src/workspace/checks.ts

@@ -37,7 +37,7 @@
  * | WSP126, WSP127 | box intent: the decision record a box names exists, and constrains a member or path of this workspace (#2850, #2857) |
  * | WSP141, WSP142 | member links resolved against a live read, with `--live` (#2549) |
  * | WSP131 to WSP133 | diagram artifacts: source and render exist, a recorded source hash still matches (#2764) |
- * | WSP151 | reserved for the `ci.workflow` preset (#4168 step 6) |
+ * | WSP151 | what a member under `ci.workflow` still lacks (#4168 step 6) |
  * | WSP161 to WSP165 | the security groups the declaration opts into: what each still lacks (#4168 step 7) |
  */
 
@@ -61,6 +61,7 @@ import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
 import { BOX_CHECKS } from "./checks/boxes";
 import { DIAGRAM_CHECKS } from "./checks/diagrams";
 import { SECURITY_CHECKS } from "./checks/security";
+import { CI_WORKFLOW_CHECKS } from "./checks/ci-workflow";
 import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
 import { resolveBoxIntents, type ResolvedBoxIntent } from "./box-intent";
 import { gatherLexiconOutputs, type MemberLexiconOutputs } from "./lexicon-outputs";
@@ -374,6 +375,8 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...DIAGRAM_CHECKS,
   // Links resolved against a live read, with --live (#2549), WSP141 and WSP142.
   ...LIVE_CHECKS,
+  // What a member under ci.workflow still lacks (#4168 step 6), WSP151.
+  ...CI_WORKFLOW_CHECKS,
   // The security groups the declaration opts into (#4168 step 7), WSP161 to WSP165.
   ...SECURITY_CHECKS,
 ];

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 });

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

@@ -531,3 +531,36 @@ describe("chant ci list (#4021)", () => {
     }
   });
 });
+
+describe("chant ci tick walks compose branches (#4168 4.3)", () => {
+  test("judges composed commits, names their branch in the tag, and warns when a source they carry is revoked", async () => {
+    const { root, origin } = workspace();
+    const a = commitAt(root, 5, "app/a.txt");
+    const b = commitAt(root, 4, "app/b.txt");
+    push(root);
+    // A composed commit on a, picking b.
+    git(root, "checkout", "-q", "-b", "chant/compose/hf", a);
+    writeFiles(root, { "app/b.txt": "app/b.txt 4\n" });
+    gitAt(root, hoursAgo(2), "add", "-A");
+    gitAt(root, hoursAgo(2), "commit", "-q", "-m", `app/b.txt\n\nChant-Composed-From: ${b}`);
+    const c = git(root, "rev-parse", "HEAD");
+    git(root, "push", "-q", "origin", "chant/compose/hf");
+    git(root, "checkout", "-q", "main");
+
+    const runs = new Map([
+      [a, PASSING],
+      [b, PASSING],
+      [c, PASSING],
+    ]);
+    const first = await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
+    expect(first.composed.map((x) => [x.branch, x.commits.map((k) => k.sha)])).toEqual([["chant/compose/hf", [c]]]);
+    expect(first.made.sort()).toEqual([`ci/green/${a}`, `ci/green/${b}`, `ci/green/${c}`].sort());
+    const note = git(origin, "tag", "-l", "--format=%(contents)", `ci/green/${c}`);
+    expect(JSON.parse(note.slice(note.indexOf("{")))).toMatchObject({ tag: "green", commit: c, branch: "chant/compose/hf" });
+
+    runs.set(b, [...PASSING, run(9, "lint", "failure")]);
+    const revoke = await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
+    expect(revoke.made).toEqual([`ci/revoked/${b}`]);
+    expect(revoke.warnings.join("\n")).toContain(`chant/compose/hf carries it as ${c.slice(0, 12)}`);
+  });
+});

package/src/workspace/ci-green.ts

@@ -71,6 +71,7 @@ import { gitRevisionSource } from "./record-source";
 import { emptyPolicy, readTrustPolicy } from "./trust/policy";
 import { loadRunnerKey } from "./trust/dsse";
 import { signCiTagRecord, verifyCiTagStatement, CI_TAG_SIGNER_ROLE, type CiTagFailure, type CiTagRecord, type CiTagSigner } from "./trust/ci-tag-statement";
+import { COMPOSE_BRANCH_PREFIX, composedIncluding, isComposeBranch, remoteComposeBranches } from "../lifecycle/compose-refs";
 
 /** The environment variable a tick (#4031) and `chant run` (#4044) read a runner key from, as PEM, when `--key` is not given. */
 export const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
@@ -478,7 +479,9 @@ export function readCiTags(top: string, green: CiGreen | null = null, base: stri
       continue;
     }
     const p = policyAtBase();
-    const v = verifyCiTagStatement(t.record, { sha: t.sha, kind: t.kind, branch: green!.branch }, p.runners, p.roles);
+    // A tag the tick made walking a compose branch (#4168 4.3) is checked against that branch.
+    const walked = isComposeBranch(t.record?.branch) ? (t.record!.branch as string) : green!.branch;
+    const v = verifyCiTagStatement(t.record, { sha: t.sha, kind: t.kind, branch: walked }, p.runners, p.roles);
     if (v.status === "signed") counted(v.signer);
     else ignore(v.status, `${v.reason}; ci.green.signedSince is ${green!.signedSince}, so a tag on a commit that is not a strict first-parent ancestor of it needs one`);
   }
@@ -501,7 +504,7 @@ export function signedRunsRequired(cwd: string): string | null {
 }
 
 /** The declaration's `ci.green`, read where `cwd` is, and the git top. */
-function readGreen(cwd: string): { green: CiGreen; top: string; workspace: { name: string; root: string; file: string } } {
+export function readGreen(cwd: string): { green: CiGreen; top: string; workspace: { name: string; root: string; file: string } } {
   const located = locateWorkspace(cwd);
   const declaration = readDeclaration(located.tree);
   const green = declaration.ci?.green ?? null;
@@ -535,12 +538,21 @@ export interface TickRequest {
   runnerKey?: string;
 }
 
+/** One compose branch a tick walked (#4168 4.3): its composed commits within the window. */
+export interface ComposedBranchTick {
+  branch: string;
+  ref: string;
+  commits: TickCommit[];
+}
+
 export interface TickResult {
   branch: string;
   window: string;
   /** The ref the commits were read from. */
   ref: string;
   commits: TickCommit[];
+  /** The compose branches walked (#4168 4.3), each with its composed commits judged. Their tags are in `made`. */
+  composed: ComposedBranchTick[];
   /** The tags made and pushed, or that would be under `dryRun`. */
   made: string[];
   /** The builds asked for (#4169), as `ci/build/<sha>` tags made and pushed, or that would be under `dryRun`. */
@@ -596,7 +608,16 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
   const now = req.now ?? new Date();
   const tracking = `refs/remotes/${remote}/${green.branch}`;
   try {
-    git(top, ["fetch", "--quiet", "--no-tags", "--prune", remote, `+refs/heads/${green.branch}:${tracking}`, "+refs/tags/ci/*:refs/tags/ci/*"]);
+    git(top, [
+      "fetch",
+      "--quiet",
+      "--no-tags",
+      "--prune",
+      remote,
+      `+refs/heads/${green.branch}:${tracking}`,
+      `+refs/heads/${COMPOSE_BRANCH_PREFIX}*:refs/remotes/${remote}/${COMPOSE_BRANCH_PREFIX}*`,
+      "+refs/tags/ci/*:refs/tags/ci/*",
+    ]);
   } catch (err) {
     throw new Error(`could not fetch ${green.branch} and the ci tags from ${remote}: ${stderrOf(err)}`);
   }
@@ -648,6 +669,28 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
     signer,
   });
   if (links) for (const c of planned) c.work = links.get(c.sha);
+  // Compose branches (#4168 4.3): each composed commit within the window is judged as trunk's are, and its tags name its branch.
+  const composed: ComposedBranchTick[] = [];
+  for (const b of remoteComposeBranches(top, remote)) {
+    const own = git(top, ["log", "--first-parent", `--max-age=${cutoff}`, "--format=%H %ct", b.ref, `^${tracking}`])
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => line.split(" "))
+      .filter(([, ct]) => Number(ct) >= cutoff)
+      .map(([sha, ct]) => ({ sha, committed: iso(new Date(Number(ct) * 1000)) }));
+    if (own.length === 0) continue;
+    const judged = await planTick({
+      green: { ...green, branch: b.branch },
+      commits: own,
+      greenTags: new Set(tags.green.keys()),
+      revokedTags: new Set(tags.revoked.keys()),
+      ignored: tags.ignored,
+      checkRuns: async (sha) => (runs ? runs.checkRuns(sha) : await forge!.checkRuns(sha)),
+      now,
+      signer,
+    });
+    composed.push({ branch: b.branch, ref: b.ref, commits: judged });
+  }
   if (runs) {
     for (const c of planned) {
       const ignored = runs.ignored.get(c.sha);
@@ -658,7 +701,14 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
   const requests = readBuildRequests(top);
   const retryVia = green.source === "runs" ? "request" : forge?.rerun ? "forge" : null;
   const builds = planBuilds({ green, commits: planned, runs: runsBy, requests, records, now, retryVia });
-  const due = planned.filter((c) => c.made !== null);
+  const due = [...planned, ...composed.flatMap((b) => b.commits)].filter((c) => c.made !== null);
+  // Decision 4: revoking a trunk commit says which composed commits carry it; their own CI decides their releases.
+  for (const c of planned) {
+    if (!c.made?.tag.startsWith(CI_REVOKED_TAG_PREFIX)) continue;
+    for (const k of composedIncluding(top, c.sha, remote)) {
+      warnings.push(`${c.sha.slice(0, 12)} is revoked, and ${k.branch} carries it as ${k.commit.slice(0, 12)}; that composed commit's own CI decides whether its releases stand`);
+    }
+  }
   if (!req.dryRun && due.length > 0) {
     const ident = taggerConfig(top);
     for (const c of due) git(top, [...ident, "tag", "-a", "-m", c.made!.message, c.made!.tag, c.sha]);
@@ -683,6 +733,7 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
     ref: tracking,
     commits: planned,
     made: due.map((c) => c.made!.tag),
+    composed,
     requested: builds.requests,
     retried,
     recorded,
@@ -964,6 +1015,23 @@ export async function readOpRunSource(cwd: string, top: string, base: string, si
   return { checkRuns: (sha) => byCommit.get(sha) ?? [], ignored };
 }
 
+/**
+ * Judge `ci.green.preMerge` on `commit` from the Op run records on the ledger
+ * (#4168 4.4), as `ci serve --land` does before it moves the target. The
+ * trust policy is read at `base`, the target's head. An unsigned run counts
+ * as the tick counts one: always, unless `ci.green.signedSince` asks for a
+ * signature. Throws {@link CiGreenError} when the declaration has no
+ * `ci.green` or names no pre-merge phase.
+ */
+export async function judgePreMerge(req: { cwd: string; commit: string; base: string }): Promise<CommitVerdict> {
+  const { green, top } = readGreen(req.cwd);
+  const pre = green.preMerge ?? [];
+  if (pre.length === 0) throw new CiGreenError("ci-green-undeclared", "ci.green.preMerge names no phase, so nothing says which checks must pass before the branch moves");
+  const runs = await readOpRunSource(req.cwd, top, req.base, green.signedSince);
+  const latest = latestAttempts(runs.checkRuns(req.commit));
+  return commitVerdictOf(pre.map((name) => evaluatePhase(green.phases.find((p) => p.name === name)!, latest)));
+}
+
 /**
  * What `chant run <op> --key` signs a run's record with (#4044): the runner
  * key `.chant/trust.json` at the checkout's `HEAD` lists for a principal
@@ -1063,6 +1131,19 @@ export function formatTick(r: TickResult, dryRun = false): string {
     for (const r of c.ignoredRuns ?? []) lines.push(`      ignored run ${r.run} of ${r.op} in ${r.env} (${r.status}): ${r.reason}`);
     if (c.blocked) lines.push(`      did not make ${c.blocked}: an ignored tag holds the name. Delete it to let the tick tag the commit: git push origin :refs/tags/${c.blocked}`);
   }
+  for (const b of r.composed ?? []) {
+    lines.push(`${b.branch}, composed commits within ${r.window}: ${b.commits.length}`);
+    for (const c of b.commits) {
+      const what = c.made
+        ? `${dryRun ? "would make" : "made"} ${c.made.tag.slice(0, c.made.tag.lastIndexOf("/"))}`
+        : c.before !== "none"
+          ? c.before
+          : c.verdict?.verdict === "fail"
+            ? `failed: phase ${c.verdict.failure!.phase}`
+            : "undecided";
+      lines.push(`  ${c.sha.slice(0, 12)}  ${what}`);
+    }
+  }
   if (r.signer && r.made.length > 0) lines.push(`signed as ${r.signer}`);
   for (const q of r.requested) lines.push(`${dryRun ? "would ask" : "asked"} for ${q.phases.join(", ")} at ${q.commit.slice(0, 12)} (${q.reason}): ${q.tag}`);
   for (const x of r.retried) lines.push(`${dryRun ? "would run" : "ran"} ${x.run} at ${x.sha.slice(0, 12)} again`);