@cleocode/core 2026.10.22 → 2026.10.23

package/dist/release/ci-evidence.js

@@ -39,6 +39,14 @@
  * {@link nonTestFailuresOn}. The stand-in search also looks past later runs red
  * for that reason alone, up to {@link CI_DESCENDANT_MAX_CANDIDATES} commits.
  *
+ * A fourth (T14032, owner decision D11192), for a WORKSPACE-WIDE change only
+ * (one a targeted test-run cannot speak for: a lockfile, a root config): when
+ * the merge commit is not green and no T12742 descendant stands in, a green
+ * push run of every required check on the default branch's CURRENT head (or
+ * on a commit differing from it only in documentation) that descends from the
+ * merge stands in, whatever the merge's own run concluded and whatever later
+ * commits touched. See {@link findGreenCurrentHead}.
+ *
  * @task T12634
  */
 import { execFileSync } from 'node:child_process';
@@ -384,6 +392,7 @@ export function evaluateMergeCommitChecks(required, checks, mergeCommitSha, opts
         if (descendantSha !== undefined &&
             descendantSha !== mergeCommitSha &&
             (SUPERSEDED_VERDICTS.has(onMerge.verdict) ||
+                opts.currentHead === true ||
                 (opts.inheritedFailures === true &&
                     onMerge.verdict !== 'missing' &&
                     !onMerge.verdict.startsWith('pending')))) {
@@ -544,6 +553,18 @@ function latestRuns(checks, sha, scope) {
     }
     return [...latest.values()];
 }
+/**
+ * Why a merge-commit run did not test the merge as it was when it landed
+ * (T14026): a re-run, or a start after a later default-branch commit landed.
+ * Null when neither is known.
+ */
+function lateRun(run, nextMainCommitAt) {
+    if ((run.runAttempt ?? 1) > 1)
+        return `is re-run attempt ${run.runAttempt}`;
+    if (run.startedAt && nextMainCommitAt && Date.parse(run.startedAt) > Date.parse(nextMainCommitAt))
+        return `started at ${run.startedAt}, after a later default-branch commit landed (${nextMainCommitAt})`;
+    return null;
+}
 /**
  * Whether the merge commit's failures were all inherited from main (T13453).
  *
@@ -555,15 +576,23 @@ function latestRuns(checks, sha, scope) {
  * the PR may have introduced and refuses. A pending merge-commit run refuses.
  * Pure: the ancestors' checks are passed in, nearest first.
  *
+ * The refusal blames the PR only when the failing run could have seen nothing
+ * but the PR's change (T14026): a re-run, or a run that started after a later
+ * default-branch commit landed, ran in a world that moved on since the merge
+ * (rotated secrets, external services), so it still refuses but says the
+ * failure may not be the PR's.
+ *
  * @param required - Required check names.
  * @param checks - Checks fetched for the merge commit.
  * @param mergeCommitSha - The merge commit.
  * @param ancestors - First-parent ancestors of the merge, nearest first, with their checks.
  * @param pins - Required-name to app/workflow pin.
+ * @param nextMainCommitAt - When the next default-branch commit after the merge landed, if known.
  * @returns The required names to stand in for and the inherited jobs, or why not.
  * @task T13453
+ * @task T14026
  */
-export function inheritedOnMerge(required, checks, mergeCommitSha, ancestors, pins) {
+export function inheritedOnMerge(required, checks, mergeCommitSha, ancestors, pins, nextMainCommitAt = null) {
     const scope = pinnedScope(required, pins);
     const onMerge = latestRuns(checks, mergeCommitSha, scope);
     const pending = onMerge.find((c) => c.status !== 'completed');
@@ -597,9 +626,13 @@ export function inheritedOnMerge(required, checks, mergeCommitSha, ancestors, pi
             };
         }
         if (base.run.conclusion === 'success') {
+            const at = `${job.name}: ${job.conclusion} on merge commit ${mergeCommitSha.slice(0, 12)} but success on its base ${base.sha.slice(0, 12)}`;
+            const late = lateRun(job, nextMainCommitAt);
             return {
                 ok: false,
-                reason: `${job.name}: ${job.conclusion} on merge commit ${mergeCommitSha.slice(0, 12)} but success on its base ${base.sha.slice(0, 12)} — the PR introduced this failure`,
+                reason: late
+                    ? `${at}; the failing run ${late}, so it may have failed on something that changed after the merge (secrets, external services) rather than on the PR`
+                    : `${at} — the PR introduced this failure`,
             };
         }
         inherited.push({
@@ -958,7 +991,7 @@ export async function findGreenDescendant(input) {
                 break;
             ancestors.push({ sha: at, checks: fetched.checks });
         }
-        const result = inheritedOnMerge(required, input.checks, merge, ancestors, pins);
+        const result = inheritedOnMerge(required, input.checks, merge, ancestors, pins, input.nextMainCommitAt?.(merge, input.ref, cwd) ?? null);
         if (result.ok) {
             superseded = { ok: true, names: result.names };
             inherited = result.inherited;
@@ -1050,59 +1083,140 @@ export async function findGreenDescendant(input) {
                 reason: `${failedJob.name}: ${failedJob.conclusion} on later ${input.ref} commit ${sha.slice(0, 12)}`,
             };
         }
-        let decided = true;
-        for (const name of supersededNames) {
-            const pinned = fetched.checks.filter((c) => c.name === name && pinMatches(c, pins[name]));
-            const verdict = judgeOnSha(pinned, sha, 'push');
-            if (verdict.ok)
-                continue;
-            if (verdict.verdict.startsWith('pending')) {
-                return {
-                    ok: false,
-                    reason: `${name}: ${verdict.verdict} on later ${input.ref} commit ${sha.slice(0, 12)} — wait for ${sha.slice(0, 12)} to finish, then verify again`,
-                };
-            }
-            if (verdict.verdict === 'missing' || SUPERSEDED_VERDICTS.has(verdict.verdict)) {
-                decided = false;
-                break;
-            }
+        const verdict = judgeStandIn(fetched.checks, sha, supersededNames, pins, input.jobs, input.ref);
+        if (verdict === 'undecided')
+            continue;
+        if (!verdict.ok)
+            return verdict;
+        return {
+            ok: true,
+            sha,
+            checks: [...fetched.checks, ...headChecks],
+            range: `${merge}..${sha}`,
+            ...(head ? { prHeadSha: head } : {}),
+            ...(inherited ? { inherited } : {}),
+            ...(nonTest ? { nonTest } : {}),
+        };
+    }
+    return {
+        ok: false,
+        reason: `no later ${input.ref} commit (first ${CI_DESCENDANT_MAX_CANDIDATES} within 7 days) has a completed push run of ${supersededNames.join(', ')}`,
+    };
+}
+/**
+ * Judge one later default-branch commit's own `push` runs as a stand-in
+ * (T12742, T14032): every named check green, and the gates' jobs run and
+ * green (T13846). A pending run refuses with "wait"; a failed one refuses —
+ * a green run is never shopped for past one that is red or may still go red.
+ * Cancelled, skipped and missing (never-started) runs leave it undecided, so
+ * the caller looks at the next candidate.
+ */
+function judgeStandIn(checks, sha, names, pins, jobs, ref) {
+    for (const name of names) {
+        const pinned = checks.filter((c) => c.name === name && pinMatches(c, pins[name]));
+        const verdict = judgeOnSha(pinned, sha, 'push');
+        if (verdict.ok)
+            continue;
+        if (verdict.verdict.startsWith('pending')) {
             return {
                 ok: false,
-                reason: `${name}: ${verdict.verdict} on later ${input.ref} commit ${sha.slice(0, 12)}`,
+                reason: `${name}: ${verdict.verdict} on later ${ref} commit ${sha.slice(0, 12)} — wait for ${sha.slice(0, 12)} to finish, then verify again`,
             };
         }
-        // T13846: the gates' own jobs must have run on the stand-in too.
-        for (const job of decided ? (input.jobs ?? []) : []) {
-            const onSha = evaluateJobs(job.globs, fetched.checks, sha, job.scope, 'push');
-            if (onSha.ok)
-                continue;
-            const pending = onSha.reasons.find((r) => r.includes(': pending ('));
-            if (pending) {
+        if (verdict.verdict === 'missing' || SUPERSEDED_VERDICTS.has(verdict.verdict)) {
+            return 'undecided';
+        }
+        return {
+            ok: false,
+            reason: `${name}: ${verdict.verdict} on later ${ref} commit ${sha.slice(0, 12)}`,
+        };
+    }
+    // T13846: the gates' own jobs must have run on the stand-in too.
+    let decided = true;
+    for (const job of jobs ?? []) {
+        const onSha = evaluateJobs(job.globs, checks, sha, job.scope, 'push');
+        if (onSha.ok)
+            continue;
+        const pending = onSha.reasons.find((r) => r.includes(': pending ('));
+        if (pending) {
+            return {
+                ok: false,
+                reason: `${pending} — wait for ${sha.slice(0, 12)} to finish, then verify again`,
+            };
+        }
+        const decisive = onSha.reasons.find((r) => !JOB_NOT_RUN.test(r));
+        if (decisive)
+            return { ok: false, reason: `${decisive} (later ${ref} commit)` };
+        decided = false;
+    }
+    return decided ? { ok: true } : 'undecided';
+}
+/**
+ * Find the green required-CI push run on the default branch's CURRENT head
+ * that stands in for a workspace-wide change's merge-commit CI (T14032, owner
+ * decision D11192). A workspace-wide change (a lockfile, a root config, a CI
+ * definition) only a full run speaks for; when its merge-commit run was red
+ * for a reason that is not the change (a secrets job failing on a re-run) and
+ * later commits touched its files, {@link findGreenDescendant} refuses, yet a
+ * full green CI on today's HEAD tests the merged change as it is now — the
+ * same reasoning as the targeted test-run stand-in (T13673), which also
+ * allows later edits.
+ *
+ * Candidates are HEAD, then its first parents while they differ from HEAD only
+ * in documentation ({@link isCiDocumentPath}, the T13784 rule: nothing a test
+ * reads moved), up to {@link CI_DESCENDANT_MAX_CANDIDATES}. Each must descend
+ * from the merge commit. The first decisive verdict decides, as in
+ * {@link findGreenDescendant}: every required check green on its own `push`
+ * runs (and the gates' jobs run, T13846) accepts; a failed or pending one
+ * refuses; cancelled, skipped or missing runs move to the parent.
+ *
+ * @param input - Required checks, pins, merge commit and injected I/O.
+ * @returns The stand-in commit, its checks and the head, or the refusal reason.
+ * @task T14032
+ */
+export async function findGreenCurrentHead(input) {
+    const { mergeCommitSha: merge, ref, cwd } = input;
+    const head = input.defaultBranchHead(ref, cwd);
+    if (!head)
+        return { ok: false, reason: `cannot read the current head of ${ref}` };
+    let sha = head;
+    for (let n = 0; n < CI_DESCENDANT_MAX_CANDIDATES && sha; n++) {
+        const at = sha === head ? `${ref} HEAD ${head.slice(0, 12)}` : `${sha.slice(0, 12)}`;
+        if (sha === merge || !input.isAncestor(merge, sha, cwd)) {
+            return {
+                ok: false,
+                reason: sha === head
+                    ? `${at} does not descend from merge commit ${merge.slice(0, 12)} here (git fetch origin, then verify again)`
+                    : `no push run between merge commit ${merge.slice(0, 12)} and ${ref} HEAD ${head.slice(0, 12)} decided the required checks`,
+            };
+        }
+        if (sha !== head) {
+            const moved = input.changedBetween(sha, head, cwd);
+            if (moved === null) {
+                return { ok: false, reason: `cannot diff ${sha.slice(0, 12)}..${head.slice(0, 12)}` };
+            }
+            const testInput = moved.find((p) => !isCiDocumentPath(p));
+            if (testInput) {
                 return {
                     ok: false,
-                    reason: `${pending} — wait for ${sha.slice(0, 12)} to finish, then verify again`,
+                    reason: `${ref} HEAD ${head.slice(0, 12)} has no completed push run of the required checks, and ${sha.slice(0, 12)}..${head.slice(0, 12)} changes ${testInput}, so an earlier run does not test HEAD — wait for HEAD's push CI to finish, then verify again`,
                 };
             }
-            const decisive = onSha.reasons.find((r) => !JOB_NOT_RUN.test(r));
-            if (decisive)
-                return { ok: false, reason: `${decisive} (later ${input.ref} commit)` };
-            decided = false;
         }
-        if (decided) {
-            return {
-                ok: true,
-                sha,
-                checks: [...fetched.checks, ...headChecks],
-                range: `${merge}..${sha}`,
-                ...(head ? { prHeadSha: head } : {}),
-                ...(inherited ? { inherited } : {}),
-                ...(nonTest ? { nonTest } : {}),
-            };
+        const fetched = await input.fetchChecks(sha, cwd);
+        if (!fetched.ok)
+            return { ok: false, reason: fetched.reason };
+        const verdict = judgeStandIn(fetched.checks, sha, input.required, input.pins, input.jobs, ref);
+        if (verdict !== 'undecided') {
+            if (!verdict.ok)
+                return verdict;
+            return { ok: true, sha, checks: fetched.checks, range: `${merge}..${sha}`, head };
         }
+        sha = input.firstParentOf(sha, cwd);
     }
     return {
         ok: false,
-        reason: `no later ${input.ref} commit (first ${CI_DESCENDANT_MAX_CANDIDATES} within 7 days) has a completed push run of ${supersededNames.join(', ')}`,
+        reason: `no commit within ${CI_DESCENDANT_MAX_CANDIDATES} first parents of ${ref} HEAD ${head.slice(0, 12)} has a completed push run of ${input.required.join(', ')}`,
     };
 }
 /**
@@ -1222,6 +1336,48 @@ export function ghDefaultBranch(cwd) {
         return null;
     }
 }
+/** Default {@link ResolveCiEvidenceOptions.nextMainCommitAt} (T14026). */
+function defaultNextMainCommitAt(mergeSha, ref, cwd) {
+    const out = gitRead(cwd, [
+        'log',
+        '--first-parent',
+        '--ancestry-path',
+        '--reverse',
+        '--format=%cI',
+        `${mergeSha}..${ref}`,
+    ]);
+    return out?.split('\n')[0] || null;
+}
+/**
+ * Default {@link ResolveCiEvidenceOptions.defaultBranchHead} (T14032): the
+ * branch head GitHub reports, so a stale local ref never passes for the
+ * current one; `git rev-parse <ref>` only when `gh` cannot answer.
+ */
+function defaultBranchHeadOf(ref, cwd) {
+    const branch = ref.replace(/^origin\//, '');
+    if (isGitWorkTree(cwd) && isGhCliAvailable()) {
+        const commit = ghApi(`repos/{owner}/{repo}/commits/${encodeURIComponent(branch)}`, cwd);
+        if (typeof commit === 'object' &&
+            commit !== null &&
+            'sha' in commit &&
+            typeof commit.sha === 'string' &&
+            /^[0-9a-f]{40}$/.test(commit.sha)) {
+            return commit.sha;
+        }
+    }
+    return gitRead(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+}
+/** Default {@link ResolveCiEvidenceOptions.changedBetween} (T14032). */
+function defaultChangedBetween(from, to, cwd) {
+    const out = gitRead(cwd, ['diff', '--name-only', '--no-renames', from, to]);
+    return out === null ? null : out.split('\n').filter(Boolean);
+}
+/** Default {@link ResolveCiEvidenceOptions.workspaceWideReason}: the `test-run:` rule (T14032). */
+async function defaultWorkspaceWideReason(root, paths) {
+    const { testRunRequirement } = await import('../tasks/test-run-binding.js');
+    const need = testRunRequirement(root, paths);
+    return need.kind === 'full' ? need.reason : null;
+}
 function defaultFirstParentOf(sha, cwd) {
     return gitRead(cwd, ['rev-parse', '--verify', '--quiet', `${sha}^1`]);
 }
@@ -1310,8 +1466,10 @@ async function defaultFetchChecks(sha, cwd) {
     for (const r of wf.workflow_runs ?? []) {
         const event = typeof r.event === 'string' ? r.event : undefined;
         const path = typeof r.path === 'string' ? r.path.replace(/@.*$/, '') : undefined;
+        const attempt = typeof r.run_attempt === 'number' ? r.run_attempt : undefined;
+        const startedAt = typeof r.run_started_at === 'string' ? r.run_started_at : undefined;
         if (typeof r.check_suite_id === 'number')
-            bySuite.set(r.check_suite_id, { event, path });
+            bySuite.set(r.check_suite_id, { event, path, attempt, startedAt });
         checks.push({
             name: String(r.name ?? ''),
             source: 'workflow-run',
@@ -1322,6 +1480,8 @@ async function defaultFetchChecks(sha, cwd) {
             appSlug: 'github-actions',
             ...(path ? { workflowPath: path } : {}),
             ...(event ? { event } : {}),
+            ...(attempt !== undefined ? { runAttempt: attempt } : {}),
+            ...(startedAt ? { startedAt } : {}),
         });
     }
     for (let page = 1; page <= 10; page++) {
@@ -1333,6 +1493,14 @@ async function defaultFetchChecks(sha, cwd) {
             const app = r.app;
             const suite = r.check_suite?.id;
             const origin = typeof suite === 'number' ? bySuite.get(suite) : undefined;
+            const startedAt = typeof r.started_at === 'string' ? r.started_at : undefined;
+            // A job started before its workflow's latest attempt belongs to an earlier one.
+            const attempt = origin?.attempt !== undefined &&
+                startedAt &&
+                origin.startedAt &&
+                Date.parse(startedAt) >= Date.parse(origin.startedAt)
+                ? origin.attempt
+                : undefined;
             checks.push({
                 name: String(r.name ?? ''),
                 source: 'check-run',
@@ -1344,6 +1512,8 @@ async function defaultFetchChecks(sha, cwd) {
                 ...(typeof app?.id === 'number' ? { appId: app.id } : {}),
                 ...(origin?.path ? { workflowPath: origin.path } : {}),
                 ...(origin?.event ? { event: origin.event } : {}),
+                ...(attempt !== undefined ? { runAttempt: attempt } : {}),
+                ...(startedAt ? { startedAt } : {}),
             });
         }
         if (runs.length < 100)
@@ -1371,7 +1541,8 @@ export async function recheckCiDescendantAtom(atom, cwd, fetchChecks = defaultFe
     if (!descendant)
         return { ok: true };
     const head = atom.descendantPrHeadSha;
-    if (!head && !atom.mainOnly) {
+    // T14032: a workspace-wide current-HEAD stand-in consulted main's push runs only.
+    if (!head && !atom.mainOnly && !atom.workspaceWide) {
         return {
             ok: false,
             reason: `ci:${atom.prNumber} leans on ${descendant.slice(0, 12)} but records no PR head; verify again`,
@@ -1650,6 +1821,7 @@ export async function resolveCiEvidenceAtom(prNumber, roots, opts = {}) {
             isAncestor: opts.isAncestor ?? defaultIsAncestor,
             firstParentOf: opts.firstParentOf ?? defaultFirstParentOf,
             fetchJobLog: opts.fetchJobLog ?? defaultFetchJobLog,
+            nextMainCommitAt: opts.nextMainCommitAt ?? defaultNextMainCommitAt,
         });
         if (found.ok) {
             const withDescendant = [...checks, ...found.checks];
@@ -1678,6 +1850,52 @@ export async function resolveCiEvidenceAtom(prNumber, roots, opts = {}) {
             descendantReason = found.reason;
         }
     }
+    // T14032 (owner decision D11192): a workspace-wide change, which only a full
+    // run speaks for, is stood in for by a green push run of every required
+    // check on the default branch's current head, descending from the merge,
+    // whatever the merge's own run concluded and whatever later commits touched:
+    // that run tested the merged change as it is now (as the T13673 test-run
+    // stand-in does). A scoped change keeps the T12742 rule alone.
+    let workspaceWide;
+    let currentHeadReason;
+    if (!judgedChecks.ok && onDefault.ref !== null && !docsOnlyDiff) {
+        const wide = await (opts.workspaceWideReason ?? defaultWorkspaceWideReason)(cwd, pr.changedPaths);
+        if (wide !== null) {
+            const found = await findGreenCurrentHead({
+                ...(jobSpecs.length > 0 ? { jobs: jobSpecs } : {}),
+                required: required.workflows,
+                mergeCommitSha: pr.mergeCommitSha,
+                pins,
+                ref: onDefault.ref,
+                cwd,
+                fetchChecks,
+                defaultBranchHead: opts.defaultBranchHead ?? defaultBranchHeadOf,
+                changedBetween: opts.changedBetween ?? defaultChangedBetween,
+                firstParentOf: opts.firstParentOf ?? defaultFirstParentOf,
+                isAncestor: opts.isAncestor ?? defaultIsAncestor,
+            });
+            const rejudged = found.ok
+                ? evaluateMergeCommitChecks(required.workflows, [...checks, ...found.checks], pr.mergeCommitSha, {
+                    ...(treeEqualHead ? { treeEquivalentSha: treeEqualHead } : {}),
+                    pins,
+                    descendantSha: found.sha,
+                    currentHead: true,
+                })
+                : null;
+            if (found.ok && rejudged?.ok) {
+                checks = [...checks, ...found.checks];
+                judgedChecks = rejudged;
+                descendant = { sha: found.sha, range: found.range };
+                workspaceWide = wide;
+            }
+            else {
+                const why = found.ok
+                    ? `${found.sha.slice(0, 12)} was green, but re-judging with it still fails: ${rejudged && !rejudged.ok ? rejudged.reasons.join('; ') : ''}`
+                    : found.reason;
+                currentHeadReason = `the change is workspace-wide (${wide}), so a green push run of the required checks on the current ${onDefault.ref} HEAD would stand in (T14032), but ${why}`;
+            }
+        }
+    }
     if (!judgedChecks.ok) {
         const waiting = judgedChecks.reasons.some((r) => /pending|not found|missing/.test(r));
         return {
@@ -1686,6 +1904,7 @@ export async function resolveCiEvidenceAtom(prNumber, roots, opts = {}) {
             reason: `Required CI on PR #${prNumber}'s merge commit ${pr.mergeCommitSha.slice(0, 12)} is not green ` +
                 `(source: ${describeRequiredWorkflowsSource(required.source)}):\n  - ${judgedChecks.reasons.join('\n  - ')}` +
                 (descendantReason ? `\n  No later main run stands in: ${descendantReason}` : '') +
+                (currentHeadReason ? `\n  No current-HEAD run stands in: ${currentHeadReason}` : '') +
                 (mainOnly
                     ? `\n  PR #${prNumber} edits the pinned workflow ${editedWorkflows.join(', ')}, so only main's push CI attests it (T13174)` +
                         (waiting
@@ -1806,6 +2025,7 @@ export async function resolveCiEvidenceAtom(prNumber, roots, opts = {}) {
                     ...(descendant.nonTest ? { nonTestFailures: descendant.nonTest } : {}),
                 }
                 : {}),
+            ...(workspaceWide ? { workspaceWide } : {}),
             ...(mainOnly ? { mainOnly: true } : {}),
             requiredSource: required.source.tier,
             taskId: context.task.id,