@intentius/chant 0.124.40 → 0.124.42

package/src/pr-loop.ts

@@ -48,6 +48,7 @@
  */
 
 import type { ChangeSetAction, ChangeSetDocument } from "./change-set";
+import type { PrRequireOutcome } from "./pr-requires";
 import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown } from "./plan-summary";
 
 /** The schema a pull-request report names in `$schema`. */
@@ -71,6 +72,18 @@ export const PR_REPORT_PLANNED_OUTPUTS_FLOOR = "0.124.32";
 /** The chant that writes the `record` stage and the `recorded` status (#4168 step 1). */
 export const PR_REPORT_RECORD_FLOOR = "0.124.33";
 
+/** The first chant whose report can carry `hooks` (#4288). */
+export const PR_REPORT_HOOKS_FLOOR = "0.124.41";
+
+/** The first chant whose plan report can carry `overdue` (#4289). */
+export const PR_REPORT_OVERDUE_FLOOR = "0.124.41";
+
+/** The first chant whose report can carry `policy` and the `policy-denied` and `policy-error` refusals (#4294). */
+export const PR_REPORT_POLICY_FLOOR = "0.124.41";
+
+/** The first chant whose apply report can carry `beforeMerge` and the `requires-unmet` and `before-merge-off` refusals (#4301, ws-106). */
+export const PR_REPORT_BEFORE_MERGE_FLOOR = "0.124.42";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -174,6 +187,8 @@ export interface PrMember {
   round?: number;
   /** Apply stage (#3999): why the first round's plan did not apply. */
   held?: string;
+  /** A blocked member's (#4291): the component whose failure held it, past any component blocked in between. */
+  blockedBy?: string;
 }
 
 /** A round of plans an apply made after an upstream applied (#3999), the report's `rounds`. */
@@ -258,7 +273,22 @@ export type PrRefusal =
   /** `--wave-gate`: an approval of the wave's gate stands for another digest, so its plan moved since. */
   | "wave-plan-changed"
   /** `--wave-gate` with `--wave <k>`: an earlier wave has work left, or no record says it applied. */
-  | "earlier-wave";
+  | "earlier-wave"
+  /** Under `ci.locks` (#4293): another open pull request holds a lock on a target this apply reaches. */
+  | "locked"
+  /** `ci.policy` at base denied the plan (#4294), and no override of it counts. */
+  | "policy-denied"
+  /** `ci.policy` at base could not be run, or gave no answer chant can read (#4294). */
+  | "policy-error"
+  /** `pr-apply --before-merge` (#4301): the pull request is not approved, mergeable, undiverged or green; `beforeMerge` says which. */
+  | "requires-unmet"
+  /** `pr-apply --before-merge`: the declaration at base does not set `ci.workflow` to `apply-before-merge` for the member. */
+  | "before-merge-off";
+
+/** An apply before merge (#4301, ws-106): the requires checks the forge answered, in order. */
+export interface PrBeforeMerge {
+  requires: PrRequireOutcome[];
+}
 
 /**
  * One wave of an apply with `--wave-gate` (#4003): what it planned, where it
@@ -289,6 +319,54 @@ export interface PrWave {
   moved?: string[];
 }
 
+/** A scheduled watch or reconcile Op that stopped running (#4289, `op/schedule-overdue.ts`). */
+export interface PrOverdue {
+  op: string;
+  cron: string;
+  /** The job's last run, or the pipeline file's first commit when `neverRan` (ISO 8601). */
+  since: string;
+  neverRan?: boolean;
+  message: string;
+}
+
+/**
+ * What `ci.policy` at base said about the change set (#4294). Rule ids are
+ * `<package>.<rule>`.
+ */
+export interface PrPolicyReport {
+  /** `denied` wins over `held`. `error`: the policy did not run or gave no readable answer. */
+  result: "passed" | "denied" | "held" | "error";
+  /** The result shape read: `conftest` or `opa`. */
+  engine: "conftest" | "opa";
+  /** The commit the settings and the policy were read at. */
+  base: string;
+  denials: Array<{ rule: string; message: string }>;
+  /** The ids of the rules that denied, sorted: what an override names. */
+  rules?: string[];
+  holds: Array<{ rule: string; message: string }>;
+  warnings: string[];
+  error?: string;
+  /** The override that lets the denied plan through. */
+  override?: { by: string; at: string; reason: string; digest: string };
+  /** While denied: the command that overrides the denial. */
+  overrideCommand?: string;
+}
+
+/**
+ * One stage hook a pull-request job ran (#4288), from `ci.hooks` in the
+ * workspace declaration at base. The shape of an Op waves hook outcome.
+ */
+export interface PrHookOutcome {
+  /** `before-observe`, `before-plan`, `after-plan`, `before-apply` or `after-apply`. */
+  moment: string;
+  name: string;
+  /** The component, for a `perRun` hook. */
+  target?: string;
+  exit: number;
+  /** `held`: an `onFailure: approve` hook failed, which the pull request's gate answers. */
+  outcome: "passed" | "failed" | "held";
+}
+
 /**
  * The document `pr-plan` and `pr-apply` write (`pr-report.schema.json`).
  * The terragucci plan report (#3349) reads it; fields are only ever added.
@@ -350,6 +428,14 @@ export interface PrReport {
   waveGate?: string;
   /** With `waveGate`: each wave reached so far, in order. */
   waves?: PrWave[];
+  /**
+   * Plan stage (#4289): the scheduled watch and reconcile Ops whose cron has
+   * fired at least twice since their job last ran, or since their pipeline
+   * file was added when no run is on record. Absent when none is overdue or
+   * the forge was not asked. Added within contract 1 by chant
+   * {@link PR_REPORT_OVERDUE_FLOOR}.
+   */
+  overdue?: PrOverdue[];
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
     changed: string[];
@@ -361,6 +447,23 @@ export interface PrReport {
   };
   members: PrMember[];
   changeSet: ChangeSetDocument;
+  /**
+   * The stage hooks the job ran (#4288), in order. Absent when it ran none.
+   * Added within contract 1 by chant {@link PR_REPORT_HOOKS_FLOOR}.
+   */
+  hooks?: PrHookOutcome[];
+  /**
+   * What `ci.policy` at base said about the change set (#4294). Absent when
+   * the base sets no policy, or the stage reached no plan to judge. Added
+   * within contract 1 by chant {@link PR_REPORT_POLICY_FLOOR}.
+   */
+  policy?: PrPolicyReport;
+  /**
+   * `pr-apply --before-merge` (#4301): the requires checks. Absent on every
+   * other stage. Added within contract 1 by chant
+   * {@link PR_REPORT_BEFORE_MERGE_FLOOR}.
+   */
+  beforeMerge?: PrBeforeMerge;
 }
 
 /** The counts a member's entries add up to. */
@@ -421,11 +524,14 @@ function headline(report: PrReport): string {
     case "recorded":
       return `Recorded the plan of ${members} on merge. Nothing applied: a release that carries this commit deploys it.`;
     case "plan-failed":
+      if (report.hooks?.some((h) => h.outcome === "failed")) return "A hook failed, so nothing can apply.";
       return `Planning failed for ${report.members.filter((m) => m.status === "plan-failed").length} of ${members}, so nothing can apply.`;
     case "applied":
       return `Applied ${members}.`;
-    case "failed":
-      return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${report.members.filter((m) => m.status === "applied").length} applied.`;
+    case "failed": {
+      const blocked = report.members.filter((m) => m.status === "blocked").length;
+      return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${blocked > 0 ? `${blocked} blocked, ` : ""}${report.members.filter((m) => m.status === "applied").length} applied.`;
+    }
     case "wave-applied": {
       const applied = (report.waves ?? []).filter((w) => w.status === "applied").map((w) => w.wave);
       const total = report.selection.waves.length;
@@ -440,6 +546,43 @@ function headline(report: PrReport): string {
   }
 }
 
+/**
+ * The blocked set (#4291): each component a failure held, grouped by the
+ * component that failed, and that the rest went on. Undefined when nothing
+ * is blocked.
+ */
+function blockedLine(members: readonly PrMember[]): string | undefined {
+  const byRoot = new Map<string, Set<string>>();
+  for (const m of members) {
+    if (m.status !== "blocked") continue;
+    const by = m.blockedBy ?? "a dependency";
+    byRoot.set(by, (byRoot.get(by) ?? new Set()).add(m.component));
+  }
+  if (byRoot.size === 0) return undefined;
+  const groups = [...byRoot]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([by, names]) => `${[...names].sort().map(code).join(", ")} (blocked by ${by === "a dependency" ? by : code(by)})`);
+  return `Blocked, so not applied: ${groups.join("; ")}. A failure blocks only the members that depend on it, so the rest went on.`;
+}
+
+/** The policy's lines in the note (#4294): what denied or held the plan, and how a denial is overridden. */
+function policyLines(report: PrReport): string[] {
+  const p = report.policy;
+  if (!p) return [];
+  const at = `read at ${code(short(p.base))}`;
+  const each = (list: Array<{ rule: string; message: string }>): string[] => list.map((f) => `- ${code(f.rule)}: ${f.message}`);
+  const out: string[] = [""];
+  if (p.result === "error") out.push(`Policy (${p.engine}, ${at}) could not be checked, so nothing applies: ${p.error ?? "no answer"}.`);
+  else if (p.result === "passed") out.push(`Policy (${p.engine}, ${at}) passed.`);
+  if (p.denials.length > 0) {
+    out.push(p.override ? `Policy (${p.engine}, ${at}) denied this plan; ${code(p.override.by)} overrode it: ${p.override.reason}` : `Policy (${p.engine}, ${at}) denied this plan:`, ...each(p.denials));
+    if (!p.override && p.overrideCommand) out.push("", `A person the overriders file at base lists may override it once pr-apply has recorded the denial: ${code(p.overrideCommand)}`);
+  }
+  if (p.holds.length > 0) out.push(`Policy (${p.engine}, ${at}) holds this plan for a person's approval of its digest:`, ...each(p.holds));
+  if (p.warnings.length > 0) out.push(`Policy warnings: ${p.warnings.join("; ")}`);
+  return out;
+}
+
 /** Who a wave applied or waits under, as a table cell. */
 function waveApproval(w: PrWave): string {
   const whose = w.approval === "pull-request" ? "the pull request's" : "its own";
@@ -513,6 +656,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
     `${headline(report)} Head ${code(short(report.head))}, measured from ${code(short(report.base))}.`,
   ];
   if (report.message) out.push("", `> ${report.message.split("\n").join("\n> ")}`);
+  for (const o of report.overdue ?? []) out.push("", `Warning: ${o.message}`);
   if (report.resumed && report.resumed.applied.length > 0) {
     out.push("", `Resumed under the same approval: ${report.resumed.applied.map(code).join(", ")} applied in an earlier attempt and did not run again.`);
   }
@@ -522,6 +666,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
       const holes = memberHoleReasons(report, m.member);
       const status =
         STATUS_WORDS[m.status] +
+        (m.status === "blocked" && m.blockedBy ? ` by ${code(m.blockedBy)}` : "") +
         (m.inputsMoved?.length ? `, inputs from ${m.inputsMoved.join(", ")} moved` : "") +
         (holes.length > 0 ? `; ${holes.length > 2 ? `${holes[0]}; and ${holes.length - 1} more, listed under Holes` : holes.join("; ")}` : "");
       // A member whose plan has holes and no entries says nothing about what
@@ -534,7 +679,17 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
       out.push("", "A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.");
     }
   }
+  const blocked = blockedLine(report.members);
+  if (blocked) out.push("", blocked);
   out.push(...waveLines(report, options.approver ?? "<you>"));
+  // #4288: the hooks that did not pass, by name; a passed hook is a count.
+  const hooks = report.hooks ?? [];
+  if (hooks.length > 0) {
+    const passed = hooks.filter((h) => h.outcome === "passed").length;
+    const other = hooks.filter((h) => h.outcome !== "passed").map((h) => `${code(h.name)} ${h.moment}${h.target ? ` for ${code(h.target)}` : ""} ${h.outcome === "held" ? "held" : "failed"} (exit ${h.exit})`);
+    out.push("", `Hooks: ${passed} passed${other.length > 0 ? `; ${other.join("; ")}` : ""}.`);
+  }
+  out.push(...policyLines(report));
   if (report.selection.unclaimed.length > 0) {
     out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
   }
@@ -635,7 +790,16 @@ export function prStatusDescription(report: PrReport): string {
         text = "refused: an earlier wave has not applied";
         break;
       }
-      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "author-approved" ? "the approver wrote the change" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+      if (report.refusal === "requires-unmet" || report.refusal === "before-merge-off") {
+        const unmet = (report.beforeMerge?.requires ?? []).filter((r) => !r.passed).map((r) => r.name);
+        text = report.refusal === "before-merge-off" ? "refused: this workspace does not apply before merge" : `refused: ${unmet.join(", ") || "a require"} unmet for an apply before merge`;
+        break;
+      }
+      if (report.refusal === "policy-denied" || report.refusal === "policy-error") {
+        text = report.refusal === "policy-denied" ? `refused: the policy denied the plan (${(report.policy?.rules ?? []).join(", ")})` : "refused: the policy could not be checked";
+        break;
+      }
+      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "author-approved" ? "the approver wrote the change" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : report.refusal === "locked" ? "another pull request holds a target lock" : "the plan is not approved"}`;
       break;
     }
   }
@@ -646,6 +810,8 @@ export function prStatusDescription(report: PrReport): string {
 export function prStatusState(report: PrReport): "success" | "failure" | "pending" {
   // #4168 decision 1: a merge whose plan differs from the approved one is recorded, and its status fails.
   if (report.status === "recorded") return report.approval.status === "changed" ? "failure" : "success";
+  // #4294: a plan the policy denied, with no override, or one it could not check, fails at the plan stage as it would at the apply.
+  if (report.status === "planned" && report.policy && (report.policy.result === "error" || (report.policy.result === "denied" && !report.policy.override))) return "failure";
   if (report.status === "planned" || report.status === "applied" || report.status === "wave-applied" || report.status === "nothing") return "success";
   if (report.status === "refused" && (report.refusal === "not-approved" || report.refusal === "wave-not-approved")) return "pending";
   if (report.status === "waiting") return "pending";

package/src/pr-post.test.ts

@@ -0,0 +1,141 @@
+/**
+ * #4295: `chant components pr-post` posts the plan's note and `chant/plan`
+ * from a report the pull request's code wrote, so it reads it as data: the
+ * pull request, head, environment and member are the caller's, a report that
+ * names others is refused, and the note carries no hidden marker but its own.
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { postPlanReport, readPlanReport } from "./pr-post";
+import { prNoteMarker, type PrReport } from "./pr-loop";
+import type { ForgeStatus, PrForge } from "./pr-forge";
+
+const FIXTURE = join(import.meta.dirname, "__fixtures__", "pr-loop", "pr-plan.golden.json");
+const REPORT = JSON.parse(readFileSync(FIXTURE, "utf-8")) as PrReport;
+const HEAD = REPORT.head;
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+function reportDir(report: unknown): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-pr-post-"));
+  dirs.push(dir);
+  mkdirSync(dir, { recursive: true });
+  if (report !== undefined) writeFileSync(join(dir, "pr-plan.json"), typeof report === "string" ? report : JSON.stringify(report));
+  return dir;
+}
+
+function fakeForge(refuse = false): { forge: PrForge; statuses: Array<{ sha: string; status: ForgeStatus }>; notes: Array<{ pr: number; marker: string; body: string }> } {
+  const statuses: Array<{ sha: string; status: ForgeStatus }> = [];
+  const notes: Array<{ pr: number; marker: string; body: string }> = [];
+  const forge = {
+    kind: "github",
+    host: "github.com",
+    runUrl: "https://github.com/acme/estate/actions/runs/1",
+    async setStatus(sha: string, status: ForgeStatus) {
+      if (refuse) throw new Error("403");
+      statuses.push({ sha, status });
+    },
+    async upsertNote(pr: number, marker: string, body: string) {
+      if (refuse) throw new Error("403");
+      notes.push({ pr, marker, body });
+      return "1";
+    },
+  } as unknown as PrForge;
+  return { forge, statuses, notes };
+}
+
+const at = { pr: REPORT.pr!, head: HEAD, env: REPORT.env };
+
+describe("pr-post reads the plan report as data (#4295)", () => {
+  test("a report for this pull request, head and environment posts its status and its note", async () => {
+    const { forge, statuses, notes } = fakeForge();
+    const r = await postPlanReport({ forge, dir: reportDir(REPORT), ...at, result: "success" });
+    expect(r).toMatchObject({ state: "success", noted: true, warnings: [] });
+    expect(statuses).toEqual([{ sha: HEAD, status: expect.objectContaining({ context: "chant/plan", state: "success", url: "https://github.com/acme/estate/actions/runs/1" }) }]);
+    expect(notes).toHaveLength(1);
+    expect(notes[0]!.marker).toBe(prNoteMarker("prod"));
+    expect(notes[0]!.body.startsWith(prNoteMarker("prod") + "\n")).toBe(true);
+  });
+
+  test("a marker the change wrote into its report is defused, so the note claims no other environment's", async () => {
+    const forged = { ...REPORT, message: `planned ${prNoteMarker("staging")} <!-- chant-pr:prod -->` };
+    const { forge, notes } = fakeForge();
+    await postPlanReport({ forge, dir: reportDir(forged), ...at });
+    const body = notes[0]!.body;
+    expect(body.split("<!--")).toHaveLength(2);
+    expect(body).toContain("&lt;!-- chant-pr:staging -->");
+  });
+
+  test.each([
+    ["another pull request", { pr: 13 }, /pull request 13, not 12/],
+    ["another head", { head: "3".repeat(40) }, /for head/],
+    ["another environment", { env: "staging" }, /environment "staging"/],
+    ["a member", { member: "net" }, /member "net"/],
+    ["the apply stage", { stage: "apply" }, /not a plan report/],
+  ])("a report for %s is refused: a failed status and no note", async (_what, change, why) => {
+    const { forge, statuses, notes } = fakeForge();
+    const r = await postPlanReport({ forge, dir: reportDir({ ...REPORT, ...change }), ...at });
+    expect(r.refused).toMatch(why);
+    expect(r.state).toBe("failure");
+    expect(statuses[0]!.sha).toBe(HEAD);
+    expect(statuses[0]!.status.state).toBe("failure");
+    expect(notes).toEqual([]);
+  });
+
+  test("no report, or one that does not read, fails the status", async () => {
+    for (const report of [undefined, "{not json", "[]", JSON.stringify({ ...REPORT, members: "x" })]) {
+      const { forge, statuses, notes } = fakeForge();
+      const r = await postPlanReport({ forge, dir: reportDir(report), ...at });
+      expect(r.state).toBe("failure");
+      expect(statuses[0]!.status.state).toBe("failure");
+      expect(notes).toEqual([]);
+    }
+    expect(readPlanReport({ dir: reportDir(undefined), ...at })).toEqual({ refused: "the plan job wrote no report" });
+  });
+
+  test("a plan job that failed fails the status, whatever its report says", async () => {
+    const { forge, statuses } = fakeForge();
+    const r = await postPlanReport({ forge, dir: reportDir(REPORT), ...at, result: "failure" });
+    expect(r.state).toBe("failure");
+    expect(statuses[0]!.status.description).toMatch(/^the plan job failed; /);
+    expect(statuses[0]!.status.description.length).toBeLessThanOrEqual(140);
+  });
+
+  test("a member's report posts under the member's context and marker, and none when the change does not reach it", async () => {
+    const { forge, statuses, notes } = fakeForge();
+    await postPlanReport({ forge, dir: reportDir({ ...REPORT, member: "net" }), ...at, member: "net" });
+    expect(statuses[0]!.status.context).toBe("chant/plan/net");
+    expect(notes[0]!.marker).toBe(prNoteMarker("prod", "net"));
+    const quiet = fakeForge();
+    await postPlanReport({ forge: quiet.forge, dir: reportDir({ ...REPORT, member: "net", status: "nothing" }), ...at, member: "net" });
+    expect(quiet.statuses).toHaveLength(1);
+    expect(quiet.notes).toEqual([]);
+  });
+
+  test("a forge that refuses is a warning", async () => {
+    const { forge } = fakeForge(true);
+    const r = await postPlanReport({ forge, dir: reportDir(REPORT), ...at });
+    expect(r.warnings).toEqual([expect.stringMatching(/could not set the chant\/plan status: 403/), expect.stringMatching(/could not post the note on #12: 403/)]);
+    expect(r.noted).toBe(false);
+  });
+});
+
+describe("pr-post asks for overdue scheduled Ops itself (#4289, #4295)", () => {
+  test("the Ops it finds go in the note, and an overdue list the change wrote is dropped", async () => {
+    const forged = { ...REPORT, overdue: [{ op: "forged", cron: "* * * * *", message: "forged warning" }] };
+    const found = { op: "drift-watch", cron: "0 * * * *", message: "Op drift-watch has not run since its cron fired twice" };
+    const { forge, notes } = fakeForge();
+    await postPlanReport({ forge, dir: reportDir(forged), ...at, overdue: async () => [found as never] });
+    expect(notes[0]!.body).toContain("drift-watch has not run");
+    expect(notes[0]!.body).not.toContain("forged warning");
+    const quiet = fakeForge();
+    await postPlanReport({ forge: quiet.forge, dir: reportDir(forged), ...at, overdue: async () => [] });
+    expect(quiet.notes[0]!.body).not.toContain("forged warning");
+  });
+});

package/src/pr-post.ts

@@ -0,0 +1,159 @@
+/**
+ * Post a pull request's plan note and its `chant/plan` status from the plan
+ * report (#4295), in a job or a process that runs none of the change's code.
+ *
+ * The plan job runs the pull request's code and holds no forge token
+ * (./ci-handover.ts), so `pr-plan --no-status` only writes its report. Then
+ * `chant components pr-post` in the `plan-note` job, or `chant ci run plan`
+ * once its steps settle, reads the report and posts.
+ *
+ * The report is the change's: its code could write anything into it. So it
+ * is read as data. The pull request, the head, the environment and the
+ * member come from the caller, never the report, and a report that names
+ * others is refused. The note is rendered again here from the report, and
+ * every hidden HTML comment after its first line is defused, so a forged
+ * marker cannot claim another environment's note. A plan job that failed
+ * fails the status whatever its report says.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { prNoteMarker, prStatusContext, prStatusDescription, prStatusState, renderPrNote, type PrOverdue, type PrReport } from "./pr-loop";
+import { forgePrincipalOf, type PrForge } from "./pr-forge";
+import { GITHUB_COMMENT_LIMIT, GITLAB_NOTE_LIMIT } from "./plan-summary";
+
+/** The plan report's file under the report directory. */
+export const PR_PLAN_REPORT_FILE = "pr-plan.json";
+
+/** What {@link postPlanReport} posts for. */
+export interface PlanPostInput {
+  forge: PrForge;
+  /** The report directory the plan job wrote, `.chant/pr`. */
+  dir: string;
+  /** The pull request, from the forge's event. */
+  pr: number;
+  /** The commit the plan job checked out, from the forge's event. */
+  head: string;
+  env: string;
+  member?: string;
+  /** The plan job's own result (`needs.plan.result`). `failure` fails the status. */
+  result?: string;
+  /**
+   * The scheduled Ops that stopped running (#4289), asked here since the plan
+   * job held no token to ask with. It replaces any `overdue` in the report.
+   */
+  overdue?: () => Promise<PrOverdue[]>;
+}
+
+/** What {@link postPlanReport} did. */
+export interface PlanPostResult {
+  state: "success" | "failure" | "pending";
+  description: string;
+  /** Whether a note was posted. A refused or missing report posts none. */
+  noted: boolean;
+  /** Why the report was not used, when it was not. */
+  refused?: string;
+  warnings: string[];
+}
+
+const SHA = /^[0-9a-f]{40}$/;
+
+/**
+ * Read the plan report under `dir` and check it is the one the caller ran:
+ * a plan report for the same pull request, head, environment and member.
+ * Returns the report, or why it is not used.
+ */
+export function readPlanReport(input: Pick<PlanPostInput, "dir" | "pr" | "head" | "env" | "member">): { report: PrReport } | { refused: string } {
+  const file = join(input.dir, PR_PLAN_REPORT_FILE);
+  if (!existsSync(file)) return { refused: "the plan job wrote no report" };
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (err) {
+    return { refused: `the plan report does not read: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return { refused: "the plan report is not an object" };
+  const r = doc as Record<string, unknown>;
+  if (r.stage !== "plan") return { refused: `the report is not a plan report (stage ${JSON.stringify(r.stage)})` };
+  if (r.pr !== input.pr) return { refused: `the report is for pull request ${JSON.stringify(r.pr)}, not ${input.pr}` };
+  if (typeof r.head !== "string" || !SHA.test(r.head) || r.head !== input.head) return { refused: `the report is for head ${JSON.stringify(r.head)}, not ${input.head}` };
+  if (r.env !== input.env) return { refused: `the report is for environment ${JSON.stringify(r.env)}, not ${input.env}` };
+  if ((r.member ?? undefined) !== input.member) return { refused: `the report is for member ${JSON.stringify(r.member ?? null)}, not ${JSON.stringify(input.member ?? null)}` };
+  if (!Array.isArray(r.members) || !r.changeSet || typeof r.changeSet !== "object" || !r.selection || typeof r.selection !== "object" || !r.approval || typeof r.approval !== "object") {
+    return { refused: "the plan report is missing its members, change set, selection or approval" };
+  }
+  return { report: doc as PrReport };
+}
+
+/**
+ * The note for `report`, rendered here, with every `<!--` after the marker
+ * line written as `&lt;!--`, so the note carries no hidden marker but its own.
+ */
+export function planNoteFor(report: PrReport, forge: Pick<PrForge, "kind" | "host">, marker: string): string {
+  const note = renderPrNote(report, {
+    limit: forge.kind === "gitlab" ? GITLAB_NOTE_LIMIT : GITHUB_COMMENT_LIMIT,
+    approver: forgePrincipalOf(forge.kind, forge.host, "<your-login>"),
+  });
+  const at = note.indexOf("\n");
+  const rest = (at < 0 ? "" : note.slice(at + 1)).split("<!--").join("&lt;!--");
+  return `${marker}\n${rest}`;
+}
+
+const cut = (text: string, max = 140): string => (text.length > max ? `${text.slice(0, max - 3)}...` : text);
+
+/**
+ * Post the status and the note for the plan report under `input.dir`. A
+ * forge that refuses a call is a warning. A report that is missing or not
+ * the caller's sets a failed status and posts no note.
+ */
+export async function postPlanReport(input: PlanPostInput): Promise<PlanPostResult> {
+  const warnings: string[] = [];
+  const context = prStatusContext("plan", input.member);
+  const read = readPlanReport(input);
+  const failedJob = input.result === "failure" || input.result === "cancelled";
+  let state: PlanPostResult["state"];
+  let description: string;
+  let note: string | undefined;
+  let refused: string | undefined;
+  if ("refused" in read) {
+    refused = read.refused;
+    state = "failure";
+    description = cut(read.refused);
+  } else {
+    let report = read.report;
+    if (input.overdue) {
+      const { overdue: _forged, ...rest } = report;
+      const found = await input.overdue().catch(() => [] as PrOverdue[]);
+      report = (found.length > 0 ? { ...rest, overdue: found } : rest) as PrReport;
+    }
+    try {
+      state = prStatusState(report);
+      description = prStatusDescription(report);
+      // A member the change does not reach has nothing to say on the pull request (as pr-plan's own publish).
+      if (!(input.member && report.status === "nothing" && !report.overdue?.length)) note = planNoteFor(report, input.forge, prNoteMarker(input.env, input.member));
+    } catch (err) {
+      refused = `the plan report does not render: ${err instanceof Error ? err.message : String(err)}`;
+      state = "failure";
+      description = cut(refused);
+      note = undefined;
+    }
+    if (failedJob && state !== "failure") {
+      state = "failure";
+      description = cut(`the plan job failed; ${description}`);
+    }
+  }
+  try {
+    await input.forge.setStatus(input.head, { context, state, description: cut(description), ...(input.forge.runUrl ? { url: input.forge.runUrl } : {}) });
+  } catch (err) {
+    warnings.push(`could not set the ${context} status: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (note !== undefined) {
+    try {
+      await input.forge.upsertNote(input.pr, prNoteMarker(input.env, input.member), note);
+    } catch (err) {
+      warnings.push(`could not post the note on #${input.pr}: ${err instanceof Error ? err.message : String(err)}`);
+      note = undefined;
+    }
+  }
+  return { state, description: cut(description), noted: note !== undefined, ...(refused ? { refused } : {}), warnings };
+}