src/complete-ci.ts

Functions

Imports

It imports src/auto-merge-policy.ts, src/env.ts, src/github/client.ts, src/github/pr-files.ts, src/job-body-check.ts, src/job-checklist.ts, src/job-outcomes.ts, src/merge-class.ts, src/test-protection.ts. Imported by src/fail-exemption.ts, src/jobs-holder.ts.

Source

1import type { Env } from "./env";
2import { ciVerdict } from "./auto-merge-policy";
3import { parsePrUrl, resolveRepo } from "./github/client";
4import { readCheckRuns, readPrFiles } from "./github/pr-files";
5import { prFacts } from "./job-outcomes";
6import { pathClassOf } from "./merge-class";
7import { weakenedTests } from "./test-protection";
8import { checklistItems, unchangedItems } from "./job-checklist";
9import { proseOnly } from "./job-body-check";
10
11// The CI gate on complete (docs/work-queue.md, "CI on complete"). A job handed on as done
12// names its pull requests, and each must show CI that ran and passed on its head. Green
13// is the only pass. Still running is a wait, failed is red, and no check run that passed
14// on a change to code is not green either: a change nothing ran on is not shown to work.
15// GitHub unreadable is a wait as well, since not answered is not green. A pull request
16// that takes a test away is refused too (src/test-protection.ts).
17//
18// A pull request Capsid has no way to read is not gated: with no GitHub App, or in a repo
19// the job's namespace does not map, its outcome stays unverified as before.
20
21const CHECKS_MAX_PAGES = 10;
22// A job opts into the test on the base with this line in its body.
23const TEST_ON_BASE = /^[ \t]*TEST ON BASE\b/m;
24const AGAIN = "Nothing was written; call complete again once it has.";
25const OR_FAIL = `Fix it and push, then complete again, or call fail with the reason; "not done, here's why" is a good outcome.`;
26
27/** What the gate reads of the named pull requests: the first refusal, or the paths they
28 *  change, with unread set when one of them could not be read. Null with no GitHub App. */
29export async function readNamedPrs(
30  env: Env,
31  namespace: string,
32  urls: readonly string[],
33  jobBody: string
34): Promise<{ refusal: { pr: string; why: string } } | { changed: string[]; unread: boolean } | null> {
35  if (!env.GITHUB_APP_CLIENT_ID || !env.GITHUB_APP_PRIVATE_KEY) return null;
36  const changed: string[] = [];
37  let unread = false;
38  for (const url of urls) {
39    const read = await notGreen(env, namespace, url, jobBody);
40    if (read === null) unread = true;
41    else if (typeof read === "string") return { refusal: { pr: url, why: read } };
42    else changed.push(...read);
43  }
44  return { changed, unread };
45}
46
47/** Why complete is refused on CI, on a test taken away, or on a DONE WHEN item no pull
48 *  request changed, with the pull request to bind the job to (null when none is named), or null. */
49export async function ciRefusal(env: Env, namespace: string, urls: readonly string[], jobBody: string): Promise<{ pr: string | null; why: string } | null> {
50  const read = await readNamedPrs(env, namespace, urls, jobBody);
51  if (read === null) return null;
52  if ("refusal" in read) return read.refusal;
53  // A pull request Capsid could not read may change the path, so the checklist is not judged.
54  if (read.unread) return null;
55  const missing = unchangedItems(checklistItems(jobBody), read.changed);
56  if (missing.length === 0) return null;
57  return {
58    pr: urls[0] ?? null,
59    why:
60      `${missing.slice(0, 3).join("; ")}${missing.length > 3 ? `; and ${missing.length - 3} more` : ""}, and ${urls.length > 0 ? "no pull request this complete names changes it" : "this complete names no pull request"}. ` +
61      `Name the pull request that changes it, or call fail with the reason.`,
62  };
63}
64
65// A refusal, the paths the pull request changes when it passes, or null when it could not be read.
66async function notGreen(env: Env, namespace: string, url: string, jobBody: string): Promise<string | string[] | null> {
67  const parsed = parsePrUrl(url);
68  if (!parsed) return [];
69  try {
70    await resolveRepo(env, namespace, `${parsed.owner}/${parsed.repo}`);
71  } catch {
72    return null;
73  }
74  const facts = await prFacts(env, namespace, url);
75  if (typeof facts === "string") return `${facts}, so its CI is not shown green. ${AGAIN}`;
76  const sha = facts.head_sha.slice(0, 7);
77  const [owner, repo] = facts.repo.split("/");
78  const checks = await readCheckRuns(env, owner, repo, facts.head_sha, CHECKS_MAX_PAGES);
79  if (checks.problem) return `${url}: the check runs on ${sha} could not be read whole (${checks.problem}), so its CI is not shown green. ${AGAIN}`;
80  // The shadow test records and never judges (src/shadow.ts), so complete does not wait on it.
81  const judged = checks.items.filter((c) => c.name !== "shadow-test");
82  if (judged.length > 0) {
83    const verdict = ciVerdict(judged);
84    if (verdict.conclusion === "pending") return `${url}: CI on ${sha} has not finished (${verdict.note}). The job stays claimed. ${AGAIN}`;
85    if (verdict.conclusion === "failure") return `${url}: CI on ${sha} failed (${verdict.note}). ${OR_FAIL}`;
86  }
87  // A job that opts into the test on the base (scripts/test-on-base.mjs) needs its run to
88  // have passed; running or failed, the verdict above already answered.
89  if (TEST_ON_BASE.test(proseOnly(jobBody)) && !checks.items.some((c) => c.name === "test-on-base" && c.conclusion === "success")) {
90    return (
91      `${url}: the job asks for its tests to be run on the base, and no test-on-base check passed on ${sha}. ` +
92      `Label the pull request test-on-base (the workflow runs in this repository only), then complete again; or call fail with the reason.`
93    );
94  }
95  const files = await readPrFiles(env, owner, repo, parsed.number);
96  if (files.problem) return `${url}: its file list could not be read whole (${files.problem}), so its tests are not shown kept. ${AGAIN}`;
97  const weakened = weakenedTests(files.rows, jobBody);
98  if (weakened.length > 0) {
99    return (
100      `${url} ${weakened.slice(0, 3).join("; ")}${weakened.length > 3 ? `; and ${weakened.length - 3} more` : ""}. ` +
101      `Green CI shows nothing once the test that would fail is gone, so this is not done unless the job names it. Put the test back, or call fail with the reason.`
102    );
103  }
104  // Skipped and neutral fail nothing, and pass nothing: a run a paths filter excluded
105  // did not judge the change.
106  if (judged.some((c) => c.conclusion === "success")) return files.paths;
107  const code = files.paths.filter((p) => pathClassOf(p) !== "docs");
108  if (code.length === 0) return files.paths;
109  return (
110    `${url}: no CI check passed on ${sha}, and it changes code (${code.slice(0, 3).join(", ")}${code.length > 3 ? `, and ${code.length - 3} more` : ""}). ` +
111    `A change no check ran on is not shown to work. Get CI to run on it, or call fail with the reason.`
112  );
113}