node-deps-bumper

Node Dependency Bumper

Taze を使って構造化された更新計画を 1 つ作成し、互換性のある範囲指定の更新を適用して、メジャーバージョンへの更新をまとめて判断します。

依存関係の追加

新しいパッケージや CLI を追加する場合は、Taze ではなく、リポジトリのパッケージマネージャーと既存のバージョン範囲の規約に従ってください。package@latest をインストールし、パッケージマネージャーによって設定された ^x.y.z の範囲をそのまま使うことは許可されています。将来のリリースが含まれる可能性があるという理由だけで、キャレット範囲を厳密なバージョン指定に置き換えないでください。

パッケージマネージャーの有効な最低リリース経過日数ポリシーがある場合、それが候補バージョンの鮮度の基準になります。その場合は、references/conditional-workflows.md を読んでください。コミット済みのロックファイルとデプロイ時のフローズンインストールにより、再現性が確保されます。ユーザーまたはリポジトリが要求している場合、既知の互換性上の制約により妥当な場合、またはコミット済みのロックファイルとフローズンインストールなしでパッケージを実行する場合に限り、厳密なバージョンを指定してください。

複数のリポジトリ

ユーザーが 2 つ以上のリポジトリを指定した場合、またはリポジトリ間の依存関係の同期や整合を求めた場合は、references/multi-repo-alignment.md を読んでください。この手順では、各リポジトリで以下のワークフローを実行し、共有する更新先の選定、リポジトリ横断のメジャーバージョン更新の一括判断、リポジトリごとのコミットを追加します。

ワークフロー

1. スキルディレクトリを特定し、対象リポジトリからヘルパーの計画を保存します。

   bash <skill-dir>/scripts/run-taze.sh --plan [--include package-a,package-b] > <taze-plan.json>
   

   JSON 計画では、検出されたすべての更新を apply、review-major、review、skip-fixed のいずれかに分類します。ヘルパーはモノレポを検出し、スキャン時にロック済みのバージョンを含め、Bun の最低リリース経過日数設定を反映します。リポジトリでパッケージマネージャーの経過日数ゲートまたは Bun カタログを使用している場合は、該当する有効な分岐についてのみ references/conditional-workflows.md を読んでください。

2. --dry-run が指定された場合は、計画と件数を提示してから、マニフェストやロックファイルを変更せずに終了します。

3. apply とマークされた範囲指定のマイナー／パッチ更新をすべて選択します。パッケージ／バージョンの移行について明示的な承認がある場合は、それを再利用します。パッケージ名だけを理由にメジャーバージョン更新を自動承認してはいけません。未解決の review-major と不明な更新を、現在のバージョン、更新先のバージョン、パッケージの役割、関連する移行情報やリリースノートとともに、1 つの判断単位として提示します。承認されたメジャーバージョン更新のみを適用します。

4. 選択対象がない場合は、変更なしであることを報告して終了します。ルートマニフェストで Bun カタログを使用している場合は、承認された計画から選択対象となったカタログの変更内容を正確にプレビューします。選択したパッケージのうち、カタログに存在するものだけを渡します。その対象が 1 つもない場合は、ヘルパーをスキップします。

   uv run <skill-dir>/scripts/update-bun-catalogs.py \
     --root <repo> --plan <taze-plan.json> --include package-a,package-b
   

   プレビューは読み取り専用です。カタログエントリの欠落、計画行の競合、未対応のバージョン、またはカタログの値が計画と一致しなくなっている場合は、書き込み前に失敗します。ヘルパーが更新を選択することはありません。

5. マニフェストまたはロックファイルへの最初の書き込み前に、選択した更新によるリグレッションを検出できるベースラインを選び、実行します。リポジトリで必須のチェックがあれば、それに従ってください。それ以外の場合は、更新されたパッケージの実際の利用箇所とリスクに基づいて、依存関係の解決、ビルド、テスト、型チェック、リンティング、フォーマット、コード生成、または不変条件のチェックを選択します。共有ツールチェーンやランタイムの変更では、単に存在するという理由だけではなく、集約テストスイートを使用してください。利用可能な場合はフローズンモードまたは書き込みを行わないモードを使い、更新後に再実行する正確なコマンドとそのカバレッジを記録します。 ブロックの判断をする前に、すべての失敗の原因を特定してください。無関係な既存の失敗が再現可能で、更新前後で比較でき、依存関係の解決や回帰検出に必要なチェックを妨げない場合は、そのまま進めてください。その失敗を更新の一環として修正してはいけません。依存関係またはピア依存関係の解決に関する競合、対処が必要な危険な動作、あるいは信頼できる更新前後の比較ができないベースラインがある場合は、更新をブロックしてください。その場合は、### ⛔ Dependency bump blocked — baseline unusable を示し、正確な前提条件と診断結果を報告してください。重複する許可を求める必要はありません。避けられない非推奨化などの情報通知は、ブロックの理由にはなりません。

6. Bun カタログの場合は、まずプレビューされた変更を適用します。同じプランとカタログの対象範囲を指定して update-bun-catalogs.py を --write とともに再実行してください。このコマンドは、一致するすべてのデフォルト／名前付きカタログの出現箇所をアトミックに更新し、既存の ^、~、または空のプレフィックスを保持します。Taze のネイティブなカタログ書き込みによってプランが古くなるため、Taze より先に適用してください。

   次に、選択したすべての Taze 更新を 1 つのコマンドで書き込みます。

   bash <skill-dir>/scripts/run-taze.sh --write --include package-a,package-b
   

7. ni を実行して、リポジトリのパッケージマネージャーでロックファイルを更新します。

8. マニフェストとロックファイルの差分を確認します。ベースラインと完全に同じコマンドを再実行し、さらに更新された依存関係と必要な移行を検証するための最小範囲のチェックを実行してください。新たに発生したエラー、型の問題、チェックの失敗（テスト、ビルド、リント、フォーマット、コード生成、リポジトリの不変条件を含む）、依存関係またはピア依存関係の解決に関する競合、対処が必要な互換性や安全性に関する警告は、証拠によって否定されない限り、更新が原因であるものとして扱ってください。

9. 意図した動作を保ちながら、更新が原因の問題をすべて修正してください。必要なソースコードや設定の移行も含みます。チェックに合格させるためだけに診断を抑制したり、検証を弱めたり、期待される動作を変更したりしてはいけません。修正のたびに、入力や動作が変わったチェックを再実行してください。完了時には、記録したテストスイート全体で最終状態を検証し、受け入れたベースラインと比較して新たな失敗がないことを確認してください。入力に変更がないチェックについては、合格済みの結果を再利用できます。ステップ 5 の比較要件を満たす無関係な既存の失敗だけは残してもかまいません。

   作業の権限内で明確かつ安全な修正方法がない場合は、### ⚠️ Dependency regression decision required を示して停止してください。そのような問題をすべて、根拠、該当箇所、修正と取り消しの選択肢、および想定される影響を記載した 1 つの表にまとめてください。ユーザーが選択し、修正が適用されるか問題のある更新が取り消され、ロックファイルが再生成され、同じベースライン比較要件を満たす完全なテストスイートが実行されるまで、完了を報告してはいけません。

ユーザー向け出力

プランは ### 📦 Dependency plan として、件数と簡潔な表を含めて提示してください。

ID	Plan value	Decision	Package	Current → target	Type	Notes

プランの apply、review-major、review、skip-fixed の値は正確に使用し、併せて平易な言葉で判断を示してください。ユーザーの選択が必要な行には、1 回の回答で指定できるように固定 ID を割り当ててください。プレビューには ### 🔎 Dry run — no files written、更新がない場合には ### ✅ No selected updates を使用してください。

適用した作業の最後には ### 🏁 Dependencies updated と、変更されたマニフェスト／ロックファイルのツリーを示し、さらに ### 🧪 Verification を記載してください。### ⚠️ Remaining review は、ブロックしない情報事項に限って使用し、更新が原因の未解決問題には使用しないでください。ヘルパー JSON、パッケージ／バージョン文字列、コマンド、診断結果は、装飾せず正確なまま記載してください。

不変条件

• 固定バージョンと SemVer 以外のプロトコルは、ユーザーから明示的な依頼がない限り変更しません。
• 新しい依存関係と CLI にはキャレット範囲を使用できます。コミット済みのロックファイルと凍結インストールで解決が制御されている場合、再現性がないと説明しないでください。
• パッケージ引数は、スキャン段階と書き込み段階の両方を制約します。
• 成熟期間のポリシーは、スキャンと書き込みの両方に適用します。
• Bun のカタログプレビューと書き込みでは、承認済みの同じ Taze プランと選択済みの同じパッケージセットを使用します。古いプランでは書き込みを行いません。
• リポジトリの根拠、ピア範囲、リリースノートが異なることを示している場合、SemVer だけから互換性を推測しないでください。

完了には、出典が明記され、比較可能な書き込み前ベースライン、レビュー済みのプラン、選択した更新内容の保持、再生成されたロックファイル、記録されたテストスイートまたは依存関係固有のチェックで新たな失敗がないこと、バージョン更新に起因する未解決の問題がないことが必要です。ドライランの完了には、構造化されたプランと書き込みがゼロであることが必要です。