Migrate changetool to pr-checks

pr-checks/changelog/validate.mts

@@ -0,0 +1,121 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { matter } from "lite-matter";
+import type { List, ListItem } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+
+// Regex for filename: YYYY-MM-DD-id.md
+const VALID_CHANGE_NOTE_FILENAME_PATTERN =
+  /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/;
+
+export const VALID_CHANGE_NOTE_CATEGORIES = {
+  breaking: "Breaking Changes",
+  feature: "New Features",
+  improvement: "Improvements",
+  securityFix: "Security Fixes",
+  fix: "Bug Fixes",
+  unship: "Removed Features",
+  deprecation: "Deprecations",
+  knownIssue: "Known Issues",
+  misc: "Miscellaneous",
+};
+
+/**
+ * Validates that the given Markdown string meets the criteria for a change-note, which is:
+ * - A single unordered list
+ * - Each list item must start with a hyphen (-)
+ * - No other Markdown elements are allowed
+ * @param content The Markdown string to validate
+ * @returns True if the string is a valid change-note, false otherwise
+ */
+export function isValidChangenoteContent(content: string): boolean {
+  const ast = fromMarkdown(content);
+  const lines = content.split("\n");
+
+  function listHasHyphenBullets(node: List | ListItem): boolean {
+    if (node.type === "list") {
+      return node.children.every(listHasHyphenBullets);
+    }
+
+    const line = lines[node.position!.start.line - 1].trim();
+    return (
+      line.startsWith("-") &&
+      node.children.every(
+        (child) => child.type !== "list" || listHasHyphenBullets(child),
+      )
+    );
+  }
+
+  return (
+    ast.children.length === 1 &&
+    ast.children[0].type === "list" &&
+    ast.children[0].ordered === false &&
+    listHasHyphenBullets(ast.children[0])
+  );
+}
+
+/**
+ * Validates that the given filename meets the criteria for a change-note filename.
+ * @param filename The name of the change-note file to validate.
+ * @returns True if the filename is valid, false otherwise.
+ */
+export function isValidChangenoteFilename(filename: string): boolean {
+  return filename.match(VALID_CHANGE_NOTE_FILENAME_PATTERN) !== null;
+}
+
+/**
+ * Validates that the given frontmatter has a valid change-note category.
+ * @param frontmatter The frontmatter object to validate.
+ * @returns True if the frontmatter has a valid category, false otherwise.
+ */
+export function hasValidChangenoteCategory(
+  frontmatter: Record<string, unknown>,
+): boolean {
+  const category = frontmatter["category"];
+  return (
+    typeof category === "string" &&
+    Object.hasOwn(VALID_CHANGE_NOTE_CATEGORIES, category)
+  );
+}
+
+/**
+ * Validates that the given change-note file meets all of the criteria for a change-note.
+ * @param filename The name of the change-note file to validate.
+ * @returns True if the file is a valid change-note, false otherwise.
+ */
+export function isValidChangenoteFile(filename: string): boolean {
+  let isValid: boolean = true;
+
+  let fileData: string | undefined;
+  try {
+    fileData = fs.readFileSync(filename, "utf8");
+  } catch (error) {
+    console.error(`${filename}: failed to read file`, error);
+    return false;
+  }
+
+  const { data: frontmatter, content } = matter(fileData);
+
+  if (!isValidChangenoteFilename(path.basename(filename))) {
+    isValid = false;
+    console.error(
+      `${filename}: invalid filename; must match pattern YYYY-MM-DD-id.md`,
+    );
+  }
+  if (!hasValidChangenoteCategory(frontmatter)) {
+    isValid = false;
+    const categories = Object.keys(VALID_CHANGE_NOTE_CATEGORIES).join(", ");
+    console.error(
+      `${filename}: invalid category; must be one of: ${categories}`,
+    );
+  }
+  if (!isValidChangenoteContent(content)) {
+    isValid = false;
+    console.error(
+      `${filename}: invalid Markdown; content must be a single unordered list with hyphen bullets and no other Markdown elements`,
+    );
+  }
+
+  return isValid;
+}

pr-checks/changelog/validate.test.mts

@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+
+import {
+  isValidChangenoteContent,
+  isValidChangenoteFile,
+  isValidChangenoteFilename,
+  hasValidChangenoteCategory,
+  VALID_CHANGE_NOTE_CATEGORIES,
+} from "./validate.mjs";
+
+async function withTmpFile<T>(
+  baseFileName: string,
+  contents: string,
+  body: (filePath: string) => Promise<T>,
+): Promise<T> {
+  const tmpDir = fs.mkdtempSync(
+    path.join(os.tmpdir(), "changetool-validate-test-"),
+  );
+  try {
+    const filePath = path.join(tmpDir, baseFileName);
+    fs.writeFileSync(filePath, contents);
+    return await body(filePath);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+await describe("isValidChangenoteContent", async () => {
+  await it("recognizes an unordered Markdown list", async () => {
+    const inputs = [
+      "- One changenote entry",
+      "- First item\n- Second item",
+      "\n\n\n\n- Fixed a bug\n- Added a feature",
+    ];
+
+    for (const input of inputs) {
+      assert.equal(isValidChangenoteContent(input), true);
+    }
+  });
+
+  await it("does not recognize non-Markdown text", async () => {
+    const inputs = [
+      "This is not a list.",
+      '["this", "is", "JSON"]',
+      "---",
+      "***",
+      "___",
+      "paragraph",
+    ];
+
+    for (const input of inputs) {
+      assert.equal(isValidChangenoteContent(input), false);
+    }
+  });
+
+  await it("does not recognize ordered Markdown lists", async () => {
+    const inputs = [
+      "1. First item\n2. Second item",
+      "\n\n\n1. First item\n1. Second item",
+    ];
+
+    for (const input of inputs) {
+      assert.equal(isValidChangenoteContent(input), false);
+    }
+  });
+
+  await it("requires all list items to use a hyphen bullet", async () => {
+    const inputs = [
+      "* Fixed a bug\n* Added feature",
+      "+ Fixed a bug\n+ Added feature",
+      "- Fixed a bug\n* Added feature",
+      "- Fixed a bug\n+ Added feature",
+      "- Fixed a bug\n  * Added feature\n    + Updated docs",
+      "\n\n\n* Fixed a bug",
+      "\n\n\n+ Fixed a bug",
+      "---\n* Fixed a bug\n* Added feature",
+    ] as const;
+
+    for (const input of inputs) {
+      assert.equal(isValidChangenoteContent(input), false);
+    }
+  });
+
+  await it("does not contain other Markdown elements", async () => {
+    const inputs = [
+      "- Fixed a bug\n\nParagraph of text",
+      "- Fixed a bug\n\n* Added a feature",
+      "# Header\n- Fixed a bug",
+      "- Fixed a bug\n## Subheader",
+    ];
+
+    for (const input of inputs) {
+      assert.equal(isValidChangenoteContent(input), false);
+    }
+  });
+});
+
+await describe("isValidChangenoteFilename", async () => {
+  await it("accepts valid filenames", async () => {
+    const inputs = [
+      "2023-01-01-fix-bug.md",
+      "2023-12-31-add-feature.md",
+      "2023-06-15-update-docs.md",
+    ];
+
+    for (const input of inputs) {
+      assert.equal(isValidChangenoteFilename(input), true);
+    }
+  });
+
+  await it("rejects invalid filenames", async () => {
+    const inputs = [
+      "missing-date-from-filename.md",
+      "2021-01-01.md",
+      "2026-12-19-wrong-file-name-extension.txt",
+    ];
+
+    for (const input of inputs) {
+      assert.equal(isValidChangenoteFilename(input), false);
+    }
+  });
+});
+
+await describe("hasValidChangenoteCategory", async () => {
+  await it("accepts valid categories", async () => {
+    for (const category of Object.keys(VALID_CHANGE_NOTE_CATEGORIES)) {
+      const frontmatter = { category };
+      assert.equal(hasValidChangenoteCategory(frontmatter), true);
+    }
+  });
+
+  await it("rejects invalid categories", async () => {
+    const inputs = [
+      "",
+      "invalid-category",
+      "bug-fix",
+      "new-feature",
+      "security-patch",
+      "miscellaneous",
+      "documentation",
+    ];
+
+    for (const category of inputs) {
+      const frontmatter = { category };
+      assert.equal(hasValidChangenoteCategory(frontmatter), false);
+    }
+  });
+
+  await it("reject missing category", async () => {
+    assert.equal(hasValidChangenoteCategory({}), false);
+    assert.equal(hasValidChangenoteCategory({ category: null }), false);
+    assert.equal(hasValidChangenoteCategory({ category: undefined }), false);
+  });
+});
+
+await describe("isValidChangenoteFile", async () => {
+  await it("accepts a valid change-note file", async () => {
+    await withTmpFile(
+      "2026-01-01-fix-bug.md",
+      "---\ncategory: fix\n---\n- Fixed a bug\n",
+      async (filePath) => {
+        assert.equal(isValidChangenoteFile(filePath), true);
+      },
+    );
+  });
+
+  await it("rejects invalid filename", async () => {
+    await withTmpFile(
+      "fix-bug.md",
+      "---\ncategory: fix\n---\n- Fixed a bug\n",
+      async (filePath) => {
+        assert.equal(isValidChangenoteFile(filePath), false);
+      },
+    );
+  });
+
+  await it("rejects missing frontmatter", async () => {
+    await withTmpFile(
+      "2026-01-01-fix-bug.md",
+      "- Fixed a bug\n",
+      async (filePath) => {
+        assert.equal(isValidChangenoteFile(filePath), false);
+      },
+    );
+  });
+
+  await it("rejects invalid Markdown", async () => {
+    await withTmpFile(
+      "2026-01-01-fix-bug.md",
+      "---\ncategory: fix\n---\n* Fixed a bug\n",
+      async (filePath) => {
+        assert.equal(isValidChangenoteFile(filePath), false);
+      },
+    );
+  });
+});