deps-upgrade

依存関係のアップグレード検証

アップグレード自体は簡単です。プロジェクト全体の整合性が保たれていることを証明するのが本番です。 このスキルは、バージョンを選択した後、通常は bun update -i -r または同等の対話的な選択を行った後に引き継ぎ、実際に反映された内容を検証します。git による実際の差分、peer と engine の整合性、更新でまたいだすべてのバージョンにおける破壊的変更と移行、新たに採用する価値のある機能、そしてプロジェクトについて読むだけでなく実際に動かす検証ゲートを確認します。また、保留中のパッケージをアップグレードできるか、そもそも package.json に記載されている理由は何か、という逆方向の問いにも答えます。

bun 1.3.14、npm 11.19.0、pnpm 11.21.0、yarn 4.18.0（2026-08-15、references/package-managers.md のコマンドマトリックス）および gh v2.103.2（2026-10-27、gh release／gh api による読み取り。v2.102.0 から変更なし）で検証済みです。bun の基準は bun-cli スキル（v1.4.4）より古いため、マトリックスに記載のないフラグについては、bun-cli を最新の参照先としてください。

使用するタイミング

• 一括アップグレードの検証――「大量のパッケージをアップグレードしたので、すべて検証してください」
• 保留中のパッケージの評価――「X をアップグレードできますか？」「何が妨げになっていますか？」
• 依存関係への疑問――「そもそも X はなぜ必要なのでしょうか。使っていません」
• リリースノートの確認――またいだバージョンにおける破壊的変更、移行手順、新機能
• アップグレード後の問題の切り分け――更新後に発生した型、ビルド、テストの失敗
• アップグレード前の調査――誰かが実行する前に、更新に伴う作業を把握する

重要なルール

1. 最初にパッケージマネージャーを特定し、その列のコマンドだけを使います。 Bun プロジェクトでは一貫して bun、pnpm プロジェクトでは pnpm、npm プロジェクトでは npm、yarn プロジェクトでは yarn を使います。別のパッケージマネージャーの CLI はインストールされていない場合があります。インストールされていても、独自のルールで依存関係を解決し、別のロックファイルや異なる形式のツリーを書き込む可能性があります。このスキルに必要な機能はすべて、4 つのパッケージマネージャーそれぞれにネイティブな形式があります――Capability Matrix を参照してください。別のパッケージマネージャーを使う理由はありません。
2. プロンプトではなく、git から差分を特定します。 「大量のパッケージをアップグレードしました」は出発点であり、一覧ではありません。完全な記録はロックファイルの差分だけです。package.json には表示されない推移的な更新も記録されています。
3. outdated が示すのはバージョンのずれであり、互換性ではありません。 bun outdated の結果が問題なしでも、すべての依存関係が指定範囲で許可される最新バージョンであることを示すだけです。依存関係ツリーの解決、ビルド、実行が引き続き可能かどうかは分かりません。その結果だけを根拠にアップグレードを検証済みと報告してはいけません。
4. エコシステムパッケージの peer 範囲が上限であり、レジストリの latest ではありません。 たとえば、フレームワークプラグインが next@">=16.2.6 <17.0.0" を指定していれば、レジストリで何が最新とされているかにかかわらず、フレームワークの上限はそこになります。更新を提案する前に、対象パッケージをラップするパッケージの peer を確認してください。
5. peer に必須とされているパッケージは、インポートが一切なくても必須です。 graphql は [email protected] の必須の peerDependency です。クエリを一度も記述しないアプリでも、宣言する必要があります。削除を提案する前に bun why を実行し、インストール済みの peer をすべて確認してください（references/dependency-audit.md を参照）。
6. 明示的な承認なしに、移行、codemod、バージョン変更を実行してはいけません。 実行する正確なコマンドと、変更対象を報告してください。スキーマの移行を提案する前に、実行順序とロールバックの方針も必要です。
7. 更新でまたいだすべてのバージョンのノートを読み、対象バージョンのノートだけで済ませてはいけません。 16.9 で導入され、16.14 のノートには記載されていない破壊的変更も、16.8 から更新するプロジェクトにとっては破壊的変更です。
8. プロジェクトを実行して検証します。 型チェック、ビルド、テストが証拠になります。互換性をうたう変更履歴は証拠になりません。
9. 確認しなかった内容も報告します。 対象外のパッケージ、未読のノート、未テストの経路は報告に含めてください。何も書かれていないと、網羅的に確認したと受け取られます。

---

Capability Matrix

プロジェクトに該当する列を上から読み、それ以外は使わないでください。空欄は、そのパッケージマネージャーに該当するコマンドがないことを示します。注記にある回避策も同じパッケージマネージャー内で完結します。

機能	bun	npm	pnpm	yarn (berry)
レジストリのメタデータ	bun info <pkg> [prop]	npm view <pkg> <field>	pnpm view <pkg> <field>	yarn npm info <pkg> -f <fields>
インストール理由	bun why <pkg>	npm why <pkg>	pnpm why <pkg>	yarn why <pkg> --peers
インストール済みの依存関係ツリー	bun pm ls --all	npm ls --all	pnpm list --depth Infinity	yarn info -A -R
ピア依存関係の検証	peer-check.ts (references/dependency-audit.md)	npm ls --all --json -> .problems	pnpm peers check	yarn explain peer-requirements <hash>
セキュリティ勧告	bun audit --json	npm audit --json	pnpm audit --json	yarn npm audit --json
更新状況	bun outdated（テーブルのみ）	npm outdated --json	pnpm outdated --format json	--
範囲内のバージョン	bun info <pkg> versions + Bun.semver	npm view '<pkg>@<range>' version	pnpm view <pkg> versions --json + filter	yarn npm info <pkg> -f versions --json + filter
ロックファイルの確認	bun install --frozen-lockfile --dry-run	npm ci --dry-run	pnpm install --frozen-lockfile	yarn install --immutable
package.json の読み取り	bun pm pkg get <field>	npm pkg get <field>	pnpm pkg get <field>	ファイルを読む
ツールの実行	bunx <tool>	npx <tool>	pnpm dlx <tool>	yarn dlx <tool>

注意すべき点：

• ピア依存関係の検証機能には大きな差があります。 pnpm peers check と yarn explain peer-requirements は専用コマンドです。どちらも、依存関係を要求しているパッケージ、要求される範囲、インストール済みのバージョンを示します。また、pnpm peers check は終了コード 1 を返すため、ゲートとして使用できます。npm には専用コマンドがありません。npm ls --all --json は .problems の下に "invalid: <pkg>@<ver>" を表示し、npm install --dry-run は書き込みをせずに依存関係の全チェーンを出力します。Bun の対応は最も弱く（対象の名前を示さない、処理を中断しない警告のみ）、そのため references/dependency-audit.md のスクリプトを使用します。
• pnpm と yarn はインストール中にピア依存関係の問題を報告します。 そのため、インストールの出力は破棄せずに確認する価値があります。pnpm は最後に Issues with peer dependencies found と表示し、yarn はパッケージ名と、yarn explain peer-requirements に渡す6文字の p で始まるハッシュを含む YN0060 を出力します。
• バージョン範囲を直接列挙できるのは npm だけです。 npm view '<pkg>@>16.8.0 <=17.0.2' version は該当するバージョンをすべて一覧表示します。同じ範囲を指定した bun info と pnpm view は、代わりに最高のものを1つだけ解決するため、範囲内の他のバージョンが何も表示されないまま隠れてしまいます。それ以外の場合は、すべてのバージョンを一覧表示してから絞り込みます。
• yarn の列は berry（v2 以降）です。Yarn Classic は別の CLI です。 何かを実行する前に、どちらかを確認してください。.yarnrc.yml を伴う yarn.lock は berry、yarn.lock のみの場合は v1 です。Classic は npm スタイルのコマンド体系を維持しています。yarn outdated、yarn info <pkg>、yarn audit --json、yarn why <pkg>（--peers なし）、yarn list、そして --immutable ではなく yarn install --frozen-lockfile を使います。v1 に対して berry の yarn npm info や yarn dlx を実行すると、単に失敗します。
• Yarn berry には outdated がありません。 v1 にはありますが、書き換え時に削除されたため、berry での yarn outdated は不明な script として失敗します。berry では yarn dlx taze または yarn upgrade-interactive を使ってください。
• Bun の outdated には JSON 出力がありません。 --json は受け付けられますが、無視されます。テーブルを解析してください。列は Current | Update | Latest です。

マネージャーごとの、範囲内バージョンの絞り込み方法：

# bun -- Bun.semver is built in, nothing to download
bun -e 'const vs = JSON.parse(await Bun.$`bun info graphql versions --json`.text());
  console.log(vs.filter(v => Bun.semver.satisfies(v, ">16.8.0 <=17.0.2"))
               .sort(Bun.semver.order).join("\n"));'

# npm -- native
npm view 'graphql@>16.8.0 <=17.0.2' version

# pnpm / yarn -- list, then filter with the semver CLI via that manager's runner
pnpm view graphql versions --json | jq -r '.[]' | xargs pnpm dlx semver -r '>16.8.0 <=17.0.2'
yarn npm info graphql -f versions --json | jq -r '.versions[]' | xargs yarn dlx semver -r '>16.8.0 <=17.0.2'

Semver の範囲では、その範囲内で名前が指定されていない限りプレリリースが除外されます。そのため、追加の絞り込みをしなくても、4つすべてで canary や rc のビルドが除外されます。

その他のツールも前提条件です。 これらのレシピでは jq と gh を使いますが、どちらもパッケージマネージャーには同梱されていません。利用する前に確認してください（command -v jq gh）。また、リリース情報を取得するには gh の認証も必要です。jq がない場合は、プロジェクト独自のランタイムで解析してください。gh がない場合は、リリースページに対する WebFetch に切り替えてください。

---

パッケージマネージャーの検出

次の順に確認します。両方ある場合は、Corepack と CI が適用する packageManager フィールドを優先します。

bun pm pkg get packageManager 2>/dev/null            # or: cat package.json | grep packageManager
ls bun.lock bun.lockb package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null
ls bunfig.toml .yarnrc.yml deno.lock 2>/dev/null     # bunfig.toml marks bun; .yarnrc.yml marks yarn berry

ロックファイル	マネージャー	対話型アップグレードコマンド
bun.lock（テキスト）または bun.lockb（バイナリ）	bun	bun update -i -r
pnpm-lock.yaml	pnpm	pnpm update -i -r -L
yarn.lock + .yarnrc.yml	yarn berry（v2 以降）	yarn upgrade-interactive
yarn.lock、.yarnrc.yml なし	yarn classic（v1）	yarn upgrade-interactive
package-lock.json	npm	組み込みコマンドなし -- npx taze -I または npx npm-check-updates -i

npm のロックファイルがなく deno.lock がある場合は Deno プロジェクトです。4 つの列はいずれも該当せず、以下のフェーズは引き続き適用されます（references/package-managers.md を参照）。マネージャーを推測せず、その旨を伝えてください。

ワークスペースがある場合、すべてのコマンドの形式が変わります。モノレポでは再帰形式またはフィルター形式が必要で、すべてのワークスペースの package.json が差分の対象になります。

参照：マネージャーごとの検証済みコマンド一覧は references/package-managers.md を参照してください。

---

フェーズ 0：差分を確定する

これが正確でない限り、ほかの情報は信頼できません。

# Declared changes (root + workspaces)
git diff HEAD -- package.json '**/package.json'

# Resolved changes, including transitive bumps nothing declared
git diff HEAD -- bun.lock            # or pnpm-lock.yaml / yarn.lock / package-lock.json

# Already committed on a branch
git diff origin/main...HEAD -- package.json '**/package.json' bun.lock

変更ごとに分類してください。アップグレードの種類によって、必要な精査の度合いが決まります。

変更	リスク	対応
メジャー（1.x -> 2.x）	高	リリースノートをすべて読み、移行情報を探し、機能を確認する
0.x でのマイナーアップグレード	高	1.0 未満では SemVer に互換性の保証はないため、メジャーとして扱う
プレリリース／rc／canary	高	意図的な変更であることを確認し、意図せず混入した --latest の成果物でないか確認する
マイナー（1.2 -> 1.5）	中	ノートで BREAKING、deprecat、removed、migrat を検索する
パッチ	低	実行時の直接依存関係またはセキュリティ修正でない限り、ノートの確認は省略する
推移的依存関係のみ（ロックファイル）	中	ノートは不要。依存関係ツリーが引き続き解決でき、メジャーアップグレードをまたいでいないことを確認する
範囲が広がり、バージョンは同じ	低	記録する。次回のインストールでコード変更なしにバージョンが変わる可能性がある

バイナリのロックファイルでは、読み取り可能な差分は得られません。 bun.lockb の場合は、bun pm ls --all で変更前後の解決済みツリーをスナップショットとして保存して差分を取るか、Bun 1.2 以降のデフォルトであるテキスト形式のロックファイルに一度変換します。

cp bun.lockb /tmp/bun.lockb.bak                                      # keep the original
bun install --save-text-lockfile --frozen-lockfile --lockfile-only   # rewrites the lockfile only

--frozen-lockfile --lockfile-only を指定すると、ロックファイルにすでに固定されている内容を超えて解決せず、node_modules にも触れないため、変換は再エンコードだけになります。これらを指定しない場合、同じコマンドでも新しいバージョンを解決できるため、測定対象の差分が変わります。

変換後も bun.lockb は残ります。これを削除するかどうかはユーザーが決めることであり、クリーンアップの一環ではありません。新しい bun.lock が誤っていた場合、解決結果のコピーはそれだけです。変換後のファイルを検証してから（bun install --frozen-lockfile --dry-run が正常に実行でき、解決されたバージョンが変換前の bun pm ls --all のスナップショットと一致すること）、rm bun.lockb を実行する前に確認してください。

結論を出す前に、作業ツリーがロックファイルと一致していることを確認してください。

bun install --frozen-lockfile --dry-run          # bun   -- validates, writes nothing
npm ci --dry-run                                 # npm   -- validates, writes nothing
pnpm install --frozen-lockfile --lockfile-only   # pnpm  -- validates without linking
yarn install --immutable                         # yarn  -- validates, but installs

Bun と npm では実際のドライランが行われます。どちらも package.json とロックファイルが一致しない場合は失敗し、ディスクには何も書き込みません。pnpm では処理が分かれています。pnpm install --dry-run はインストールで変更される内容をプレビューし、何も書き込みません。一方、検証を行う --frozen-lockfile は副作用としてインストールします。これに --lockfile-only を組み合わせると、node_modules をリンクせずにチェックできます。ここでは Yarn にドライランがありません。yarn install --immutable は差異があるとすぐに失敗し、その処理中にインストールも行うため、インストールしても問題ない環境でのみ実行してください。

フェーズ 1：静的整合性

リリースノートを読む前に、まずこれらを実行してください。コストが低く、変更履歴では警告されない問題を検出できます。

ピア依存関係の競合（最も検出効果の高いチェック）。 パッケージマネージャーの以下のコマンドを使います。

pnpm peers check                     # names package, wanted range, installed version; exits 1
yarn explain peer-requirements <hash>  # hash comes from the YN0060 line in install output
npm ls --all --json | jq '.problems'   # "invalid: <pkg>@<ver>"; npm install --dry-run for the full chain
bun run peer-check.ts                  # see references/dependency-audit.md

スクリプトが必要なのは Bun だけです。範囲違反は warn: incorrect peer dependency "[email protected]" と報告されます。致命的ではなく、誰の依存関係かも示されず、機械可読な出力にも含まれません。

$ bun run peer-check.ts
CONFLICT [email protected] needs graphql@^0.9.0 || ... || ^16.0.0 -- installed 17.0.2

npm の通常の npm ls も同様に誤解を招きます。深さ 0 では、ピア依存関係が無効なツリーでも終了コード 0 で正常として表示されるため、--all --json が必要です。

エンジン要件と実際に使用中のランタイムの照合：

bun info <pkg>@<ver> engines     # npm view / pnpm view / yarn npm info -f engines
bun --version; node --version

今回の更新で導入された非推奨項目：

bun info <pkg>@<ver> deprecated || echo "not deprecated"

非推奨ではないパッケージにはこのプロパティがなく、bun info はプロパティがない場合にエラーを返します：error: Property deprecated not found、終了コード 1。これは正常な状態です。検索の失敗として報告しないでください。同じケースで npm view と pnpm view は何も出力せず、終了コード 0 を返します。

ツリー内の重複したメジャーバージョン — 状態を保持するライブラリ（React、GraphQL、ORM クライアントなど）が 2 つインストールされているのは、サイズの問題ではなくランタイムの不具合です。マトリックスの「インストール理由」と「インストール済みツリー」の行を使います。

bun why <pkg> --depth 3          # pnpm why / npm why / yarn why --peers
bun pm ls --all                  # pnpm list --depth Infinity / npm ls --all / yarn info -A -R

更新後のセキュリティ状況：

bun audit --json | jq 'to_entries[] | {pkg: .key, advisories: [.value[] | {severity, title, vulnerable_versions}]}'
bun pm scan                      # bun only: lockfile scan, no installed tree needed

npm audit --json、pnpm audit --json、yarn npm audit --json は、それぞれ異なる出力形式で同じ質問に答えます。フィルターを書く前に、出力形式を確認してください。

型パッケージの整合性 — @types/* のメジャーバージョンは、ランタイムパッケージのメジャーバージョンに合わせます。不一致はインストール失敗ではなく、フェーズ 6 で型エラーとして表面化するため、差分テーブルでは両者を組み合わせてください。

参考：ピア依存関係の上限を確認する方法、重複したメジャーバージョンの診断方法、削除判断のフローチャートについては、references/dependency-audit.md を参照してください。

フェーズ 2：リリースノート

このフェーズにかける時間は、フェーズ 0 のリスク列を基準に調整してください。すべての推移的なパッチのリリースノートを取得すると、コンテキストを浪費し、重要な調査結果が埋もれてしまいます。

bun info <pkg> repository        # npm view <pkg> repository.url / pnpm view / yarn npm info -f repository
bun info <pkg> homepage          # docs site, where upgrade guides live
gh release view v17.0.0 --repo <owner>/<repo> --json tagName,publishedAt,body

機能マトリックスのパッケージマネージャーに対応する行を使い、対象となるすべてのバージョンを列挙してください。範囲を直接指定できるのは npm だけです。bun と pnpm では、<pkg>@<range> は一致する範囲内で最も新しいバージョン 1 つだけに解決されます（bun info 'graphql@16' version は 16.14.2 を返します）。その間のバージョンはすべて、何も通知されずに見落とされます。

ソースはコストの低い順に確認します：node_modules/<pkg>/CHANGELOG.md（無料で、すでにディスク上にありますが、提供していないパッケージも多くあります）→ gh release view → リポジトリの CHANGELOG.md／UPGRADING.md／MIGRATION.md → WebFetch を使ってドキュメントサイトのアップグレードガイドを確認します。

抽出するのは次の 4 点だけです：破壊的変更、移行手順、削除予定バージョンを伴う非推奨項目、プロジェクトがすでに独自に実装しているコードを置き換えられる追加機能。それ以外はノイズです。

参考：リポジトリの解決方法、タグ名のフォールバック順、モノレポへの対応、gh の使用例については、references/release-notes.md を参照してください。

フェーズ 3：移行

リリースノートでは移行要件が文章の中に埋もれがちです。また、次の 2 種類はそれぞれ異なる形で失敗します。

• コードの移行 — codemod、API 名の変更、設定の移動や構造変更。失敗は明確かつ局所的で、ビルドが壊れます。
• スキーマとデータの移行 — ORM や CMS のモデル変更に伴い、生成した移行ファイルをコミットし、デプロイとの特定の順序で適用する必要があります。開発環境では失敗が表面化せず、本番環境ではデータを破壊する可能性があります。

どちらも正確なコマンド、今すぐ必要か任意かの判定とともに報告します。スキーマの移行については、実行順序とロールバックに関する注記も記載します。承認なしに実行することはありません。

参考：検出パターン、エコシステムごとのコマンド、デプロイ順序については、references/migrations.md を参照してください。

フェーズ 4：保留中および疑わしいパッケージ

ユーザーがアップグレードしなかったパッケージ、または不要だと疑っているパッケージごとに、次の両方の質問に明確に答えてください。

1. なぜここにありますか？ 直接依存かつインポートされている／ピア依存パッケージが必要としているため直接依存／推移的依存のみで誤って宣言されている／本当に未使用。
2. アップグレードを妨げているものは何ですか？ 上限を設定しているパッケージ名とピア依存の範囲を示すか、妨げるものはなくアップグレード可能だと述べてください。

最初の質問に、インポートの grep 結果だけを根拠に答えてはいけません。必須のピア依存パッケージが削除される原因となるのは、まさにその判断です。

参考：判断フローの全容については、references/dependency-audit.md を参照してください。

フェーズ 5：採用可能な機能

フェーズ 2 でまとめたメモをもとに、プロジェクトに取り入れられる機能を、削除できるものの優先度順に提示してください。手作業で実装した回避策を置き換える機能を最初にし、次に依存関係を取り除く機能、続いてパフォーマンスと DX の機能を挙げます。提案する前に、置き換え対象のパターンがプロジェクトに実際に存在することを確認してください。古い API を grep します。これらは作業量の見積もりを含む提案であり、変更を加えるものではありません。

フェーズ 6：検証ゲート

最も手軽なものから実行し、最初の失敗で止め、その原因を特定してから次に進みます。

bun install --frozen-lockfile     # npm ci / pnpm install --frozen-lockfile / yarn install --immutable
bun run typecheck                 # or: bun --check (Bun >= 1.4.3, never runs a "check" script), bunx tsc --noEmit
bun run lint
bun run build
bun test                          # or the project's own test script

使用するパッケージマネージャーに合わせて、全体を通じて実行コマンドを置き換えてください（npm run、pnpm、yarn）。bun test は Bun 独自のテストランナーである点に注意してください。テストに Jest または Vitest を使うプロジェクトでは、ゲートは bun run test です。これはプロジェクトのスクリプトを実行します。名前を推測せず、package.json から実際のスクリプト名を確認してください。プロジェクトで定義されていないゲートはスキップし、その旨を記載します。その後、ランタイムのスモークチェックを行います。開発サーバーを起動し、アップグレードしたパッケージを使うルートまたはエントリーポイントを 1 つ実行します。型チェックとビルドを通過したコードでも、初期化処理、設定スキーマ、アダプター API の変更によって、実行時に失敗することがあります。

失敗はすべて、原因となったパッケージに結び付けてください。「ビルドに失敗する」は所見ではありません。「16.0 で設定オプションの名前が変更されたため、ビルドに失敗する」が所見です。

フェーズ 7：報告

まず表を示し、その後に判断が必要なセクションを続けます。

| Package | Old -> New | Bump | Risk | Breaking | Migration | Action |
|---------|-----------|------|------|----------|-----------|--------|
| next    | 15.4.2 -> 16.3.1 | major | high | yes | codemod | run codemod |
| graphql | 16.8.0 (held) | -- | -- | -- | -- | blocked by payload peer ^16.8.1 |

続いて、該当する内容がある場合に限り、ブロック中（保留した各パッケージの上限となっているもの）、対応が必要（移行とコード変更、およびコマンド）、採用（任意機能と作業量）、削除（不要であることが証明された依存関係と根拠）、セキュリティ（解消または新たに導入されたアドバイザリ）、未確認（スキップしたパッケージと未テストの経路）を記載します。

コミットメッセージでは、作業の進め方ではなく、変更内容を示してください。fix: post-upgrade fixes ではなく、fix: update config for renamed option とします（git-commit スキルを参照）。

---

主な注意点

1. 検出されなかったパッケージマネージャーは、インストールされていない可能性があります。インストールされている場合も、そのマネージャー独自のルールで解決され、2つ目のロックファイルが残ることがあります。特に、bun がインストールされているすべてのマシンに npm があるとは限りません。4つのマネージャーすべてに、各機能のネイティブな方法があります（機能マトリックス）。別のマネージャーに頼る必要はなく、問題が起きないとも限りません。同じ注意は、どのマネージャーもインストールしない jq と gh にも当てはまります。
2. bun outdated は JSON 出力に対応していません（1.3.x まで）。--json は無視され、表がそのまま出力されます。そのためにマネージャーを切り替えるのではなく、表（Current | Update | Latest）を解析してください。
3. bun info はプロジェクト外では失敗します。単純なレジストリー検索でも、error: Bun could not find a package.json file to install from と表示されます。プロジェクト内では適切なツールです。
4. bun info <pkg> deprecated は、パッケージに問題がない場合にエラーになります。error: Property deprecated not found と表示され、終了コードは 1 です。プロパティが見つからないと bun info はエラーになるため、正常な結果がコマンドの失敗に見えます。終了ステータスではなくメッセージで分岐してください（npm view は何も表示せず、終了コード 0 になります）。
5. bun info '<pkg>@<range>' version は、範囲ではなく1つのバージョンを返します。一致する中で最も高いバージョンに解決され、その間のバージョンはすべて表示されません。bun info <pkg> versions で列挙し、Bun.semver.satisfies で絞り込んでください。
6. Bun.Glob のブレース内の選択肢には / を含められません。{*,@*}/package.json は問題なく一致しますが、{*,@*/*}/package.json は何も一致せず、エラーも報告されません。そのため、node_modules のスキャンではパッケージが0件として返され、それを使ったすべてのチェックが成功と報告されます。形状ごとにパターンを1つずつ使用してください。同じように、ドットディレクトリーも何も検出されません。dot: true を指定しない限り、node_modules/.bun と node_modules/.pnpm は scan から見えません。
7. ピア依存関係の競合報告は、マネージャー間の違いが最も大きい部分です。pnpm peers check はパッケージ、範囲、インストール済みバージョンを表示して終了コード 1 で終了します。yarn はインストール時に YN0060 と、yarn explain peer-requirements 用のハッシュを表示します。npm では npm ls --all --json -> .problems または npm install --dry-run が必要です。bun は、対象を示さない警告を出します。あるマネージャーの報告品質が別のマネージャーでも同じだと思わないでください。
8. npm ls は深さ0ではピア依存関係の不整合を隠します。ピア依存関係の範囲に違反しているツリーでも、終了コード 0 で問題なく表示されます。npm ls --all --json | jq '.problems' を使用してください。npm プロジェクトに限り、npm install --dry-run は何も書き込まず（確認済み。package-lock.json は作成されません）、必要となる依存関係の完全な連鎖を表示します。
9. bun はバナーを stderr に、データを stdout に書き込みます。bun audit --json | jq はそのままパイプでつなげられます。バナーを取り除く必要はありません。
10. dist-tags に不要なタグが混在していることがあります。canary タグや実験用タグが何十個もあるパッケージもあります。最初のエントリーではなく、dist-tags.latest を参照してください。
11. リリースタグの命名には一貫性がありません。v17.0.2、17.0.2、パッケージタグ付きモノレポの @scope/[email protected]、さらにバージョン以外の情報を含むリリース名もあります（React はタグ v19.2.8 の名前を 19.2.8 (July 21st, 2026) としているため、tagName で一致する場合でも名前の照合には失敗します）。一度試して諦めず、段階的に解決してください。
12. canary が多いリポジトリーでは、リリース一覧が埋もれてしまいます。gh release list --repo vercel/next.js はプレリリースが大半を占めます。--exclude-pre-releases を指定してください。
13. repository.url が改名後の組織を指していることがあります。React のメタデータには github.com/react/react と記載されています。gh はリダイレクトに追従するため、手作業で検証せず、そのまま渡してください。
14. どこにも変更履歴を公開していないパッケージは数多くあります。tarball 内にも、モノレポのルートにもないことがあります。その場合、GitHub のリリースが唯一の情報源となり、一部のパッケージではドキュメントサイトが情報源になります。
15. Yarn berry には outdated コマンドがありません。v1 から引き継がれておらず、yarn outdated は不明なコマンドではなく、不明な スクリプト として失敗します。yarn dlx taze または yarn upgrade-interactive を使用してください。
16. 推移的依存関係の更新は package.json に表示されません。サプライチェーンのインシデントや、ネストされた依存関係の破壊的変更は、ロックファイルの差分でしか確認できません。
17. 同日に公開されたバージョンは、もう一度確認する価値があります。bun info <pkg> time --json はすべてのバージョンの日付を表示します。このため、どのマネージャーにもクールダウン機能が備わっています（bun install --minimum-release-age=<seconds>、npm install --min-release-age=<days>、pnpm の minimumReleaseAge 設定、yarn のデフォルトの公開時刻ゲート）。そのため、ツールが選択を拒否したバージョンは、壊れているのではなく、意図的に保留されている可能性があります。
18. knip などの未使用依存関係ツールは、ピア依存関係として必要なパッケージを未使用と報告します。これは、Critical Rule 4 があるまさにその理由です。結果は調査対象の候補リストとして扱い、削除リストとして扱わないでください。
19. ロックファイルのずれは、アップグレード後も残ります。インストール済みバージョンを変えずに範囲だけを広げると、次回のクリーンインストールで異なるバージョンが解決されます。変更が何もないように見えても、範囲だけの編集には注意してください。

---

参照：パッケージマネージャーごとのコマンド一覧については、references/package-managers.md を参照してください。 参照：リリースノートと変更履歴の取得については、references/release-notes.md を参照してください。 参照：コードモッドとスキーマ移行については、references/migrations.md を参照してください。 参照：peer の上限と依存関係の妥当性については、references/dependency-audit.md を参照してください。 参照：自動承認のパターンについては、references/allowlist.md を参照してください。