Validate change-notes as a PR check

.github/workflows/pr-checks.yml

@@ -114,6 +114,10 @@ jobs:
         working-directory: pr-checks
         run: npx tsx --test
 
+      - name: Run `pr-checks/changenotes.mts` to ensure that all unreleased change notes are valid
+        if: ${{ !cancelled() && steps.install-deps.outcome == 'success' }}
+        run: npx tsx pr-checks/changenotes.mts validate
+
       - name: Verify all Actions use the same Node version
         id: head-version
         run: |

eslint.config.mjs

@@ -158,7 +158,7 @@ export default [
     },
   },
   {
-    files: ["**/*.ts", "**/*.js"],
+    files: ["**/*.ts", "**/*.js", "**/*.mts"],
 
     rules: {
       "@typescript-eslint/no-explicit-any": "off",

pr-checks/changelog/validate.mts

@@ -119,3 +119,14 @@ export function isValidChangenoteFile(filename: string): boolean {
 
   return isValid;
 }
+
+/**
+ * Validates the change-note files of the given list of file paths, ignoring ".gitkeep".
+ * @param filepaths A list of filepaths to validate
+ * @returns True if all the paths are valid, false otherwise.
+ */
+export function isValidAllChangenoteFiles(filepaths: string[]): boolean {
+  return filepaths
+    .filter((f) => f !== ".gitkeep")
+    .reduce((r, filePath) => r && isValidChangenoteFile(filePath), true);
+}

pr-checks/changelog/validate.test.mts

@@ -1,10 +1,13 @@
 import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { describe, it } from "node:test";
 
-import { withTmpFile } from "../../src/util";
+import { withTmpDir, withTmpFile } from "../../src/util";
 
 import {
   hasValidChangenoteCategory,
+  isValidAllChangenoteFiles,
   isValidChangenoteContent,
   isValidChangenoteFile,
   isValidChangenoteFilename,
@@ -150,6 +153,10 @@ await describe("isValidChangenoteFile", async () => {
     );
   });
 
+  await it("rejects a non-existent path", async () => {
+    assert.equal(isValidChangenoteFile("non-existent-file.md"), false);
+  });
+
   await it("rejects invalid filename", async () => {
     await withTmpFile(
       "fix-bug.md",
@@ -180,3 +187,39 @@ await describe("isValidChangenoteFile", async () => {
     );
   });
 });
+
+await describe("isValidAllChangenoteFiles", async () => {
+  await it("accepts a directory of valid change-note files", async () => {
+    await withTmpDir(async (tmpDir) => {
+      const fileName1 = path.join(tmpDir, "2026-01-01-fix-bug.md");
+      const fileName2 = path.join(tmpDir, "2026-01-02-add-feature.md");
+      fs.writeFileSync(fileName1, "---\ncategory: fix\n---\n- Fixed a bug\n");
+      fs.writeFileSync(
+        fileName2,
+        "---\ncategory: feature\n---\n- Added a feature\n",
+      );
+      assert.equal(isValidAllChangenoteFiles([fileName1, fileName2]), true);
+    });
+  });
+
+  await it("accepts an empty list", async () => {
+    assert.equal(isValidAllChangenoteFiles([]), true);
+  });
+
+  await it("accepts a list of .gitkeep only", async () => {
+    assert.equal(isValidAllChangenoteFiles([".gitkeep"]), true);
+  });
+
+  await it("rejects directory with an invalid change-note file", async () => {
+    await withTmpDir(async (tmpDir) => {
+      const fileName1 = path.join(tmpDir, "2026-01-01-fix-bug.md");
+      const fileName2 = path.join(tmpDir, "2026-01-02-wrong-category.md");
+      fs.writeFileSync(fileName1, "---\ncategory: fix\n---\n- Fixed a bug\n");
+      fs.writeFileSync(
+        fileName2,
+        "---\ncategory: foobar\n---\n- Added a feature\n",
+      );
+      assert.equal(isValidAllChangenoteFiles([fileName1, fileName2]), false);
+    });
+  });
+});

pr-checks/changenotes.mts

@@ -1,9 +1,11 @@
 #!/usr/bin/env npx tsx
 
+import * as fs from "node:fs";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 
-import { isValidChangenoteFile } from "./changelog/validate.mjs";
+import { isValidAllChangenoteFiles } from "./changelog/validate.mjs";
+import { CHANGENOTES_DIR } from "./config";
 
 const entryPoint = process.argv[1];
 if (entryPoint && import.meta.url === pathToFileURL(entryPoint).href) {
@@ -20,34 +22,32 @@ function main(): number {
     allowPositionals: true,
     strict: true,
   });
-  const [command, ...paths] = positionals;
+  const [command] = positionals;
   switch (command) {
     case undefined:
     case "help":
       return usage();
     case "validate":
-      return validate(paths);
+      return validate();
     default:
       console.error(`Unknown command: ${command}`);
       return 1;
   }
 }
 
 function usage(): number {
-  console.log(`Usage: changenotes.mts validate <path> [<path> ...]`);
+  console.log(`Usage: changenotes.mts validate`);
   return 0;
 }
 
-function validate(paths: string[]): number {
-  let valid = true;
-  if (paths.length === 0) {
-    console.error("error: no paths provided (see 'help' command for usage)");
+function validate(): number {
+  try {
+    return isValidAllChangenoteFiles(fs.readdirSync(CHANGENOTES_DIR)) ? 0 : 1;
+  } catch (error) {
+    console.error(
+      `${CHANGENOTES_DIR}: failed to read file or directory`,
+      error,
+    );
     return 1;
   }
-  for (const path of paths) {
-    if (!isValidChangenoteFile(path)) {
-      valid = false;
-    }
-  }
-  return valid ? 0 : 1;
 }

pr-checks/config.ts

@@ -18,6 +18,9 @@ export const PACKAGE_JSON = path.join(REPO_ROOT, "package.json");
 /** The path of the changelog. */
 export const CHANGELOG_FILE = path.join(REPO_ROOT, "CHANGELOG.md");
 
+/** The path to the unreleased change-notes directory. */
+export const CHANGENOTES_DIR = path.join(REPO_ROOT, "unreleased-change-notes");
+
 /** The path to the esbuild metadata file. */
 export const BUNDLE_METADATA_FILE = path.join(REPO_ROOT, "meta.json");