src/maintenance-releases.ts

Functions

Imports

It imports src/encoding.ts, src/env.ts, src/github/client.ts, src/github/releases.ts, src/maintenance.ts, src/shared-code.ts, src/store-guards.ts. Imported by src/maintenance.ts.

Source

1import type { Env } from "./env";
2import { base64Decode } from "./encoding";
3import { ghFetch, getDefaultBranch } from "./github/client";
4import { createTag, publishRelease, releaseNotes } from "./github/releases";
5import type { MaintenanceItem } from "./maintenance";
6import { readRootManifest, readSharedConfig, releaseDecision } from "./shared-code";
7import { auditStatement } from "./store-guards";
8
9// The daily maintenance pass's release-tag rule (Capsid improvement list, item 13:
10// releases without Dustin's PC). A cloud session cannot push a tag, so a shared package's
11// version bump merged from one sat untagged until he tagged it at his desk, and every
12// package repo's bump-consumers workflow (on push: tags: v*) waited with it. Merging the
13// bump is the release decision; this rule makes the tag that follows from it.
14//
15// For each shared package (shared_packages, migrations/0036; the Shared code view's
16// configuration, src/shared-code.ts) the version in the repo's root package.json on its
17// default branch is compared with the repo's tags by releaseDecision, the rule the view
18// uses for "untagged":
19// - a version a tag already names is left alone;
20// - a version newer than every release tag is tagged v<version> at the commit that set
21//   it: walking the commits that touched package.json, newest first, the oldest of the
22//   run that carries this version. Not the newest such commit: a later dependency change
23//   that kept the version is not the release. When the run reaches the end of what was
24//   read (COMMITS_READ) and the file's history is longer, the commit is not known, and
25//   the version is listed rather than tagged at a guess;
26// - a version below the newest release tag is never tagged (it would start
27//   bump-consumers on an older version) and is listed;
28// - a pre-release or missing version is left for a person.
29// A tag made through the App's installation token fires push workflows (only events
30// made with a workflow's own GITHUB_TOKEN are suppressed), so the tag starts
31// bump-consumers in the package repo, which opens the apps' bump pull requests.
32//
33// Tag, and a release only when the CHANGELOG has a section for the version: the notes
34// are then the package's own words (src/github/releases.ts, releaseNotes, the rule
35// capsid_close_pr action release applies). With no section the tag alone is made, since
36// a release with empty or guessed notes is what that action refuses. A failed release
37// after a made tag is listed, never retried by retagging.
38//
39// On by default, unlike the branch prune: a tag adds and never removes, GitHub refuses a
40// tag that exists (so nothing is retagged or moved), and the decision was the merge. The
41// seat turns it off by setting RELEASE_TAGS_SWITCH_KEY to "off"; off, what would be
42// tagged is listed. At most RELEASE_TAG_CAP tags per run; the rest wait for the next.
43// Each tag is audit-logged, before the next, with the repo, tag and sha
44// (snapshot invariant, test/write-invariants.test.ts: a write leaves its record). A system action of the pass, like the
45// branch prune, so it takes no caller's grant; the writes are the ones guardedWrite
46// files for capsid_close_pr action tag and release, through the same helpers.
47
48/** The switch the seat sets to "off" to stop the pass tagging. Anything else, or no key,
49 *  is on. A KV key rather than a control, as the prune switch is
50 *  (src/maintenance-branches.ts): a control would add to a served tool's surface. */
51export const RELEASE_TAGS_SWITCH_KEY = "maintenance:release-tags";
52export const RELEASE_TAG_CAP = 3;
53export const RELEASE_TAG_AUDIT_ACTION = "maintenance-release-tag";
54// Commits that touched package.json read per package, newest first.
55export const COMMITS_READ = 20;
56const CHANGELOG_PATH = "CHANGELOG.md";
57const TAGS_PER_PAGE = 100;
58const SYSTEM_ACTOR = "system:maintenance";
59
60export interface ReleasePackage {
61  name: string;
62  repo: string;
63  /** The namespace whose repos include the package's repo, for the item and the audit
64   *  row; "capsid", which keeps the configuration, when none does. */
65  namespace: string;
66}
67
68export interface ReleaseReaders {
69  /** The configured shared packages. Throws when the table could not be read. */
70  packages(): Promise<ReleasePackage[]>;
71  /** The root package.json's version on the default branch, and that branch. */
72  head(repo: string): Promise<{ version: string | null; branch: string }>;
73  /** The repo's tag names (one page). */
74  tags(repo: string): Promise<string[]>;
75  /** The commits on `branch` that touched package.json, newest first, at most `limit`;
76   *  complete when fewer came back, so the file's whole history was read. */
77  manifestCommits(repo: string, branch: string, limit: number): Promise<{ shas: string[]; complete: boolean }>;
78  /** The root package.json's version at a commit. */
79  versionAt(repo: string, sha: string): Promise<string | null>;
80  /** CHANGELOG.md at a commit, or null when there is none. */
81  changelog(repo: string, sha: string): Promise<string | null>;
82  tag(repo: string, tag: string, sha: string): Promise<void>;
83  /** Publish the tag's release; its URL. */
84  release(repo: string, tag: string, notes: string): Promise<string>;
85}
86
87/**
88 * The commit that set `version`, from the commits that touched package.json, newest first,
89 * each with the version it carries: the oldest of the leading run that carries it. Null
90 * when the newest does not carry it, or the run reaches the end of an incomplete read.
91 */
92export function versionCommit(history: ReadonlyArray<{ sha: string; version: string | null }>, version: string, complete: boolean): string | null {
93  if (history.length === 0 || history[0].version !== version) return null;
94  let i = 0;
95  while (i + 1 < history.length && history[i + 1].version === version) i++;
96  if (i + 1 < history.length) return history[i].sha;
97  return complete ? history[i].sha : null;
98}
99
100/** The release-tag rule over every shared package, how many were read, and how many tagged. */
101export async function gatherReleaseItems(env: Env, readers: ReleaseReaders): Promise<{ items: MaintenanceItem[]; read: number; tagged: number }> {
102  const items: MaintenanceItem[] = [];
103  let read = 0;
104  let tagged = 0;
105
106  let on: boolean;
107  let packages: ReleasePackage[];
108  try {
109    on = (await env.APP_KV.get(RELEASE_TAGS_SWITCH_KEY)) !== "off";
110    packages = await readers.packages();
111  } catch (err) {
112    return { items: [notChecked("capsid", `the switch or the shared packages could not be read: ${err instanceof Error ? err.message : String(err)}`)], read, tagged };
113  }
114
115  for (const pkg of packages) {
116    const { namespace, repo } = pkg;
117    let tag: string;
118    let sha: string;
119    let changelog: string | null;
120    try {
121      const head = await readers.head(repo);
122      const decision = releaseDecision(head.version, await readers.tags(repo));
123      read++;
124      if (decision.kind === "tagged") continue;
125      if (decision.kind === "not-a-release") {
126        if (decision.version !== null) items.push({ rule: "release-untagged", namespace, job: null, line: `${repo} is at version ${decision.version}, which is not a plain x.y.z release, so the pass does not tag it: tag it by hand if it is one.` });
127        continue;
128      }
129      if (decision.kind === "backwards") {
130        items.push({ rule: "release-backwards", namespace, job: null, line: `${repo} is at version ${head.version} on ${head.branch}, below its newest tag ${decision.newest}, so ${decision.tag} was not made: raise the version past ${decision.newest}.` });
131        continue;
132      }
133      tag = decision.tag;
134      if (!on) {
135        items.push({ rule: "release-untagged", namespace, job: null, line: `${repo} is at version ${head.version} with no tag; the auto-tag is off (${RELEASE_TAGS_SWITCH_KEY}), so ${tag} was not made.` });
136        continue;
137      }
138      if (tagged >= RELEASE_TAG_CAP) {
139        items.push({ rule: "release-untagged", namespace, job: null, line: `${repo} is at version ${head.version} with no tag: it waits for the next run (${RELEASE_TAG_CAP} tags are made per run).` });
140        continue;
141      }
142      const listed = await readers.manifestCommits(repo, head.branch, COMMITS_READ);
143      const history: Array<{ sha: string; version: string | null }> = [];
144      for (const s of listed.shas) {
145        const v = await readers.versionAt(repo, s);
146        history.push({ sha: s, version: v });
147        if (v !== head.version) break;
148      }
149      const found = versionCommit(history, decision.tag.slice(1), listed.complete);
150      if (!found) {
151        items.push({ rule: "release-untagged", namespace, job: null, line: `${repo} is at version ${head.version} with no tag, and the commit that set it was not found in the last ${COMMITS_READ} commits to package.json: tag it by hand.` });
152        continue;
153      }
154      sha = found;
155      changelog = await readers.changelog(repo, sha);
156    } catch (err) {
157      items.push(notChecked(namespace, `${repo}: ${err instanceof Error ? err.message : String(err)}`));
158      continue;
159    }
160
161    try {
162      await readers.tag(repo, tag, sha);
163    } catch (err) {
164      items.push(notChecked(namespace, `${repo} ${tag} was not made: ${err instanceof Error ? err.message : String(err)}`));
165      continue;
166    }
167    tagged++;
168    // The release, when the CHANGELOG has a section. Its failure is listed: the tag stands.
169    const notes = changelog === null ? null : releaseNotes(changelog, tag);
170    let release: string | null = null;
171    let releaseError: string | null = null;
172    if (notes) {
173      try {
174        release = await readers.release(repo, tag, notes);
175      } catch (err) {
176        releaseError = err instanceof Error ? err.message : String(err);
177      }
178    }
179    // One audit row per tag, written before the next tag. A failed write stops the rule
180    // and the pass, as the branch prune's does: the next run finds the tag made and
181    // makes no other.
182    await auditStatement(env.DB, SYSTEM_ACTOR, RELEASE_TAG_AUDIT_ACTION, namespace, null, { repo, package: pkg.name, tag, sha, release, release_error: releaseError }).run();
183    const after = release ? ` and its release was published (${release})` : releaseError ? `; its release was not published (${releaseError}): publish it from the tag on GitHub` : ` (no ${CHANGELOG_PATH} section, so no release)`;
184    items.push({ rule: "release-tagged", namespace, job: null, line: `${repo} was tagged ${tag} at ${sha}${after}. Its bump-consumers workflow runs on the tag.` });
185  }
186  return { items, read, tagged };
187}
188
189function notChecked(namespace: string, problem: string): MaintenanceItem {
190  return { rule: "releases-not-checked", namespace, job: null, line: `Releases were not fully checked (${problem}): what is missing is not a clean result.` };
191}
192
193/** The readers on GitHub, through the App: the package's repo by its own name, since a
194 *  shared package's repo need not be any namespace's. */
195export function githubReleaseReaders(env: Env): ReleaseReaders {
196  const split = (full: string) => {
197    const [owner, name] = full.split("/");
198    return { owner, name };
199  };
200  const getJson = async (full: string, path: string): Promise<unknown> => {
201    const { owner, name } = split(full);
202    const resp = await ghFetch(env, owner, name, `/repos/${owner}/${name}${path}`);
203    if (!resp.ok) {
204      await resp.body?.cancel();
205      throw new Error(`GitHub answered ${resp.status} for ${full}${path.split("?")[0]}`);
206    }
207    return resp.json();
208  };
209  return {
210    async packages() {
211      const config = await readSharedConfig(env.DB);
212      const { results } = await env.DB.prepare("SELECT namespace, repos FROM namespaces LIMIT 200").all<{ namespace: string; repos: string | null }>();
213      const owner = new Map<string, string>();
214      for (const row of results ?? []) {
215        let list: unknown;
216        try {
217          list = JSON.parse(row.repos ?? "[]");
218        } catch {
219          continue;
220        }
221        if (!Array.isArray(list)) continue;
222        for (const entry of list) {
223          const r = (entry as { repo?: unknown })?.repo;
224          if (typeof r === "string" && !owner.has(r.toLowerCase())) owner.set(r.toLowerCase(), row.namespace);
225        }
226      }
227      return config.map((c) => ({ name: c.name, repo: c.repo, namespace: owner.get(c.repo.toLowerCase()) ?? "capsid" }));
228    },
229    async head(repo) {
230      const { owner, name } = split(repo);
231      const branch = await getDefaultBranch(env, owner, name);
232      return { version: (await readRootManifest(env, repo, branch)).version, branch };
233    },
234    async tags(repo) {
235      return ((await getJson(repo, `/tags?per_page=${TAGS_PER_PAGE}`)) as Array<{ name: string }>).map((t) => t.name);
236    },
237    async manifestCommits(repo, branch, limit) {
238      const list = (await getJson(repo, `/commits?sha=${encodeURIComponent(branch)}&path=package.json&per_page=${limit}`)) as Array<{ sha: string }>;
239      return { shas: list.map((c) => c.sha), complete: list.length < limit };
240    },
241    async versionAt(repo, sha) {
242      return (await readRootManifest(env, repo, sha)).version;
243    },
244    async changelog(repo, sha) {
245      const { owner, name } = split(repo);
246      const resp = await ghFetch(env, owner, name, `/repos/${owner}/${name}/contents/${CHANGELOG_PATH}?ref=${encodeURIComponent(sha)}`);
247      if (resp.status === 404) {
248        await resp.body?.cancel();
249        return null;
250      }
251      if (!resp.ok) {
252        await resp.body?.cancel();
253        throw new Error(`GitHub answered ${resp.status} for ${repo}'s ${CHANGELOG_PATH}`);
254      }
255      const data = (await resp.json()) as { content?: unknown; encoding?: unknown };
256      return data.encoding === "base64" && typeof data.content === "string" ? base64Decode(data.content) : null;
257    },
258    async tag(repo, tag, sha) {
259      const { owner, name } = split(repo);
260      await createTag(env, owner, name, tag, sha);
261    },
262    async release(repo, tag, notes) {
263      const { owner, name } = split(repo);
264      return (await publishRelease(env, owner, name, tag, notes)).url;
265    },
266  };
267}