ci: Add action to validate changelog diffs after merging (#7525)

## Explanation

This fixes an issue in changelogs where changelog entries may be
incorrectly moved after merging into the main branch. Given the
following (partial) changelog for example:

```md
## [Unreleased]

### Changed

- Changelog entry A ([#1234](...))
- Changelog entry B ([#5678](...))
- Changelog entry C ([#1337](...))
```

After a release, this changelog may look like this:

```diff
  ## [Unreleased]

+ ## [1.0.0]

  ### Changed

  - Changelog entry A ([#1234](...))
  - Changelog entry B ([#5678](...))
  - Changelog entry C ([#1337](...))
```

But if another PR based on the original changelog also adds an entry to
the unreleased section like this:

```diff
  ## [Unreleased]

  ### Changed

  - Changelog entry A ([#1234](...))
  - Changelog entry B ([#5678](...))
  - Changelog entry C ([#1337](...))
+ - Changelog entry D ([#0000](...))
```

The final changelog will look like this, since Git can merge the entry
based on the other entries around it:

```md
## [Unreleased]

## [1.0.0]

### Changed

- Changelog entry A ([#1234](...))
- Changelog entry B ([#5678](...))
- Changelog entry C ([#1337](...))
- Changelog entry D ([#0000](...))
```

Here it appears that the release included "entry D", but in reality that
was meant to be under the unreleased section.

To address this issue, I've added a simple workflow that checks for
changelog diffs. It uses a minimal algorithm to parse the markdown
files, find entries that are included in unreleased originally, and
checks if they still are after merging. If not, the workflow will fail
and show an error such as this:

> Checking changelog file: packages/some-package/CHANGELOG.md
> The following lines added in the PR are missing from the "Unreleased"
section after merge:
>
>    - Changelog entry D ([#0000](...))
>
> Please update your pull request and ensure that new changelog entries
remain in the "Unreleased" section.

Long term we should solve this problem by using changesets instead, in
which case the unreleased changes will never be merged or conflict with
each other, but until we figure out how to implement those in our
release workflows, we can use this workflow.

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk CI-only change that adds a new workflow gate; main failure
mode is false positives/negatives that could block merges.
> 
> **Overview**
> Adds a new composite GitHub Action (`check-merge-queue-changelogs`)
and Node script to detect when changelog lines introduced in a PR get
moved out of the `## [Unreleased]` section after merge (a common
merge-queue conflict artifact).
> 
> Updates `lint-build-test.yml` to run a new `validate-changelog-diffs`
job on `pull_request` and `merge_group` events, failing the workflow
when modified `CHANGELOG.md` files lose newly-added Unreleased entries
in the merged result.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
ef5a189. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Mrtenz

.github/actions/check-merge-queue-changelogs/action.yml

@@ -0,0 +1,98 @@
+name: Check merge queue changelogs
+description: Check if the changelog was incorrectly merged in a merge queue
+  pull request.
+
+inputs:
+  github-token:
+    description: The GitHub token to use for authentication.
+    required: false
+    default: ${{ github.token }}
+
+runs:
+  using: composite
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+      with:
+        fetch-depth: 0
+
+    - name: Get pull request number
+      id: pr-number
+      uses: actions/github-script@v8
+      env:
+        HEAD_REF: ${{ github.event.pull_request.head.ref || github.event.merge_group.head_ref }}
+      with:
+        github-token: ${{ inputs.github-token }}
+        script: |
+          const { HEAD_REF } = process.env;
+
+          if (context.eventName === 'pull_request') {
+            const prNumber = context.payload.pull_request.number;
+            return core.setOutput('pr-number', prNumber);
+          }
+
+          const match = HEAD_REF.match(/\/pr-([0-9]+)-/u);
+          if (!match) {
+            return core.setFailed(`Could not extract pull request number from head ref: "${HEAD_REF}".`);
+          }
+
+          const number = parseInt(match[1], 10);
+          core.setOutput('pr-number', number);
+
+    - name: Get pull request branch
+      id: pr-branch
+      shell: bash
+      env:
+        REPOSITORY: ${{ github.repository }}
+        PR_NUMBER: ${{ steps.pr-number.outputs.pr-number }}
+        GH_TOKEN: ${{ inputs.github-token }}
+      run: |
+        BRANCH=$(gh api "/repos/${REPOSITORY}/pulls/${PR_NUMBER}" --jq=.head.ref)
+        echo "pr-branch=$BRANCH" >> "$GITHUB_OUTPUT"
+
+    - name: Check changelog changes
+      id: changelog-check
+      shell: bash
+      env:
+        BASE_REF: ${{ github.event.pull_request.base.ref || github.event.merge_group.base_ref }}
+        PR_BRANCH: ${{ steps.pr-branch.outputs.pr-branch }}
+        ACTION_PATH: ${{ github.action_path }}
+      run: |
+        set -euo pipefail
+
+        # Strip invalid prefix from `BASE_REF`
+        # It comes prefixed with `refs/heads/`, but the branch is not checked out in this context
+        # We need to express it as a remote branch
+        PREFIXED_REF_REGEX='refs/heads/(.+)'
+        if [[ "$BASE_REF" =~ $PREFIXED_REF_REGEX ]]; then
+          BASE_REF="${BASH_REMATCH[1]}"
+        fi
+
+        TARGET_REF=$(git merge-base "origin/$BASE_REF" "origin/$PR_BRANCH")
+        git fetch origin "$TARGET_REF"
+
+        UPDATED_CHANGELOGS=$(git diff --name-only "$TARGET_REF" "origin/$PR_BRANCH" | grep -E 'CHANGELOG\.md$' || true)
+        if [ -n "$UPDATED_CHANGELOGS" ]; then
+          for FILE in $UPDATED_CHANGELOGS; do
+            if [ ! -f "$FILE" ]; then
+              echo "Changelog file \"$FILE\" was deleted in this PR. Skipping."
+              continue
+            fi
+
+            if ! git cat-file -e "$TARGET_REF":"$FILE" 2>/dev/null; then
+              echo "Changelog file \"$FILE\" is new in this PR. Skipping."
+              continue
+            fi
+
+            echo "Checking changelog file: $FILE"
+            git show "$TARGET_REF":"$FILE" > /tmp/base-changelog.md
+            git show origin/"$PR_BRANCH":"$FILE" > /tmp/pr-changelog.md
+
+            node "${ACTION_PATH}/check-changelog-diff.cjs" \
+              /tmp/base-changelog.md \
+              /tmp/pr-changelog.md \
+              "$FILE"
+          done
+        else
+          echo "No CHANGELOG.md files were modified in this PR."
+        fi

.github/actions/check-merge-queue-changelogs/check-changelog-diff.cjs

@@ -0,0 +1,101 @@
+// This script checks that any new changelog entries added in a PR
+// remain in the [Unreleased] section after the PR is merged.
+
+const fs = require('fs');
+
+if (process.argv.length < 5) {
+  console.error(
+    'Usage: node check-changelog-diff.cjs <base-file> <pr-file> <merged-file>',
+  );
+
+  // eslint-disable-next-line n/no-process-exit
+  process.exit(1);
+}
+
+/* eslint-disable n/no-sync */
+// The type of these is inferred as `Buffer` when using "utf-8" directly instead
+// of an options object. Even though it's a plain JavaScript file, it's nice to
+// keep the types correct.
+const baseContent = fs.readFileSync(process.argv[2], {
+  encoding: 'utf-8',
+});
+
+const prContent = fs.readFileSync(process.argv[3], {
+  encoding: 'utf-8',
+});
+
+const mergedContent = fs.readFileSync(process.argv[4], {
+  encoding: 'utf-8',
+});
+/* eslint-enable n/no-sync */
+
+/**
+ * Extract the "[Unreleased]" section from the changelog content.
+ *
+ * This doesn't actually parse the Markdown, it just looks for the section
+ * header and collects lines until the next section header.
+ *
+ * @param {string} content - The changelog content.
+ * @returns {Set<string>} The lines in the "[Unreleased]" section as a
+ * {@link Set}.
+ */
+function getUnreleasedSection(content) {
+  const lines = content.split('\n');
+
+  let inUnreleased = false;
+  const sectionLines = new Set();
+
+  for (const line of lines) {
+    // Find unreleased header.
+    if (line.trim().match(/^##\s+\[Unreleased\]/u)) {
+      inUnreleased = true;
+      continue;
+    }
+
+    // Stop if we hit the next version header (## [x.x.x]).
+    if (inUnreleased && line.trim().match(/^##\s+\[/u)) {
+      break;
+    }
+
+    // If inside the unreleased header, add lines to the set.
+    if (inUnreleased) {
+      sectionLines.add(line.trim());
+    }
+  }
+
+  return sectionLines;
+}
+
+/**
+ * Get the lines that were added in the PR content compared to the base content.
+ *
+ * @param {Set<string>} oldLines - The base changelog content.
+ * @param {Set<string>} newLines - The PR changelog content.
+ * @returns {string[]} The added lines as an array of strings.
+ */
+function getAddedLines(oldLines, newLines) {
+  return Array.from(newLines).filter(
+    (line) => line.length > 0 && !oldLines.has(line) && !line.startsWith('#'),
+  );
+}
+
+const mergedUnreleased = getUnreleasedSection(mergedContent);
+const addedLines = getAddedLines(
+  getUnreleasedSection(baseContent),
+  getUnreleasedSection(prContent),
+);
+
+const missingLines = [];
+for (const line of addedLines) {
+  if (!mergedUnreleased.has(line)) {
+    missingLines.push(line);
+  }
+}
+
+if (missingLines.length > 0) {
+  console.error(
+    `The following lines added in the PR are missing from the "Unreleased" section after merge:\n\n  ${missingLines.join('\n  ')}\n\nPlease update your pull request and ensure that new changelog entries remain in the "Unreleased" section.`,
+  );
+
+  process.exitCode = 1;
+}

.github/workflows/lint-build-test.yml

@@ -70,6 +70,16 @@ jobs:
             exit 1
           fi
 
+  validate-changelog-diffs:
+    name: Validate changelog diffs
+    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Validate changelog diffs
+        uses: ./.github/actions/check-merge-queue-changelogs
+
   build:
     name: Build
     runs-on: ubuntu-latest