dep-lib-review

依存関係のレビュー

実行条件

次の場合にこのレビューを実行します。

• 毎月のメンテナンス
• メジャーリリースまたはブランチ凍結の前
• CI で pnpm audit が脆弱性を報告したとき
• 主要なエコシステムライブラリ（React、Vite、TypeScript など）が新しいメジャーバージョンをリリースしたとき

ステップ 1 — 現状を把握する

並行して実行します。

# Outdated packages (name, current, wanted, latest)
pnpm outdated 2>/dev/null || true

# Security vulnerabilities (runtime + dev)
pnpm audit --json 2>/dev/null | jq '
  .vulnerabilities | to_entries[] |
  { name: .key, severity: .value.severity,
    isDirect: .value.isDirect,
    via: [.value.via[] | select(type=="object") | .title] }'

# Check if Renovate / Dependabot is configured
ls .github/renovate.json renovate.json .github/dependabot.yml 2>/dev/null || echo "no bot configured"

ボット（Renovate/Dependabot）がすでに設定されている場合は、まず未対応の PR を確認し、作業の重複を避けます。

ステップ 2 — トリアージ

セキュリティに関する指摘

CVSS スコアだけで判断しないでください。攻撃ベクトルの重みを考慮します。

CVE の種類	devDep のみ	ブラウザー SPA	SSR / Edge
RCE	無視	無視	P0
ライブラリ経由の XSS	無視	P0	P0
プロトタイプ汚染	無視	P1（入力経路を確認）	P0
ReDoS	無視	P1（ユーザー入力への到達経路を確認）	P0
サプライチェーン（postinstall）	P0	P0	P0
パストラバーサル / SSRF	無視	無視	P0

# Exclude devDeps to focus on runtime CVEs
# Fallback to plain text if jq parsing fails (pnpm JSON schema varies by version)
pnpm audit --prod --json 2>/dev/null | jq -r '
  .vulnerabilities | to_entries[] |
  .value.via[] | select(type=="object") |
  "\(.severity)\t\(.name)\t\(.title)"' 2>/dev/null | sort -k1 \
  || pnpm audit --prod 2>/dev/null

バージョン更新 — 一括対応の方針

更新の種類	方針
パッチ（1.2.3 → 1.2.4）	すべてまとめて 1 つの PR にします。変更履歴を読む必要はありません。
マイナー（1.2.x → 1.3.x）	非推奨化について変更履歴を確認します。互換性を損なわない更新はまとめます。
メジャー（1.x → 2.x）	パッケージごとに PR を作成します。移行ガイドを読みます。他の変更とまとめることはありません。

古くなったパッケージごとにカテゴリを特定します。

# Categorize outdated packages (deprecated / major / minor / patch)
pnpm outdated --json 2>/dev/null | jq -r '
  to_entries[] |
  (.value.current // "none") as $cur |
  (.value.latest // "none") as $lat |
  (.value.dependencyType // "dependencies") as $t |
  ($cur | split(".")[0]) as $curMaj |
  ($lat | split(".")[0]) as $latMaj |
  (if .value.isDeprecated then "deprecated"
   elif $curMaj != $latMaj then "major"
   elif ($cur | split(".")[1]) != ($lat | split(".")[1]) then "minor"
   else "patch" end) as $category |
  "\($category)\t\(.key)\t\($cur) → \($lat)\t\($t)"' | sort

トレンドの確認（手動チェック）

次に該当するパッケージにフラグを付けます。

• jest → vitest に移行
• axios → fetch / ky に移行
• moment → Temporal / date-fns / ネイティブの Date に移行
• lodash → ネイティブの Array/Object API に置き換え
• webpack → Vite に移行
• mocha/chai → vitest に移行
• ESM プロジェクトで CJS のみをサポートするパッケージ（package.json の exports フィールドを確認）
• 非推奨とマークされた @types/<pkg> → ベースパッケージに型定義が同梱されている可能性があります。確認方法：cat node_modules/<pkg>/package.json | jq '.types, .typings'。null 以外の場合は、@types/<pkg> の devDep を削除します。移行コストはゼロです。

ステップ 3 — 更新を実行する

パッチと安全なマイナー更新を一括対応

# Update all packages to their "wanted" semver range
pnpm update

# Validate
pnpm typecheck && pnpm test:ci && pnpm lint

プロジェクトに E2E テストがある場合：

pnpm test:e2e

次のコミットメッセージで、単一の PR としてコミットします：chore: update patch/minor dependencies。

メジャーバージョンの更新（パッケージごとに対応）

# Update single package to latest
pnpm add <package>@latest

# For devDep
pnpm add -D <package>@latest

次に：

1. 公式の移行ガイド / CHANGELOG を読み、破壊的変更を確認します。
2. 公式の codemod があるか確認します（例：@tailwindcss/upgrade、React codemods）。まず実行します。機械的な変更の約 80〜90% を自動で処理できます。
   • codemod の実行後、package.json の配置を監査します。codemod によって、ビルド時のパッケージが devDependencies ではなく dependencies に追加されることがあります。必要に応じて移動します。
   • 複雑なプラグインが関係する場合、codemod で移行が完全に行われないことがあります。出力ログで「could not be automatically migrated」の警告を確認し、手動で対応します。
3. grep -r "deprecated API" src/ を実行するか、ast-grep を使って変更された API を探します。
4. 問題があれば修正します。
5. 検証します：pnpm typecheck && pnpm test:ci && pnpm lint。
6. VRT スナップショットがある場合は、UI に影響するアップグレード後に Linux コンテナーで再生成します。
7. 独立した PR として、次のコミットメッセージでコミットします：chore: upgrade <package> to v<N>。

メジャーアップグレード時の pnpm のトラブルシューティング

package.json の編集後に pnpm install が失敗した場合：

エラー	原因	対処方法
ERR_PNPM_MISSING_TIME	pnpm ストアのメタデータが古い	pnpm store prune を実行してから再試行
レジストリに存在するパッケージで ERR_PNPM_NO_MATCHING_VERSION が発生	古い lockfile のエントリーが、新しい推移的依存関係と競合している	pnpm-lock.yaml を削除し、pnpm install を実行して依存関係を新たに解決

lockfile を削除した場合は、新しい lockfile を package.json の変更とともに同じ PR でコミットします。

ステップ 4 — 検証チェックリスト

PR を準備完了にする前に、次を確認します。

• pnpm typecheck が成功する
• pnpm test:ci が成功する
• pnpm lint が成功する
• pnpm build が成功する（バンドルサイズが 5% を超えて増加していない）
• E2E スモークテストが成功する（該当する場合）
• pnpm audit で高または重大な指摘がゼロ件になる（または、残りすべてがトリアージ済みである）

ステップ 5 — 出力

以下を含む簡潔な要約を書きます：

## Dependency review — <YYYY-MM-DD>

### Security
- [FIXED] <package>@<ver>: <CVE title> (was <severity>)
- [IGNORED] <package>: <reason> (devDep-only / browser-only / no user input path)

### Updated
- Patch batch: <N> packages → see commit <sha>
- Major: <package> v<old> → v<new> (standalone PR #<N>)

### Deferred
- <package> v<old> → v<new>: migration effort high, scheduled for <date>

### Trend watch
- <package>: migration recommended → <alternative>

アンチパターン

• 大規模なアップグレードをまとめて行うこと — 1 つの回帰でバッチ全体をテストできなくなります
• pnpm audit fix --force を無批判に受け入れること — メジャーバージョンが気付かないうちに更新される可能性があります
• トリアージの理由を記録せずに CVE を無視すること
• @types/* パッケージを対応するランタイムパッケージとは別に更新すること — 必ず同時に更新してください

関連項目

• frontend-review-deps — frontend-review スイート向けのスクリプトを含む拡張版（CVE トリアージ + トレンド監視用データファイル）
• upstream-fix-and-pin — パッチを上流に適用して修正する必要がある場合