Maintain Package JSON

maintain-package-json

依頼に応じて、スクリプト整理・依存削除・依存更新・メンテナンス状況の調査を組み合わせる。 調査だけの依頼ではファイルを変更しない。特定の依存や整理だけの依頼を、全依存の更新や置き換えに広げない。

1. 現状把握

• package.json、ロックファイル、packageManager、engines、CI を読み、使用中のパッケージマネージャーとバージョン、Node.js の対応範囲、検証コマンドを把握する。
• モノレポではワークスペース構成と対象パッケージを確認する。依存の宣言範囲とロックファイルで実際に解決されたバージョンを区別する。
• 依頼に関係する以下の観点を調べ、修正方針を短く伝えて、依頼された範囲の作業を進める。既存の承認を繰り返し求めず、範囲を超える移行など判断が必要な事項だけ確認する。

スクリプトと未使用依存

• エイリアス、単純なコマンドのラッパー、preX / postX、命名の不統一を確認する。ただし build、lint などの標準的な入口や、CI・利用者が参照するスクリプトは、短いという理由だけで削除しない。
• 依存の利用箇所は import だけでなく、設定ファイル、CLI、スクリプト、CI、動的読み込み、プラグイン自動検出、型宣言まで検索する。
• Tauri / Electron などのネイティブ連携、peerDependencies、optionalDependencies、ワークスペース間の依存も確認する。テキスト検索で見つからないだけでは未使用と断定しない。

更新候補と互換性

• 使用中のパッケージマネージャーの outdated 相当の機能とレジストリ情報から、現在の解決バージョン、宣言範囲内の更新候補、最新安定版を確認する。既存ツールを優先し、調査用ツールをプロジェクト依存に追加しない。
• 公式リリースノートと移行ガイドで、破壊的変更、Node.js の要件、peerDependencies、関連パッケージとの互換性を確認する。メジャー番号だけで安全性を判断せず、プレリリース版や Node.js の対応範囲変更を暗黙に採用しない。
• 更新範囲の指定がなければ、既存の実行環境と構成で互換性を確認できる安定版を優先する。大きなコード移行や実行環境変更が必要な候補は分けて提示する。最新化やメジャー更新が依頼されている場合は、その範囲内で必要な移行も行う。
• 直接依存と推移的依存を区別する。推移的依存は原則として親パッケージの更新で対応し、不要な直接依存への追加や根拠のない overrides / resolutions を避ける。

メンテナンス状況

メンテナンス状況を調べる依頼、または依存全体の保守依頼では、対象の直接依存を確認する。更新・置き換え判断に影響する推移的依存があれば、その経路も調べる。

• 調査時点のレジストリ情報、公式リポジトリ、リリース履歴、保守方針を確認する。レジストリから公式リポジトリへのリンクをたどり、同名の別プロジェクトやモノレポ内の別パッケージと混同しない。
• deprecated 指定、アーカイブ、保守終了や後継への移行宣言、最新リリース日、最近の変更・issue / PR 対応を根拠として記録する。サポート対象バージョンが明記されていれば、採用中のバージョンが対象かも確認する。
• リリースやコミットが古いという理由だけで「保守されていない」と断定しない。成熟して変更が少ない場合と、明示的な保守終了を区別し、情報不足や複数の兆候だけの場合は「要確認」とする。
• パッケージごとに「継続を確認」「保守終了・非推奨」「要確認」などの判断と根拠 URL・確認日を示す。ネットワークや非公開リポジトリの制約で確認できない場合は、未確認と明記する。
• 問題のある依存は、継続利用・更新・削除・代替への移行を比較する。代替候補も保守状況と互換性、移行コストを確認し、人気や更新頻度だけで選ばない。置き換えは依頼範囲に含まれる場合に実施する。

2. 変更の実施

• スクリプトの統合・命名変更では、呼び出し元と引数の引き渡しを保つ。preX / postX の明示化は、実行順序、失敗時の停止、単独実行時の振る舞いを確認して行う。install / publish などのライフサイクルを一律に書き換えない。
• スクリプト名や依存の利用方法が変わる場合は、README、AGENTS.md / CLAUDE.md、docs、CI、設定ファイルも更新する。
• 未使用と確認できた依存を削除し、更新は互換性のある関連パッケージ単位で適用する。必要なコード・設定の移行も合わせて行う。
• プロジェクト既存のパッケージマネージャーでマニフェストとロックファイルを整合させる。通常はロックファイルや node_modules を全削除せず、対象の remove / update / install 相当の操作を使う。別のパッケージマネージャーのロックファイルを生成しない。
• ロックファイルの差分を確認し、意図しない広範囲の更新があれば原因を調べ、対象を絞る。全再生成は破損修復や明示された再解決など、必要な場合に限定する。

3. 検証と報告

• 既存の lint、型チェック、テスト、ビルドから変更に適したものを実行する。削除した依存の利用箇所や、更新に伴う移行箇所が検証対象に含まれることを確認する。
• プロジェクトの frozen / immutable 相当のインストール検証で、マニフェストとロックファイルの整合性を確認する。
• エラーは今回の変更と既存の問題を切り分ける。検証できなかった項目を明記し、未実行を成功扱いしない。
• 変更内容、更新前後のバージョン、検証結果、保留した候補と理由を簡潔に報告する。保守状況を調査した場合は、対象ごとの判断と根拠・確認日を添える。

評価ケースは evals/evals.json にある。実行時は各 fixture を一時ディレクトリへコピーし、調査のみ・動的利用・限定更新の境界を検証する。