@intentius/chant 0.124.40 → 0.124.42

package/dist/pr-loop.d.ts

@@ -47,6 +47,7 @@
  * `identity.gates` entry covers every member.
  */
 import type { ChangeSetDocument } from "./change-set.js";
+import type { PrRequireOutcome } from "./pr-requires.js";
 /** The schema a pull-request report names in `$schema`. */
 export declare const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json";
 /** The read-contract version the report follows. */
@@ -63,6 +64,14 @@ export declare const PR_REPORT_WAVES_FLOOR = "0.124.32";
 export declare const PR_REPORT_PLANNED_OUTPUTS_FLOOR = "0.124.32";
 /** The chant that writes the `record` stage and the `recorded` status (#4168 step 1). */
 export declare const PR_REPORT_RECORD_FLOOR = "0.124.33";
+/** The first chant whose report can carry `hooks` (#4288). */
+export declare const PR_REPORT_HOOKS_FLOOR = "0.124.41";
+/** The first chant whose plan report can carry `overdue` (#4289). */
+export declare 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 declare 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 declare const PR_REPORT_BEFORE_MERGE_FLOOR = "0.124.42";
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export declare const PR_APPLY_GATE = "pr-apply";
 /**
@@ -152,6 +161,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`. */
 export interface PrRound {
@@ -232,7 +243,21 @@ 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
  * got to, and which approval it applied or waits under.
@@ -261,6 +286,62 @@ export interface PrWave {
     /** Why the approved change set does not cover the wave's plan, one line per member. */
     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.
@@ -324,6 +405,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[];
@@ -335,6 +424,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. */
 export declare function memberCounts(doc: Pick<ChangeSetDocument, "summary">, member: string): PrMemberCounts;

package/dist/pr-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-loop.d.ts","sourceRoot":"","sources":["../src/pr-loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pr-loop.d.ts","sourceRoot":"","sources":["../src/pr-loop.ts"],"names":[],"mappings":"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"}

package/dist/pr-loop.js

@@ -63,6 +63,14 @@ export const PR_REPORT_WAVES_FLOOR = "0.124.32";
 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";
 /**
@@ -143,11 +151,15 @@ function headline(report) {
         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;
@@ -161,6 +173,49 @@ function headline(report) {
             return `Applied ${report.members.filter((m) => m.status === "applied").length} of ${members}; ${report.members.filter((m) => m.status === "waiting").length} wait on an approval of the plan made after their upstream applied.`;
     }
 }
+/**
+ * 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) {
+    const byRoot = new Map();
+    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) {
+    const p = report.policy;
+    if (!p)
+        return [];
+    const at = `read at ${code(short(p.base))}`;
+    const each = (list) => list.map((f) => `- ${code(f.rule)}: ${f.message}`);
+    const out = [""];
+    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) {
     const whose = w.approval === "pull-request" ? "the pull request's" : "its own";
@@ -219,6 +274,8 @@ export function renderPrNote(report, options = {}) {
     ];
     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.`);
     }
@@ -227,6 +284,7 @@ export function renderPrNote(report, options = {}) {
         for (const m of report.members) {
             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
@@ -239,7 +297,18 @@ export function renderPrNote(report, options = {}) {
             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(", ")}.`);
     }
@@ -334,7 +403,16 @@ export function prStatusDescription(report) {
                 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;
         }
     }
@@ -345,6 +423,9 @@ export function prStatusState(report) {
     // #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"))

package/dist/pr-post.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 { type PrOverdue, type PrReport } from "./pr-loop.js";
+import { type PrForge } from "./pr-forge.js";
+/** The plan report's file under the report directory. */
+export declare 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[];
+}
+/**
+ * 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 declare function readPlanReport(input: Pick<PlanPostInput, "dir" | "pr" | "head" | "env" | "member">): {
+    report: PrReport;
+} | {
+    refused: string;
+};
+/**
+ * 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 declare function planNoteFor(report: PrReport, forge: Pick<PrForge, "kind" | "host">, marker: string): string;
+/**
+ * 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 declare function postPlanReport(input: PlanPostInput): Promise<PlanPostResult>;
+//# sourceMappingURL=pr-post.d.ts.map

package/dist/pr-post.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-post.d.ts","sourceRoot":"","sources":["../src/pr-post.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAmF,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3I,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5D,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CACtC;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC,GAAG;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAoB/I;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ3G;AAID;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAkDlF"}

package/dist/pr-post.js

@@ -0,0 +1,134 @@
+/**
+ * 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 } from "./pr-loop.js";
+import { forgePrincipalOf } from "./pr-forge.js";
+import { GITHUB_COMMENT_LIMIT, GITLAB_NOTE_LIMIT } from "./plan-summary.js";
+/** The plan report's file under the report directory. */
+export const PR_PLAN_REPORT_FILE = "pr-plan.json";
+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) {
+    const file = join(input.dir, PR_PLAN_REPORT_FILE);
+    if (!existsSync(file))
+        return { refused: "the plan job wrote no report" };
+    let doc;
+    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;
+    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 };
+}
+/**
+ * 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, forge, marker) {
+    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, max = 140) => (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) {
+    const warnings = [];
+    const context = prStatusContext("plan", input.member);
+    const read = readPlanReport(input);
+    const failedJob = input.result === "failure" || input.result === "cancelled";
+    let state;
+    let description;
+    let note;
+    let refused;
+    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(() => []);
+            report = (found.length > 0 ? { ...rest, overdue: found } : rest);
+        }
+        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 };
+}

package/dist/pr-requires.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The requires checks of an apply before merge (#4301, ws-106): the pull
+ * request is approved, mergeable, undiverged and its checks passed, each
+ * asked of the forge through its {@link PrForge} method. All four must pass.
+ *
+ * The checks are terragucci's `apply.requires` (comment-apply.ts:781-860 at
+ * INTENTIUS/terragucci e6cb431), with no setting to drop one. A check the
+ * forge has not settled, such as GitHub working out whether a pull request
+ * can merge, is asked again a few times before it counts as unmet.
+ *
+ * Like ./pr-forge.ts this imports nothing beyond it, so a product bundles it
+ * without the TypeScript toolchain.
+ */
+import type { PrForge, PrRequireResult } from "./pr-forge.js";
+/** The four checks, in the order they run and the report lists them. */
+export declare const PR_APPLY_REQUIRES: readonly ["approved", "mergeable", "undiverged", "checks"];
+export type PrApplyRequire = (typeof PR_APPLY_REQUIRES)[number];
+/** One check as the pull-request report's `beforeMerge.requires` holds it. */
+export interface PrRequireOutcome extends PrRequireResult {
+    name: PrApplyRequire;
+}
+export interface PrRequiresOptions {
+    /** Status names the `checks` require leaves out: the apply's own. */
+    ignore?: readonly string[];
+    /** How many times a pending check is asked in all. Default 5. */
+    reads?: number;
+    /** The wait between reads. Default 3 seconds. */
+    wait?: (ms: number) => Promise<void>;
+}
+/**
+ * Ask `forge` each of the four checks for pull request `pr` at `head`. A
+ * forge client without a method, or a call that throws, gives an unmet
+ * check with the reason, so nothing applies on a check nobody made.
+ */
+export declare function checkPrRequires(forge: PrForge, pr: number, head: string, opts?: PrRequiresOptions): Promise<PrRequireOutcome[]>;
+/** The unmet checks as one line, or null when all four passed. */
+export declare function unmetRequires(outcomes: readonly PrRequireOutcome[]): string | null;
+//# sourceMappingURL=pr-requires.d.ts.map

package/dist/pr-requires.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-requires.d.ts","sourceRoot":"","sources":["../src/pr-requires.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE3D,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,YAAI,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,CAAU,CAAC;AAE5F,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,8EAA8E;AAC9E,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAKD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA6BzI;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,GAAG,IAAI,CAIlF"}

package/dist/pr-requires.js

@@ -0,0 +1,48 @@
+/** The four checks, in the order they run and the report lists them. */
+export const PR_APPLY_REQUIRES = ["approved", "mergeable", "undiverged", "checks"];
+const READS = 5;
+const WAIT_MS = 3000;
+/**
+ * Ask `forge` each of the four checks for pull request `pr` at `head`. A
+ * forge client without a method, or a call that throws, gives an unmet
+ * check with the reason, so nothing applies on a check nobody made.
+ */
+export async function checkPrRequires(forge, pr, head, opts = {}) {
+    const wait = opts.wait ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const reads = Math.max(1, opts.reads ?? READS);
+    const ask = {
+        approved: forge.prApproved ? () => forge.prApproved(pr, head) : undefined,
+        mergeable: forge.prMergeable ? () => forge.prMergeable(pr, head) : undefined,
+        undiverged: forge.prUndiverged ? () => forge.prUndiverged(pr, head) : undefined,
+        checks: forge.prChecksPassed ? () => forge.prChecksPassed(pr, head, opts.ignore ?? []) : undefined,
+    };
+    const out = [];
+    for (const name of PR_APPLY_REQUIRES) {
+        const call = ask[name];
+        if (!call) {
+            out.push({ name, passed: false, reason: `this ${forge.kind} client cannot say` });
+            continue;
+        }
+        let result;
+        for (let read = 1;; read++) {
+            try {
+                result = await call();
+            }
+            catch (err) {
+                result = { passed: false, reason: `could not ask ${forge.kind}: ${err instanceof Error ? err.message : String(err)}` };
+            }
+            if (result.passed || !result.pending || read >= reads)
+                break;
+            await wait(WAIT_MS);
+        }
+        out.push({ name, ...result });
+    }
+    return out;
+}
+/** The unmet checks as one line, or null when all four passed. */
+export function unmetRequires(outcomes) {
+    const unmet = outcomes.filter((o) => !o.passed);
+    if (unmet.length === 0)
+        return null;
+    return unmet.map((o) => `${o.name}: ${o.reason}`).join("; ");
+}