@cleocode/core 2026.10.27 → 2026.11.1-canary.10

package/dist/release/ci-evidence.d.ts

@@ -47,6 +47,14 @@
  * merge stands in, whatever the merge's own run concluded and whatever later
  * commits touched. See {@link findGreenCurrentHead}.
  *
+ * A fifth (T14434, owner decision D11241, extending D11192): the same
+ * current-head run stands in for a SCOPED change too, when the merge commit's
+ * red or cancelled run is not the PR's (the T12742, T13453, T13809 and T14049
+ * judgements), the PR head's own CI was green, and every hunk the PR added is
+ * still there at the stand-in. It runs today's CI definition: the owner
+ * accepted that a later change weakening a check also releases the tasks
+ * waiting behind it. A failure that is the PR's still refuses.
+ *
  * @task T12634
  */
 import type { EvidenceAtom, EvidenceValidationContext } from '@cleocode/contracts';
@@ -79,6 +87,10 @@ export interface CommitCheck {
     runAttempt?: number;
     /** ISO 8601 time the run (or this attempt of it) started, when known (T14026). */
     startedAt?: string;
+    /** The workflow run a job belongs to, when read per attempt (T14253). */
+    runId?: number;
+    /** ISO 8601 time the job completed, when read per attempt (T14253). */
+    completedAt?: string;
 }
 /** A judged check: which run, on which commit, attests a required name. */
 export interface JudgedCheck {
@@ -146,10 +158,27 @@ export interface MainCommit {
     /** Number of parents; 2+ is a merge commit. */
     parents: number;
 }
+/**
+ * What a targeted `test-run:` report must cover, worded once for the
+ * validator's refusal and for every hint that offers a targeted run (T14119),
+ * so a hint never offers a route the validator refuses.
+ *
+ * @task T14119
+ */
+export declare const TARGETED_RUN_COVERAGE: string;
 /** Most later default-branch commits examined for a green stand-in run (T12742). */
 export declare const CI_DESCENDANT_MAX_CANDIDATES = 20;
 /** Latest committer time after the merge commit a stand-in may have (T12742): 7 days. */
 export declare const CI_DESCENDANT_MAX_AGE_SECONDS: number;
+/**
+ * What a `ci:` refusal says while the current-head stand-in is still open
+ * (T14032, T14434): nothing on the merge commit is the PR's to fix, and the
+ * task closes once the default branch's head has green CI. The merge sweep
+ * reads it to keep waiting instead of refusing.
+ *
+ * @task T14434
+ */
+export declare const CURRENT_HEAD_STAND_IN_OPEN = "a green push run of the required checks on the default branch head will stand in";
 /** A `ci:` atom resolution: the validated atom, or the refusal. */
 export type CiAtomResolution = {
     ok: true;
@@ -220,6 +249,12 @@ export interface ResolveCiEvidenceOptions {
      * `git log --first-parent -- <paths>`.
      */
     touchingCommits?: (from: string, to: string, paths: readonly string[], cwd: string) => MainCommit[] | null;
+    /**
+     * When later commits edited the PR's files, the first hunk the PR added
+     * that is no longer present at `at` (T14119), or null when every one is.
+     * Defaults to {@link missingPrHunk}.
+     */
+    missingPrHunk?: (merge: string, at: string, paths: readonly string[], cwd: string) => string | null;
     /**
      * Plain-text log of one Actions job (a check-run id), or null when it cannot
      * be read (T13809). Defaults to `gh api repos/{owner}/{repo}/actions/jobs/<id>/logs`.
@@ -278,16 +313,6 @@ export declare function ciSatisfiesRemedy(root: string, opts?: {
  * @task T12634
  */
 export declare function readCiChecks(projectRoot: string): CiChecksConfig;
-/**
- * One `evidence.ciChecks.covering` rule (T13175): changed paths matching
- * `paths` are covered by the jobs matching `jobs`.
- */
-export interface CoveringJobRule {
-    /** Repo-relative path globs (`**` any depth, `*` within one segment). */
-    paths: string[];
-    /** Job-name globs (`*` wildcard) that must each have run and succeeded. */
-    jobs: string[];
-}
 /** `evidence.ciChecks` as read from project context (T12634). */
 export interface CiChecksConfig {
     /** Required checks attesting testsPassed. */
@@ -304,18 +329,16 @@ export interface CiChecksConfig {
         tests?: string[];
         qa?: string[];
     };
-    /**
-     * T13175: jobs that cover changed paths a change-detection filter keeps out
-     * of the `jobs` globs (e.g. `scripts/**` → `Scripts Tests`). When every
-     * required job of a gate was SKIPPED (by its `if:` filter; a failure upstream
-     * already turns the required check red) and every changed path matches a
-     * rule whose jobs ran and succeeded, those jobs attest the gate instead.
-     */
-    covering?: {
-        tests?: CoveringJobRule[];
-        qa?: CoveringJobRule[];
-    };
 }
+/**
+ * The package code roots (T14260): every path under them is code for CI's
+ * `code` change filter (so a template `.md` runs the unit shards) and for
+ * evidence (so a filter skip never stands in for their tests). The CI filter
+ * is pinned to this list by a test in `__tests__/ci-evidence.test.ts`.
+ *
+ * @task T14260
+ */
+export declare const PACKAGE_CODE_ROOTS: readonly string[];
 /**
  * Stricter than `pr:`'s {@link isDocumentArtifact}: a documentation artifact
  * that lives outside every code root. Only a diff made entirely of these may
@@ -327,37 +350,42 @@ export interface CiChecksConfig {
  */
 export declare function isCiDocumentPath(path: string): boolean;
 /**
- * Path glob to an anchored regular expression (T13175): `**` followed by `/` is
- * any number of whole directories (including none), a trailing `/` followed by
- * `**` is everything below, `*` any run of characters within one segment, `?`
- * one character within a segment. Everything else is literal.
+ * Whether a check run's name is the job a configured glob names (T14148). A
+ * matrix job's `name:` is a template (`Type Check${{ matrix.node … }}`), and a
+ * job skipped before its matrix expands reports that raw template as its check
+ * name; its static prefix (`Type Check`) is the job's name, so the skip counts
+ * as the job's, the same job its rendered variants run as.
  *
- * @param glob - Repo-relative path glob.
- * @returns The anchored expression.
+ * @param re - The configured job glob, anchored.
+ * @param name - The check run's name.
+ * @returns True when the run belongs to the job.
+ * @task T14148
  */
-export declare function pathGlobToRegExp(glob: string): RegExp;
+export declare function jobNameMatches(re: RegExp, name: string): boolean;
 /**
- * Judge a gate's required jobs with the covering rules (T13175): accepted only
+ * Judge a gate's required jobs as skipped by CI's own change filter (T14260):
+ * accepted only for a diff entirely outside the {@link PACKAGE_CODE_ROOTS},
  * when each required glob either succeeded or had every latest run completed
- * `skipped` (never cancelled, failed, pending or missing), at least one was
- * skipped, every changed path matches a rule, and every job glob of each rule
- * used has run and succeeded on `sha`.
+ * `skipped` (never cancelled, failed, pending or missing) and at least one
+ * was skipped. The caller has already found the required checks (the `CI`
+ * aggregate) green, so the skip is CI's verdict that the change touches
+ * nothing those jobs test.
  *
  * @param globs - The gate's required job globs (`evidence.ciChecks.jobs`).
- * @param rules - The gate's covering rules.
  * @param changedPaths - The PR's changed paths.
  * @param checks - Every check reported for the commit.
  * @param sha - Commit being judged.
  * @param scope - The app and workflow files the jobs must come from.
- * @returns The covering job names, or why coverage does not apply.
- * @task T13175
+ * @returns The jobs that ran and the ones the filter skipped, or why the skip does not count.
+ * @task T14260
  */
-export declare function evaluateCoveringJobs(globs: readonly string[], rules: readonly CoveringJobRule[], changedPaths: readonly string[], checks: readonly CommitCheck[], sha: string, scope: {
+export declare function evaluateFilterSkippedJobs(globs: readonly string[], changedPaths: readonly string[], checks: readonly CommitCheck[], sha: string, scope: {
     app?: string | number;
     workflows: readonly string[];
 }): {
     ok: true;
     jobs: string[];
+    skipped: string[];
 } | {
     ok: false;
     reason: string;
@@ -427,7 +455,9 @@ export type SupersededOnMergeResult = {
  * SUPERSEDED there (T12742): its latest merge-commit verdict is `cancelled`
  * or `skipped`, and no run of a required check or of a job in a pinned
  * workflow on the merge commit — any attempt — concluded with a failure. A
- * failed, timed-out, pending or missing check is never superseded. Pure.
+ * failed, timed-out or pending check is never superseded, nor is a missing
+ * one unless its pinned workflow's run on the merge commit was cancelled or
+ * skipped, so it never ran (T14103, T14144). Pure.
  *
  * @param required - Required check names.
  * @param checks - Every check fetched for the merge commit (and PR head).
@@ -645,6 +675,28 @@ export declare function untestedJobFailures(checks: readonly CommitCheck[], sha:
  * @task T13809
  */
 export declare function isSetupStepFailureLog(log: string): boolean;
+/**
+ * The step a job failed in (T14252): the `Run …` header of the group the
+ * log's first `##[error]` line belongs to, trimmed; `null` when the log names
+ * no error or no step. Two runs that fail in the same step failed the same way
+ * even when no test ran (a gate script, a bundle budget).
+ *
+ * @param log - The job's plain-text log (ANSI colour codes allowed).
+ * @returns The step's command line, or `null`.
+ * @task T14252
+ */
+export declare function failedStepOf(log: string): string | null;
+/**
+ * The test files that failed a job and decided it (T14252), as
+ * `<project>:<file>` from vitest's `FAIL  <project> <file>` lines. When the
+ * job re-ran its failing files once (T13145), only the files that failed
+ * again count; a first-run failure the re-run cleared never blocked the job.
+ *
+ * @param log - The job's plain-text log (ANSI colour codes allowed).
+ * @returns The blocking test identities, sorted.
+ * @task T14252
+ */
+export declare function blockingTestIds(log: string): string[];
 /**
  * Whether a later commit's CI failed before any test ran (T13809): every
  * failing job's log is readable and failed in a setup action step
@@ -697,6 +749,8 @@ export interface FindGreenDescendantInput {
     listDescendants: NonNullable<ResolveCiEvidenceOptions['listDescendants']>;
     /** First-parent commits in a range touching paths. */
     touchingCommits: NonNullable<ResolveCiEvidenceOptions['touchingCommits']>;
+    /** First PR hunk missing at a later commit (T14119). */
+    missingPrHunk: NonNullable<ResolveCiEvidenceOptions['missingPrHunk']>;
     /** Ancestry test. */
     isAncestor: NonNullable<ResolveCiEvidenceOptions['isAncestor']>;
     /** First parent of a commit (T13453: the inherited-failure walk); absent = never inherit. */
@@ -747,10 +801,41 @@ export type FindGreenDescendantResult = {
     untested?: UntestedJobFailure[];
     /** Later runs the search looked past, and why (T14086). */
     passedOver?: PassedOverRun[];
+    /**
+     * What was proven before the walk (T14434), for the caller whose
+     * re-judgement with this stand-in still fails (a required check that
+     * never ran on the merge commit): the current-head stand-in may be tried.
+     */
+    cleared: ClearedMerge;
 } | {
     ok: false;
     reason: string;
+    /**
+     * Set when only the walk refused (T14434): the merge commit's run is not
+     * the PR's failure and the PR head's own CI was green, so the
+     * current-head stand-in may still be tried.
+     */
+    cleared?: ClearedMerge;
 };
+/**
+ * A merge commit whose red or cancelled run is not the PR's, with a green PR
+ * head: what {@link findGreenDescendant} proved before it walked (T14434).
+ */
+export interface ClearedMerge {
+    /** The PR head whose `pull_request` runs were green; absent in `mainOnly` mode. */
+    prHeadSha?: string;
+    /** Checks fetched for that head. */
+    headChecks: CommitCheck[];
+    /** The merge commit's inherited failures (T13453). */
+    inherited?: InheritedFailure[];
+    /** The merge commit's quarantine-budget failures (T13809). */
+    nonTest?: Array<{
+        name: string;
+        mergeRunId: number;
+    }>;
+    /** The merge commit's failures that tested nothing (T14049, T14074). */
+    untested?: UntestedJobFailure[];
+}
 /**
  * Find a later default-branch commit whose green `push` CI stands in for a
  * merge-commit run that a concurrency group cancelled (T12742).
@@ -775,8 +860,10 @@ export type FindGreenDescendantResult = {
  *    failed job of a pinned workflow) refuses, and a PENDING run refuses with
  *    "wait for <sha>" — a later green run is never shopped for past one that
  *    is red or may still go red. Only cancelled, skipped and missing
- *    (never-started) runs, and a run red only for the flaky-quarantine budget
- *    (T13809), move on to the next candidate.
+ *    (never-started) runs, a run red only for the flaky-quarantine budget
+ *    (T13809), and a run whose every failing job tested nothing — its runner
+ *    was cancelled or a test worker crashed, no test failed (T14176) — move
+ *    on to the next candidate.
  *
  * @param input - Merge-commit checks, pins, changed paths, PR head and injected I/O.
  * @returns The stand-in SHA, its checks and proven range, or the refusal reason.
@@ -836,12 +923,18 @@ export type FindGreenCurrentHeadResult = {
  *
  * 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
+ * reads moved), or while every commit stepped past had green required checks
+ * and its gates' jobs skipped by CI's own change filter (T14177: the filter
+ * judged its change untested), 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.
  *
+ * The same run stands in for a scoped change (T14434, owner decision D11241)
+ * once the caller has shown the merge commit's failure is not the PR's, the PR
+ * head's own CI was green and the PR's hunks are intact at the stand-in.
+ *
  * @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
@@ -875,6 +968,22 @@ export declare function listMainDescendants(mergeSha: string, ref: string, cwd:
  * @task T12742
  */
 export declare function listPathTouchingMainCommits(from: string, to: string, paths: readonly string[], cwd: string): MainCommit[] | null;
+/**
+ * Default {@link ResolveCiEvidenceOptions.missingPrHunk} (T14119): the first
+ * hunk the PR added (`git diff -U0 <merge>^1 <merge>`) whose added lines no
+ * longer appear, contiguous and in order, in that file at `at`. A binary file
+ * counts as missing once its blob differs. Lines the PR removed are not
+ * checked: a later commit cannot un-test a deletion. A git error is reported
+ * as missing, never as present.
+ *
+ * @param merge - The PR's merge commit (its first parent is the base).
+ * @param at - The later commit whose run would stand in.
+ * @param paths - The PR's changed paths.
+ * @param cwd - Repository work tree.
+ * @returns The missing hunk, described, or null when every hunk is present.
+ * @task T14119
+ */
+export declare function missingPrHunk(merge: string, at: string, paths: readonly string[], cwd: string): string | null;
 /**
  * Default branch name from `gh repo view --json defaultBranchRef`.
  *
@@ -884,6 +993,10 @@ export declare function listPathTouchingMainCommits(from: string, to: string, pa
  * @task T12959
  */
 export declare function ghDefaultBranch(cwd: string): string | null;
+/** The first parent of `sha` in `cwd`'s git, or `null` when unknown. */
+export declare function defaultFirstParentOf(sha: string, cwd: string): string | null;
+/** Default {@link ResolveCiEvidenceOptions.fetchJobLog}: the job's plain-text log via `gh` (T13809). */
+export declare function defaultFetchJobLog(jobId: number, cwd: string): Promise<string | null>;
 /**
  * Fetch once more when a required check's run came back without the identity
  * its pin names (T13017): GitHub lists a job before its workflow run, and a
@@ -908,14 +1021,46 @@ export declare function refetchIncompleteIdentity(fetchChecks: NonNullable<Resol
  * @task T13623
  */
 export declare function withoutScheduledRuns(fetchChecks: NonNullable<ResolveCiEvidenceOptions['fetchChecks']>): NonNullable<ResolveCiEvidenceOptions['fetchChecks']>;
+/**
+ * Default {@link ResolveCiEvidenceOptions.fetchChecks}: check runs + workflow
+ * runs for a SHA. Workflow runs carry their event and workflow file; a check
+ * run inherits both from the workflow run of its check suite.
+ */
+export declare function defaultFetchChecks(sha: string, cwd: string): Promise<{
+    ok: true;
+    checks: CommitCheck[];
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Every attempt's jobs of the GitHub Actions `event` runs on `sha` (T14253):
+ * `commits/<sha>/check-runs` keeps only each job's latest attempt, so a
+ * rerun would replace the evidence; `actions/runs/<id>/attempts/<n>/jobs`
+ * keeps each attempt, with its run id, attempt number and times.
+ *
+ * @param sha - The commit.
+ * @param cwd - Repository work tree for `gh`.
+ * @param event - The triggering event (`push` for main).
+ * @returns The jobs of every attempt, or why they could not be read.
+ * @task T14253
+ */
+export declare function defaultFetchRunAttemptJobs(sha: string, cwd: string, event?: string): Promise<{
+    ok: true;
+    checks: CommitCheck[];
+} | {
+    ok: false;
+    reason: string;
+}>;
 /**
  * Re-check, at `cleo complete`, a `ci:` atom that leaned on a later main
  * commit (T12742). A completed conclusion is NOT immutable: a GitHub re-run
  * adds a newer attempt that can go red. Every check judged on the
  * descendant is re-fetched and its latest `push` attempt (same app and
  * workflow) must still be `success`; each such check's latest
- * `pull_request` attempt on the recorded PR head must be too. Atoms without
- * `descendantSha` pass untouched.
+ * `pull_request` attempt on the recorded PR head must be too; for a
+ * `currentHead` atom (T14434) every required check on that head must be.
+ * Atoms without `descendantSha` pass untouched.
  *
  * @param atom - The recorded `ci:` atom.
  * @param cwd - Repository work tree for `gh`.
@@ -945,4 +1090,3 @@ export declare function recheckCiDescendantAtom(atom: Extract<EvidenceAtom, {
  * @task T12634
  */
 export declare function resolveCiEvidenceAtom(prNumber: number, roots: EvidenceRoots, opts?: ResolveCiEvidenceOptions): Promise<CiAtomResolution>;
-//# sourceMappingURL=ci-evidence.d.ts.map