@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

package/src/publish/npmPublishPlan.ts

@@ -0,0 +1,64 @@
+/**
+ * pure derivation of what an npmPackage deploy publishes — version and
+ * dist-tag from the pipeline trigger. Kept free of process/env access
+ * so it is trivially testable; `npmPublishJob` supplies the CI context.
+ */
+
+export type NpmPublishContext = {
+  /** catladder env type of the deploy job (passed by the generated job) */
+  envType: string;
+  /** git tag the pipeline runs for, without `refs/` prefix; null on branch/MR pipelines */
+  ciTag: string | null;
+  /** slugified branch name (the source branch for merge requests) */
+  refSlug: string;
+  /** short commit sha */
+  shortSha: string;
+  /** explicit dist-tag from the deploy config, overrides the derivation */
+  distTagOverride?: string;
+};
+
+export type NpmPublishPlan = {
+  version: string;
+  distTag: string;
+};
+
+/**
+ * branches whose canary publishes get their own dist-tag instead of
+ * `canary`, so consumers can track them (`yarn add pkg@next`)
+ */
+export const BRANCH_DIST_TAGS = ["next", "beta"];
+
+export const computeNpmPublishPlan = (
+  ctx: NpmPublishContext,
+): NpmPublishPlan => {
+  if (ctx.envType === "prod" || ctx.envType === "stage") {
+    if (!ctx.ciTag) {
+      throw new Error(
+        `npm publish for env type "${ctx.envType}" expects a tagged-release pipeline, but no git tag is set`,
+      );
+    }
+    return {
+      version: ctx.ciTag.replace(/^v/, ""),
+      distTag: ctx.distTagOverride ?? "latest",
+    };
+  }
+  return {
+    version: `0.0.0-${ctx.refSlug}-${ctx.shortSha}`,
+    distTag:
+      ctx.distTagOverride ??
+      (BRANCH_DIST_TAGS.includes(ctx.refSlug) ? ctx.refSlug : "canary"),
+  };
+};
+
+/**
+ * mirrors gitlab's CI_COMMIT_REF_SLUG derivation (github has no
+ * equivalent predefined variable): lowercased, everything except
+ * `0-9a-z` replaced with `-`, shortened to 63 bytes, trimmed of
+ * leading/trailing `-`
+ */
+export const slugifyRef = (ref: string): string =>
+  ref
+    .toLowerCase()
+    .replace(/[^0-9a-z]/g, "-")
+    .slice(0, 63)
+    .replace(/^-+|-+$/g, "");

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

@@ -0,0 +1,87 @@
+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",
+      packageManager: "yarn",
+    });
+    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",
+      packageManager: "yarn",
+    });
+    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",
+      packageManager: "yarn",
+    });
+    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("names the project's own package manager in the how-to hint", () => {
+    const forPm = (packageManager: "yarn" | "pnpm") =>
+      runChangesetCheck({
+        addedFiles: [],
+        pending: [],
+        lastTag: "v4.7.0",
+        requestLabel: "merge request",
+        packageManager,
+      }).markdown;
+    expect(forPm("pnpm")).toContain("`pnpm changeset`");
+    expect(forPm("pnpm")).not.toContain("yarn");
+    expect(forPm("yarn")).toContain("`yarn changeset`");
+  });
+
+  it("handles the first release (no previous tag)", () => {
+    const result = runChangesetCheck({
+      addedFiles: ["init.md"],
+      pending: [changeset("minor", "Initial feature")],
+      lastTag: null,
+      requestLabel: "pull request",
+      packageManager: "yarn",
+    });
+    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/__tests__/changesets.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import {
+  getNextVersion,
+  maxBump,
+  parseChangesetFile,
+  prependToChangelog,
+  renderChangelogEntries,
+} from "../changesets";
+
+describe("parseChangesetFile", () => {
+  it("parses the official changesets format", () => {
+    const changeset = parseChangesetFile(
+      "brave-lions-smile.md",
+      '---\n"my-app": minor\n---\n\nAdd the fancy new dashboard\n',
+    );
+    expect(changeset).toEqual({
+      fileName: "brave-lions-smile.md",
+      bump: "minor",
+      summary: "Add the fancy new dashboard",
+    });
+  });
+
+  it("takes the highest bump when multiple packages are declared", () => {
+    const changeset = parseChangesetFile(
+      "x.md",
+      '---\n"pkg-a": patch\n"pkg-b": major\n---\nbreaking rework\n',
+    );
+    expect(changeset.bump).toBe("major");
+  });
+
+  it("accepts unquoted package names", () => {
+    const changeset = parseChangesetFile(
+      "x.md",
+      "---\nmy-app: patch\n---\nfix it\n",
+    );
+    expect(changeset.bump).toBe("patch");
+  });
+
+  // format details handled by @changesets/parse (real YAML) that the
+  // previous hand-rolled regex parser got wrong:
+
+  it("accepts quoted bump values", () => {
+    const changeset = parseChangesetFile(
+      "x.md",
+      '---\n"my-app": "minor"\n---\nsummary\n',
+    );
+    expect(changeset.bump).toBe("minor");
+  });
+
+  it("ignores `none` releases and uses the highest real bump", () => {
+    const changeset = parseChangesetFile(
+      "x.md",
+      '---\n"pkg-a": none\n"pkg-b": minor\n---\nsummary\n',
+    );
+    expect(changeset.bump).toBe("minor");
+  });
+
+  it("ignores yaml comments in the frontmatter", () => {
+    const changeset = parseChangesetFile(
+      "x.md",
+      '---\n# only bumping the app\n"my-app": patch\n---\nfix it\n',
+    );
+    expect(changeset.bump).toBe("patch");
+  });
+
+  it("throws on a file without frontmatter", () => {
+    expect(() => parseChangesetFile("x.md", "just some text")).toThrow(
+      /not a valid changeset/,
+    );
+  });
+
+  it("throws on an invalid bump", () => {
+    expect(() =>
+      parseChangesetFile("x.md", '---\n"my-app": huge\n---\nsummary\n'),
+    ).toThrow(/not a valid changeset/);
+  });
+
+  it("throws on an empty summary", () => {
+    expect(() =>
+      parseChangesetFile("x.md", '---\n"my-app": patch\n---\n\n'),
+    ).toThrow(/no summary/);
+  });
+
+  it("throws when the changeset declares no effective bump (all none)", () => {
+    expect(() =>
+      parseChangesetFile("x.md", '---\n"pkg-a": none\n---\nsummary\n'),
+    ).toThrow(/no effective version bump/);
+  });
+
+  it("throws when the frontmatter is empty", () => {
+    expect(() => parseChangesetFile("x.md", "---\n---\nsummary\n")).toThrow(
+      /no effective version bump/,
+    );
+  });
+});
+
+describe("maxBump", () => {
+  it("orders patch < minor < major", () => {
+    expect(maxBump(["patch"])).toBe("patch");
+    expect(maxBump(["patch", "minor", "patch"])).toBe("minor");
+    expect(maxBump(["minor", "major", "patch"])).toBe("major");
+  });
+});
+
+describe("getNextVersion", () => {
+  it("starts at 1.0.0 without a previous tag (like semantic-release)", () => {
+    expect(getNextVersion(null, "patch")).toBe("1.0.0");
+  });
+
+  it("bumps from the last tag", () => {
+    expect(getNextVersion("v1.2.3", "patch")).toBe("1.2.4");
+    expect(getNextVersion("v1.2.3", "minor")).toBe("1.3.0");
+    expect(getNextVersion("v1.2.3", "major")).toBe("2.0.0");
+  });
+
+  it("rejects tags that are not plain vX.Y.Z", () => {
+    expect(() => getNextVersion("v1.2.3-beta.1", "patch")).toThrow(
+      /not of the form vX\.Y\.Z/,
+    );
+  });
+});
+
+describe("renderChangelogEntries", () => {
+  it("groups by bump level, highest first", () => {
+    const entries = renderChangelogEntries([
+      { fileName: "a.md", bump: "patch", summary: "fix a leak" },
+      { fileName: "b.md", bump: "major", summary: "drop old api" },
+      { fileName: "c.md", bump: "patch", summary: "fix a typo" },
+    ]);
+    expect(entries).toBe(
+      [
+        "### Major Changes",
+        "",
+        "- drop old api",
+        "",
+        "### Patch Changes",
+        "",
+        "- fix a leak",
+        "- fix a typo",
+      ].join("\n"),
+    );
+  });
+
+  it("indents multi-line summaries into the bullet", () => {
+    const entries = renderChangelogEntries([
+      { fileName: "a.md", bump: "minor", summary: "first line\nsecond line" },
+    ]);
+    expect(entries).toBe("### Minor Changes\n\n- first line\n  second line");
+  });
+});
+
+describe("prependToChangelog", () => {
+  it("creates a fresh changelog", () => {
+    expect(prependToChangelog(null, "1.0.0", "2026-07-20", "- initial")).toBe(
+      "# Changelog\n\n## 1.0.0 (2026-07-20)\n\n- initial\n",
+    );
+  });
+
+  it("prepends to an existing changelog below the header", () => {
+    const existing = "# Changelog\n\n## 1.0.0 (2026-01-01)\n\n- initial\n";
+    expect(
+      prependToChangelog(existing, "1.1.0", "2026-07-20", "- new stuff"),
+    ).toBe(
+      "# Changelog\n\n## 1.1.0 (2026-07-20)\n\n- new stuff\n\n" +
+        "## 1.0.0 (2026-01-01)\n\n- initial\n",
+    );
+  });
+});

package/src/release/changesetCheck.ts

@@ -0,0 +1,88 @@
+/**
+ * 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;
+  /**
+   * the project's package manager, so the "how to add one" hint names a
+   * command that actually exists there
+   */
+  packageManager: "yarn" | "pnpm";
+};
+
+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,
+  packageManager,
+}: 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 \`${packageManager} 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,224 @@
+/**
+ * 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 { existsSync } from "fs";
+import { writeFile } from "fs/promises";
+import { CHANGESET_CHECK_MARKER, runChangesetCheck } from "./changesetCheck";
+import { readPendingChangesets } from "./changesetsReleaseJob";
+import { ensureReleaseHistory, getLastReleaseTag, git } from "./releaseGit";
+import { appendStepSummary } from "./stepSummary";
+
+export const CHANGESET_REPORT_FILE = "changeset-report.md";
+
+const onGithub = () => process.env.GITHUB_ACTIONS === "true";
+
+/**
+ * the repo's package manager, from the lockfile in the checkout — the
+ * hint for adding a changeset should name a command the project has
+ */
+const detectPackageManager = (): "yarn" | "pnpm" =>
+  existsSync("pnpm-lock.yaml") ? "pnpm" : "yarn";
+
+/**
+ * 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",
+    packageManager: detectPackageManager(),
+  });
+
+  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) {
+    if (onGithub()) {
+      // github has no "warning" job state: exiting non-zero would show
+      // the job as failed (a red ❌ and "exit code 1"), which reads like
+      // something broke. A warning annotation plus the step summary and
+      // the sticky PR comment carry the signal instead.
+      console.log(
+        "::warning title=No changeset::this pull request adds no changeset — " +
+          "if the change is user-facing, add one so it appears in the next release's changelog",
+      );
+      appendStepSummary(
+        result.markdown.replace(`${CHANGESET_CHECK_MARKER}\n`, ""),
+      );
+      return;
+    }
+    // gitlab: exit 1 turns the (allow_failure) job yellow so reviewers
+    // notice
+    process.exitCode = 1;
+  }
+};