@cleocode/core 2026.9.19 → 2026.9.21

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

@@ -0,0 +1,223 @@
+/**
+ * `ci:<pr>` evidence — required CI green on a merged PR's MERGE COMMIT.
+ *
+ * Owner decision D11149: when every required check completed with `success`
+ * on the commit a PR actually merged as, that satisfies `testsPassed` and
+ * `qaPassed` for the task the PR closes. It replaces the post-merge local
+ * full-suite rerun, which was the single largest override driver. Opt-in via
+ * `evidence.ciSatisfies: true` in `.cleo/project-context.json`.
+ *
+ * Verified the way `pr:` provenance is:
+ *
+ *  - the PR itself goes through {@link resolvePrEvidenceAtom} (merged, a real
+ *    merge-commit identity), so a `ci:` atom can never outrun `pr:`;
+ *  - the required-check list comes from the SAME resolver `pr:` uses
+ *    (env → `release.prRequiredWorkflows` → branch protection), and an
+ *    undetermined list refuses rather than accepting vacuously;
+ *  - each required name is judged on the merge commit's own check runs and
+ *    workflow runs (GitHub REST, by SHA). A run whose `head_sha` is anything
+ *    else — the PR head included — never counts, and a required check found
+ *    only there is named as such.
+ *
+ * Pending, failed, cancelled, skipped and missing required checks are each
+ * refused with the check's name and state.
+ *
+ * @task T12634
+ */
+import type { EvidenceAtom, EvidenceValidationContext } from '@cleocode/contracts';
+import { type EvidenceRoots } from '../tasks/evidence.js';
+import { type PrAtomResolution, type RequiredCheckPinSpec } from './pr-evidence.js';
+/** One check on a commit: a job (check run) or a whole workflow run. */
+export interface CommitCheck {
+    /** Check-run (job) name or workflow name. */
+    name: string;
+    /** Which GitHub object reported it. */
+    source: 'check-run' | 'workflow-run';
+    /** `queued` / `in_progress` / `completed` / … */
+    status: string;
+    /** `success` / `failure` / `skipped` / … — null until completed. */
+    conclusion: string | null;
+    /** The commit the check ran on. */
+    headSha: string;
+    /** GitHub id; a higher id is a later attempt within the same event. */
+    id: number;
+    /** Posting GitHub App slug (`github-actions`, …), when known. */
+    appSlug?: string;
+    /** Posting GitHub App id, when known. */
+    appId?: number;
+    /** Workflow file that produced the run, when known. */
+    workflowPath?: string;
+    /** Triggering event (`push`, `pull_request`, …), when known. */
+    event?: string;
+}
+/** A judged check: which run, on which commit, attests a required name. */
+export interface JudgedCheck {
+    name: string;
+    conclusion: string;
+    sha: string;
+    app?: string;
+    workflow?: string;
+    event?: string;
+}
+/** Result of {@link evaluateMergeCommitChecks}. */
+export type MergeCommitCheckResult = {
+    ok: true;
+    checks: JudgedCheck[];
+} | {
+    ok: false;
+    reasons: string[];
+};
+/** Options for {@link evaluateMergeCommitChecks}. */
+export interface EvaluateMergeCommitChecksOptions {
+    /**
+     * PR head whose `pull_request` runs tested exactly the merged tree (tree
+     * equal AND the merge's first parent is an ancestor of it). Its runs stand
+     * in for a merge-commit run that was cancelled or never started.
+     */
+    treeEquivalentSha?: string;
+    /** Required-name → app/workflow pin; a run from anything else never counts. */
+    pins?: Record<string, RequiredCheckPinSpec>;
+}
+/** A `ci:` atom resolution: the validated atom, or the refusal. */
+export type CiAtomResolution = {
+    ok: true;
+    atom: Extract<EvidenceAtom, {
+        kind: 'ci';
+    }>;
+} | {
+    ok: false;
+    reason: string;
+    codeName: 'E_EVIDENCE_INSUFFICIENT' | 'E_EVIDENCE_TESTS_FAILED' | 'E_EVIDENCE_TOOL_FAILED' | 'E_EVIDENCE_INVALID' | 'E_EVIDENCE_GIT_ROOT' | 'E_EVIDENCE_CONTENT_MISMATCH';
+};
+/** Injectable I/O for {@link resolveCiEvidenceAtom}. */
+export interface ResolveCiEvidenceOptions {
+    /** Task, gates and criteria the atom is validated for; required (like `pr:`). */
+    context?: EvidenceValidationContext;
+    /** PR provenance; defaults to {@link resolvePrEvidenceAtom}. */
+    resolvePr?: (prNumber: number, roots: EvidenceRoots) => Promise<PrAtomResolution>;
+    /** Checks reported for one commit SHA; defaults to the GitHub REST API via `gh`. */
+    fetchChecks?: (sha: string, cwd: string) => Promise<{
+        ok: true;
+        checks: CommitCheck[];
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** Parsed `.cleo/project-context.json`, for the required-check list and pins. */
+    projectContext?: Record<string, unknown> | null;
+    /** Tree SHA of a commit, or null when the object is not local; defaults to `git rev-parse`. */
+    treeOf?: (sha: string, cwd: string) => string | null;
+    /** Whether `ancestor` is an ancestor of `descendant`; defaults to `git merge-base --is-ancestor`. */
+    isAncestor?: (ancestor: string, descendant: string, cwd: string) => boolean;
+    /** First parent of a commit, or null; defaults to `git rev-parse <sha>^1`. */
+    firstParentOf?: (sha: string, cwd: string) => string | null;
+    /**
+     * Whether a commit has landed on origin's default branch; defaults to
+     * `origin/HEAD` (else origin/main, origin/master) and `merge-base --is-ancestor`.
+     */
+    onDefaultBranch?: (sha: string, cwd: string) => {
+        ref: string | null;
+        landed: boolean;
+    };
+}
+/**
+ * Whether the project opted in to merge-commit CI as test/QA evidence
+ * (`evidence.ciSatisfies === true`; anything else, including a missing file,
+ * is `false`).
+ *
+ * @param projectRoot - CLEO store root.
+ * @returns True only for an explicit boolean `true`.
+ * @task T12634
+ */
+export declare function readCiSatisfies(projectRoot: string): boolean;
+/**
+ * The checks that attest each gate (`evidence.ciChecks`, T12634).
+ *
+ * @param projectRoot - CLEO store root.
+ * @returns `tests` → testsPassed, `qa` → qaPassed; a missing list is absent.
+ * @task T12634
+ */
+export declare function readCiChecks(projectRoot: string): CiChecksConfig;
+/** `evidence.ciChecks` as read from project context (T12634). */
+export interface CiChecksConfig {
+    /** Required checks attesting testsPassed. */
+    tests?: string[];
+    /** Required checks attesting qaPassed. */
+    qa?: string[];
+    /**
+     * Job-name globs (`*` wildcard) that must each match at least one job run by
+     * the pinned workflows of that gate's checks, all `success`, before a `code`
+     * task's gate is attested — an aggregate that counts skipped jobs as a pass
+     * is not enough.
+     */
+    jobs?: {
+        tests?: string[];
+        qa?: string[];
+    };
+}
+/**
+ * Stricter than `pr:`'s {@link isDocumentArtifact}: a documentation artifact
+ * that lives outside every code root. Only a diff made entirely of these may
+ * leave its test and typecheck jobs honestly skipped.
+ *
+ * @param path - Repo-relative changed path.
+ * @returns True when the path cannot affect code, tests or CI.
+ * @task T12634
+ */
+export declare function isCiDocumentPath(path: string): boolean;
+/**
+ * Judge job globs on one SHA: every glob must match at least one job (check
+ * run) from the allowed workflows/app, and the latest run of each matched
+ * (job, event) must be `success` — a `skipped` job is refused by name.
+ *
+ * @param globs - Job-name globs for the gate.
+ * @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.
+ * @param onlyEvent - Restrict to runs of this event (the PR-head substitution).
+ * @returns The judged job names, or one reason per unmet glob.
+ * @task T12634
+ */
+export declare function evaluateJobs(globs: readonly string[], checks: readonly CommitCheck[], sha: string, scope: {
+    app?: string | number;
+    workflows: readonly string[];
+}, onlyEvent?: string): {
+    ok: true;
+    jobs: string[];
+} | {
+    ok: false;
+    reasons: string[];
+};
+/**
+ * Judge required checks on one merge commit. Pure.
+ *
+ * For each required name, runs are grouped by source (job / workflow) and
+ * triggering event, and within a group only the LATEST attempt counts; every
+ * group on the merge commit must be `completed`/`success`. A pinned name only
+ * considers runs from its pinned app/workflow. When `treeEquivalentSha` is
+ * given, that commit's `pull_request` runs (and only those) stand in for a
+ * merge-commit verdict that failed or is missing.
+ *
+ * @param required - Required check names.
+ * @param checks - Every check reported for the commits involved.
+ * @param mergeCommitSha - The merge commit being judged.
+ * @param opts - Tree-equivalent PR head and pins.
+ * @returns The judged checks, or one reason per unmet name.
+ * @task T12634
+ */
+export declare function evaluateMergeCommitChecks(required: readonly string[], checks: readonly CommitCheck[], mergeCommitSha: string, opts?: EvaluateMergeCommitChecksOptions): MergeCommitCheckResult;
+/**
+ * Validate a `ci:<pr>` atom end to end.
+ *
+ * @param prNumber - The merged PR.
+ * @param roots - Store root (config, caches) and execution root (`gh` cwd).
+ * @param opts - Injectable PR resolution and check fetching.
+ * @returns The validated atom, or a refusal naming every unmet check.
+ * @example
+ * ```ts
+ * const r = await resolveCiEvidenceAtom(357, { storeRoot, executionRoot });
+ * ```
+ * @task T12634
+ */
+export declare function resolveCiEvidenceAtom(prNumber: number, roots: EvidenceRoots, opts?: ResolveCiEvidenceOptions): Promise<CiAtomResolution>;
+//# sourceMappingURL=ci-evidence.d.ts.map

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

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