@intentius/chant 0.124.33 → 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/__fixtures__/contract-repo.ts

@@ -27,7 +27,7 @@ export function scratchDir(prefix = "chant-contract-"): string {
 }
 
 export function git(cwd: string, ...args: string[]): string {
-  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", "-c", "gc.auto=0", "-c", "maintenance.auto=false", ...args], {
     cwd,
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
@@ -67,7 +67,16 @@ export function repoFixture(build: () => string, prefix = "chant-contract-copy-"
   return () => {
     if (template === undefined || !existsSync(template)) template = build();
     const root = scratchDir(prefix);
-    cpSync(template, root, { recursive: true });
+    // A commit can leave a detached `git gc --auto` or maintenance run moving
+    // the template's objects, and a copy that meets it fails with ENOENT on
+    // .git/objects. Copy once more after it settles.
+    try {
+      cpSync(template, root, { recursive: true });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      rmSync(root, { recursive: true, force: true });
+      cpSync(template, root, { recursive: true });
+    }
     return root;
   };
 }

package/src/workspace/check-contract.test.ts

@@ -14,6 +14,7 @@ import { BOX_FINDING_CODES } from "./checks/boxes";
 import { RECORD_FINDING_CODES } from "./checks/records";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { SECURITY_FINDING_CODES } from "./checks/security";
+import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { CHECK_CODES, CHECK_CONTRACT_VERSION, CHECK_ERROR_CODES, CHECK_OUTPUT_SCHEMA_ID, runChecks, type CheckDocument } from "./lineage-check";
 
@@ -39,8 +40,8 @@ describe("check output schema", () => {
   test("lists exactly the codes the code can return", () => {
     expect(schema.$defs.lockFinding.properties.code.enum).toEqual([...CHECK_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...CHECK_ERROR_CODES]);
-    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES]);
-    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES]);
+    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES, ...CI_WORKFLOW_FINDING_CODES]);
+    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES, ...CI_WORKFLOW_FINDING_CODES]);
   });
 });
 

package/src/workspace/check.schema.json

@@ -332,7 +332,16 @@
 
             "security-runner-start-no-role",
 
-            "security-trust-unreadable"
+            "security-trust-unreadable",
+            "ci-workflow-green-undeclared",
+            "ci-workflow-no-pre-merge",
+            "ci-workflow-apply-in-green",
+            "ci-workflow-no-components",
+            "ci-workflow-no-environments",
+            "ci-workflow-ungated-env",
+            "ci-workflow-pipeline-missing",
+            "ci-workflow-pipeline-differs",
+            "ci-workflow-publish-missing"
           ],
           "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP118, flag-stale (#4024). For WSP131 to WSP133, the diagram finding (#2764)."
         }
@@ -445,7 +454,16 @@
 
             "security-runner-start-no-role",
 
-            "security-trust-unreadable"
+            "security-trust-unreadable",
+            "ci-workflow-green-undeclared",
+            "ci-workflow-no-pre-merge",
+            "ci-workflow-apply-in-green",
+            "ci-workflow-no-components",
+            "ci-workflow-no-environments",
+            "ci-workflow-ungated-env",
+            "ci-workflow-pipeline-missing",
+            "ci-workflow-pipeline-differs",
+            "ci-workflow-publish-missing"
           ],
           "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP118, flag-stale (#4024). For WSP131 to WSP133, the diagram finding (#2764)."
         },

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

@@ -0,0 +1,160 @@
+/**
+ * WSP151, what a member under ci.workflow still lacks (#4168 step 6), and the
+ * reference page printed from CI_WORKFLOW_REQUIREMENTS.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "../checks";
+import { ciWorkflowTable, CI_WORKFLOW_FINDING_CODES, workflowOf } from "../ci-workflow";
+import { REASON_CODES } from "../reason-codes";
+
+const DOCS = fileURLToPath(new URL("../../../../../docs/src/content/docs/", import.meta.url));
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-ci-workflow-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const member = (extra: Record<string, unknown> = {}) => ({ name: "app", dir: "app", kind: "other", because: "the app", ...extra });
+const declaration = (extra: Record<string, unknown> = {}, members = [member()]) => JSON.stringify({ name: "acme", schema: 1, members, ...extra }, null, 2);
+const green = (extra: Record<string, unknown> = {}) => ({ branch: "main", phases: { check: ["check"], suites: ["suites"] }, require: ["check", "suites"], preMerge: ["check"], ...extra });
+
+const CONFIG = 'export default { lexicons: ["aws"], environments: ["staging", "prod"] };\n';
+const COMPONENT = 'import { gate, phase } from "@intentius/chant/components/component";\nexport const app = { name: "app", deploy: [phase("Apply", [gate("prod")])] };\n';
+const PIPELINE = [
+  "on: [pull_request, push]",
+  "jobs:",
+  "  plan:",
+  "    steps:",
+  "      - run: chant ci run plan --in-place --no-push --env prod --gate pr-apply --forge github",
+  "  record:",
+  "    steps:",
+  "      - 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";
+
+/** A member under trunk-curated with everything the workflow needs. */
+const complete = (extra: Record<string, string> = {}) => ({
+  "chant.workspace.json": declaration({ ci: { workflow: "trunk-curated", green: green() } }),
+  "app/chant.config.ts": CONFIG,
+  "app/app.component.ts": COMPONENT,
+  ".github/workflows/chant-pr.yml": PIPELINE,
+  ".github/workflows/chant-ci-green.yml": TICK,
+  ".github/workflows/chant-release.yml": PUBLISH,
+  ...extra,
+});
+
+/** The WSP151 findings as [code, entity]. */
+const found = async (root: string) =>
+  (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId === "WSP151").map((d) => [d.code, d.entity ?? null]);
+
+describe("ci.workflow (WSP151)", () => {
+  test("a declaration that names no workflow gets no finding", async () => {
+    const root = repo({ "chant.workspace.json": declaration(), "app/chant.config.ts": "export default {};\n" });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a workspace with everything trunk-curated needs passes", async () => {
+    expect(await found(repo(complete()))).toEqual([]);
+  });
+
+  test("an empty workspace under trunk-curated reports each missing piece", async () => {
+    const root = repo({ "chant.workspace.json": declaration({ ci: { workflow: "trunk-curated" } }), "app/chant.config.ts": "export default {};\n" });
+    expect(await found(root)).toEqual([
+      ["ci-workflow-no-environments", "app"],
+      ["ci-workflow-no-components", "app"],
+      ["ci-workflow-green-undeclared", null],
+      ["ci-workflow-pipeline-missing", null],
+      ["ci-workflow-publish-missing", null],
+    ]);
+  });
+
+  test("no preMerge phases, and a required phase that matches the apply job", async () => {
+    const root = repo(complete({ "chant.workspace.json": declaration({ ci: { workflow: "trunk-curated", green: green({ phases: { check: ["check"], deploy: ["*apply"] }, require: ["check", "deploy"], preMerge: [] }) } }) }));
+    expect(await found(root)).toEqual([
+      ["ci-workflow-no-pre-merge", null],
+      ["ci-workflow-apply-in-green", null],
+    ]);
+  });
+
+  test("a component with no gate", async () => {
+    const root = repo(complete({ "app/app.component.ts": 'export const app = { name: "app", deploy: [] };\n' }));
+    expect(await found(root)).toEqual([["ci-workflow-ungated-env", "app"]]);
+  });
+
+  test("trunk-curated with an apply job on merge differs", async () => {
+    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": 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 () => {
+    const root = repo({
+      ...complete(),
+      "chant.workspace.json": declaration({ ci: { green: green() } }, [member({ ci: { workflow: "trunk-curated" } }), member({ name: "docs", dir: "docs" })]),
+      "docs/README.md": "",
+    });
+    expect(await found(root)).toEqual([]);
+    const top = repo({ ...complete(), "docs/README.md": "", "chant.workspace.json": declaration({ ci: { workflow: "trunk-curated", green: green() } }, [member(), member({ name: "docs", dir: "docs" })]) });
+    expect(await found(top)).toEqual([]);
+  });
+
+  test("ci.green.preMerge must name declared phases", async () => {
+    const root = repo({ "chant.workspace.json": declaration({ ci: { green: green({ preMerge: ["lint"] }) } }) });
+    const report = await runDeclarationChecks(root, (f) => f, { gather: false });
+    expect(report.diagnostics.find((d) => d.ruleId === "WSP001")?.message).toMatch(/ci\.green\.preMerge names the phase "lint"/);
+  });
+});
+
+describe("workflowOf", () => {
+  test("the member's own wins over the top level's", () => {
+    const d = { ci: { green: null, workflow: "trunk-curated" as const, reportUrl: null } };
+    expect(workflowOf(d, { ciWorkflow: null })).toBe("trunk-curated");
+    expect(workflowOf(d, { ciWorkflow: "trunk-curated+apply-on-merge" })).toBe("trunk-curated+apply-on-merge");
+    expect(workflowOf({ ci: null }, null)).toBeNull();
+  });
+});
+
+describe("the ci.workflow codes and reference page", () => {
+  test("every code is a read-contract reason code", () => {
+    for (const code of CI_WORKFLOW_FINDING_CODES) expect(REASON_CODES, code).toContain(code);
+  });
+
+  test("the CI workflows page carries the table CI_WORKFLOW_REQUIREMENTS prints", () => {
+    const page = readFileSync(join(DOCS, "reference", "ci-workflows.mdx"), "utf-8");
+    const table = /^\| Code \| Requirement \|[^\n]*\n(?:\|[^\n]*\n)*/m.exec(page)?.[0].trimEnd();
+    expect(table, "regenerate the table under Requirements from ciWorkflowTable()").toBe(ciWorkflowTable());
+  });
+});