@intentius/chant 0.124.43 → 0.124.45

package/src/components/pr-environment.ts

@@ -32,14 +32,19 @@
  *
  * terragucci's `ephemeral.ts` gives each copy a suffixed Terraform state key.
  * That part is Terraform's own and stays there; chant keys ownership on the
- * marker its lexicons stamp and read back (`../lifecycle/teardown.ts`).
+ * marker its lexicons stamp and read back (`../lifecycle/teardown.ts`). A
+ * product supplies the rest as adapters (#4330): its plan and apply
+ * (`./pr-env-run.ts`), and a teardown for what no lexicon tears down
+ * ({@link PrEnvTeardownAdapter}), which reads the marker back from the copy
+ * as a lexicon does.
  */
 
 import { environmentEndpoint, environmentName, isEnvironmentPattern, isOwnershipParamRef, matchesDeclaredEnvironment, resolveOwnershipStack, type ChantConfig, type EnvironmentDeclaration } from "../config";
 import type { OwnershipMarker } from "../ownership";
 import { executeTeardown, planTeardown, type TeardownPlan, type TeardownPlanEntry, type TeardownReport } from "../lifecycle/teardown";
-import type { ObservationLexicon } from "../lexicon";
+import type { ObservationLexicon, TeardownCandidate, TeardownEnumeration, TeardownExecution } from "../lexicon";
 import { applyLiveEndpoint } from "../live-endpoint";
+import type { ComponentEnvironmentDeclaration } from "./component";
 
 /** The gate a pull request's environment waits on, under the pull request's op `pr-<n>`. */
 export const PR_ENV_GATE = "pr-env";
@@ -167,6 +172,35 @@ export function derivePrEnvironment(config: ChantConfig, template: string, pr: n
   return { env, template, stack, param: own.param, environments, ...(endpoint ? { endpoint } : {}) };
 }
 
+/** The placeholder a template's site URL or domain names the environment with (#4330). */
+export const PR_ENV_SITE_PLACEHOLDER = "{env}";
+
+/**
+ * A component's site in `env`, a pull request's environment, carried over
+ * from its site in `template` (#4330). An entry the component declares for
+ * `env` itself wins. Otherwise the template's runtime and lifecycle remote
+ * carry over as they are. Its URL and domain carry over only when they name
+ * the environment with `{env}`, which becomes `pr-<n>`: a literal URL or
+ * domain is the template's own release, so it is left out rather than
+ * pointing pr-<n> at it. Undefined when neither is declared.
+ */
+export function prEnvironmentSite(declared: readonly ComponentEnvironmentDeclaration[] | undefined, template: string, env: string): ComponentEnvironmentDeclaration | undefined {
+  const own = declared?.find((d) => d.name === env);
+  if (own) return { ...own };
+  const from = declared?.find((d) => d.name === template);
+  if (!from) return undefined;
+  const named = (v: string | undefined): string | undefined => (v && v.includes(PR_ENV_SITE_PLACEHOLDER) ? v.split(PR_ENV_SITE_PLACEHOLDER).join(env) : undefined);
+  const url = named(from.url);
+  const domain = named(from.domain);
+  return {
+    name: env,
+    ...(from.runtime ? { runtime: from.runtime } : {}),
+    ...(url ? { url } : {}),
+    ...(domain ? { domain } : {}),
+    ...(from.lifecycle ? { lifecycle: from.lifecycle } : {}),
+  };
+}
+
 // ── records ────────────────────────────────────────────────────────────────
 
 /** One line of `_pr-envs/records.jsonl`: an apply, or a teardown. */
@@ -186,6 +220,12 @@ export interface PrEnvRecord {
   commit: string;
   /** The components applied (up) or the lexicons torn down (down). */
   components: string[];
+  /**
+   * Up (#4330): where each component's copy lives, by component, as the
+   * adapter that applied it says (a Terraform root's suffixed state key).
+   * A teardown adapter reads it back from the live environment.
+   */
+  locations?: Record<string, string>;
   /** The change-set digest applied; empty for a teardown. */
   planDigest: string;
   /** `incomplete`: a teardown that left something, so the environment stays live and the sweep tries again. */
@@ -229,6 +269,8 @@ export interface LivePrEnvironment {
   commit: string;
   /** Every component an apply of it ever touched. */
   components: string[];
+  /** Where each component's copy lives, merged over every up (#4330). */
+  locations?: Record<string, string>;
   applied: string;
   expiresAt: string;
   /** Its last teardown left something, so the sweep tries again. */
@@ -245,6 +287,7 @@ export function livePrEnvironments(records: readonly PrEnvRecord[]): Map<string,
   for (const r of records) {
     if (r.kind === "up") {
       const was = live.get(r.env);
+      const locations = { ...(was?.locations ?? {}), ...(r.locations ?? {}) };
       live.set(r.env, {
         pr: r.pr,
         env: r.env,
@@ -253,6 +296,7 @@ export function livePrEnvironments(records: readonly PrEnvRecord[]): Map<string,
         marker: { ...r.marker },
         commit: r.commit,
         components: [...new Set([...(was?.components ?? []), ...r.components])],
+        ...(Object.keys(locations).length > 0 ? { locations } : {}),
         applied: r.timestamp,
         expiresAt: r.expiresAt ?? r.timestamp,
       });
@@ -302,12 +346,61 @@ export function ownedEntries(plan: TeardownPlan, marker: OwnershipMarker): { pla
   return { plan: { ...plan, entries: plan.entries.filter(owns) }, dropped: plan.entries.filter((e) => !owns(e)) };
 }
 
+/**
+ * A teardown a product supplies for what no lexicon tears down (#4330), such
+ * as a Terraform root's copy under a suffixed state key: chant has no
+ * Terraform runner, so terragucci supplies this. It takes part in the same
+ * two halves a lexicon's teardown does (`../lifecycle/teardown.ts`): `owned`
+ * names what the environment owns, each with the marker read back from it,
+ * and `teardown` deletes the candidates chant hands back. Every candidate
+ * whose marker is not exactly `{ stack, env: "pr-<n>" }` is dropped before
+ * `teardown` sees it, and a candidate it says nothing about counts as failed.
+ */
+export interface PrEnvTeardownAdapter {
+  /** The name outcomes are attributed to, as a lexicon's are. */
+  name: string;
+  /**
+   * The lexicons this adapter tears down in place of (`terraform`). Their own
+   * teardown is left out, so a lexicon with no teardown execution does not
+   * leave the environment incomplete when the adapter covers it.
+   */
+  lexicons?: string[];
+  /** What the environment owns: candidates with their read-back markers, and what could not be read. */
+  owned(input: PrEnvTeardownAdapterInput): Promise<TeardownEnumeration>;
+  /** Delete the candidates: one outcome per candidate, keyed by name. */
+  teardown(input: PrEnvTeardownAdapterInput & { candidates: TeardownCandidate[] }): Promise<TeardownExecution>;
+}
+
+/** What a {@link PrEnvTeardownAdapter} is told about the environment. */
+export interface PrEnvTeardownAdapterInput {
+  /** `pr-<n>`. */
+  environment: string;
+  /** The marker everything is selected on. */
+  marker: OwnershipMarker;
+  /** The environment as its records say it stands: the commit last applied, its components and their locations. */
+  live: LivePrEnvironment;
+}
+
+/** An adapter in the shape `planTeardown` and `executeTeardown` call: a lexicon with only its two teardown halves. */
+function adapterLexicon(adapter: PrEnvTeardownAdapter, live: LivePrEnvironment): ObservationLexicon {
+  const shaped: Pick<ObservationLexicon, "name" | "teardownOwned" | "executeTeardown"> = {
+    name: adapter.name,
+    teardownOwned: (o) => adapter.owned({ environment: o.environment, marker: o.marker, live }),
+    executeTeardown: (o) => adapter.teardown({ environment: o.environment, marker: o.marker, live, candidates: o.candidates }),
+  };
+  return shaped as ObservationLexicon;
+}
+
 /** What {@link tearDownPrEnvironment} needs. */
 export interface PrEnvTeardownInput {
   pr: number;
   live: LivePrEnvironment;
-  config: ChantConfig;
-  plugins: ObservationLexicon[];
+  /** The project's config, for its environments and stacks. Absent: a product with no chant.config.ts, whose adapters do the teardown. */
+  config?: ChantConfig;
+  /** The lexicons whose teardown runs. Default none. */
+  plugins?: ObservationLexicon[];
+  /** Teardowns a product supplies (#4330), run after the lexicons'. */
+  adapters?: PrEnvTeardownAdapter[];
   warn?: (message: string) => void;
 }
 
@@ -316,18 +409,30 @@ export interface PrEnvTeardownInput {
  * before any read when {@link teardownRefusal} says so; otherwise the live
  * resources under the record's marker are planned, every entry whose marker
  * is not exactly `{ stack, env: "pr-<n>" }` is dropped ({@link ownedEntries}),
- * and only the rest go to each lexicon's teardown. The endpoint is the one
- * the environment was applied at: its own `pr-*` entry's, else the template's.
+ * and only the rest go to each lexicon's or adapter's teardown. The endpoint
+ * is the one the environment was applied at: its own `pr-*` entry's, else the
+ * template's. A lexicon an adapter covers (`lexicons`) is left out.
  */
 export async function tearDownPrEnvironment(input: PrEnvTeardownInput): Promise<{ refusal: string } | { report: TeardownReport; dropped: number; marker: { stack: string; env: string } }> {
-  const { pr, live, config, plugins } = input;
+  const { pr, live } = input;
+  const config = input.config ?? {};
   const refusal = teardownRefusal(pr, live, config.environments);
   if (refusal) return { refusal };
+  const adapters = input.adapters ?? [];
+  const covered = new Set(adapters.flatMap((a) => a.lexicons ?? []));
+  const names = new Set<string>();
+  for (const a of adapters) {
+    if (names.has(a.name)) return { refusal: `two teardown adapters are named ${a.name}, so their outcomes could not be told apart; nothing was torn down` };
+    names.add(a.name);
+  }
+  const lexicons = (input.plugins ?? []).filter((x) => !covered.has(x.name));
+  if (lexicons.some((x) => names.has(x.name))) return { refusal: `a teardown adapter shares its name with a lexicon (${[...names].filter((n) => lexicons.some((x) => x.name === n)).join(", ")}), so their outcomes could not be told apart; nothing was torn down` };
   const env = prEnvironmentName(pr);
   const marker = { stack: live.marker.stack, env };
   const endpoint = environmentEndpoint(config.environments, env) ?? environmentEndpoint(config.environments, live.template);
-  const applied = applyLiveEndpoint(endpoint ? [{ name: env, endpoint }] : [], env, plugins.filter((x) => x.teardownOwned || x.describeResources || x.executeTeardown));
+  const applied = applyLiveEndpoint(endpoint ? [{ name: env, endpoint }] : [], env, lexicons.filter((x) => x.teardownOwned || x.describeResources || x.executeTeardown));
   if (applied.notice) input.warn?.(applied.notice);
+  const plugins = [...lexicons, ...adapters.map((a) => adapterLexicon(a, live))];
   const deployedStacks = (config.stacks ?? []).map((s) => ({ name: s.name, ...(s.region ? { region: s.region } : {}) }));
   try {
     const planned = await planTeardown({ environment: env, stack: marker.stack, plugins, ...(deployedStacks.length > 0 ? { deployedStacks } : {}) });
@@ -405,6 +510,7 @@ export function acceptHandedRecord(raw: unknown, check: HandedRecordCheck): { re
       marker: { stack: r.marker.stack, env },
       commit: check.head,
       components: [...r.components],
+      ...(handedLocations(r.locations) ? { locations: handedLocations(r.locations)! } : {}),
       planDigest: typeof r.planDigest === "string" ? r.planDigest : "",
       result: r.result,
       by: check.by,
@@ -417,6 +523,21 @@ export function acceptHandedRecord(raw: unknown, check: HandedRecordCheck): { re
   };
 }
 
+/** A handed-on report row's site, kept only as its three strings. */
+function handedSite(raw: unknown): PrEnvReportRow["site"] | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const r = raw as Record<string, unknown>;
+  const site = Object.fromEntries((["runtime", "url", "domain"] as const).filter((k) => typeof r[k] === "string").map((k) => [k, r[k] as string]));
+  return Object.keys(site).length > 0 ? site : undefined;
+}
+
+/** A handed-on record's locations, kept only as a map of strings to strings. */
+function handedLocations(raw: unknown): Record<string, string> | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
+  const out = Object.fromEntries(Object.entries(raw as Record<string, unknown>).filter((e): e is [string, string] => typeof e[1] === "string"));
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /**
  * The report `pr-env up` handed on, checked as data before the post job
  * renders a note from it: an `up` report for this pull request's `pr-<n>`.
@@ -445,7 +566,16 @@ export function handedPrEnvReport(raw: unknown, check: { pr: number; head: strin
       status: r.status,
       ...(typeof r.message === "string" ? { message: r.message } : {}),
       ...(typeof r.endpoint === "string" ? { endpoint: r.endpoint } : {}),
-      components: (Array.isArray(r.components) ? r.components : []).map((c) => ({ component: str(c?.component), status: str(c?.status), create: num(c?.create), update: num(c?.update), replace: num(c?.replace), delete: num(c?.delete) })),
+      components: (Array.isArray(r.components) ? r.components : []).map((c) => ({
+        component: str(c?.component),
+        status: str(c?.status),
+        create: num(c?.create),
+        update: num(c?.update),
+        replace: num(c?.replace),
+        delete: num(c?.delete),
+        ...(typeof c?.location === "string" ? { location: c.location } : {}),
+        ...(handedSite(c?.site) ? { site: handedSite(c?.site)! } : {}),
+      })),
       ...(Array.isArray(r.approvedBy) ? { approvedBy: r.approvedBy.filter((a): a is string => typeof a === "string") } : {}),
     },
   };
@@ -453,6 +583,20 @@ export function handedPrEnvReport(raw: unknown, check: { pr: number; head: strin
 
 // ── the note ───────────────────────────────────────────────────────────────
 
+/** One component's row in the report and the note. */
+export interface PrEnvReportRow {
+  component: string;
+  status: string;
+  create: number;
+  update: number;
+  replace: number;
+  delete: number;
+  /** Where its copy lives, as the adapter says (#4330). */
+  location?: string;
+  /** Its site in pr-<n>: the runtime, URL and domain carried over from the template's (#4330, {@link prEnvironmentSite}). */
+  site?: { runtime?: string; url?: string; domain?: string };
+}
+
 /** What one `pr-env up` or `down` run came to, as `pr-env.json` holds it. */
 export interface PrEnvReport {
   stage: "up" | "down";
@@ -467,7 +611,7 @@ export interface PrEnvReport {
   status: "applied" | "nothing" | "waiting" | "changed" | "plan-failed" | "failed" | "refused" | "destroyed" | "incomplete" | "absent";
   message?: string;
   endpoint?: string;
-  components: Array<{ component: string; status: string; create: number; update: number; replace: number; delete: number }>;
+  components: PrEnvReportRow[];
   approvedBy?: string[];
   expiresAt?: string;
   outcomes?: PrEnvRecord["outcomes"];
@@ -505,8 +649,11 @@ export function renderPrEnvNote(r: PrEnvReport, approver = "<you>"): string {
   }
   if (r.message) out.push("", `> ${r.message.split("\n").join("\n> ")}`);
   if (r.components.length > 0) {
-    out.push("", "| Component | Status | Create | Update | Replace | Delete |", "|---|---|---:|---:|---:|---:|");
-    for (const c of r.components) out.push(`| ${code(c.component)} | ${c.status} | ${c.create} | ${c.update} | ${c.replace} | ${c.delete} |`);
+    // #4330: a Where column when a row has a URL or a location, as code: env-up ran the change's code, so the post job does not link it.
+    const at = (c: PrEnvReportRow): string | undefined => c.site?.url ?? c.site?.domain ?? c.location;
+    const where = r.components.some((c) => at(c));
+    out.push("", `| Component | Status | Create | Update | Replace | Delete |${where ? " Where |" : ""}`, `|---|---|---:|---:|---:|---:|${where ? "---|" : ""}`);
+    for (const c of r.components) out.push(`| ${code(c.component)} | ${c.status} | ${c.create} | ${c.update} | ${c.replace} | ${c.delete} |${where ? ` ${at(c) ? code(at(c)!) : ""} |` : ""}`);
   }
   if (r.digest) out.push("", `Plan digest: ${code(r.digest)}${r.approvedBy?.length ? `, approved by ${r.approvedBy.map(code).join(", ")}` : ""}`);
   out.push("", `${code(r.env)} is not a release target: releases come from green commits.`);

package/src/components/pr-pipeline.ts

@@ -89,7 +89,7 @@ import { EMPTY_TREE_SHA } from "./changed-files";
 import { layerWaves } from "../gated-waves";
 import type { DriverComponent } from "./driver";
 import type { GatedWavePipelineOptions } from "./gated-wave-pipeline";
-import type { PipelineCloudIdentity } from "../ci-identity";
+import type { CloudTradeSpec, PipelineCloudIdentity } from "../ci-identity";
 
 /** The variable `chant ci run` reads its runner key from (`RUNNER_KEY_ENV` in ../workspace/ci-green.ts). */
 const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
@@ -211,6 +211,15 @@ export interface PrLoopPipelineOptions {
    * ({@link prEnvJobs}). Set from `--pr-env` beside `--pr-loop`. Default false.
    */
   prEnvironment?: boolean;
+  /**
+   * The cloud identity a pull request environment's jobs take (#4330), from
+   * `ci.identity.cloud` (`resolvePrEnvCloudIdentity` in ../ci-identity.ts):
+   * the apply identity of a rule that names the pull request environments.
+   * env-up, env-down and env-sweep trade their OIDC token for it before the
+   * checkout, and env-up's later steps start without the token variables.
+   * Absent: they request no OIDC token.
+   */
+  prEnvIdentity?: CloudTradeSpec;
 }
 
 /** One job's command and the forge values it reads, as environment variables for its step. */

package/src/op/op-waves.ts

@@ -76,6 +76,7 @@
 
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
 import type { CiRunner } from "../ci-jobs";
+import type { CloudTradeSpec } from "../ci-identity";
 import { gatePointProblems, type GatePoint } from "./gate-point";
 import { quorumProblems, type GateQuorumRule } from "./gate-quorum";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
@@ -261,6 +262,13 @@ export interface OpWaveJobGroup {
    * is requested.
    */
   idTokens?: Record<string, string>;
+  /**
+   * The cloud identities the group's jobs trade the job's OIDC token for
+   * (#4332), in place of the wave's: a {@link CloudTradeSpec}, as
+   * `cloudIdentityWave` in ../ci-identity.ts gives a group its apply
+   * identities. The trade runs before the checkout.
+   */
+  cloud?: CloudTradeSpec;
 }
 
 /** One wave: runs that apply together, behind one gate. */
@@ -321,6 +329,15 @@ export interface OpWave {
    * job's, and a group's own replace them.
    */
   idTokens?: Record<string, string>;
+  /**
+   * The cloud identities this wave's jobs trade the job's OIDC token for
+   * (#4332), before the checkout: a {@link CloudTradeSpec}. With `jobs`,
+   * the deciding job's, and a group's own `cloud` replaces it.
+   * `cloudIdentityWave` in ../ci-identity.ts gives the deciding job every
+   * plan identity of the wave's targets. Each later step of the job starts
+   * without the variables a token is requested with.
+   */
+  cloud?: CloudTradeSpec;
   /**
    * Split the wave's apply into job groups (#3914): a deciding job, which
    * runs with the wave's own settings, plans every run and decides the gate,
@@ -644,6 +661,7 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
     }
     if (wave.runner !== undefined) assertOpWaveRunner(where, `wave "${wave.name}" runner`, wave.runner);
     if (wave.idTokens !== undefined) assertOpWaveIdTokens(where, `wave "${wave.name}" idTokens`, wave.idTokens);
+    if (wave.cloud !== undefined) assertOpWaveCloud(where, `wave "${wave.name}" cloud`, wave.cloud);
     if (wave.jobs !== undefined) assertOpWaveJobGroups(where, wave);
     if (wave.discover !== undefined && typeof wave.discover !== "boolean") throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
     if (wave.rest !== undefined && typeof wave.rest !== "boolean") throw new Error(`${where}: wave "${wave.name}" has rest ${JSON.stringify(wave.rest)}; use true or false.`);
@@ -684,6 +702,24 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+/** The key each cloud of a `cloud` trade names its identity under (`IDENTITY_KEY` in ../ci-identity.ts, kept here so this module imports none of it). */
+const CLOUD_IDENTITY_KEY: Record<string, string> = { aws: "role", gcp: "serviceAccount", azure: "clientId" };
+
+/** Refuse a `cloud` (#4332) the trade could not run: an unknown cloud, one that names no identity, or no audience. */
+function assertOpWaveCloud(where: string, field: string, cloud: unknown): void {
+  if (cloud === null || typeof cloud !== "object" || Array.isArray(cloud) || Object.keys(cloud).length === 0) throw new Error(`${where}: ${field} must name one or more of aws, gcp and azure.`);
+  for (const [name, c] of Object.entries(cloud as Record<string, unknown>)) {
+    const key = CLOUD_IDENTITY_KEY[name];
+    if (!key) throw new Error(`${where}: ${field}.${name} is not a cloud; use aws, gcp or azure.`);
+    const t = c as Record<string, unknown> | null;
+    const targets = t?.targets;
+    const targetsOk = targets === undefined || (Array.isArray(targets) && targets.every((e) => e && Array.isArray((e as { targets?: unknown }).targets) && typeof (e as Record<string, unknown>)[key] === "string"));
+    if (!t || typeof t.audience !== "string" || !targetsOk || (typeof t[key] !== "string" && !(Array.isArray(targets) && targets.length > 0))) {
+      throw new Error(`${where}: ${field}.${name} must give an audience and a ${key}, or targets each with targets and a ${key}, as cloudIdentityWave gives them.`);
+    }
+  }
+}
+
 /** Refuse a `runner` no forge could read (#3914). */
 function assertOpWaveRunner(where: string, field: string, runner: unknown): void {
   const labels = (value: unknown): boolean => Array.isArray(value) && value.length > 0 && value.every((l) => typeof l === "string" && l.trim() !== "");
@@ -723,7 +759,7 @@ function assertOpWaveJobGroups(where: string, wave: OpWave): void {
     if (group.name === "decide" || /^share-\d+$/.test(group.name)) throw new Error(`${where}: ${field} is named like the wave's own jobs (decide, share-<i>); name it another way.`);
     if (names.has(group.name)) throw new Error(`${where}: ${at} names job group "${group.name}" twice.`);
     names.add(group.name);
-    const known = new Set(["name", "runs", "shares", "runner", "environment", "variables", "setup", "idTokens"]);
+    const known = new Set(["name", "runs", "shares", "runner", "environment", "variables", "setup", "idTokens", "cloud"]);
     const extra = Object.keys(group).find((key) => !known.has(key));
     if (extra !== undefined) throw new Error(`${where}: ${field}.${extra} is not a setting; a job group takes ${[...known].join(", ")}.`);
     if (!Array.isArray(group.runs) || group.runs.length === 0 || !group.runs.every((r) => typeof r === "string" && r.trim() !== "")) {
@@ -733,6 +769,7 @@ function assertOpWaveJobGroups(where: string, wave: OpWave): void {
     if (!Number.isInteger(shares) || shares < 1) throw new Error(`${where}: ${field} has shares ${group.shares}; use a whole number from 1.`);
     if (group.runner !== undefined) assertOpWaveRunner(where, `${field} runner`, group.runner);
     if (group.idTokens !== undefined) assertOpWaveIdTokens(where, `${field} idTokens`, group.idTokens);
+    if (group.cloud !== undefined) assertOpWaveCloud(where, `${field} cloud`, group.cloud);
     if (group.variables !== undefined && (group.variables === null || typeof group.variables !== "object" || Array.isArray(group.variables) || !Object.values(group.variables).every((v) => typeof v === "string"))) {
       throw new Error(`${where}: ${field} variables must be { "<name>": "<value>" }.`);
     }

package/src/pr-forge-bundle.test.ts

@@ -34,7 +34,7 @@ describe("the pr-forge bundle", () => {
       expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
     }
     expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual(["packages/core/src/pr-forge.ts"]);
-    // About 50 KB today, after the pull request authors (#4000), pullRequestOpen for target locks (#4293), the four requires checks of an apply before merge (#4301) and the approver filter (#4337).
+    // About 50 KB today, after the pull request authors (#4000), pullRequestOpen for target locks (#4293), the four requires checks of an apply before merge (#4301) the approver filter (#4337) and the approved fields (#4287).
     expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(52 * 1024);
   });
 });

package/src/pr-forge.ts

@@ -420,8 +420,11 @@ export interface PrForge {
    * counts when it came after the merge request's latest push, read from its
    * system notes, and never from the token's own user. `approvers` narrows
    * who counts (#4337), and a refusal names each approver left out and why.
+   * The result also lists who counted and who was left out (#4287), so a
+   * caller never parses `reason`. On GitLab the newest diff version must be
+   * of `head`, or the check is pending.
    */
-  prApproved?(pr: number, head: string, approvers?: PrApproverFilter): Promise<PrRequireResult>;
+  prApproved?(pr: number, head: string, approvers?: PrApproverFilter): Promise<PrApprovalResult>;
   /**
    * The forge says `pr` merges as it stands: no conflicts, and on GitHub no
    * branch protection blocking it. Pending while the forge works it out. On
@@ -481,19 +484,26 @@ async function countApprovers(
   authors: ReadonlySet<string>,
   filter: PrApproverFilter | undefined,
   rule: (login: string) => Promise<string | undefined>,
-): Promise<{ by: string[]; not: string[] }> {
+): Promise<{ by: string[]; not: PrExcludedApprover[] }> {
   const by: string[] = [];
-  const not: string[] = [];
+  const not: PrExcludedApprover[] = [];
   for (const login of approved) {
     const why = authors.has(login) ? `${login} is one of its authors` : (excludedWhy(filter, login) ?? (filter?.forgeRule ? await rule(login) : undefined));
-    if (why) not.push(why);
+    if (why) not.push({ login, reason: why });
     else by.push(login);
   }
   return { by, not };
 }
 
-/** A refusal for no approver counted, naming each one left out. */
-const noApprover = (line: string, not: readonly string[]): PrRequireResult => refuse(not.length > 0 ? `${line}: ${not.join("; ")}` : line);
+/** The approved verdict over who counted: a pass naming them, or a refusal naming each one left out and why. */
+function approvalVerdict(by: string[], not: PrExcludedApprover[], passLine: string, noneLine: string): PrApprovalResult {
+  const fields = { approvers: by, excluded: not };
+  if (by.length > 0) return { ...pass(`${passLine} by ${by.join(", ")}`), ...fields };
+  return { ...refuse(not.length > 0 ? `${noneLine}: ${not.map((n) => n.reason).join("; ")}` : noneLine), ...fields };
+}
+
+/** An approved refusal before anyone was counted. */
+const notCounted = (r: PrRequireResult): PrApprovalResult => ({ ...r, approvers: [], excluded: [] });
 
 /** GitLab's access level for Developer, the least that may push. */
 const GITLAB_DEVELOPER = 30;
@@ -510,6 +520,18 @@ export interface PrRequireResult {
   reason: string;
 }
 
+/**
+ * What {@link PrForge.prApproved} found (#4287). `approvers` and `excluded`
+ * are empty when it refused before counting, such as on a moved head or a
+ * request for changes.
+ */
+export interface PrApprovalResult extends PrRequireResult {
+  /** The logins whose approval of the head counted, sorted. */
+  approvers: string[];
+  /** The logins that approved and did not count, each with the reason the refusal gives. */
+  excluded: PrExcludedApprover[];
+}
+
 const short = (sha: string | undefined): string => (sha ?? "nothing").slice(0, 8);
 const pass = (reason: string): PrRequireResult => ({ passed: true, reason });
 const refuse = (reason: string, pending = false): PrRequireResult => ({ passed: false, ...(pending ? { pending: true } : {}), reason });
@@ -867,7 +889,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     async prApproved(pr, head, approvers) {
       const got = await api.call("GET", `${repo}/pulls/${pr}`);
       const at = headOf(got);
-      if (at !== head) return moved(`pull request ${pr}`, head, at);
+      if (at !== head) return notCounted(moved(`pull request ${pr}`, head, at));
       // A reviewer's newest deciding review stands, as in approvers; an approval counts only of this head.
       const standing = new Map<string, { state: string; commit?: string; official?: boolean }>();
       for (const r of await api.list(`${repo}/pulls/${pr}/reviews`, pageParams, pageSize)) {
@@ -879,7 +901,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
         standing.set(login, { state, ...(commit ? { commit } : {}), ...(typeof r.official === "boolean" ? { official: r.official } : {}) });
       }
       const changes = [...standing].filter(([, r]) => r.state === "CHANGES_REQUESTED" || r.state === "REQUEST_CHANGES").map(([l]) => l).sort();
-      if (changes.length > 0) return refuse(`${changes.join(", ")} asked for changes`);
+      if (changes.length > 0) return notCounted(refuse(`${changes.join(", ")} asked for changes`));
       const authors = new Set(await authorsOf(pr));
       const approved = [...standing].filter(([, r]) => r.state === "APPROVED" && r.commit === head).map(([l]) => l).sort();
       const rule = async (login: string): Promise<string | undefined> => {
@@ -895,8 +917,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
         return p.some((x) => x !== undefined && GITHUB_WRITERS.has(x)) ? undefined : `${login} has no write access`;
       };
       const { by, not } = await countApprovers(approved, authors, approvers, rule);
-      if (by.length === 0) return noApprover(`no reviewer other than its authors approved its head ${short(head)}`, not);
-      return pass(`approved at ${short(head)} by ${by.join(", ")}`);
+      return approvalVerdict(by, not, `approved at ${short(head)}`, `no reviewer other than its authors approved its head ${short(head)}`);
     },
     async prMergeable(pr, head) {
       const got = await api.call("GET", `${repo}/pulls/${pr}`);
@@ -1262,14 +1283,21 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
     async prApproved(mr, head, approvers) {
       const got = await api.call("GET", `${notes}/${mr}`);
       const at = isObject(got) ? str(got.sha) : undefined;
-      if (at !== head) return moved(`merge request !${mr}`, head, at);
+      if (at !== head) return notCounted(moved(`merge request !${mr}`, head, at));
       // The token's own user approves for the pipeline, never as a reviewer.
       const me = await api.call("GET", "/user");
       const self = isObject(me) ? str(me.username) : undefined;
-      if (!self) return refuse("GitLab did not say which user the job's token acts as, so no approval counts");
-      // An approval counts once it came after the latest push: the newest version of the diff.
+      if (!self) return notCounted(refuse("GitLab did not say which user the job's token acts as, so no approval counts"));
+      // An approval counts once it came after the latest push: the newest version of the diff, which must be of head.
       const versions = await api.call("GET", `${notes}/${mr}/versions`);
-      const since = Math.max(-Infinity, ...(Array.isArray(versions) ? versions : []).map((v) => Date.parse((isObject(v) ? str(v.created_at) : undefined) ?? "")).filter(Number.isFinite));
+      let since = -Infinity;
+      let latest: string | undefined;
+      for (const v of Array.isArray(versions) ? versions : []) {
+        const when = Date.parse((isObject(v) ? str(v.created_at) : undefined) ?? "");
+        if (Number.isFinite(when) && when > since) [since, latest] = [when, isObject(v) ? str(v.head_commit_sha) : undefined];
+      }
+      // GitLab records a push's version after it moves the head, so an older one is asked again.
+      if (latest !== head) return notCounted(refuse(`merge request !${mr}'s newest diff version is of ${short(latest)}, not ${short(head)}`, true));
       const said = new Map<string, { what: string; at: number; id?: number }>();
       for (const n of await api.list(`${notes}/${mr}/notes?sort=asc&order_by=created_at`, pageParams, 100)) {
         if (!isObject(n) || n.system !== true) continue;
@@ -1283,7 +1311,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         if (!before || when >= before.at) said.set(who, { what, at: when, ...(id !== undefined ? { id } : {}) });
       }
       const changes = [...said].filter(([, v]) => v.what === "changes").map(([w]) => w).sort();
-      if (changes.length > 0) return refuse(`${changes.join(", ")} requested changes`);
+      if (changes.length > 0) return notCounted(refuse(`${changes.join(", ")} requested changes`));
       const authors = new Set(await authorsOf(mr));
       const approved = [...said].filter(([, v]) => v.what === "approved" && v.at > since).map(([w]) => w).sort();
       const least = approvers?.minAccessLevel ?? GITLAB_DEVELOPER;
@@ -1301,8 +1329,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         return level >= least ? undefined : `${login} has access level ${level}, under ${least}`;
       };
       const { by, not } = await countApprovers(approved, authors, approvers, rule);
-      if (by.length === 0) return noApprover(`no member other than its authors approved it after its latest push, ${short(head)}`, not);
-      return pass(`approved after ${short(head)} by ${by.join(", ")}`);
+      return approvalVerdict(by, not, `approved after ${short(head)}`, `no member other than its authors approved it after its latest push, ${short(head)}`);
     },
     async prMergeable(mr, head) {
       const got = await api.call("GET", `${notes}/${mr}`);

package/src/pr-requires.test.ts

@@ -32,14 +32,14 @@ describe("github", () => {
 
   test("approved: a reviewer other than the authors approved this head", async () => {
     const f = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }] });
-    expect(await f.prApproved!(7, HEAD)).toEqual({ passed: true, reason: "approved at aaaaaaaa by bob" });
+    expect(await f.prApproved!(7, HEAD)).toEqual({ passed: true, reason: "approved at aaaaaaaa by bob", approvers: ["bob"], excluded: [] });
   });
 
   test("approved: an approval of an older head, the author's own, or a request for changes does not pass", async () => {
     const older = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: OTHER }, { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD }] });
     expect((await older.prApproved!(7, HEAD)).passed).toBe(false);
     const changes = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }, { user: { login: "carol" }, state: "CHANGES_REQUESTED", commit_id: HEAD }] });
-    expect(await changes.prApproved!(7, HEAD)).toEqual({ passed: false, reason: "carol asked for changes" });
+    expect(await changes.prApproved!(7, HEAD)).toEqual({ passed: false, reason: "carol asked for changes", approvers: [], excluded: [] });
   });
 
   test("approved: forgeRule counts only writers, exclude leaves a login out, and the refusal says why (#4337)", async () => {
@@ -53,10 +53,24 @@ describe("github", () => {
       [`GET ${repo}/collaborators/bob/permission`]: { permission: "read", role_name: "triage" },
       [`GET ${repo}/collaborators/Carol/permission`]: { permission: "write", role_name: "maintain" },
     });
-    expect(await f.prApproved!(7, HEAD, { forgeRule: true })).toEqual({ passed: true, reason: "approved at aaaaaaaa by Carol" });
+    expect(await f.prApproved!(7, HEAD, { forgeRule: true })).toEqual({
+      passed: true,
+      reason: "approved at aaaaaaaa by Carol",
+      approvers: ["Carol"],
+      excluded: [
+        { login: "alice", reason: "alice is one of its authors" },
+        { login: "bob", reason: "bob has no write access" },
+      ],
+    });
     expect(await f.prApproved!(7, HEAD, { forgeRule: true, exclude: [{ login: "carol", reason: "carol asked for aaaaaaa" }] })).toEqual({
       passed: false,
       reason: "no reviewer other than its authors approved its head aaaaaaaa: carol asked for aaaaaaa; alice is one of its authors; bob has no write access",
+      approvers: [],
+      excluded: [
+        { login: "Carol", reason: "carol asked for aaaaaaa" },
+        { login: "alice", reason: "alice is one of its authors" },
+        { login: "bob", reason: "bob has no write access" },
+      ],
     });
     expect((await f.prApproved!(7, HEAD, { exclude: ["bob"] })).reason).toBe("approved at aaaaaaaa by Carol");
   });
@@ -112,7 +126,14 @@ describe("forgejo", () => {
     const f = forge({ [`GET ${repo}/pulls/4/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD, official: false }, { user: { login: "erin" }, state: "APPROVED", commit_id: HEAD, official: true }] });
     expect((await f.prApproved!(4, HEAD, { forgeRule: true })).reason).toBe("approved at aaaaaaaa by erin");
     const out = await checkPrRequires(f, 4, HEAD, { only: ["approved"], approvers: { forgeRule: true, exclude: ["erin"] } });
-    expect(out[0]!.reason).toBe("no reviewer other than its authors approved its head aaaaaaaa: bob's review is not official; erin is excluded");
+    expect(out[0]).toMatchObject({
+      reason: "no reviewer other than its authors approved its head aaaaaaaa: bob's review is not official; erin is excluded",
+      approvers: [],
+      excluded: [
+        { login: "bob", reason: "bob's review is not official" },
+        { login: "erin", reason: "erin is excluded" },
+      ],
+    });
   });
 
   test("undiverged: the pull request's merge base is the base branch's tip", async () => {
@@ -150,7 +171,7 @@ describe("gitlab", () => {
         [`GET ${project}/merge_requests/3`]: mr(),
         [`GET ${project}/merge_requests/3/commits`]: [],
         "GET /api/v4/user": { id: 1, username: "chant-bot" },
-        [`GET ${project}/merge_requests/3/versions`]: [{ created_at: "2026-10-01T10:00:00Z" }],
+        [`GET ${project}/merge_requests/3/versions`]: [{ created_at: "2026-10-01T10:00:00Z", head_commit_sha: HEAD }],
         ...routes,
       }),
     });
@@ -165,7 +186,7 @@ describe("gitlab", () => {
     });
     expect((await f.prApproved!(3, HEAD)).passed).toBe(false);
     const g = forge({ [`GET ${project}/merge_requests/3/notes`]: [note("bob", "approved this merge request", "2026-10-01T11:00:00Z")] });
-    expect(await g.prApproved!(3, HEAD)).toEqual({ passed: true, reason: "approved after aaaaaaaa by bob" });
+    expect(await g.prApproved!(3, HEAD)).toEqual({ passed: true, reason: "approved after aaaaaaaa by bob", approvers: ["bob"], excluded: [] });
     const h = forge({ [`GET ${project}/merge_requests/3/notes`]: [note("bob", "approved this merge request", "2026-10-01T11:00:00Z"), note("carol", "requested changes", "2026-10-01T12:00:00Z")] });
     expect((await h.prApproved!(3, HEAD)).reason).toBe("carol requested changes");
   });
@@ -185,6 +206,22 @@ describe("gitlab", () => {
     expect((await f.prApproved!(3, HEAD, { forgeRule: true, minAccessLevel: 50 })).reason).toBe(
       "no member other than its authors approved it after its latest push, aaaaaaaa: bob has access level 20, under 50; dan has access level 40, under 50; eve is not a member",
     );
+    expect((await f.prApproved!(3, HEAD, { forgeRule: true })).excluded).toEqual([
+      { login: "bob", reason: "bob has access level 20, under 30" },
+      { login: "eve", reason: "eve is not a member" },
+    ]);
+  });
+
+  test("approved: pending until GitLab's newest diff version is of the head, as terragucci checked (#4287)", async () => {
+    const approval = note("bob", "approved this merge request", "2026-10-01T11:00:00Z");
+    const versions = [
+      { created_at: "2026-10-01T10:00:00Z", head_commit_sha: HEAD },
+      { created_at: "2026-10-01T12:00:00Z", head_commit_sha: OTHER },
+    ];
+    const f = forge({ [`GET ${project}/merge_requests/3/notes`]: [approval], [`GET ${project}/merge_requests/3/versions`]: versions });
+    expect(await f.prApproved!(3, HEAD)).toEqual({ passed: false, pending: true, reason: "merge request !3's newest diff version is of cccccccc, not aaaaaaaa", approvers: [], excluded: [] });
+    const none = forge({ [`GET ${project}/merge_requests/3/notes`]: [approval], [`GET ${project}/merge_requests/3/versions`]: [] });
+    expect(await none.prApproved!(3, HEAD)).toMatchObject({ passed: false, pending: true });
   });
 
   test("mergeable and undiverged read the merge request", async () => {