pr-merge-queue 0.0.0-stage → 0.0.0

package/dist/unblock-prs/checks.d.mts

@@ -0,0 +1,307 @@
+/**
+ * What the merge is waiting for, read from the head commit's checks and
+ * judged against the contexts the ruleset requires.
+ */
+import { Result } from 'ts-data-forge';
+import * as t from 'ts-fortress';
+import { type ApiContext } from '../lib/index.mjs';
+import type { ChecksSummary } from './types.mjs';
+/**
+ * One check on the head, in the shape `gh pr checks --json` printed, which
+ * is what this script read until it called the API itself.
+ */
+export type ReportedCheck = Readonly<{
+    name: string;
+    /** `pass` | `fail` | `pending` | `skipping` | `cancel` */
+    bucket: string;
+    link: string;
+    /** ISO 8601; GitHub's zero time before the check has started. */
+    startedAt: string;
+    /** ISO 8601; GitHub's zero time before the check has finished. */
+    completedAt: string;
+    /** The workflow the job belongs to; empty for a commit status. */
+    workflow: string;
+}>;
+/**
+ * A check on the head that has not finished, when it started, and the
+ * workflow run it is a job of.
+ */
+export type RunningCheck = Readonly<{
+    name: string;
+    startedAt: string;
+    workflow: string;
+    link: string;
+}>;
+/**
+ * The checks that gate the merge, as GitHub reports them for the head commit.
+ * `isRequired` is GitHub's own answer for this pull request, so the list
+ * follows the ruleset without this script having to know it.
+ */
+export declare const listRequiredChecks: (api: ApiContext, prNumber: number) => Promise<Result<readonly ReportedCheck[], string>>;
+/**
+ * The checks on the head commit that have not finished, required or not.
+ *
+ * A required aggregate has no run in a new round until the jobs it waits on
+ * are done, so until then the required ones answer with the round before.
+ * When that round was the one `skip-ci` skipped, every aggregate reads
+ * `skipped` and the commit looks green halfway through its matrix. Anything
+ * still running is what says the round is not over, and when it started is
+ * what tells a failure of the round before from one of this round.
+ */
+export declare const listRunningChecks: (api: ApiContext, prNumber: number) => Promise<Result<readonly RunningCheck[], string>>;
+/**
+ * What the head commit's checks say, as `gh pr checks` said it: each check
+ * run and commit status in a bucket, and of the runs of one job in one
+ * workflow and event only the latest — a re-run, or the round `skip-ci`
+ * cancelled under the one now running — so that a superseded failure does
+ * not speak for its context. `which` is `'required'` for only what GitHub
+ * says this pull request requires.
+ *
+ * Unlike `gh`, the survivors keep the order GitHub listed them in. A commit
+ * status's start and finish are both when it was set, the one time it has.
+ */
+export declare const reportedChecksOf: (contexts: readonly CheckContextNode[], which: 'all' | 'required') => readonly ReportedCheck[];
+/** A context of the head commit's status check rollup, as read. */
+export type CheckContextNode = t.TypeOf<typeof CheckContextNodeSchema>;
+declare const CheckContextNodeSchema: Readonly<{
+    typeName: string;
+    defaultValue: Readonly<{
+        __typename: "CheckRun";
+        checkSuite: Readonly<{
+            workflowRun: Readonly<{
+                event: string;
+                workflow: Readonly<{
+                    name: string;
+                }>;
+            }> | null;
+        }> | null;
+        completedAt: string | null;
+        conclusion: string | null;
+        detailsUrl: string | null;
+        isRequired: boolean;
+        name: string;
+        startedAt: string | null;
+        status: string;
+    }> | Readonly<{
+        __typename: "StatusContext";
+        context: string;
+        createdAt: string;
+        isRequired: boolean;
+        state: string;
+        targetUrl: string | null;
+    }>;
+    is: (a: unknown) => a is Readonly<{
+        __typename: "CheckRun";
+        checkSuite: Readonly<{
+            workflowRun: Readonly<{
+                event: string;
+                workflow: Readonly<{
+                    name: string;
+                }>;
+            }> | null;
+        }> | null;
+        completedAt: string | null;
+        conclusion: string | null;
+        detailsUrl: string | null;
+        isRequired: boolean;
+        name: string;
+        startedAt: string | null;
+        status: string;
+    }> | Readonly<{
+        __typename: "StatusContext";
+        context: string;
+        createdAt: string;
+        isRequired: boolean;
+        state: string;
+        targetUrl: string | null;
+    }>;
+    assertIs: (a: unknown) => asserts a is Readonly<{
+        __typename: "CheckRun";
+        checkSuite: Readonly<{
+            workflowRun: Readonly<{
+                event: string;
+                workflow: Readonly<{
+                    name: string;
+                }>;
+            }> | null;
+        }> | null;
+        completedAt: string | null;
+        conclusion: string | null;
+        detailsUrl: string | null;
+        isRequired: boolean;
+        name: string;
+        startedAt: string | null;
+        status: string;
+    }> | Readonly<{
+        __typename: "StatusContext";
+        context: string;
+        createdAt: string;
+        isRequired: boolean;
+        state: string;
+        targetUrl: string | null;
+    }>;
+    cast: (a: unknown) => Readonly<{
+        __typename: "CheckRun";
+        checkSuite: Readonly<{
+            workflowRun: Readonly<{
+                event: string;
+                workflow: Readonly<{
+                    name: string;
+                }>;
+            }> | null;
+        }> | null;
+        completedAt: string | null;
+        conclusion: string | null;
+        detailsUrl: string | null;
+        isRequired: boolean;
+        name: string;
+        startedAt: string | null;
+        status: string;
+    }> | Readonly<{
+        __typename: "StatusContext";
+        context: string;
+        createdAt: string;
+        isRequired: boolean;
+        state: string;
+        targetUrl: string | null;
+    }>;
+    fill: (a: unknown) => Readonly<{
+        __typename: "CheckRun";
+        checkSuite: Readonly<{
+            workflowRun: Readonly<{
+                event: string;
+                workflow: Readonly<{
+                    name: string;
+                }>;
+            }> | null;
+        }> | null;
+        completedAt: string | null;
+        conclusion: string | null;
+        detailsUrl: string | null;
+        isRequired: boolean;
+        name: string;
+        startedAt: string | null;
+        status: string;
+    }> | Readonly<{
+        __typename: "StatusContext";
+        context: string;
+        createdAt: string;
+        isRequired: boolean;
+        state: string;
+        targetUrl: string | null;
+    }>;
+    prune: <B extends Readonly<{
+        __typename: "CheckRun";
+        checkSuite: Readonly<{
+            workflowRun: Readonly<{
+                event: string;
+                workflow: Readonly<{
+                    name: string;
+                }>;
+            }> | null;
+        }> | null;
+        completedAt: string | null;
+        conclusion: string | null;
+        detailsUrl: string | null;
+        isRequired: boolean;
+        name: string;
+        startedAt: string | null;
+        status: string;
+    }> | Readonly<{
+        __typename: "StatusContext";
+        context: string;
+        createdAt: string;
+        isRequired: boolean;
+        state: string;
+        targetUrl: string | null;
+    }>>(a: B) => Readonly<{
+        __typename: "CheckRun";
+        checkSuite: Readonly<{
+            workflowRun: Readonly<{
+                event: string;
+                workflow: Readonly<{
+                    name: string;
+                }>;
+            }> | null;
+        }> | null;
+        completedAt: string | null;
+        conclusion: string | null;
+        detailsUrl: string | null;
+        isRequired: boolean;
+        name: string;
+        startedAt: string | null;
+        status: string;
+    }> | Readonly<{
+        __typename: "StatusContext";
+        context: string;
+        createdAt: string;
+        isRequired: boolean;
+        state: string;
+        targetUrl: string | null;
+    }>;
+    validate: (a: unknown) => Result<Readonly<{
+        __typename: "CheckRun";
+        checkSuite: Readonly<{
+            workflowRun: Readonly<{
+                event: string;
+                workflow: Readonly<{
+                    name: string;
+                }>;
+            }> | null;
+        }> | null;
+        completedAt: string | null;
+        conclusion: string | null;
+        detailsUrl: string | null;
+        isRequired: boolean;
+        name: string;
+        startedAt: string | null;
+        status: string;
+    }> | Readonly<{
+        __typename: "StatusContext";
+        context: string;
+        createdAt: string;
+        isRequired: boolean;
+        state: string;
+        targetUrl: string | null;
+    }>, readonly Readonly<{
+        path: readonly string[];
+        actualValue: unknown;
+        expectedType: string;
+        typeName: string;
+        details?: t.ValidationErrorDetails | undefined;
+    }>[]>;
+    structure?: t.TypeStructure;
+    annotations?: t.TypeAnnotations;
+    optional?: true;
+}>;
+/**
+ * `checks` is what {@link listRequiredChecks} reported for the head commit;
+ * `requiredContexts` is what the ruleset asks for. The difference between the
+ * two is the point: a context in the second and not the first has not
+ * reported yet, and GitHub will not merge until it does. `running` is every
+ * check on the head that has not finished ({@link listRunningChecks}); while
+ * it is not empty the required ones may be the round before speaking, so
+ * they cannot pass the pull request.
+ *
+ * Nor can they fail it when they finished before the round still running
+ * began: the round `skip-ci` cancelled, as `open-pr` opens every pull request
+ * under it, leaves its aggregates red, and reading that red as this round's
+ * set a pull request aside while its first real round was under way (#2246).
+ * Such a failure waits for the round to end, as a check not yet reported
+ * does. So does one that finished after the round began but whose workflow
+ * has a newer run still going: the round `skip-ci` was put on for can take
+ * long enough to be cancelled that its aggregate goes red after the round
+ * taking its place has started, and only the run that replaced it says it is
+ * the round before (#2463). A failure of this round still fails the pull
+ * request at once.
+ *
+ * The verdict itself is `pr-report-core`'s `summarizeChecks`, which
+ * `pr-report` and the page reach theirs through, so the worker and the report
+ * cannot disagree about one; what is here turns what GitHub reports into
+ * the states that reads.
+ */
+export declare const summarizeChecks: (checks: readonly ReportedCheck[], requiredContexts: readonly string[], running: readonly RunningCheck[]) => ChecksSummary;
+/** Everything the merge is still waiting for, reported and unreported. */
+export declare const describeWaitingOn: (summary: ChecksSummary) => string;
+export {};
+//# sourceMappingURL=checks.d.mts.map

package/dist/unblock-prs/checks.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.mts","sourceRoot":"","sources":["../../src/unblock-prs/checks.mts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAAY,MAAM,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,CAAC,MAAM,aAAa,CAAC;AACjC,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QACxB,UAAU,YACL,MAAM,KACf,OAAO,CAAC,MAAM,CAAC,SAAS,aAAa,EAAE,EAAE,MAAM,CAAC,CAGhD,CAAC;AAEJ;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,QACvB,UAAU,YACL,MAAM,KACf,OAAO,CAAC,MAAM,CAAC,SAAS,YAAY,EAAE,EAAE,MAAM,CAAC,CAU/C,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,aACjB,SAAS,gBAAgB,EAAE,SAC9B,KAAK,GAAG,UAAU,KACxB,SAAS,aAAa,EAqBxB,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAsGvE,QAAA,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+B1B,CAAC;AAuGH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,eAAe,WAClB,SAAS,aAAa,EAAE,oBACd,SAAS,MAAM,EAAE,WAC1B,SAAS,YAAY,EAAE,KAC/B,aAmEF,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,YAAa,aAAa,KAAG,MAQ1D,CAAC"}

package/dist/unblock-prs/checks.mjs

@@ -0,0 +1,372 @@
+
+
+
+
+import { combineContextStates, epochMsOf, summarizeChecks as summarizeContexts, } from 'pr-report-core';
+import { Arr, Num, Result } from 'ts-data-forge';
+import * as t from 'ts-fortress';
+import { graphqlQuery } from '../lib/index.mjs';
+
+
+
+
+
+export const listRequiredChecks = async (api, prNumber) => Result.map(await readCheckContexts(api, prNumber), (contexts) => reportedChecksOf(contexts, 'required'));
+
+
+
+
+
+
+
+
+
+
+export const listRunningChecks = async (api, prNumber) => Result.map(await readCheckContexts(api, prNumber), (contexts) => reportedChecksOf(contexts, 'all')
+    .filter((check) => check.bucket === 'pending')
+    .map(({ name, startedAt, workflow, link }) => ({
+    name,
+    startedAt,
+    workflow,
+    link,
+})));
+
+
+
+
+
+
+
+
+
+
+
+export const reportedChecksOf = (contexts, which) => {
+    const mut_latest = new Map();
+    for (const context of contexts) {
+        const key = keyOf(context);
+        const kept = mut_latest.get(key);
+        if (kept === undefined || startedAtOf(context) > startedAtOf(kept)) {
+            mut_latest.set(key, context);
+        }
+    }
+    const survivors = new Set(mut_latest.values());
+    return contexts
+        .filter((context) => survivors.has(context) && (which === 'all' || context.isRequired))
+        .map(reportedCheckOf);
+};
+
+
+
+
+const readCheckContexts = async (api, prNumber) => {
+    const mut_contexts = [];
+    let mut_after = undefined;
+    for (const _page of Arr.seq(MAX_PAGES)) {
+        const rollup = await readRollupPage(api, prNumber, mut_after);
+        if (Result.isErr(rollup)) {
+            return rollup;
+        }
+        if (rollup.value === null) {
+            return Result.ok(mut_contexts);
+        }
+        mut_contexts.push(...rollup.value.nodes);
+        const { hasNextPage, endCursor } = rollup.value.pageInfo;
+        if (!hasNextPage || endCursor === null) {
+            return Result.ok(mut_contexts);
+        }
+        mut_after = endCursor;
+    }
+    return Result.err(`#${prNumber} has more than ${MAX_PAGES * PAGE_SIZE} checks on its head`);
+};
+
+
+
+
+const readRollupPage = async (api, prNumber, after) => Result.map(await graphqlQuery(api, CHECKS_QUERY, {
+    owner: api.repo.owner,
+    name: api.repo.name,
+    number: prNumber,
+    ...(after === undefined ? {} : { after }),
+}, ChecksAnswerSchema), (answer) => answer.repository.pullRequest.commits.nodes[0]?.commit.statusCheckRollup
+    ?.contexts ?? null);
+const PAGE_SIZE = 100;
+const MAX_PAGES = 10;
+const CHECKS_QUERY = [
+    'query($owner: String!, $name: String!, $number: Int!, $after: String) {',
+    '  repository(owner: $owner, name: $name) {',
+    '    pullRequest(number: $number) {',
+    '      commits(last: 1) { nodes { commit { statusCheckRollup {',
+    `        contexts(first: ${PAGE_SIZE}, after: $after) {`,
+    '          pageInfo { hasNextPage endCursor }',
+    '          nodes {',
+    '            __typename',
+    '            ... on CheckRun {',
+    '              name status conclusion startedAt completedAt detailsUrl',
+    '              isRequired(pullRequestNumber: $number)',
+    '              checkSuite { workflowRun { event workflow { name } } }',
+    '            }',
+    '            ... on StatusContext {',
+    '              context state targetUrl createdAt',
+    '              isRequired(pullRequestNumber: $number)',
+    '            }',
+    '          }',
+    '        }',
+    '      } } }',
+    '    }',
+    '  }',
+    '}',
+].join('\n');
+const CheckContextNodeSchema = t.union([
+    t.record({
+        __typename: t.literal('CheckRun'),
+        name: t.string(),
+        status: t.string(),
+        conclusion: t.union([t.string(), t.nullType]),
+        startedAt: t.union([t.string(), t.nullType]),
+        completedAt: t.union([t.string(), t.nullType]),
+        detailsUrl: t.union([t.string(), t.nullType]),
+        isRequired: t.boolean(),
+        checkSuite: t.union([
+            t.record({
+                workflowRun: t.union([
+                    t.record({
+                        event: t.string(),
+                        workflow: t.record({ name: t.string() }),
+                    }),
+                    t.nullType,
+                ]),
+            }),
+            t.nullType,
+        ]),
+    }),
+    t.record({
+        __typename: t.literal('StatusContext'),
+        context: t.string(),
+        state: t.string(),
+        targetUrl: t.union([t.string(), t.nullType]),
+        createdAt: t.string(),
+        isRequired: t.boolean(),
+    }),
+]);
+const ChecksAnswerSchema = t.record({
+    repository: t.record({
+        pullRequest: t.record({
+            commits: t.record({
+                nodes: t.array(t.record({
+                    commit: t.record({
+                        statusCheckRollup: t.union([
+                            t.record({
+                                contexts: t.record({
+                                    pageInfo: t.record({
+                                        hasNextPage: t.boolean(),
+                                        endCursor: t.union([t.string(), t.nullType]),
+                                    }),
+                                    nodes: t.array(CheckContextNodeSchema),
+                                }),
+                            }),
+                            t.nullType,
+                        ]),
+                    }),
+                })),
+            }),
+        }),
+    }),
+});
+
+const ZERO_TIME = '0001-01-01T00:00:00Z';
+
+
+
+
+const keyOf = (context) => context.__typename === 'StatusContext'
+    ? `status:${context.context}`
+    : [
+        'run',
+        context.name,
+        context.checkSuite?.workflowRun?.workflow.name ?? '',
+        context.checkSuite?.workflowRun?.event ?? '',
+    ].join(':');
+const startedAtOf = (context) => (context.__typename === 'StatusContext'
+    ? context.createdAt
+    : context.startedAt) ?? ZERO_TIME;
+const reportedCheckOf = (context) => context.__typename === 'StatusContext'
+    ? {
+        name: context.context,
+        bucket: bucketOf(context.state),
+        link: context.targetUrl ?? '',
+        startedAt: context.createdAt,
+        completedAt: context.createdAt,
+        workflow: '',
+    }
+    : {
+        name: context.name,
+        bucket: bucketOf(context.status === 'COMPLETED'
+            ? (context.conclusion ?? '')
+            : context.status),
+        link: context.detailsUrl ?? '',
+        startedAt: context.startedAt ?? ZERO_TIME,
+        completedAt: context.completedAt ?? ZERO_TIME,
+        workflow: context.checkSuite?.workflowRun?.workflow.name ?? '',
+    };
+
+
+
+
+
+const bucketOf = (state) => {
+    switch (state) {
+        case 'SUCCESS':
+            return 'pass';
+        case 'SKIPPED':
+        case 'NEUTRAL':
+            return 'skipping';
+        case 'ERROR':
+        case 'FAILURE':
+        case 'TIMED_OUT':
+        case 'ACTION_REQUIRED':
+        case 'STARTUP_FAILURE':
+            return 'fail';
+        case 'CANCELLED':
+            return 'cancel';
+        default:
+            return 'pending';
+    }
+};
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export const summarizeChecks = (checks, requiredContexts, running) => {
+    const roundStartedMs = earliestStart(running);
+    const isOfRoundBefore = (check) => {
+        const completedMs = epochMsOf(check.completedAt);
+        return ((roundStartedMs !== undefined &&
+            completedMs !== undefined &&
+            completedMs < roundStartedMs) ||
+            isSuperseded(check, running));
+    };
+    const isFailureOfThisRound = (check) => isFailure(check) && !isOfRoundBefore(check);
+    const mut_reported = new Map();
+    for (const check of checks) {
+        const state = stateOf(check, isOfRoundBefore(check));
+        const previous = mut_reported.get(check.name);
+        mut_reported.set(check.name, previous === undefined ? state : combineContextStates(previous, state));
+    }
+    const pendingNames = new Set(checks
+        .filter((check) => mut_reported.get(check.name) === 'pending')
+        .map((check) => check.name));
+    const stillRunning = running
+        .map(({ name }) => name)
+        .filter((name) => !pendingNames.has(name));
+    const summary = summarizeContexts({
+
+
+        required: Arr.uniq([
+            ...requiredContexts,
+            ...checks.map((check) => check.name),
+        ]),
+        reported: mut_reported,
+
+        paused: false,
+
+
+        running: Arr.isNonEmpty(stillRunning) || !Arr.isNonEmpty(checks),
+
+
+
+
+        baseCovered: true,
+    });
+    return {
+        ...summary,
+        failedRuns: checks
+            .filter(isFailureOfThisRound)
+            .map(({ name, link }) => ({ name, link })),
+        running: stillRunning,
+    };
+};
+
+export const describeWaitingOn = (summary) => {
+    const waiting = [
+        ...summary.pending,
+        ...summary.missing.map((context) => `${context} (not reported yet)`),
+        ...summary.running.map((name) => `${name} (running)`),
+    ];
+    return Arr.isNonEmpty(waiting) ? waiting.join(', ') : 'checks to be reported';
+};
+const isFailure = (check) => check.bucket === 'fail' || check.bucket === 'cancel';
+
+
+
+
+const stateOf = (check, ofRoundBefore) => isFailure(check)
+    ? ofRoundBefore
+        ? 'pending'
+        : 'failed'
+    : check.bucket === 'pending'
+        ? 'pending'
+        : check.bucket === 'skipping'
+            ? 'skipped'
+            : 'passed';
+
+
+
+
+
+const isSuperseded = (check, running) => {
+    const runId = workflowRunId(check.link);
+    return (check.workflow !== '' &&
+        runId !== undefined &&
+        running.some((other) => {
+            const otherRunId = workflowRunId(other.link);
+            return (other.workflow === check.workflow &&
+                otherRunId !== undefined &&
+                otherRunId > runId);
+        }));
+};
+
+const workflowRunId = (link) => {
+    const id = /\/actions\/runs\/(\d+)\//u.exec(link)?.[1];
+    return id === undefined
+        ? undefined
+        : Result.unwrapOkOr(Num.safeParseInt(id), undefined);
+};
+
+
+
+
+const earliestStart = (running) => {
+    const starts = Arr.generate(function* () {
+        for (const { startedAt } of running) {
+            const ms = epochMsOf(startedAt);
+            if (ms !== undefined) {
+                yield ms;
+            }
+        }
+    });
+    return Arr.isNonEmpty(starts) ? Math.min(...starts) : undefined;
+};
+//# sourceMappingURL=checks.mjs.map