@codyswann/lisa 4.42.2 → 4.42.3

package/typescript/copy-overwrite/scripts/check-skipped-required-checks.mjs

@@ -344,6 +344,7 @@ export const VIOLATIONS = Object.freeze({
   absent: "absent_required_check",
   reviewWaived: "review_evidence_waived",
   reviewUnsatisfied: "review_evidence_unsatisfied",
+  reviewCarried: "review_evidence_carried_unreviewed",
 });
 
 /**
@@ -475,6 +476,12 @@ export const NEVER_BLOCKING = Object.freeze([
   // operator must see that — and it never fails the build, which is the whole
   // content of the owner's ruling on CodySwannGT/lisa#3221.
   VIOLATIONS.reviewWaived,
+  // A carried finding is about ANOTHER pull request. Reddening this one for a
+  // condition its own author cannot reach would punish the batch for the
+  // constituent, and #3658 is a VISIBILITY defect, not an enforcement one: the
+  // constituents' own gates already went red, on branches no ruleset watches.
+  // What was missing was that the batch rendered green anyway.
+  VIOLATIONS.reviewCarried,
 ]);
 
 /**
@@ -1863,6 +1870,103 @@ export function evaluateReviewGate(declaration, checks, options = {}) {
   return { violations, states, conditions, descriptions, checked };
 }
 
+/**
+ * How many carried pull requests this will account for before it gives up.
+ *
+ * A cap that SILENTLY truncates is the fail-open this file exists to refuse, so
+ * exceeding it is reported as "not read" rather than as the part that was read.
+ * Fifty is well above any batch observed here — the drain that produced #3658
+ * carried seven — and it exists so a pathological history cannot turn one job
+ * into hundreds of API reads.
+ */
+export const CARRIED_PULL_REQUEST_LIMIT = 50;
+
+/** Why a carried finding matters, appended to every one of them. */
+const CARRIED_WHY =
+  "A batch integration pull request is the only place this gap is enforceable. The constituent's own review gate ran on its own pull request, whose base branch no ruleset watches, so its red changed nothing; merging this one carries that unreviewed diff into the default branch. Read the constituent before recording this batch as reviewed.";
+
+/**
+ * Runs the review gate over the pull requests THIS pull request carries.
+ *
+ * ## Why a batch needs its own arm (#3658)
+ *
+ * {@link evaluateReviewGate} reads one commit: this pull request's head. That is
+ * the right commit for the pull request's own diff and the wrong one for a
+ * batch, because a stack integration pull request's head carries the merges of
+ * every constituent and none of their review statuses. MEASURED 2026-09-03 on
+ * one queue drain: four constituents based on a batching branch each reported
+ * `Review skipped: reviews are disabled for this base branch`, each one's own
+ * review-evidence run went red, and every one of those reds landed on a branch
+ * outside the rulesets' ref conditions — so nothing was watching. The
+ * integration pull request that carried all of them into the default branch was
+ * the one place a ruleset applied, and it read only itself.
+ *
+ * Pure, and injected with already-read rows, so the property that matters — a
+ * batch carrying an unreviewed constituent never renders as a reviewed one — is
+ * testable without a GitHub API.
+ *
+ * @param {object} declaration - The per-repo declaration
+ * @param {ReadonlyArray<{number: number|string, headSha?: string, checks?: ReadonlyArray<object>, unreadable?: string}>} carried -
+ *   One entry per carried pull request; `unreadable` marks one whose evidence
+ *   could not be fetched, which counts AGAINST the batch rather than for it
+ * @returns {{violations: object[], unreviewed: string[], reviewed: number}} Findings and the tally
+ */
+export function evaluateCarriedReview(declaration, carried) {
+  const declared = Object.entries(declaration.evidence_bearing_checks ?? {});
+  const violations = [];
+  const unreviewed = [];
+  let reviewed = 0;
+
+  for (const constituent of carried) {
+    const label = `#${constituent.number}`;
+    if (constituent.unreadable) {
+      unreviewed.push(label);
+      violations.push({
+        kind: VIOLATIONS.reviewCarried,
+        token: label,
+        contexts: [],
+        message: `This pull request CARRIES ${label}, whose review evidence could NOT be read (${constituent.unreadable}). An unread constituent is not a reviewed one. ${CARRIED_WHY}`,
+      });
+      continue;
+    }
+    const failing = [];
+    for (const [name, entry] of declared) {
+      const vocabulary =
+        typeof entry === "object" && entry !== null ? entry : {};
+      const found = (constituent.checks ?? []).find(
+        check => check.name === name
+      );
+      const verdict = reviewGateState(
+        found === undefined
+          ? { present: false }
+          : {
+              present: true,
+              state: found.state,
+              description: found.description,
+            },
+        vocabulary
+      );
+      if (verdict.state !== REVIEW_GATE_STATES.satisfied)
+        failing.push({ name, verdict });
+    }
+    if (failing.length === 0) {
+      reviewed += 1;
+      continue;
+    }
+    unreviewed.push(label);
+    for (const { name, verdict } of failing) {
+      violations.push({
+        kind: VIOLATIONS.reviewCarried,
+        token: label,
+        contexts: [name],
+        message: `This pull request CARRIES ${label}, whose \`${name}\` ${verdict.why}${citeHeadSha(constituent.headSha)} ${CARRIED_WHY}`,
+      });
+    }
+  }
+
+  return { violations, unreviewed, reviewed };
+}
+
 /**
  * The check-run conclusion each review-gate verdict is published under.
  *
@@ -1928,6 +2032,27 @@ function waiveRateSuffix(rate) {
     : ` · waived on ${rate.waived} of the last ${rate.sampled} merged pull requests`;
 }
 
+/**
+ * The carried-batch sentence appended to a verdict title, or nothing.
+ *
+ * NUMBERS ONLY, no vendor descriptions. The title is capped at
+ * {@link REVIEW_VERDICT_TITLE_LIMIT}, and one quoted skip string is long enough
+ * to push the constituent list out of it — which would lose exactly the fact
+ * this exists to render. The quotes live in the findings, where nothing
+ * truncates them.
+ *
+ * @param {{unreviewed?: readonly string[], unread?: string}|undefined} carried - The carried tally
+ * @returns {string} The sentence, or an empty string when the batch is accounted for
+ */
+function carriedSuffix(carried) {
+  if (carried === undefined) return "";
+  if (carried.unread !== undefined && carried.unread !== "")
+    return " · the pull requests this one CARRIES could NOT be enumerated, so nothing accounts for their review";
+  const unreviewed = carried.unreviewed ?? [];
+  if (unreviewed.length === 0) return "";
+  return ` · carries ${unreviewed.length} UNREVIEWED pull request${unreviewed.length === 1 ? "" : "s"}: ${unreviewed.join(", ")}`;
+}
+
 /**
  * Renders one merge-time verdict for every declared evidence-bearing check.
  *
@@ -1948,9 +2073,14 @@ function waiveRateSuffix(rate) {
  * the one path where it mattered, a red check blocking a merge, was the one
  * path that never said it. The conditions are carried here for that reason.
  *
- * @param {{states?: Record<string, string>, conditions?: Record<string, string>, descriptions?: Record<string, string>, refusal?: {kind: string}|null, waiveRate?: {waived: number, sampled: number}}} reading -
+ * AND SO IS WHAT THE PULL REQUEST CARRIES (#3658), for the same reason one step
+ * out: every state above is read from THIS pull request's head, which is the
+ * one commit a batch integration pull request does not speak for.
+ *
+ * @param {{states?: Record<string, string>, conditions?: Record<string, string>, descriptions?: Record<string, string>, refusal?: {kind: string}|null, waiveRate?: {waived: number, sampled: number}, carried?: {unreviewed?: readonly string[], reviewed?: number, unread?: string}}} reading -
  *   The gate's per-check states and conditions, the descriptions they were read
- *   from, any refusal, and an optional sampled waive rate
+ *   from, any refusal, an optional sampled waive rate, and the tally for the
+ *   pull requests this one CARRIES
  * @returns {{verdict: string, conclusion: string, title: string}} What to publish
  */
 export function reviewGateVerdict(reading = {}) {
@@ -1958,7 +2088,8 @@ export function reviewGateVerdict(reading = {}) {
   const conditions = reading.conditions ?? {};
   const descriptions = reading.descriptions ?? {};
   const names = Object.keys(states);
-  const suffix = waiveRateSuffix(reading.waiveRate);
+  const carried = carriedSuffix(reading.carried);
+  const suffix = `${carried}${waiveRateSuffix(reading.waiveRate)}`;
 
   if (reading.refusal || names.length === 0) {
     return {
@@ -2033,6 +2164,28 @@ export function reviewGateVerdict(reading = {}) {
     };
   }
 
+  // #3658. Everything above judged THIS pull request's own head commit, which
+  // is the only commit a batch integration pull request does not speak for. A
+  // batch whose own review completed while it carries constituents nothing read
+  // is the exact indistinguishability #3639 removed one level down: green here
+  // and green for a fully reviewed pull request, character for character.
+  //
+  // It renders `waived`, never `unsatisfied`, and the cap is deliberate. The
+  // constituents' own gates already reached the failing verdict on their own
+  // pull requests; re-failing the batch would redden every integration pull
+  // request for a vendor condition its author cannot reach, which is the
+  // "gate that gets deleted" failure this file names twice already. The batch
+  // stops looking reviewed without acquiring the power to block.
+  if (carried !== "") {
+    return {
+      verdict: REVIEW_GATE_STATES.waived,
+      conclusion: REVIEW_VERDICT_CONCLUSIONS.waived,
+      title: fitTitle(
+        `CARRIED UNREVIEWED — this pull request's own review ran, but the work it carries was not reviewed with it${suffix}`
+      ),
+    };
+  }
+
   return {
     verdict: REVIEW_GATE_STATES.satisfied,
     conclusion: REVIEW_VERDICT_CONCLUSIONS.satisfied,
@@ -2153,6 +2306,193 @@ export function sampleWaiveRate(declaration, limit, repo, fetch) {
   }
 }
 
+/**
+ * How many merge commits this will look behind before giving up on the batch.
+ *
+ * Each one costs a REST read, and an ordinary pull request has none, so the
+ * ceiling only ever binds on a history nobody could review by hand either.
+ */
+export const CARRIED_MERGE_COMMIT_LIMIT = 200;
+
+/**
+ * Refuses a commit list that the pull-request endpoint silently truncated.
+ *
+ * `GET /repos/{owner}/{repo}/pulls/{pr}/commits` stops at **250 commits** and
+ * does not paginate past it — `--paginate` gets the same 250. A caller that
+ * reads the short list and carries on has enumerated a PARTIAL batch and cannot
+ * tell that it did, which is precisely the fail-open this whole file exists to
+ * refuse: the missing merge commits are constituents nobody accounted for, and
+ * the batch would render as though they had been.
+ *
+ * So the count is checked against the pull request's own `commits` figure,
+ * which comes from a different endpoint and is not subject to the ceiling. A
+ * mismatch is reported as UNREAD, never as the part that was read. An
+ * unreadable figure is also unread — without it there is no way to tell a
+ * complete list from a truncated one, and guessing in the permissive direction
+ * is the whole defect.
+ *
+ * Pure and exported so the refusal can be exercised without a 251-commit pull
+ * request, which is not a fixture anybody can reasonably build.
+ *
+ * @param {string|number} pr - The pull request, named in the message
+ * @param {number} enumerated - How many commits the list endpoint returned
+ * @param {unknown} declared - The pull request's own commit count
+ * @returns {void}
+ * @throws {Error} When the counts disagree or the declared count is unreadable
+ */
+export function assertCompleteCommitList(pr, enumerated, declared) {
+  // `Number("")` is 0, not NaN — an empty answer from `gh` would otherwise read
+  // as "this pull request has zero commits" and produce the TRUNCATED message
+  // for what is really an unreadable count. Two different facts, two messages.
+  const raw = String(declared ?? "").trim();
+  const total = raw === "" ? Number.NaN : Number(raw);
+  if (!Number.isInteger(total) || total < 0) {
+    throw new Error(
+      `could not read how many commits PR ${pr} has (${JSON.stringify(declared)}), so nothing can tell a complete commit list from a truncated one`
+    );
+  }
+  if (enumerated !== total) {
+    throw new Error(
+      `enumerated ${enumerated} of the ${total} commits on PR ${pr} — \`/pulls/{pr}/commits\` stops at 250 even under --paginate, so this batch is TRUNCATED and cannot be accounted for`
+    );
+  }
+}
+
+/**
+ * Enumerates the pull requests this pull request CARRIES.
+ *
+ * The merge commits in a pull request's own commit list are what a batch is
+ * made of, and `/commits/{sha}/pulls` resolves each one to the pull request it
+ * brought in, head SHA included. MEASURED 2026-09-03 against the integration
+ * pull request that surfaced #3658: every constituent resolved, including one
+ * reached through a back-merge of the batching branch into a constituent
+ * branch, which deduplicates against the constituent it already found.
+ *
+ * NO BRANCH-NAME MATCHING ANYWHERE, deliberately. Matching a batching-branch
+ * pattern would be an allowlist of bases, which is the shape the convention can
+ * rename its way out of without anybody noticing. Merge commits are what
+ * carrying actually IS, so this generalises to any batched pull request and
+ * cannot be dodged by naming the branch something else.
+ *
+ * A pull request that merged its own base back in yields merge commits that
+ * resolve to ITSELF, which is filtered out — so an ordinary pull request
+ * reports an empty batch rather than a false one.
+ *
+ * @param {string|number} pr - The pull request whose carried work to enumerate
+ * @param {string} [repo] - `OWNER/NAME`; defaults to the current repository
+ * @returns {Array<{number: number, headSha: string}>} One entry per carried pull request
+ * @throws {Error} When the slug cannot be resolved, `gh` cannot answer, the commit list was truncated (see {@link assertCompleteCommitList}), or the batch exceeds {@link CARRIED_MERGE_COMMIT_LIMIT}
+ */
+export function fetchCarriedPullRequests(pr, repo) {
+  const slug = resolveRepoSlug(repo);
+  if (slug === undefined) {
+    throw new Error(
+      `check-skipped-required-checks: cannot enumerate what PR ${pr} carries without an OWNER/NAME. Pass \`--repo=OWNER/NAME\`, or set GITHUB_REPOSITORY.`
+    );
+  }
+  // Read BEFORE the list, so a pull request that grows mid-read is caught by
+  // the comparison rather than hidden by it.
+  const declaredCommits = boundedExecFileSync(
+    "gh",
+    ["api", `repos/${slug}/pulls/${pr}`, "--jq", ".commits"],
+    { encoding: "utf8" }
+  ).trim();
+  const commits = ghApiPaginatedArray(
+    `repos/${slug}/pulls/${pr}/commits?per_page=100`,
+    "[.[] | {sha: .sha, parents: (.parents | length)}]"
+  );
+  assertCompleteCommitList(pr, commits.length, declaredCommits);
+  const merges = commits
+    .filter(row => Number(row?.parents) > 1)
+    .map(row => String(row?.sha));
+  // Applied only to a list already proven COMPLETE. A ceiling checked against a
+  // truncated list is a ceiling that never fires.
+  if (merges.length > CARRIED_MERGE_COMMIT_LIMIT) {
+    throw new Error(
+      `PR ${pr} contains ${merges.length} merge commits, past the ${CARRIED_MERGE_COMMIT_LIMIT} this will look behind`
+    );
+  }
+  const carried = new Map();
+  for (const sha of merges) {
+    const rows = ghApiPaginatedArray(
+      `repos/${slug}/commits/${sha}/pulls?per_page=100`,
+      "[.[] | {number: .number, headSha: .head.sha}]"
+    );
+    for (const row of rows) {
+      const number = row?.number;
+      const headSha = row?.headSha;
+      if (number === undefined || headSha === undefined) continue;
+      if (String(number) === String(pr)) continue;
+      if (!carried.has(number)) carried.set(number, { number, headSha });
+    }
+  }
+  return [...carried.values()];
+}
+
+/**
+ * Reads and judges the review evidence for everything this pull request carries.
+ *
+ * FAILING TO READ IS NOT PASSING. Every error path here — an unresolvable
+ * repository, an unreadable commit, a batch past the cap — reports the batch as
+ * UNREAD, which renders the same way an unreviewed one does. That is the
+ * "refusing to report a clean scan that never ran" shape already in this tree,
+ * applied to the one arm whose silence would otherwise read as approval.
+ *
+ * @param {object} declaration - The per-repo declaration
+ * @param {string|number} pr - The pull request under inspection
+ * @param {string} [repo] - `OWNER/NAME`; defaults to the current repository
+ * @param {{fetchCarried?: Function, fetchCarriedChecks?: Function}} [options] - Injection seams
+ * @returns {{violations: object[], unreviewed: string[], reviewed: number, unread?: string}} Findings and the tally
+ */
+export function readCarriedReview(declaration, pr, repo, options = {}) {
+  const enumerate = options.fetchCarried ?? fetchCarriedPullRequests;
+  const readChecks = options.fetchCarriedChecks ?? fetchChecksForCommit;
+  /**
+   * Renders "the batch was not read" as a finding, never as an empty one.
+   *
+   * @param {string} why - What stopped the read
+   * @returns {{violations: object[], unreviewed: string[], reviewed: number, unread: string}} The unread result
+   */
+  const unread = why => ({
+    violations: [
+      {
+        kind: VIOLATIONS.reviewCarried,
+        token: "carried",
+        contexts: [],
+        message: `The pull requests this one CARRIES could not be enumerated (${why}), so this run cannot say whether the work it brings was reviewed. Refusing to report a clean batch nothing read. ${CARRIED_WHY}`,
+      },
+    ],
+    unreviewed: [],
+    reviewed: 0,
+    unread: why,
+  });
+
+  let listed;
+  try {
+    listed = enumerate(pr, repo);
+  } catch (error) {
+    return unread(error instanceof Error ? error.message : String(error));
+  }
+  if (listed.length > CARRIED_PULL_REQUEST_LIMIT) {
+    return unread(
+      `PR ${pr} carries ${listed.length} pull requests, past the ${CARRIED_PULL_REQUEST_LIMIT} this will account for`
+    );
+  }
+  return evaluateCarriedReview(
+    declaration,
+    listed.map(entry => {
+      try {
+        return { ...entry, checks: readChecks(entry.headSha, repo) };
+      } catch (error) {
+        return {
+          ...entry,
+          unreadable: error instanceof Error ? error.message : String(error),
+        };
+      }
+    })
+  );
+}
+
 /**
  * Publishes the verdict where a workflow step can read it.
  *
@@ -2917,6 +3257,15 @@ export function inspectVacuity(argv, declaration, options = {}) {
     // downstream sees a check row that looks identical either way (#3716).
     waitExpired: read.settled === false,
   });
+  // #3658. Everything above judged ONE commit — this pull request's head — and
+  // that is the one commit a batch integration pull request does not speak for.
+  // Armed by the same flag as the gate itself, because this IS the gate,
+  // applied to what the pull request CARRIES rather than to what it changes. A
+  // pull request with no merge commits enumerates an empty batch and pays one
+  // read for the privilege, so the ordinary case is untouched.
+  const carried = requireReviewEvidence
+    ? readCarriedReview(declaration, pr, repo, options)
+    : undefined;
   // Sampled ONLY when this pull request is itself waived. The rate answers
   // "is this the exception or the rule?", a question that only arises once a
   // waiver is on the table, and every other run keeps the sampler's network
@@ -2940,17 +3289,20 @@ export function inspectVacuity(argv, declaration, options = {}) {
       ...evaluated.violations,
       ...absent.violations,
       ...gate.violations,
+      ...(carried?.violations ?? []),
     ],
     absent: absent.absent,
     gateStates: gate.states,
     gateConditions: gate.conditions,
     gateDescriptions: gate.descriptions,
     waiveRate,
+    carried,
     verdict: reviewGateVerdict({
       states: gate.states,
       conditions: gate.conditions,
       descriptions: gate.descriptions,
       waiveRate,
+      carried,
     }),
     settled: read.settled,
     refusal: null,
@@ -3110,7 +3462,21 @@ function violationBlocks(violation, policy) {
   if (REVIEW_GATE_BLOCKING.includes(violation.kind)) {
     return policy.requireReviewEvidence;
   }
-  if (violation.kind === VIOLATIONS.reviewWaived) return false;
+  // A named waiver is report-only under every flag. `--fail-on-vacuous`
+  // governs checks that claimed success without proving work; it must not
+  // turn a vendor entitlement waiver into a failure through a shared array.
+  //
+  // A carried finding (#3658) is report-only for a second reason on top of
+  // that one: it is about ANOTHER pull request, whose own gate already
+  // reached its own verdict on its own diff. `--fail-on-vacuous` asks "did
+  // the checks on THIS pull request prove their work?", and answering it with
+  // a constituent's condition would fail an author for a diff they did not
+  // write and cannot change.
+  if (
+    violation.kind === VIOLATIONS.reviewWaived ||
+    violation.kind === VIOLATIONS.reviewCarried
+  )
+    return false;
   if (NEVER_BLOCKING.includes(violation.kind)) return policy.failOnVacuous;
   return !policy.warnOnly || ALWAYS_BLOCKING.includes(violation.kind);
 }

package/typescript/create-only/.github/workflows/review-evidence.yml

@@ -43,6 +43,26 @@
 # a gate that reddens every pull request on a vendor's billing state gets
 # deleted, and then nothing is watching at all.
 #
+# AND A PULL REQUEST SPEAKS FOR ONE COMMIT ONLY (#3658). Everything above judges
+# this pull request's HEAD, which is the one commit a batch integration pull
+# request does not speak for: its head carries the MERGES of every constituent
+# and none of their review statuses. MEASURED 2026-09-03 on one queue drain —
+# four constituents based on a batching branch each reported `Review skipped:
+# reviews are disabled for this base branch`, each one's own run of this workflow
+# went red, and every one of those reds landed on a branch outside the rulesets'
+# ref conditions, so nothing was watching. The integration pull request that
+# carried all four into the default branch was the one place a ruleset applied,
+# and it read only itself. `--require-review-evidence` now also enumerates what
+# this pull request CARRIES — through its merge commits, never through a branch
+# NAME, because a name is an allowlist the convention can rename its way out of
+# — reads each constituent at its OWN head, and renders a batch carrying an
+# unreviewed constituent `neutral` instead of `success`. Capped at `neutral`
+# deliberately: the constituents' own runs already reached the failing verdict
+# where their diffs live, and reddening the batch too would fail an author for a
+# diff they did not write. Failing to READ the batch renders `neutral` as well —
+# an unread batch is not a reviewed one. An ordinary pull request has no merge
+# commits, enumerates an empty batch, and is untouched.
+#
 # `--waive-rate-sample=<N>` samples recently merged pull requests and reports
 # how many of them waived, in the job summary and in the verdict title. It runs
 # ONLY when this pull request is itself waived, is one GraphQL call, and is