feat: add pnpm peers check command by zkochan · Pull Request #11061 · pnpm/pnpm

zkochan · 2026-03-22T13:04:12Z

Summary

Adds a pnpm peers check command that detects unmet, missing, and conflicting peer dependency issues by reading the lockfile. No full resolution needed — it walks the lockfile directly using @pnpm/lockfile.walker.

New package @pnpm/deps.inspection.peers-checker — lockfile-based peer dependency checker
New command pnpm peers check (also runs as default for pnpm peers)
Runs workspace-wide by default (uses recursiveByDefault)
Respects peerDependencyRules (ignoreMissing, allowAny, allowedVersions with parent-scoped selectors)
Supports --json for CI/automation
Supports --lockfile-only to skip reading node_modules
Exits with non-zero exit code when issues are found
Unknown subcommands show help with exit code 1

Example output

Issues with peer dependencies found

✕ unmet peer react
  Installed: 18.3.1
  Wanted:
    "^0.14.0 || ^15.0.0 || ^16.0.0":
      redbox-react@1.6.0
      draft-js@0.10.5
      react-highcharts@16.1.0
    ^15.6.1:
      medium-draft@0.5.18
      react-input-calendar@0.5.4
    ^16.0.0:
      react-hot-loader@4.13.1
      react-responsive-tabs@4.4.3

✕ missing peer ajv
  Wanted:
    ^6.9.1:
      ajv-keywords@3.4.1

Closes #7087

Test plan

Unit tests for checkPeerDependencies function (6 tests, all passing)
Verified CLI output manually with unmet peers, missing peers, conflicts, and no-issues scenarios
Verified --json output format
Verified --help shows the new command
CI passes

🤖 Generated with Claude Code

Copilot

Pull request overview

This PR introduces a new pnpm peers command (defaulting to pnpm peers check) to detect unmet/missing peer dependency issues by analyzing existing lockfile data (without forcing a full resolution), with support for --json and --recursive.

Changes:

Registers a new peers inspection command in the pnpm CLI and adds a peers check subcommand implementation.
Adds a new @pnpm/deps.inspection.peers-checker package that reads lockfiles and reports peer dependency issues, with unit tests + fixtures.
Wires new workspace dependencies (including render-peer-issues) and adds a Changeset entry for release notes.

Reviewed changes

Copilot reviewed 14 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pnpm/src/cmd/index.ts	Registers the new `peers` command in the pnpm CLI command list.
deps/inspection/commands/src/peers.ts	Implements `pnpm peers check` (human + JSON output, recursive support).
deps/inspection/commands/src/index.ts	Exports the new `peers` command namespace from inspection commands.
deps/inspection/commands/package.json	Adds dependencies required for the new command (`peers-checker`, `render-peer-issues`).
deps/inspection/commands/tsconfig.json	Adds TS project references for new dependencies used by the command.
deps/inspection/peers-checker/src/checkPeerDependencies.ts	Core lockfile-walking and peer issue detection/filtering logic.
deps/inspection/peers-checker/src/index.ts	Public entrypoint export for the peers-checker package.
deps/inspection/peers-checker/package.json	New package metadata/scripts/deps for peers-checker.
deps/inspection/peers-checker/tsconfig*.json	New TS configs for building/linting the peers-checker package.
deps/inspection/peers-checker/test/checkPeerDependencies.test.ts	Unit tests for peer issue detection + rule filtering basics.
deps/inspection/peers-checker/test/fixtures/**	Fixture lockfiles/manifests for test scenarios (unmet/missing/etc.).
pnpm-lock.yaml	Adds workspace links for the new package and new internal dependencies.
.changeset/list-check-peers.md	Declares minor bumps and release note for `pnpm peers check`.

Files not reviewed (3)

deps/inspection/peers-checker/test/fixtures/with-missing-peer/pnpm-lock.yaml: Language not supported
deps/inspection/peers-checker/test/fixtures/with-unmet-peers/pnpm-lock.yaml: Language not supported
pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Adds a `--check-peers` flag to `pnpm list` that detects unmet and missing peer dependency issues by reading the lockfile. This allows users to check for peer dependency problems without triggering a full resolution, which is especially useful in CI or after pulling a lockfile from another developer. Closes #7087 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Introduces `pnpm peers check` as a standalone subcommand instead of a flag on `pnpm list`. The command checks for unmet and missing peer dependency issues by reading the lockfile and exits with a non-zero exit code when issues are found. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Running `pnpm peers` without a subcommand now defaults to `check`. Unknown subcommands show help and exit with a non-zero exit code. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ers-checker Move peer dependency checking logic from @pnpm/deps.inspection.list into a dedicated @pnpm/deps.inspection.peers-checker package. This better separates concerns — the list package is for listing dependencies, not checking peer issues. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

These fixtures belong in the peers-checker package now. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Use semver-range-intersect for proper intersection/conflict detection instead of picking the first range for missing peers - Remove silent error swallowing in parseOverrides — invalid peerDependencyRules.allowedVersions now surfaces the error - Support parent-scoped allowedVersions selectors (e.g. parent>peer) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Also add recursiveByDefault to list, ll, and why commands. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 14 out of 17 changed files in this pull request and generated 4 comments.

Files not reviewed (3)

deps/inspection/peers-checker/test/fixtures/with-missing-peer/pnpm-lock.yaml: Language not supported
deps/inspection/peers-checker/test/fixtures/with-unmet-peers/pnpm-lock.yaml: Language not supported
pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- Check only the declaring parent (last in parents chain) for parent-scoped allowedVersions, matching install-time behavior - Wrap parseOverrides errors with INVALID_ALLOWED_VERSION_SELECTOR code and mention pnpm.peerDependencyRules.allowedVersions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Show peer issues grouped by the peer dependency (like pnpm why) instead of grouped by the depending package. This makes it easier to see at a glance which peers need attention and all the packages requesting them. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Build a proper nested tree from parent chains instead of flat strings, so shared prefixes are merged and each package appears only once. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Each peer dependency gets its own top-level tree separated by blank lines, similar to how pnpm why groups results by searched package. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace tree rendering with a simple flat list grouped by peer name. Each peer issue shows a header line and a "Required by:" line listing the parent chains. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

For readability, each package requiring the peer gets its own indented line. Transitive chains show the declaring package with a "(via ...)" note indicating the direct dependency that pulls it in. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Each requester line now shows the specific range it wants, which is more useful than showing the transitive dependency chain. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Packages requiring the same range are listed together on one line, making it easy to see which groups of packages share a requirement. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Blank lines between peer groups - Each package on its own indented line - When all packages want the same range, skip the "Wants" label - When multiple ranges exist, group under "Wants <range>:" headers Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Peer name bold white, issue type yellow/red (already there) - Range headers in cyan - Package names dimmed to keep focus on the peer and range Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Missing peers with incompatible ranges (conflicts) are now shown as "✕ conflicting peer" with the per-range grouping making the conflict visible. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

When all packages want the same range, include it in the header line (e.g. "✕ missing peer ajv@^6.9.1") instead of only listing packages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Always use the "Wants <range>:" format with indented packages, regardless of how many range groups there are. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Use "Installed: <version>" as a parallel label to "Wants <range>:" for better readability of unmet peer issues. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Group all ranges under a single "Wanted:" label, with each range on its own line and packages indented below it. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace the custom walkDependency function with the existing lockfileWalkerGroupImporterSteps from @pnpm/lockfile.walker, which already handles dep resolution, visited tracking, and link handling. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

jonboulle · 2026-03-26T15:53:07Z

Just wondering if there's any chance this would make it into a 10.x release? or is it only targeted for 11? thanks :)

zkochan changed the title ~~feat: add --check-peers flag to pnpm list~~ feat: add pnpm peers check command Mar 22, 2026

zkochan marked this pull request as ready for review March 22, 2026 13:57

Copilot AI review requested due to automatic review settings March 22, 2026 13:57

Copilot started reviewing on behalf of zkochan March 22, 2026 13:58 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

Comment thread deps/inspection/peers-checker/src/checkPeerDependencies.ts Outdated

Comment thread deps/inspection/peers-checker/src/checkPeerDependencies.ts Outdated

Comment thread deps/inspection/peers-checker/src/checkPeerDependencies.ts Outdated

zkochan force-pushed the feat/list-check-peers branch 2 times, most recently from e77eb73 to e95948f Compare March 22, 2026 14:44

zkochan and others added 9 commits March 22, 2026 16:05

fix: sort package.json and tsconfig.json entries alphabetically

d49f992

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: make check the default subcommand for pnpm peers

5b5cdb6

Running `pnpm peers` without a subcommand now defaults to `check`. Unknown subcommands show help and exit with a non-zero exit code. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: add missing test-fixtures reference to peers-checker tsconfig

e1ba76e

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: remove peer-related fixtures from list package

0a9aeea

These fixtures belong in the peers-checker package now. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

refactor: rename workspaceWideByDefault to recursiveByDefault

f23596e

Also add recursiveByDefault to list, ll, and why commands. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zkochan mentioned this pull request Mar 22, 2026

pnpm does not warn about issues with peer dependencies if the lockfile is up to date #7087

Closed

4 tasks

zkochan force-pushed the feat/list-check-peers branch from e95948f to f23596e Compare March 22, 2026 15:05

zkochan added this to the v11.0 milestone Mar 22, 2026

zkochan requested a review from Copilot March 22, 2026 15:14

Copilot started reviewing on behalf of zkochan March 22, 2026 15:14 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

zkochan and others added 8 commits March 22, 2026 18:32

fix: merge shared parent chains in peer issues tree

d2d72c4

Build a proper nested tree from parent chains instead of flat strings, so shared prefixes are merged and each package appears only once. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: group peer issues output by peer name

9a8c6e2

Each peer dependency gets its own top-level tree separated by blank lines, similar to how pnpm why groups results by searched package. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

refactor: use flat list output for peer issues

dfd68b1

Replace tree rendering with a simple flat list grouped by peer name. Each peer issue shows a header line and a "Required by:" line listing the parent chains. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: show per-package wanted range instead of transitive chain info

a2302f1

Each requester line now shows the specific range it wants, which is more useful than showing the transitive dependency chain. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: group peer issue requesters by wanted range

d9e0329

Packages requiring the same range are listed together on one line, making it easy to see which groups of packages share a requirement. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zkochan and others added 7 commits March 22, 2026 19:00

fix: add colors to peer issues output

595208d

- Peer name bold white, issue type yellow/red (already there) - Range headers in cyan - Package names dimmed to keep focus on the peer and range Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: display conflicting peer dependencies

edb3b08

Missing peers with incompatible ranges (conflicts) are now shown as "✕ conflicting peer" with the per-range grouping making the conflict visible. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: show wanted range in header for single-range peer issues

d873917

When all packages want the same range, include it in the header line (e.g. "✕ missing peer ajv@^6.9.1") instead of only listing packages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: use consistent Wants format for all peer issues

15a95d7

Always use the "Wants <range>:" format with indented packages, regardless of how many range groups there are. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: show installed version on its own labeled line

77c07c7

Use "Installed: <version>" as a parallel label to "Wants <range>:" for better readability of unmet peer issues. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: use single Wanted label with nested ranges and packages

58e07ae

Group all ranges under a single "Wanted:" label, with each range on its own line and packages indented below it. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

zkochan force-pushed the feat/list-check-peers branch from 950d716 to 58e07ae Compare March 23, 2026 00:36

zkochan and others added 5 commits March 23, 2026 01:40

fix: add lockfile.walker tsconfig reference

d95d0d4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: remove --recursive from peers help since it's the default

a22cdce

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: add README for peers-checker package

fb1ba5b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore: commit tsconfig.json

582b2b1

zkochan merged commit 263a8bc into main Mar 23, 2026
12 checks passed

zkochan deleted the feat/list-check-peers branch March 23, 2026 09:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add pnpm peers check command#11061

feat: add pnpm peers check command#11061
zkochan merged 29 commits into
mainfrom
feat/list-check-peers

zkochan commented Mar 22, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jonboulle commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

zkochan commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Example output

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jonboulle commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zkochan commented Mar 22, 2026 •

edited

Loading