1k-pkg-upgrade-review

パッケージのアップグレードレビュー

ソースレベルの差分分析を行い、すべての呼び出し箇所を追跡して、構造化された互換性レポートを作成することで、npm/yarn パッケージのバージョンアップを評価します。

出力言語：チームの慣例に合わせて、中国語で出力します。

クイックリファレンス

トピック	ガイド	説明
レビューワークフロー	review-workflow.md	手順に沿ったレビュープロセス
レポートテンプレート	report-template.md	出力形式とリスクに関するガイドライン
レポート例	example-report.md	実例：@isaacs/brace-expansion 5.0.0 -> 5.0.1

使用するタイミング

• 依存関係のバージョンを更新する Dependabot / Renovate の PR
• 手動での yarn upgrade または npm update による変更
• yarn.lock または package-lock.json を変更するすべての PR
• マージ前に、パッケージ内で実際に何が変更されたかをチームで把握する必要がある場合

ワークフローの概要

1. 特定：パッケージ名とバージョン範囲（旧 -> 新）を特定します
2. ダウンロード：npm レジストリから両方のバージョンをダウンロードして展開します
3. 差分を確認：バージョン間のソースコードの差分を確認します（メタデータではなく、主に JS/TS を対象とします）
4. 分類：変更を分類します。API シグネチャ、戻り値、新しいエクスポート、削除されたエクスポート、動作の変更
5. 検索：プロジェクトのソースコードで直接のインポートや使用箇所を検索します
6. 検索：中間パッケージを介した間接的な使用箇所を node_modules で検索します
7. 追跡：各呼び出し箇所を追跡し、引数の使用方法と互換性を確認します
8. 評価：互換性リスクを評価します。シグネチャ、戻り値の型、戻り値の内容、副作用
9. 生成：構造化レポートを node_modules/.cache/pkg-upgrade/ に生成します
10. 投稿：gh pr comment を使って、レポート全文を PR のコメントとして投稿します

主なコマンド

# Download and extract both versions for diffing
mkdir -p /tmp/pkg-diff && cd /tmp/pkg-diff
curl -sL $(npm view PKG@OLD_VER dist.tarball) | tar xz -C old
curl -sL $(npm view PKG@NEW_VER dist.tarball) | tar xz -C new

# Compare file lists
diff -rq old/package new/package

# Diff main source
diff old/package/dist/commonjs/index.js new/package/dist/commonjs/index.js

# Search project code for direct usage
grep -r "PACKAGE_NAME" --include="*.ts" --include="*.tsx" --include="*.js" -l . \
  --exclude-dir=.git --exclude-dir=node_modules

# Search node_modules for indirect usage
grep -rn "from ['\"]PACKAGE_NAME['\"]" node_modules/ --include="*.js" --include="*.mjs" \
  | grep -v "node_modules/.cache"

# Check package metadata
npm view PKG@NEW_VER deprecated
npm view PKG@NEW_VER dist.integrity

レポートの出力先

• ローカルファイル：node_modules/.cache/pkg-upgrade/<package-name>-<old>-to-<new>.md
• PR コメント：gh pr comment を使って、レポート全文を PR のコメントとして必ず投稿してください

関連スキル

• /1k-code-review-pr - 包括的な PR コードレビュー（セキュリティ、コード品質、プラットフォームのパターン）