Skip to content
This repository was archived by the owner on Oct 22, 2026. It is now read-only.

feat: add automated dependency bump checker and changelog validator - #267

Merged
cryptodev-2s merged 46 commits into
mainfrom
feat/add-dependency-bump-checker
Apr 13, 2026
Merged

cryptodev-2s merged 46 commits into
mainfrom
feat/add-dependency-bump-checker

Conversation

@cryptodev-2s

@cryptodev-2s cryptodev-2s commented Dec 5, 2025 •

Copy link
Copy Markdown
Contributor

Summary

Adds --checkDeps flag to validate command to detect missing dependency bump entries in changelogs.

  • Compares dependencies and peerDependencies in package.json between git refs using git show JSON comparison (ignores devDependencies)
  • Validates changelog contains matching entries with correct versions
  • With --fix --currentPr <number>, automatically adds or updates missing entries
  • Tracks PR numbers across multiple commits via git log
  • Peer dependency bumps get a **BREAKING:** prefix
  • Detects Bump, Update, and Upgrade forms when parsing existing entries

API changes

  • Changelog.addChange() accepts optional dependencyBump for structured bump metadata
  • Changelog.updateChange() method for modifying existing entries (union-typed options like addChange)
  • parsePossibleDependencyBumpDescription() recognizes Bump/Update/Upgrade patterns for round-trip fidelity
  • MissingDependencyEntriesError carries the parsed Changelog instance and currentVersion for reuse by fix handlers
  • validateChangelog split into focused helpers: validateReleaseCandidateState, validatePrLinks, validateDependencyBumps, validateFormatting, validateNonEmptyReleases
  • Exports: getDependencyChanges, BaseRefNotFoundError, DependencyCheckResult, DependencyBump, MissingDependencyEntriesError

File structure

  • src/validate-command/ — groups CLI validation logic (validate.ts, cli-utils.ts, index.ts)
  • src/find-dependency-bump-changelog-entry.ts — finds existing dep bump entries in parsed changelog
  • src/update-changelog-with-dependency-bumps.ts — adds/updates dep bump entries
  • src/get-dependency-changes.ts — compares package.json across git refs

CLI options

  • --checkDeps — enable dependency bump validation
  • --fromRef <ref> — starting git ref (auto-detects from merge-base if omitted)
  • --toRef <ref> — ending git ref (defaults to HEAD)
  • --remote <name> — remote for base branch auto-detection (defaults to origin)
  • --baseBranch <ref> — base branch ref (defaults to <remote>/main)
  • --currentPr <number> — PR number for changelog entries (required with --fix)

Usage

# Validate
yarn auto-changelog validate --checkDeps

# Fix missing entries
yarn auto-changelog validate --checkDeps --fix --currentPr 1234

Testing in MetaMask/core

# Build auto-changelog
cd /path/to/auto-changelog && yarn build

# In core's root package.json, add resolution to local auto-changelog:
# "resolutions": {
#   "@metamask/auto-changelog": "file:/path/to/auto-changelog"
# }

# From core
cd /path/to/core
yarn install --force
git checkout -b test-dep-bumps

# In one or more packages, modify package.json to:
# - Bump some dependencies
# - Bump some peerDependencies
# - Bump some devDependencies (to verify they're correctly excluded)
# - Change the package version (to test release detection)

git add . && git commit -m "Test: bump dependencies"

# Validate (auto-detects fromRef)
yarn changelog:validate --checkDeps

# Validate with explicit ref
yarn changelog:validate --checkDeps --fromRef origin/main

# Fix with PR number
yarn changelog:validate --checkDeps --fix --currentPr 4532

Note

Medium Risk
Moderate risk because it expands CLI validation behavior, adds git-based ref auto-detection, and introduces new changelog mutation paths (--fix) that could affect CI outcomes and changelog contents if edge cases are missed.

Overview
Adds a new validate --checkDeps mode that compares dependencies/peerDependencies in package.json between git refs (auto-detecting a merge-base when possible) and validates that matching dependency-bump entries exist in the appropriate changelog section.

When --fix --currentPr is provided, missing or stale dependency bump entries are automatically added/updated (including PR number merging and **BREAKING:** handling for peer dependency bumps) via new helper modules and a new Changelog.updateChange() API.

Refactors validation CLI wiring by moving validate logic into src/validate-command/, adds a small fs wrapper, teaches parseChangelog to recognize Bump/Update/Upgrade dependency bump formats, exports new dependency-checking APIs/errors from index.ts, and updates docs/tests/coverage thresholds accordingly.

Reviewed by Cursor Bugbot for commit 9c0acc9. Bugbot is set up for automated code reviews on this repo. Configure here.

@cryptodev-2s
cryptodev-2s marked this pull request as draft December 5, 2025 16:26
@cryptodev-2s
cryptodev-2s force-pushed the feat/add-dependency-bump-checker branch from a6b2b18 to cd10640 Compare December 5, 2025 16:27
@cryptodev-2s
cryptodev-2s force-pushed the feat/add-dependency-bump-checker branch 14 times, most recently from 16089f8 to 3d0c830 Compare December 5, 2025 21:26
- Rename defaultBranch to baseBranch (more accurate terminology)
- Add --remote option (default: 'origin') for customizing remote name
- Default base branch is now ${remote}/main instead of local 'main'
- Remove misleading fallback logic in getMergeBase that could give wrong results
- Rename getGitDiff to getManifestGitDiff for clarity
- Remove unnecessary try/catch in getManifestGitDiff (git diff returns 0 for no changes)
@cryptodev-2s
cryptodev-2s force-pushed the feat/add-dependency-bump-checker branch from 63df851 to 5804a00 Compare December 10, 2025 16:36
@cryptodev-2s

Copy link
Copy Markdown
Contributor Author

@metamaskbot publish-preview

@github-actions

Copy link
Copy Markdown
Contributor

A preview build for this branch has been published.

You can configure your project to use the preview build with this identifier:

npm:@metamask-previews/auto-changelog@5.3.0-preview-5804a00

See these instructions for more information about preview builds.

@cryptodev-2s
cryptodev-2s marked this pull request as ready for review December 17, 2025 17:12
@cryptodev-2s
cryptodev-2s requested a review from a team as a code owner December 17, 2025 17:12
…angelog validation

- Integrate dependency checking into validate command with --checkDeps flag
- Add new CLI options: --fromRef, --toRef, --remote, --baseBranch, --currentPr
- Auto-detect git reference from merge-base when --fromRef not provided
- Validate dependency/peerDependency bumps with exact version matching
- Auto-fix missing entries with --fix flag (requires --currentPr)
- Support renamed packages via existing --tagPrefixBeforePackageRename option
- Add comprehensive unit tests for parseDependencyDiff and getDependencyChangesForPackage
- Add unit tests for updateChangelogWithDependencies
- Add dependency validation tests for validateChangelog
- Refactor parseDependencyDiff to be internal (not exported)
- Update CHANGELOG.md with new feature documentation
@cryptodev-2s
cryptodev-2s force-pushed the feat/add-dependency-bump-checker branch from 2e6df05 to 57a884e Compare December 17, 2025 17:14
Comment thread src/cli.ts Resolved
- Rename DiffParseResult to DependencyCheckResult
- Pass dependencyResult object directly to validateChangelog
- Fix validation to check correct changelog section (Unreleased vs version)
Comment thread src/dependency-changelog.ts Resolved
validateChangelog already parses the changelog, so include the parsed
Changelog instance on the error. updateChangelogWithDependencyBumps
now accepts an optional pre-parsed changelog to skip re-reading and
re-parsing the file.
Extract validateReleaseCandidateState, validatePrLinks,
validateDependencyBumps, validateFormatting, and
validateNonEmptyReleases from the monolithic validateChangelog.
Move validate-command.ts, cli-utils.ts, and the test into
src/validate-command/ with an index.ts barrel. validate-changelog.ts
stays at src/ since it's part of the public API.
parsePossibleDependencyBumpDescription now recognizes:
- Update `dep` from `old` to `new`
- Upgrade `dep` from `old` to `new`
- Bump/Update/Upgrade `dep` to `new` (no "from")

in addition to the existing Bump `dep` from `old` to `new` pattern.
Remove the fs mock — tests now write real changelog files to a temp
directory. getDependencyChanges is still mocked since it needs git.
- Use discriminated union for UpdateChangeOptions (mirrors AddChangeOptions)
- Update description and dependencyBump together consistently
- Improve error messages to be more descriptive
getDependencyChanges now throws a specific BaseRefNotFoundError
when the base ref can't be auto-detected, instead of returning null.
Callers catch the error for a clearer control flow.
Use addToStart: false so auto-added dependency bump entries
appear below manually written entries, not above them.
Comment thread src/changelog.ts Resolved
- Fix no-shadow violations by renaming catch params and function params
- Fix prettier formatting issues
- Fix JSDoc descriptions and @returns/@PARAM tags in test helpers
- Move beforeEach/afterEach hooks inside describe block
- Add error message to toThrow() assertion
- Fix import ordering
@cryptodev-2s

Copy link
Copy Markdown
Contributor Author

@metamaskbot publish-preview

@github-actions

github-actions Bot commented Apr 5, 2026

Copy link
Copy Markdown
Contributor

A preview build for this branch has been published.

You can configure your project to use the preview build with this identifier:

npm:@metamask-previews/auto-changelog@5.3.2-preview-e9fdf39

See these instructions for more information about preview builds.

Comment thread src/validate-changelog.ts
`Dependency \`${depChange.dependency}\` has a changelog entry but ${expected} is expected`,
);
}
missingEntries.push(depChange);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrong-breaking check misleads when stale correct entry exists

Low Severity

In validateDependencyBumps, when findDependencyBumpChangelogEntry finds a stale-version match with the correct isBreaking status (result.existingEntry is set but hasExactMatch is false), the code still runs the wrong-breaking check. If a second entry for the same dependency also exists with the opposite breaking status, the code throws InvalidChangelogError about wrong BREAKING prefix — even though a correct-breaking entry exists and just needs a version update. This prevents the fix handler from updating the stale entry. The wrong-breaking search at the point where result.existingEntry is already populated is too aggressive.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit c2d2ddf. Configure here.

@mcmire mcmire Apr 6, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't make sense. If we find a changelog entry for the dependency change, and the "BREAKING" status is correct but the version is not, then it should not hit the logic between lines 352 and 357.

We probably should have a separate check for whether the version is correct or not. Or, we could change the existing error message so it says something like:

Expected to find changelog entry: 'Bump `@metamask/accounts-controller` from ^1.0.0 to ^1.1.0' but found 'Bump `@metamask/accounts-controller` from ^1.0.0 to ^1.3.0'

In other words, we handle any kind of differences, not just those where "BREAKING" was specified when it was not supposed to be or vice versa.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch — fixed in f937c9c. The wrong-breaking check now only runs when no correct-breaking entry exists at all, so stale entries get updated instead of erroring.

Comment thread src/validate-command/validate.ts Resolved

@mcmire mcmire left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One last Cursor comment we might want to address.

Only check for wrong isBreaking status when no entry with the correct
breaking status exists at all. Previously, a stale-version match with
the correct breaking status would still trigger the wrong-breaking
error if a second entry with the opposite status also existed.
The message now says "Fixed N entry/entries (added or updated)"
instead of always saying "Added N missing entries".
@cryptodev-2s
cryptodev-2s requested a review from mcmire April 6, 2026 18:27
@cryptodev-2s
cryptodev-2s enabled auto-merge (squash) April 6, 2026 18:31
@cryptodev-2s

Copy link
Copy Markdown
Contributor Author

@metamaskbot publish-preview

@github-actions

github-actions Bot commented Apr 6, 2026

Copy link
Copy Markdown
Contributor

A preview build for this branch has been published.

You can configure your project to use the preview build with this identifier:

npm:@metamask-previews/auto-changelog@5.3.2-preview-9c0acc9

See these instructions for more information about preview builds.

@cryptodev-2s

Copy link
Copy Markdown
Contributor Author

@cursor review

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 5 total unresolved issues (including 4 from previous reviews).

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 9c0acc9. Configure here.

entryIndex: entryCheck.entryIndex,
dependencyBump: {
...bump,
oldVersion: existingOldVersion ?? bump.oldVersion,

@cursor cursor Bot Apr 7, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nullish coalescing preserves empty string as oldVersion

Medium Severity

When parsePossibleDependencyBumpDescription parses a short-form entry like "Update dep to 1.5.0" (no "from" clause), it sets oldVersion: ''. Later in updateChangelogWithDependencyBumps, the expression existingOldVersion ?? bump.oldVersion uses nullish coalescing (??), which only falls back for null/undefined — not for empty string. So '' ?? bump.oldVersion evaluates to '', and formatDependencyBumpDescription then produces the malformed output Bump `dep` from `` to `2.0.0` with empty backticks. The ?? operator here needs to be || (or an explicit empty-string check) to properly fall back when existingOldVersion is ''.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 9c0acc9. Configure here.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes this is unhandled, but considering how rare this is, it's okay. We will deal with this bug when it comes.

@mcmire mcmire left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

@cryptodev-2s
cryptodev-2s merged commit 738b3a5 into main Apr 13, 2026
26 checks passed
@cryptodev-2s
cryptodev-2s deleted the feat/add-dependency-bump-checker branch April 13, 2026 13:28
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants