ci(release): add local release sanity checks

Validate package version, changelog coverage, dist packaging, and release tag parity before publishing so release failures surface before tag workflows.

Author: AlbinoGeek

.github/workflows/release.yml

@@ -41,15 +41,8 @@ jobs:
       - name: Unit tests
         run: bun run test
 
-      - name: Verify git tag matches package.json version
-        run: |
-          set -euo pipefail
-          TAG="${GITHUB_REF#refs/tags/v}"
-          PKG=$(node -p "require('./package.json').version")
-          if [ "$TAG" != "$PKG" ]; then
-            echo "::error::Git tag v$TAG must match package.json version $PKG (publish aborted)."
-            exit 1
-          fi
+      - name: Release sanity checks
+        run: bun run release:check
 
       - name: Create tarball for GitHub Release
         id: pack

package.json

@@ -32,7 +32,8 @@
     "check:fix": "biome check --write .",
     "test": "bun test src/",
     "test:coverage": "bun src/coverage-threshold.ts",
-    "prepublishOnly": "bun run build && bun run check && bun run test",
+    "release:check": "bun src/release-sanity.ts",
+    "prepublishOnly": "bun run release:check && bun run build && bun run check && bun run test",
     "setup-hooks": "git config core.hooksPath .githooks"
   },
   "keywords": [

src/release-sanity.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+
+import { checkReleaseSanity } from "./release-sanity.js";
+
+const BASE_PACKAGE = {
+  name: "@rethunk/github-mcp",
+  version: "1.2.3",
+  files: ["dist", "README.md"],
+};
+
+describe("checkReleaseSanity", () => {
+  test("accepts a package version with matching changelog entry and tag ref", () => {
+    expect(
+      checkReleaseSanity({
+        packageJson: BASE_PACKAGE,
+        changelog: "## [1.2.3] — 2026-04-26\n\n### Changed\n",
+        githubRef: "refs/tags/v1.2.3",
+      }),
+    ).toEqual([]);
+  });
+
+  test("reports mismatched tags and missing changelog entries", () => {
+    expect(
+      checkReleaseSanity({
+        packageJson: BASE_PACKAGE,
+        changelog: "## [1.2.2] — 2026-04-26\n",
+        githubRef: "refs/tags/v1.2.4",
+      }),
+    ).toEqual([
+      "CHANGELOG.md must contain a ## [1.2.3] release entry.",
+      "Git tag v1.2.4 must match package.json version 1.2.3.",
+    ]);
+  });
+
+  test("requires dist to be included in package files", () => {
+    expect(
+      checkReleaseSanity({
+        packageJson: { ...BASE_PACKAGE, files: ["README.md"] },
+        changelog: "## [1.2.3] — 2026-04-26\n",
+      }),
+    ).toEqual(['package.json "files" must include "dist".']);
+  });
+});

src/release-sanity.ts

@@ -0,0 +1,72 @@
+import { readFileSync } from "node:fs";
+
+interface PackageJson {
+  version?: unknown;
+  files?: unknown;
+}
+
+interface ReleaseSanityInput {
+  packageJson: PackageJson;
+  changelog: string;
+  githubRef?: string;
+}
+
+export function checkReleaseSanity(input: ReleaseSanityInput): string[] {
+  const errors: string[] = [];
+  const version = input.packageJson.version;
+
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
+    errors.push("package.json version must be a valid semver string.");
+    return errors;
+  }
+
+  const releaseHeading = new RegExp(`^## \\[${escapeRegExp(version)}\\](?:\\s|$)`, "m");
+  if (!releaseHeading.test(input.changelog)) {
+    errors.push(`CHANGELOG.md must contain a ## [${version}] release entry.`);
+  }
+
+  if (
+    !Array.isArray(input.packageJson.files) ||
+    !input.packageJson.files.some((entry) => entry === "dist")
+  ) {
+    errors.push('package.json "files" must include "dist".');
+  }
+
+  if (input.githubRef?.startsWith("refs/tags/")) {
+    const tagVersion = input.githubRef.slice("refs/tags/v".length);
+    if (tagVersion !== version) {
+      errors.push(`Git tag v${tagVersion} must match package.json version ${version}.`);
+    }
+  }
+
+  return errors;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function readPackageJson(): PackageJson {
+  return JSON.parse(readFileSync("package.json", "utf8")) as PackageJson;
+}
+
+function runReleaseSanityCli(): void {
+  const errors = checkReleaseSanity({
+    packageJson: readPackageJson(),
+    changelog: readFileSync("CHANGELOG.md", "utf8"),
+    githubRef: process.env.GITHUB_REF,
+  });
+
+  if (errors.length > 0) {
+    for (const error of errors) {
+      process.stderr.write(`Release sanity check failed: ${error}\n`);
+    }
+    process.exit(1);
+  }
+
+  console.log("Release sanity OK");
+}
+
+if (import.meta.main) {
+  runReleaseSanityCli();
+}