@catladder/cli 0.0.0-next-883523ef → 0.0.0-next-5b3ef3ac

package/package.json

@@ -53,7 +53,7 @@
     }
   ],
   "license": "MIT",
-  "version": "0.0.0-next-883523ef",
+  "version": "0.0.0-next-5b3ef3ac",
   "scripts": {
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",

package/src/catci.ts

@@ -23,6 +23,7 @@ import {
   changesetsReleaseJob,
   dispatchTaggedReleaseWorkflow,
 } from "./release/changesetsReleaseJob";
+import { changesetCheckJob } from "./release/changesetCheckJob";
 import { npmPublishJob, parseNpmPublishArgs } from "./publish/npmPublishJob";
 
 const GITLAB_HOST = "https://git.panter.ch";
@@ -44,6 +45,12 @@ usage:
       from the last v* tag, writes the changelog, commits, tags and
       pushes (no-op when no changesets are pending)
 
+  catci release changeset-check
+      MR/PR pipelines: reports which changesets the merge request adds,
+      what is pending and what version merging would release (job log,
+      changeset-report.md, sticky MR/PR comment where a token allows);
+      exits 1 when the merge request adds no changeset
+
   catci release dispatch-tagged-workflow <tag>
       github only: dispatches the generated taggedRelease workflow for
       the tag (tags pushed with the job token don't trigger it)
@@ -139,6 +146,13 @@ const main = async () => {
   if (group === "release" && command === "changesets" && args.length === 0) {
     return changesetsReleaseJob();
   }
+  if (
+    group === "release" &&
+    command === "changeset-check" &&
+    args.length === 0
+  ) {
+    return changesetCheckJob();
+  }
   if (
     group === "release" &&
     command === "dispatch-tagged-workflow" &&

package/src/release/__tests__/changesetCheck.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import type { Changeset } from "../changesets";
+import { CHANGESET_CHECK_MARKER, runChangesetCheck } from "../changesetCheck";
+
+const changeset = (bump: Changeset["bump"], summary: string): Changeset => ({
+  fileName: `${summary.toLowerCase().replace(/\s+/g, "-")}.md`,
+  bump,
+  summary,
+});
+
+describe("runChangesetCheck", () => {
+  it("reports an added changeset and the resulting version", () => {
+    const result = runChangesetCheck({
+      addedFiles: ["fancy-dashboard.md"],
+      pending: [changeset("minor", "Add the fancy dashboard")],
+      lastTag: "v4.7.0",
+      requestLabel: "merge request",
+    });
+    expect(result.addsChangeset).toBe(true);
+    expect(result.markdown).toContain(CHANGESET_CHECK_MARKER);
+    expect(result.markdown).toContain("✅ This merge request adds 1 changeset");
+    expect(result.markdown).toContain("`fancy-dashboard.md`");
+    expect(result.markdown).toContain("**v4.8.0**");
+    expect(result.markdown).toContain("(from v4.7.0)");
+    expect(result.markdown).toContain("Add the fancy dashboard");
+  });
+
+  it("warns when the merge request adds no changeset", () => {
+    const result = runChangesetCheck({
+      addedFiles: [],
+      pending: [],
+      lastTag: "v4.7.0",
+      requestLabel: "merge request",
+    });
+    expect(result.addsChangeset).toBe(false);
+    expect(result.markdown).toContain(
+      "**This merge request adds no changeset.**",
+    );
+    expect(result.markdown).toContain("will **not** trigger a release");
+  });
+
+  it("still previews earlier pending changesets when this MR adds none", () => {
+    const result = runChangesetCheck({
+      addedFiles: [],
+      pending: [
+        changeset("major", "Remove the legacy mode"),
+        changeset("patch", "Fix a leak"),
+      ],
+      lastTag: "v4.7.0",
+      requestLabel: "merge request",
+    });
+    expect(result.addsChangeset).toBe(false);
+    expect(result.markdown).toContain("2 changesets are pending");
+    expect(result.markdown).toContain("**v5.0.0**");
+    expect(result.markdown).toContain("Remove the legacy mode");
+  });
+
+  it("handles the first release (no previous tag)", () => {
+    const result = runChangesetCheck({
+      addedFiles: ["init.md"],
+      pending: [changeset("minor", "Initial feature")],
+      lastTag: null,
+      requestLabel: "pull request",
+    });
+    expect(result.markdown).toContain("✅ This pull request adds 1 changeset");
+    expect(result.markdown).toContain("**v1.0.0**");
+    expect(result.markdown).toContain("(first release)");
+  });
+});

package/src/release/changesetCheck.ts

@@ -0,0 +1,82 @@
+/**
+ * pure logic of the changeset check (run in MR/PR pipelines by catci):
+ * given the changesets added by the merge request and everything
+ * pending on the branch, render the markdown report shown as job
+ * output, exposed artifact and sticky MR/PR comment.
+ */
+import type { Changeset } from "./changesets";
+import { getNextVersion, maxBump, renderChangelogEntries } from "./changesets";
+
+/**
+ * identifies the sticky comment across pushes: the check finds the
+ * existing comment carrying this marker and updates it in place
+ * instead of posting a new one
+ */
+export const CHANGESET_CHECK_MARKER = "<!-- catladder-changeset-check -->";
+
+export type ChangesetCheckInput = {
+  /**
+   * file names of changesets ADDED by this merge request (relative to
+   * `.changeset/`)
+   */
+  addedFiles: string[];
+  /**
+   * all changesets pending on this branch (added here or merged
+   * earlier and not yet released)
+   */
+  pending: Changeset[];
+  lastTag: string | null;
+  /** platform wording: "merge request" (gitlab) or "pull request" (github) */
+  requestLabel: string;
+};
+
+export type ChangesetCheckResult = {
+  /** whether this merge request adds at least one changeset */
+  addsChangeset: boolean;
+  /** the full report, marker included (comment + artifact body) */
+  markdown: string;
+};
+
+export const runChangesetCheck = ({
+  addedFiles,
+  pending,
+  lastTag,
+  requestLabel,
+}: ChangesetCheckInput): ChangesetCheckResult => {
+  const addsChangeset = addedFiles.length > 0;
+
+  const lines: string[] = [CHANGESET_CHECK_MARKER, "## 🦋 Changeset check", ""];
+
+  if (addsChangeset) {
+    lines.push(
+      `✅ This ${requestLabel} adds ${addedFiles.length} changeset${addedFiles.length === 1 ? "" : "s"}: ${addedFiles.map((f) => `\`${f}\``).join(", ")}`,
+    );
+  } else {
+    lines.push(
+      `⚠️ **This ${requestLabel} adds no changeset.** If the change is user-facing it will be missing from the next release's changelog — add \`.changeset/<name>.md\` (or run \`yarn changeset\`). For docs/chore changes this warning can be ignored.`,
+    );
+  }
+  lines.push("");
+
+  if (pending.length === 0) {
+    lines.push(
+      "No changesets are pending — merging will **not** trigger a release.",
+    );
+  } else {
+    const version = getNextVersion(
+      lastTag,
+      maxBump(pending.map((c) => c.bump)),
+    );
+    lines.push(
+      `${pending.length} changeset${pending.length === 1 ? " is" : "s are"} pending after merge — the next release will be **v${version}**${lastTag ? ` (from ${lastTag})` : " (first release)"}:`,
+      "",
+      "<details><summary>Changelog preview</summary>",
+      "",
+      renderChangelogEntries(pending),
+      "",
+      "</details>",
+    );
+  }
+
+  return { addsChangeset, markdown: lines.join("\n") };
+};

package/src/release/changesetCheckJob.ts

@@ -0,0 +1,199 @@
+/**
+ * the changeset check CI job (run by catci via the `changesetCheck`
+ * script of the `changesets` job image, in MR/PR pipelines only):
+ * reports which changesets the merge request adds, what is pending and
+ * what version merging would release. The report goes to the job log,
+ * to `changeset-report.md` (exposed as an artifact on gitlab) and to a
+ * sticky MR/PR comment where a token allows it. Exits 1 (the job runs
+ * with allow_failure) when the merge request adds no changeset.
+ */
+import { writeFile } from "fs/promises";
+import { CHANGESET_CHECK_MARKER, runChangesetCheck } from "./changesetCheck";
+import { readPendingChangesets } from "./changesetsReleaseJob";
+import { ensureReleaseHistory, getLastReleaseTag, git } from "./releaseGit";
+
+export const CHANGESET_REPORT_FILE = "changeset-report.md";
+
+const onGithub = () => process.env.GITHUB_ACTIONS === "true";
+
+/**
+ * the changeset files added by this merge request: diffed against the
+ * merge base with the target branch (fetched explicitly — CI checkouts
+ * don't carry the target branch). Returns null when there is no MR/PR
+ * context to diff against.
+ */
+const getAddedChangesetFiles = async (): Promise<string[] | null> => {
+  const targetBranch = onGithub()
+    ? process.env.GITHUB_BASE_REF
+    : process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME;
+  if (!targetBranch) {
+    return null;
+  }
+  await git("fetch", "--quiet", "origin", targetBranch);
+  // FETCH_HEAD instead of origin/<branch>: CI remotes don't always
+  // carry the standard branch refspec
+  const mergeBase = await git("merge-base", "HEAD", "FETCH_HEAD");
+  const diff = await git(
+    "diff",
+    "--name-only",
+    "--diff-filter=A",
+    mergeBase,
+    "HEAD",
+  );
+  return diff
+    .split("\n")
+    .filter(
+      (file) =>
+        file.startsWith(".changeset/") &&
+        file.endsWith(".md") &&
+        !file.toLowerCase().endsWith("readme.md"),
+    )
+    .map((file) => file.slice(".changeset/".length));
+};
+
+type StickyComment = { id: number; body?: string };
+
+const findSticky = (comments: StickyComment[]): StickyComment | undefined =>
+  comments.find((comment) => comment.body?.includes(CHANGESET_CHECK_MARKER));
+
+const request = async (
+  url: string,
+  init: RequestInit,
+): Promise<{ ok: boolean; status: number; json: () => Promise<any> }> => {
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    throw new Error(
+      `${init.method ?? "GET"} ${url} failed: ${response.status} ${await response.text()}`,
+    );
+  }
+  return response;
+};
+
+/**
+ * sticky PR comment via the workflow's own token
+ * (`permissions: pull-requests: write`)
+ */
+const upsertGithubComment = async (markdown: string) => {
+  const token = process.env.GITHUB_TOKEN;
+  const apiUrl = process.env.GITHUB_API_URL ?? "https://api.github.com";
+  const repository = process.env.GITHUB_REPOSITORY;
+  // pull_request workflows check out refs/pull/<number>/merge
+  const prNumber = parseInt(process.env.GITHUB_REF_NAME ?? "");
+  if (!token || !repository || !prNumber) {
+    console.log("no PR context/token — skipping the PR comment");
+    return;
+  }
+  const headers = {
+    authorization: `Bearer ${token}`,
+    accept: "application/vnd.github+json",
+    "content-type": "application/json",
+  };
+  const comments: StickyComment[] = await (
+    await request(
+      `${apiUrl}/repos/${repository}/issues/${prNumber}/comments?per_page=100`,
+      { headers },
+    )
+  ).json();
+  const existing = findSticky(comments);
+  if (existing) {
+    await request(
+      `${apiUrl}/repos/${repository}/issues/comments/${existing.id}`,
+      {
+        method: "PATCH",
+        headers,
+        body: JSON.stringify({ body: markdown }),
+      },
+    );
+  } else {
+    await request(`${apiUrl}/repos/${repository}/issues/${prNumber}/comments`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ body: markdown }),
+    });
+  }
+  console.log("updated the sticky PR comment");
+};
+
+/**
+ * sticky MR note — only when the project makes GL_TOKEN available to
+ * MR pipelines (opt-in: an api-scope token in MR pipelines is a
+ * security trade-off). Without it the report is still in the job log
+ * and the exposed artifact.
+ */
+const upsertGitlabComment = async (markdown: string) => {
+  const token = process.env.GL_TOKEN;
+  if (!token) {
+    console.log(
+      "GL_TOKEN is not available in this pipeline — skipping the MR comment (report available in the job log and the exposed artifact)",
+    );
+    return;
+  }
+  const apiUrl = process.env.CI_API_V4_URL;
+  const projectId = process.env.CI_PROJECT_ID;
+  const mrIid = process.env.CI_MERGE_REQUEST_IID;
+  if (!apiUrl || !projectId || !mrIid) {
+    console.log("no MR context — skipping the MR comment");
+    return;
+  }
+  const headers = {
+    "PRIVATE-TOKEN": token,
+    "content-type": "application/json",
+  };
+  const notesUrl = `${apiUrl}/projects/${projectId}/merge_requests/${mrIid}/notes`;
+  const notes: StickyComment[] = await (
+    await request(`${notesUrl}?per_page=100`, { headers })
+  ).json();
+  const existing = findSticky(notes);
+  if (existing) {
+    await request(`${notesUrl}/${existing.id}`, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify({ body: markdown }),
+    });
+  } else {
+    await request(notesUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ body: markdown }),
+    });
+  }
+  console.log("updated the sticky MR comment");
+};
+
+export const changesetCheckJob = async () => {
+  await ensureReleaseHistory();
+  const pending = await readPendingChangesets();
+  const lastTag = await getLastReleaseTag();
+  const addedFiles = await getAddedChangesetFiles();
+
+  const result = runChangesetCheck({
+    addedFiles: addedFiles ?? [],
+    pending,
+    lastTag,
+    requestLabel: onGithub() ? "pull request" : "merge request",
+  });
+
+  console.log(result.markdown.replace(`${CHANGESET_CHECK_MARKER}\n`, ""));
+  await writeFile(CHANGESET_REPORT_FILE, result.markdown);
+
+  // a failed comment must not fail the check — the report has already
+  // been printed and written
+  try {
+    if (onGithub()) {
+      await upsertGithubComment(result.markdown);
+    } else {
+      await upsertGitlabComment(result.markdown);
+    }
+  } catch (error) {
+    console.warn(`could not update the sticky comment: ${error}`);
+  }
+
+  if (addedFiles === null) {
+    console.log("not running against a merge request — check skipped");
+    return;
+  }
+  if (!result.addsChangeset) {
+    // exit 1 turns the (allow_failure) job yellow so reviewers notice
+    process.exitCode = 1;
+  }
+};

package/src/release/changesetsReleaseJob.ts

@@ -5,10 +5,9 @@
  * from the last `v*` tag, writes the changelog, commits, tags and
  * pushes — the pushed tag triggers the taggedRelease pipeline.
  */
-import { execFile as execFileCb } from "child_process";
 import { readFile, readdir, rm, writeFile } from "fs/promises";
 import { join } from "path";
-import { promisify } from "util";
+import type { Changeset } from "./changesets";
 import {
   getNextVersion,
   maxBump,
@@ -16,8 +15,7 @@ import {
   prependToChangelog,
   renderChangelogEntries,
 } from "./changesets";
-
-const execFile = promisify(execFileCb);
+import { ensureReleaseHistory, getLastReleaseTag, git } from "./releaseGit";
 
 const CHANGESET_DIR = ".changeset";
 const CHANGELOG_FILE = "CHANGELOG.md";
@@ -29,12 +27,7 @@ const CHANGELOG_FILE = "CHANGELOG.md";
  */
 const GITHUB_TAGGED_RELEASE_WORKFLOW = "catladder-release.yml";
 
-const git = async (...args: string[]): Promise<string> => {
-  const { stdout } = await execFile("git", args);
-  return stdout.trim();
-};
-
-const readPendingChangesets = async () => {
+export const readPendingChangesets = async () => {
   const entries = await readdir(CHANGESET_DIR).catch(() => []);
   const files = entries.filter(
     (file) => file.endsWith(".md") && file.toLowerCase() !== "readme.md",
@@ -49,40 +42,6 @@ const readPendingChangesets = async () => {
   );
 };
 
-/**
- * CI checkouts are usually shallow and tagless (gitlab clones with
- * depth 1; github's checkout needs fetch-depth: 0) — the local history
- * then cannot answer "nearest v* tag" and the job would rederive the
- * FIRST release version. Deepen and fetch tags before deriving.
- */
-const ensureReleaseHistory = async () => {
-  const shallow = await git("rev-parse", "--is-shallow-repository").catch(
-    () => "false",
-  );
-  try {
-    if (shallow === "true") {
-      await git("fetch", "--quiet", "--unshallow", "--tags", "origin");
-    } else {
-      await git("fetch", "--quiet", "--tags", "origin");
-    }
-  } catch (e) {
-    console.warn(
-      `could not fetch tags from origin (${e}) — version derivation may be wrong on a shallow clone`,
-    );
-  }
-};
-
-const getLastReleaseTag = async (): Promise<string | null> => {
-  try {
-    // the nearest v* tag in the history of HEAD — on hotfix branches
-    // this is deliberately the branch's own release line, not the
-    // globally highest version
-    return await git("describe", "--tags", "--abbrev=0", "--match", "v[0-9]*");
-  } catch {
-    return null;
-  }
-};
-
 const ensureGitIdentity = async () => {
   const email = await git("config", "user.email").catch(() => "");
   if (email !== "") return;
@@ -164,17 +123,38 @@ export const dispatchTaggedReleaseWorkflow = async (tag: string) => {
   console.log(`dispatched ${GITHUB_TAGGED_RELEASE_WORKFLOW} for ${tag}`);
 };
 
+/**
+ * the escape hatch of the force-release job: releasing without pending
+ * changesets (e.g. a hotfix merged without one) must not require a new
+ * MR, so a forced empty release becomes a patch bump with a generic
+ * changelog entry instead of a no-op
+ */
+const FORCED_RELEASE_CHANGESET: Changeset = {
+  fileName: "",
+  bump: "patch",
+  summary: "Forced release without pending changesets.",
+};
+
 export const changesetsReleaseJob = async () => {
-  const changesets = await readPendingChangesets();
-  if (changesets.length === 0) {
+  const pending = await readPendingChangesets();
+  const forcedEmpty =
+    pending.length === 0 && process.env.CATLADDER_FORCE_RELEASE === "true";
+  if (pending.length === 0 && !forcedEmpty) {
     console.log(
       `no changesets found in ${CHANGESET_DIR}/ — nothing to release`,
     );
     console.log(
       "add one with `yarn changeset` (or write .changeset/<name>.md by hand) and merge it to release",
     );
+    console.log(
+      "to release anyway (patch bump), run the force release job instead",
+    );
     return;
   }
+  const changesets = forcedEmpty ? [FORCED_RELEASE_CHANGESET] : pending;
+  if (forcedEmpty) {
+    console.log("no changesets pending — forced release, bumping a patch");
+  }
 
   await ensureReleaseHistory();
   const lastTag = await getLastReleaseTag();
@@ -197,11 +177,19 @@ export const changesetsReleaseJob = async () => {
     prependToChangelog(existingChangelog, version, date, entries),
   );
   await Promise.all(
-    changesets.map((changeset) => rm(join(CHANGESET_DIR, changeset.fileName))),
+    // pending, not changesets: the synthetic forced-release changeset
+    // has no file to delete
+    pending.map((changeset) => rm(join(CHANGESET_DIR, changeset.fileName))),
   );
 
   await ensureGitIdentity();
-  await git("add", CHANGELOG_FILE, CHANGESET_DIR);
+  // a forced empty release consumes no changeset files — and .changeset/
+  // may not even exist yet, which `git add` would reject
+  if (forcedEmpty) {
+    await git("add", CHANGELOG_FILE);
+  } else {
+    await git("add", CHANGELOG_FILE, CHANGESET_DIR);
+  }
   await git("commit", "-m", `chore(release): ${version}\n\n${entries}`);
   await git("tag", tag);
   await pushCommitAndTag(tag);

package/src/release/releaseGit.ts

@@ -0,0 +1,47 @@
+/**
+ * git helpers shared by the release-related catci jobs (changesets
+ * release, changeset check).
+ */
+import { execFile as execFileCb } from "child_process";
+import { promisify } from "util";
+
+const execFile = promisify(execFileCb);
+
+export const git = async (...args: string[]): Promise<string> => {
+  const { stdout } = await execFile("git", args);
+  return stdout.trim();
+};
+
+/**
+ * CI checkouts are usually shallow and tagless (gitlab clones with
+ * depth 1; github's checkout needs fetch-depth: 0) — the local history
+ * then cannot answer "nearest v* tag" and the job would rederive the
+ * FIRST release version. Deepen and fetch tags before deriving.
+ */
+export const ensureReleaseHistory = async () => {
+  const shallow = await git("rev-parse", "--is-shallow-repository").catch(
+    () => "false",
+  );
+  try {
+    if (shallow === "true") {
+      await git("fetch", "--quiet", "--unshallow", "--tags", "origin");
+    } else {
+      await git("fetch", "--quiet", "--tags", "origin");
+    }
+  } catch (e) {
+    console.warn(
+      `could not fetch tags from origin (${e}) — version derivation may be wrong on a shallow clone`,
+    );
+  }
+};
+
+export const getLastReleaseTag = async (): Promise<string | null> => {
+  try {
+    // the nearest v* tag in the history of HEAD — on hotfix branches
+    // this is deliberately the branch's own release line, not the
+    // globally highest version
+    return await git("describe", "--tags", "--abbrev=0", "--match", "v[0-9]*");
+  } catch {
+    return null;
+  }
+};