From b3c3a637b2512cac14b6dea8b325e5ea7c1e524b Mon Sep 17 00:00:00 2001
From: Guillaume Roux <guillaumeroux123@gmail.com>
Date: Fri, 16 Oct 2026 14:31:48 +0200
Subject: [PATCH] feat: add changelog metadata

---
 README.md                                     |  1 +
 packages/changesets-changelog/CHANGELOG.md    |  1 +
 packages/changesets-changelog/package.json    |  2 +
 packages/changesets-changelog/src/index.ts    |  3 ++
 .../changesets-changelog/src/options.test.ts  | 29 +++++++++++++++
 packages/changesets-changelog/src/options.ts  | 37 +++++++++++++++++++
 .../src/resolve-pull-request.ts               |  6 +--
 .../changesets-changelog/tsconfig.build.json  |  2 +-
 packages/changesets-changelog/tsconfig.json   |  2 +-
 .../changesets-changelog/tsconfig.lint.json   |  2 +-
 packages/changesets-utils/CHANGELOG.md        |  1 +
 .../changesets-utils/src/categories.test.ts   | 16 ++++++++
 packages/changesets-utils/src/categories.ts   | 13 +++++++
 packages/changesets-utils/src/index.ts        |  7 ++--
 .../src/parse-changeset-summary.test.ts       |  6 +--
 .../src/parse-changeset-summary.ts            | 13 +------
 yarn.lock                                     |  4 +-
 17 files changed, 120 insertions(+), 25 deletions(-)
 create mode 100644 packages/changesets-changelog/src/index.ts
 create mode 100644 packages/changesets-changelog/src/options.test.ts
 create mode 100644 packages/changesets-changelog/src/options.ts
 create mode 100644 packages/changesets-utils/src/categories.test.ts
 create mode 100644 packages/changesets-utils/src/categories.ts

diff --git a/README.md b/README.md
index 4e42faf..3c67cc6 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,7 @@ linkStyle default opacity:0.5
   changesets_changelog(["@metamask/changesets-changelog"]);
   changesets_utils(["@metamask/changesets-utils"]);
   create_release_branch(["@metamask/create-release-branch"]);
+  changesets_changelog --> changesets_utils;
 ```
 
 <!-- end dependency graph -->
diff --git a/packages/changesets-changelog/CHANGELOG.md b/packages/changesets-changelog/CHANGELOG.md
index 6d74180..7ec7053 100644
--- a/packages/changesets-changelog/CHANGELOG.md
+++ b/packages/changesets-changelog/CHANGELOG.md
@@ -10,5 +10,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add local pull request resolution from Git commit subjects ([#84](https://github.com/MetaMask/release-tools/pull/84))
+- Add Keep a Changelog categories and repository option validation ([#87](https://github.com/MetaMask/release-tools/pull/87))
 
 [Unreleased]: https://github.com/MetaMask/release-tools/
diff --git a/packages/changesets-changelog/package.json b/packages/changesets-changelog/package.json
index 4ce13c5..6f18419 100644
--- a/packages/changesets-changelog/package.json
+++ b/packages/changesets-changelog/package.json
@@ -47,6 +47,8 @@
   },
   "dependencies": {
     "@changesets/types": "^7.0.0",
+    "@metamask/changesets-utils": "^0.0.0",
+    "@metamask/utils": "^11.12.0",
     "execa": "^8.0.1"
   },
   "devDependencies": {
diff --git a/packages/changesets-changelog/src/index.ts b/packages/changesets-changelog/src/index.ts
new file mode 100644
index 0000000..796ec2b
--- /dev/null
+++ b/packages/changesets-changelog/src/index.ts
@@ -0,0 +1,3 @@
+// Re-exported as `categories` because the categorized changelog interface in
+// `@metamask/apply-release-plan` requires a `categories` export.
+export { CATEGORIES as categories } from '@metamask/changesets-utils';
diff --git a/packages/changesets-changelog/src/options.test.ts b/packages/changesets-changelog/src/options.test.ts
new file mode 100644
index 0000000..66a9746
--- /dev/null
+++ b/packages/changesets-changelog/src/options.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { getGitHubRepository, validateChangelogOptions } from './options.js';
+
+describe('validateChangelogOptions', () => {
+  it('does not throw for options with a validated repository', () => {
+    expect(() =>
+      validateChangelogOptions({ repository: 'MetaMask/core' }),
+    ).not.toThrow();
+  });
+
+  it.each([
+    null,
+    {},
+    { repository: '' },
+    { repository: '   ' },
+    { repository: 123 },
+  ])('throws when repository is missing or invalid: %j', (options) => {
+    expect(() => validateChangelogOptions(options)).toThrow('"repository"');
+  });
+});
+
+describe('getGitHubRepository', () => {
+  it('returns the validated repository', () => {
+    expect(getGitHubRepository({ repository: 'MetaMask/core' })).toBe(
+      'MetaMask/core',
+    );
+  });
+});
diff --git a/packages/changesets-changelog/src/options.ts b/packages/changesets-changelog/src/options.ts
new file mode 100644
index 0000000..27fcd2a
--- /dev/null
+++ b/packages/changesets-changelog/src/options.ts
@@ -0,0 +1,37 @@
+import { hasProperty, isObject } from '@metamask/utils';
+
+export type ChangelogOptions = {
+  repository: string;
+};
+
+/**
+ * Validates and narrows changelog options.
+ *
+ * @param changelogOpts - The changelog options.
+ * @throws If `repository` is missing or empty.
+ */
+export function validateChangelogOptions(
+  changelogOpts: unknown,
+): asserts changelogOpts is ChangelogOptions {
+  if (
+    !isObject(changelogOpts) ||
+    !hasProperty(changelogOpts, 'repository') ||
+    typeof changelogOpts.repository !== 'string' ||
+    changelogOpts.repository.trim() === ''
+  ) {
+    throw new Error(
+      'Please provide a repository to this changelog generator: "repository": "org/repo"',
+    );
+  }
+}
+
+/**
+ * Returns the configured GitHub repository.
+ *
+ * @param changelogOpts - The changelog options.
+ * @returns The repository in `owner/repo` form.
+ */
+export function getGitHubRepository(changelogOpts: unknown): string {
+  validateChangelogOptions(changelogOpts);
+  return changelogOpts.repository;
+}
diff --git a/packages/changesets-changelog/src/resolve-pull-request.ts b/packages/changesets-changelog/src/resolve-pull-request.ts
index 5f6506c..139c9ba 100644
--- a/packages/changesets-changelog/src/resolve-pull-request.ts
+++ b/packages/changesets-changelog/src/resolve-pull-request.ts
@@ -28,12 +28,12 @@ export function extractPullRequestNumber(subject: string): string {
  * Resolves the pull request link for a changeset using its local Git commit.
  *
  * @param changeset - The changeset whose commit should be inspected.
- * @param repo - The GitHub repository in `owner/repo` form.
+ * @param repository - The GitHub repository in `owner/repo` form.
  * @returns The Markdown pull request link.
  */
 export async function getPullRequestLink(
   changeset: NewChangesetWithCommit,
-  repo: string,
+  repository: string,
 ): Promise<string> {
   if (!changeset.commit) {
     throw new Error(`Changeset ${changeset.id} has no commit`);
@@ -61,5 +61,5 @@ export async function getPullRequestLink(
   }
 
   const pullRequestNumber = extractPullRequestNumber(subject.trim());
-  return `[#${pullRequestNumber}](https://github.com/${repo}/pull/${pullRequestNumber})`;
+  return `[#${pullRequestNumber}](https://github.com/${repository}/pull/${pullRequestNumber})`;
 }
diff --git a/packages/changesets-changelog/tsconfig.build.json b/packages/changesets-changelog/tsconfig.build.json
index 6fa9af6..296f7a5 100644
--- a/packages/changesets-changelog/tsconfig.build.json
+++ b/packages/changesets-changelog/tsconfig.build.json
@@ -5,6 +5,6 @@
     "rootDir": "./src",
     "types": ["node"]
   },
-  "references": [],
+  "references": [{ "path": "../changesets-utils/tsconfig.build.json" }],
   "include": ["./src"]
 }
diff --git a/packages/changesets-changelog/tsconfig.json b/packages/changesets-changelog/tsconfig.json
index ba29d25..9eff4b3 100644
--- a/packages/changesets-changelog/tsconfig.json
+++ b/packages/changesets-changelog/tsconfig.json
@@ -3,6 +3,6 @@
   "compilerOptions": {
     "types": ["node"]
   },
-  "references": [],
+  "references": [{ "path": "../changesets-utils/tsconfig.json" }],
   "include": ["./src"]
 }
diff --git a/packages/changesets-changelog/tsconfig.lint.json b/packages/changesets-changelog/tsconfig.lint.json
index fb65dcf..7e9409e 100644
--- a/packages/changesets-changelog/tsconfig.lint.json
+++ b/packages/changesets-changelog/tsconfig.lint.json
@@ -4,5 +4,5 @@
     "outDir": "./.tsc-lint-cache",
     "tsBuildInfoFile": "./.tsc-lint-cache/tsconfig.tsbuildinfo"
   },
-  "references": []
+  "references": [{ "path": "../changesets-utils/tsconfig.lint.json" }]
 }
diff --git a/packages/changesets-utils/CHANGELOG.md b/packages/changesets-utils/CHANGELOG.md
index 24b3e7a..19797b5 100644
--- a/packages/changesets-utils/CHANGELOG.md
+++ b/packages/changesets-utils/CHANGELOG.md
@@ -15,5 +15,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Returns new changeset and release objects, preserves summaries and metadata, drops changesets with no selected releases, and does not mutate its inputs.
 - Add `restoreResidualChangesets` for rewriting Changeset files after a partial release ([#78](https://github.com/MetaMask/release-tools/pull/78))
   - Writes back only the releases for packages that were not released, preserves the original summary and bump types, leaves fully consumed Changeset files deleted, and is safe to run more than once.
+- Export the supported changeset categories for changelog plugins ([#87](https://github.com/MetaMask/release-tools/pull/87)).
 
 [Unreleased]: https://github.com/MetaMask/release-tools/
diff --git a/packages/changesets-utils/src/categories.test.ts b/packages/changesets-utils/src/categories.test.ts
new file mode 100644
index 0000000..4147890
--- /dev/null
+++ b/packages/changesets-utils/src/categories.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+
+import { CATEGORIES } from './categories.js';
+
+describe('categories', () => {
+  it('lists the supported changeset categories', () => {
+    expect(CATEGORIES).toStrictEqual([
+      'Added',
+      'Changed',
+      'Deprecated',
+      'Removed',
+      'Fixed',
+      'Security',
+    ]);
+  });
+});
diff --git a/packages/changesets-utils/src/categories.ts b/packages/changesets-utils/src/categories.ts
new file mode 100644
index 0000000..dac5fa5
--- /dev/null
+++ b/packages/changesets-utils/src/categories.ts
@@ -0,0 +1,13 @@
+/**
+ * The changeset categories supported by the summary parser.
+ */
+export const CATEGORIES = [
+  'Added',
+  'Changed',
+  'Deprecated',
+  'Removed',
+  'Fixed',
+  'Security',
+] as const;
+
+export type ChangesetCategory = (typeof CATEGORIES)[number];
diff --git a/packages/changesets-utils/src/index.ts b/packages/changesets-utils/src/index.ts
index b17d8ec..8dc5612 100644
--- a/packages/changesets-utils/src/index.ts
+++ b/packages/changesets-utils/src/index.ts
@@ -1,11 +1,10 @@
 export { GrammarError } from './grammar-error.js';
+export { CATEGORIES } from './categories.js';
+export type { ChangesetCategory } from './categories.js';
 export { filterChangesets } from './filter-changesets.js';
 export {
   restoreResidualChangesets,
   type RestoreOptions,
 } from './restore-residual-changesets.js';
 export { parseChangesetSummary } from './parse-changeset-summary.js';
-export type {
-  ChangesetCategory,
-  ParsedEntry,
-} from './parse-changeset-summary.js';
+export type { ParsedEntry } from './parse-changeset-summary.js';
diff --git a/packages/changesets-utils/src/parse-changeset-summary.test.ts b/packages/changesets-utils/src/parse-changeset-summary.test.ts
index d674c9e..cfa374d 100644
--- a/packages/changesets-utils/src/parse-changeset-summary.test.ts
+++ b/packages/changesets-utils/src/parse-changeset-summary.test.ts
@@ -86,7 +86,7 @@ describe('parseChangesetSummary', () => {
         'The summary must start with a level-two category heading.',
         1,
         'missing-heading',
-        'Start with a level-two heading such as `## Added`, `## Changed`, `## Removed`, `## Fixed`, `## Security`, or `## Deprecated`.',
+        'Start with a level-two heading such as `## Added`, `## Changed`, `## Deprecated`, `## Removed`, `## Fixed`, or `## Security`.',
       ),
     ],
     [
@@ -96,7 +96,7 @@ describe('parseChangesetSummary', () => {
         'The category heading must name a supported category.',
         1,
         'unknown-category',
-        'Use `Added`, `Changed`, `Removed`, `Fixed`, `Security`, or `Deprecated` as the category.',
+        'Use `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, or `Security` as the category.',
       ),
     ],
     [
@@ -106,7 +106,7 @@ describe('parseChangesetSummary', () => {
         'The category heading must name a supported category.',
         1,
         'unknown-category',
-        'Use `Added`, `Changed`, `Removed`, `Fixed`, `Security`, or `Deprecated` as the category.',
+        'Use `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, or `Security` as the category.',
       ),
     ],
     [
diff --git a/packages/changesets-utils/src/parse-changeset-summary.ts b/packages/changesets-utils/src/parse-changeset-summary.ts
index 8e62f82..c346aff 100644
--- a/packages/changesets-utils/src/parse-changeset-summary.ts
+++ b/packages/changesets-utils/src/parse-changeset-summary.ts
@@ -1,16 +1,7 @@
+import { CATEGORIES } from './categories.js';
+import type { ChangesetCategory } from './categories.js';
 import { GrammarError } from './grammar-error.js';
 
-const CATEGORIES = [
-  'Added',
-  'Changed',
-  'Removed',
-  'Fixed',
-  'Security',
-  'Deprecated',
-] as const;
-
-export type ChangesetCategory = (typeof CATEGORIES)[number];
-
 export type ParsedEntry = {
   category: ChangesetCategory;
   description: string;
diff --git a/yarn.lock b/yarn.lock
index 6d4dfa0..a3749d7 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1254,6 +1254,8 @@ __metadata:
   dependencies:
     "@changesets/types": "npm:^7.0.0"
     "@metamask/auto-changelog": "npm:^6.1.0"
+    "@metamask/changesets-utils": "npm:^0.0.0"
+    "@metamask/utils": "npm:^11.12.0"
     "@types/node": "npm:^22.13.14"
     "@typescript/native": "npm:typescript@^7.0.2"
     "@vitest/coverage-istanbul": "npm:^5.0.1"
@@ -1266,7 +1268,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@metamask/changesets-utils@workspace:packages/changesets-utils":
+"@metamask/changesets-utils@npm:^0.0.0, @metamask/changesets-utils@workspace:packages/changesets-utils":
   version: 0.0.0-use.local
   resolution: "@metamask/changesets-utils@workspace:packages/changesets-utils"
   dependencies: