src/github/releases.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/github/contents.ts. Imported by src/maintenance-releases.ts, src/tools/repo.ts.

Source

1import type { Env } from "../env";
2import { assertRepoArg, getDefaultBranch, getRefSha, ghFetch, resolveRepo } from "./client";
3import { readRepoFile } from "./contents";
4
5// Tag a commit, and publish its release with the notes from the repo's CHANGELOG.
6// Served as capsid_close_pr actions tag and release, which need can_merge
7// (src/scope.ts repoWriteFlags): a tag or a release can start a deploy as a merge can.
8//
9// A release is refused before anything is written when its CHANGELOG has no section for
10// the tag, so a release never goes out with empty or guessed notes.
11
12// A tag name as GitHub and semver tooling read it: a v, then a version, optionally a
13// pre-release or build suffix. Narrower than git allows, on purpose.
14const TAG = /^v?[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]{1,40})?$/;
15const SHA = /^[0-9a-f]{40}$/;
16const NOTES_MAX = 50_000;
17
18/** Why a tag name is refused, or null. */
19export function tagRefusal(tag: string): string | null {
20  return TAG.test(tag) ? null : `'${tag}' is not a release tag: use a version such as v1.4.0 or 1.4.0-rc.1.`;
21}
22
23/**
24 * The CHANGELOG section for a version: the lines under the first heading that names it
25 * (with or without a leading v, bare or in brackets, as "## [1.4.0] - 2026-10-10" or
26 * "## v1.4.0"), up to the next heading of the same or a higher level. Null when no
27 * heading names it, or the section is empty.
28 */
29export function changelogSection(markdown: string, tag: string): string | null {
30  const version = tag.replace(/^v/, "");
31  const escaped = version.replace(/[.+]/g, (c) => `\\${c}`);
32  const names = new RegExp(`^(#{1,6})\\s+\\[?v?${escaped}\\]?(?:\\s|$|\\]|\\))`);
33  const lines = markdown.split(/\r?\n/);
34  let level = 0;
35  const out: string[] = [];
36  for (const line of lines) {
37    const heading = /^(#{1,6})\s/.exec(line);
38    if (level === 0) {
39      const found = names.exec(line);
40      if (found) level = found[1].length;
41      continue;
42    }
43    if (heading && heading[1].length <= level) break;
44    out.push(line);
45  }
46  const body = out.join("\n").trim();
47  return level > 0 && body.length > 0 ? body : null;
48}
49
50export interface TagReleaseArgs {
51  tag: string;
52  // The commit: a full sha, or a ref (a branch) resolved to its head now. Default: the
53  // default branch.
54  sha?: string;
55  ref?: string;
56  publishRelease: boolean;
57  changelogPath: string;
58}
59
60export async function tagRelease(env: Env, namespace: string, args: TagReleaseArgs, repoSelector?: string) {
61  const badTag = tagRefusal(args.tag);
62  if (badTag) throw new Error(badTag);
63  assertRepoArg("changelog", args.changelogPath);
64  if (args.sha !== undefined && !SHA.test(args.sha)) throw new Error("sha must be a full 40-character commit sha.");
65  if (args.sha !== undefined && args.ref !== undefined) throw new Error("pass sha or ref, not both.");
66  if (args.ref !== undefined) assertRepoArg("ref", args.ref);
67  const { owner, repo, full } = await resolveRepo(env, namespace, repoSelector);
68  const sha = args.sha ?? (await getRefSha(env, owner, repo, args.ref ?? (await getDefaultBranch(env, owner, repo))));
69
70  // The notes first, at the tagged commit, so a release with no section writes nothing.
71  let notes: string | null = null;
72  if (args.publishRelease) {
73    const file = await readRepoFile(env, namespace, args.changelogPath, sha, repoSelector);
74    notes = releaseNotes(file.content, args.tag);
75    if (!notes) {
76      throw new Error(`${args.changelogPath} at ${sha.slice(0, 7)} has no section for ${args.tag}. Add one (a heading naming the version), merge it, and release that commit. Nothing was tagged.`);
77    }
78  }
79
80  await createTag(env, owner, repo, args.tag, sha);
81  if (!notes) return { repo: full, tag: args.tag, sha, release: null };
82
83  let release: { id: number; url: string };
84  try {
85    release = await publishRelease(env, owner, repo, args.tag, notes);
86  } catch (err) {
87    throw new Error(
88      `the tag ${args.tag} was created at ${sha.slice(0, 7)} but the release was not (${err instanceof Error ? err.message : String(err)}). ` +
89        `Publish it from the tag on GitHub, or delete the tag and release again.`
90    );
91  }
92  return { repo: full, tag: args.tag, sha, release: { id: release.id, url: release.url, notes_chars: notes.length } };
93}
94
95// The two writes, shared with the maintenance pass's release-tag rule
96// (src/maintenance-releases.ts). That rule tags a shared package's own repo, which need
97// not be any namespace's, so it cannot go through tagRelease's namespace lookup; it
98// calls these with the repo it read, and writes its own audit row for each tag.
99
100/** The CHANGELOG section for a tag as release notes, capped at NOTES_MAX; null when there is none. */
101export function releaseNotes(markdown: string, tag: string): string | null {
102  const notes = changelogSection(markdown, tag);
103  if (!notes) return null;
104  return notes.length > NOTES_MAX ? `${notes.slice(0, NOTES_MAX)}\n\n(The CHANGELOG section continues past ${NOTES_MAX} characters.)` : notes;
105}
106
107/** Create the tag's ref at `sha`. Never moves a tag: GitHub refuses a ref that already
108 *  exists (422), and that refusal is thrown saying nothing was changed. */
109export async function createTag(env: Env, owner: string, repo: string, tag: string, sha: string): Promise<void> {
110  const badTag = tagRefusal(tag);
111  if (badTag) throw new Error(badTag);
112  if (!SHA.test(sha)) throw new Error("sha must be a full 40-character commit sha.");
113  const tagged = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/git/refs`, {
114    method: "POST",
115    headers: { "Content-Type": "application/json" },
116    body: JSON.stringify({ ref: `refs/tags/${tag}`, sha }),
117  });
118  if (!tagged.ok) {
119    const detail = await tagged.text();
120    if (tagged.status === 422) throw new Error(`tag ${tag} already exists in ${owner}/${repo}, or the commit is unknown. Nothing was changed. Detail: ${detail.slice(0, 300)}`);
121    throw new Error(`tag failed (${tagged.status}): ${detail.slice(0, 300)}`);
122  }
123}
124
125/** Publish the release of an existing tag with these notes. Throws with GitHub's answer. */
126export async function publishRelease(env: Env, owner: string, repo: string, tag: string, notes: string): Promise<{ id: number; url: string }> {
127  const released = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/releases`, {
128    method: "POST",
129    headers: { "Content-Type": "application/json" },
130    body: JSON.stringify({ tag_name: tag, name: tag, body: notes, draft: false, prerelease: /-/.test(tag) }),
131  });
132  if (!released.ok) throw new Error(`${released.status}: ${(await released.text()).slice(0, 300)}`);
133  const release = (await released.json()) as { id: number; html_url: string };
134  return { id: release.id, url: release.html_url };
135}