audit-and-reduce-dependencies

依存関係を監査して削減する

JavaScript の依存関係の規模を削減します。pnpm のみを使用してください。具体的な理由がない限り、ロックファイル、ワークスペースの構成、依存関係の範囲のスタイルは維持してください。

GitHub Actions ワークフローのトリアージ（アクションの選択、権限、ピン留め）には、以下の報告形式ではなく、専用のワークフロー監査を使用してください（検出事項が pnpm のインストールポリシーに関する場合に限り、ワークフローファイルとステップを含めます）。

ワークフロー

0. 強化ゲート：/check-npm を実行します（読み取り専用）。check-npm を参照してください。
1. ベースラインを確認します。
2. 未使用の直接依存関係を削除します。
3. モノレポ内の直接依存関係のバージョンを重複排除します。
4. 推移的なロックファイル依存関係の範囲に基づいて、直接依存関係に優先順位を付けます。
5. 依存関係の範囲データを使って、リスクの低いマイナー／パッチアップグレードを見つけます。
6. 依存関係の範囲データを使って、インライン化する価値のある単純な依存関係を見つけます。
7. 置き換えや削除に関する e18e の推奨事項を確認します。
8. 再インストールして検証し、測定した効果を報告します。

ステップ 0：強化ゲート（/check-npm）

マニフェストまたはロックファイルを変更する前に、/check-npm を実行してください。

• いずれかのチェックが失敗した場合は、表と修正用スニペットを報告し、クリーンアップ中に pnpm-workspace.yaml、.npmrc、CI のインストールフラグ、または Renovate の経過時間ゲートを緩和しないでください。
• このワークフローに強化設定全体を貼り付けないでください。バージョンのしきい値、スクリプトのポリシー、Git 依存関係のプロトコル、最小リリース経過時間は /check-npm が管理します。
• ユーザーの依頼が強化のみ（削減は含まない）の場合は、クリーンアップも求められていない限り、/check-npm の実行後に終了してください。

pnpm 11 以降： スクリプトとリリース経過時間のポリシーは .npmrc や package.json#pnpm ではなく、pnpm-workspace.yaml にあります（pnpm 11 は package.json#pnpm フィールドを読み取らなくなりました）。各キーを提案する前に、インストール済みの pnpm のメジャーバージョンでサポートされていることを確認してください。サポートされていないキーは追加しないでください。クリーンアップ中に、既存の minimumReleaseAge（または組織で相当する設定）を引き下げないでください。

依存関係のトリアージ

重要度の高い直接依存関係ごとに（特にステップ 4～7 の後）、次のラベルを 1 つ割り当てます。

ラベル	意味
維持	必要であり、推移的なコストに見合い、適切にメンテナンスされています。
より優れたものに置き換え	必要ですが、より適切にメンテナンスされている、またはより安全な代替手段があります。
内部実装に置き換え	必要ですが、外部依存関係のリスクを踏まえると、内部実装が望ましいです。
削除	削除またはインライン化できます（ステップ 6）。
ユーザーによる確認が必要	使用状況が曖昧、ポリシー上のトレードオフがある、または人による検証が必要な変更です。

置き換えと新しい直接依存関係

• ユーザーの明示的な承認なしに、新しい直接依存関係（置き換えを含む）を追加しないでください。
• 同等の機能がある場合は、より優れたものに置き換えるよりも、インライン化やネイティブ API の利用による削除を優先してください。
• より優れたものに置き換える場合は、その理由（メンテナンス状況、セキュリティ、依存関係ツリーの縮小）を述べ、信頼できるメンテナーによる、広く採用された活発にメンテナンスされているパッケージを優先してください。
• リポジトリの minimumReleaseAge／Renovate ゲートを遵守してください。コマンドレベルの 72 時間という鮮度要件は最低基準であり、より厳しい設定を回避する許可ではありません。

pnpm とサプライチェーン

リポジトリが pnpm を使用していることを確認します。ルートの package.json に pnpm-lock.yaml、pnpm-workspace.yaml、および／または packageManager / devEngines.packageManager.name が pnpm に設定されているかを確認してください。pnpm を使用していない場合は作業を中止してください。クリーンアップの一環としてパッケージマネージャーを移行してはいけません。

リポジトリにインストールポリシーがある場合は、それに従ってください（例：pnpm install --frozen-lockfile --ignore-scripts）。

操作	コマンド
ロックファイルをインストール／更新する	pnpm install --ignore-scripts（＋リポジトリのフラグ。例：--frozen-lockfile）
直接依存関係を削除する	pnpm remove <pkg> --ignore-scripts
直接依存関係を追加／更新する	pnpm add <pkg>@<version> --ignore-scripts
依存関係を確認する	pnpm why <pkg>
ロックファイルを重複排除する	pnpm dedupe（ロックファイルが変更された場合は、その後に pnpm install --ignore-scripts）
古いパッケージ／バージョン情報を確認する	pnpm outdated <pkg>
一時的なツール	pnpm --config.ignore-scripts=true dlx <pkg>@<version> <args...>（バージョンを固定してください。ロックファイルにある場合は pnpm exec を優先してください）

ライフサイクルスクリプト： 同じメッセージ内でユーザーが明示的に allow scripts と記載しない限り、pnpm install、pnpm add、pnpm remove では必ず --ignore-scripts を指定してください（実行されるスクリプトとリスクを明示してください）。pnpm dlx は --ignore-scripts を直接受け付けません。pnpm --config.ignore-scripts=true dlx を使用してください（dlx の後のフラグは実行されるバイナリに渡されます）。依存関係にビルドスクリプトが正当に必要な場合（ネイティブモジュールなど）は、スクリプトを実行せずに作業を完了し、特定の手動リビルド（例：pnpm rebuild <pkg>）を実行してよいかユーザーに確認してください。

鮮度チェック（72 時間以上） — 名前を指定したパッケージのバージョンを追加またはアップグレードするコマンド（pnpm add、新規またはアップグレードされた直接依存バージョンを指定する pnpm dlx）を実行する前に必ず行ってください。新しいパッケージ引数を伴わない通常の pnpm install / pnpm remove では不要です。

名前を直接指定したパッケージごとに、以下を実行します。

1. curl -s https://registry.npmjs.org/<package-name>
2. バージョンを解決します。固定された [email protected] → そのバージョン、範囲／latest／未指定 → dist-tags.latest
3. time["<version>"] を確認します
4. 公開から 72 時間未満 の場合は、作業を中止してください。パッケージ名、バージョン、正確な経過時間をユーザーに伝えてください。ユーザーが override freshness check と記載しない限り、より古く、正常に動作することが確認済みのバージョンを提案してください。
5. @grafana/* のスコープ付きパッケージは鮮度チェックの対象外です。--ignore-scripts は引き続き適用されます。

鮮度チェックに失敗した場合は、ユーザーの承認なしに別のバージョンへ置き換えてはいけません。

安全に関するルール

• ロックファイルの差分を確認しやすく保てるよう、小さな単位で作業してください。
• 未使用依存関係を検出するツールを鵜呑みにしてはいけません。インポート、設定ファイル、スクリプト、生成コードのフック、フレームワークの規約、プラグイン名、CLI、動的インポートを確認してください。
• package.json とロックファイルの依存関係の対応を検証するために、スクリプトやパーサーを作成してもかまいません。
• peerDependencies、optionalDependencies、パッケージの bin の使用状況、テストフィクスチャ、公開されるパッケージマニフェストは、より高いリスクがあるものとして扱ってください。
• セキュリティ、解析、暗号化、Unicode、URL の処理、日付／時刻、国際化、プラットフォーム互換性に使われる依存関係は、置き換えが同等であることを確認できない限り、削除したりインライン化したりしてはいけません。
• クリーンアップの一環としてパッケージマネージャーを切り替えたり、pnpm-lock.yaml を削除したり、ワークスペース構成を書き換えたりしてはいけません。
• pnpm dedupe は動作に影響する可能性があるものとして扱ってください。結果を採用する前にロックファイルの差分を確認し、対象を絞った検証を実行してください。
• 変更前と変更後を測定してください。直接依存関係の数、ロックファイルの行数またはエントリ数、パッケージ数、可能であれば node_modules の推定サイズを記録してください。

ステップ 1：ベースライン

以下を収集します。

• すべての package.json ファイルとワークスペースの境界（pnpm-workspace.yaml）。
• pnpm-lock.yaml、pnpm-workspace.yaml のセキュリティ設定（minimumReleaseAge、strictDepBuilds、blockExoticSubdeps、allowBuilds）、および .npmrc／CI フラグでのインストールポリシー（例：--frozen-lockfile、--ignore-scripts）。
• マニフェストのセクションごとの直接依存関係名：dependencies、devDependencies、peerDependencies、optionalDependencies。
• スクリプト、CI、またはリポジトリのドキュメントにある既存の検証コマンド。
• CI のスポットチェック（.github/workflows または同等の場所）：インストールでは pnpm install --frozen-lockfile を使用し、スクリプトのブロック設定はワークスペース設定と一致させる必要があります。実行のたびにロックファイルを再生成するワークフローにフラグを立てます。
• Renovate／Dependabot（存在する場合）：npm パッケージの minimumReleaseAge を記録します。クリーンアップ中に値を下げないでください。

ベースラインの指標を記録します：git status --short、wc -l pnpm-lock.yaml。node_modules がインストールされている場合は、プラットフォームに適したツールで容量を推定します。主な指標はロックファイルの削減量です。node_modules が存在することを前提にしないでください。

ステップ 2：未使用の直接依存関係を削除する

安全でない直接依存関係プロトコル — すべてのワークスペースの package.json の依存関係セクションをスキャンします。値がセマンティックバージョン範囲、workspace:、patch:、またはセマンティックバージョンへの npm: エイリアス以外のものにフラグを立てます。git:／github:／tarball の URL／user/repo の省略形／file:／link:／exec: などにフラグを立てます（/check-npm と同じ許可リスト）。フラグが立ったエントリを報告せずに削除しないでください。ユーザーが修正を依頼した場合を除き、別のセキュリティ強化 PR 向けに報告します。

静的解析ツールは出発点として使用し、証明として扱わないでください（knip、depcheck、またはリポジトリ固有のツール）。インストールされていない場合は、ピン留めした pnpm --config.ignore-scripts=true dlx <tool>@<version> <args...> を実行します（まずピン留めしたバージョンの新しさを確認します）。

候補ごとに、次を確認します。

• コード、設定、パッケージスクリプト、ビルドツール、テスト、ドキュメントで、パッケージ名と既知のインポートパスを検索します。
• 公開パッケージのマニフェスト、ピア依存関係の契約、プラグインローダー、CLI コマンド、または動的な require／import で必要とされていないか確認します。
• 実際の使用箇所が残っていない場合にのみ削除します。
• pnpm install --ignore-scripts（およびリポジトリのフラグ）を実行し、対象を絞った検証を行います。

スクリプトまたは設定でのみ使用されている場合は、削除する代わりに dependencies と devDependencies の間で移動することを検討します。

ステップ 3：モノレポ内の直接依存関係のバージョンを重複解消する

パッケージのマニフェスト間で、同じ直接依存関係が複数のバージョン／範囲で宣言されていないか確認します。まず既存のポリシーを使用します：厳密なピン留め、キャレット範囲、カタログ／プロトコルの使用、ワークスペースプロトコル、または一元化された制約。

• syncpack list-mismatches または同等のツールを使って検出します。
• パッケージ間で互換性のある同じバージョンを共有できる場合は、直接依存関係の範囲を標準化します。
• pnpm.overrides を追加する前に、マニフェストレベルでの一貫性を優先します。
• pnpm.overrides は、推移的依存関係の収束またはセキュリティ修正にのみ使用し、その理由を記録します。

重複解消後、pnpm install --ignore-scripts（およびリポジトリのフラグ）を実行し、マニフェストとロックファイルの差分を確認します。その後、pnpm dedupe を検討します。推移的な依存関係の解決結果が変わる可能性があるため、慎重に適用してください。

ステップ 4：推移的なロックファイルの依存関係閉包を順位付けする

重要な直接依存関係ごとに、その依存関係から到達可能な推移的なロックファイルのエントリ数を推定します。

次の両方を報告します。

• 合計の依存関係閉包：その依存関係から到達可能なすべてのパッケージ。
• 排他的な依存関係閉包：この依存関係を削除すると消え、他の直接依存関係によって保持されないパッケージ。

決定論的な測定を優先します。

1. ベースラインのロックファイル指標を保存します。
2. 所有するマニフェストから直接依存関係を一時的に削除します。
3. pnpm install --ignore-scripts（およびリポジトリのフラグ）を実行します。
4. ロックファイルの行数／エントリ数の減少と、パッケージ数の減少を測定します。
5. 次の依存関係を測定する前に、マニフェストと pnpm-lock.yaml の両方を元に戻します（例：git checkout -- <manifest> pnpm-lock.yaml）。

大きな推移的パッケージには pnpm why <pkg> を使用します。単純なサイズだけでなく、影響とリスクに基づいて順位付けします。

ステップ 5：リスクが低く、影響の大きいアップグレードを見つける

依存関係のクロージャランキングを使って、新しいマイナー／パッチバージョンにより推移的依存関係が減る、直接依存関係を対象にします。

候補ごとに、次の作業を行います。

• pnpm outdated で利用可能なメジャーバージョン以外のバージョンを確認します。
• 依存関係ツリーの変更について、変更履歴／リリースノートを確認します。
• 対象バージョンの最新性を確認してから、依存関係を1つずつ、または密接なまとまりごとにアップグレードします（pnpm add <pkg>@<version> --ignore-scripts）。
• pnpm install --ignore-scripts（およびリポジトリ固有のフラグ）を実行し、クロージャの指標を比較します。
• 対象を絞ったテストと、関連するビルド／型チェックのコマンドを実行します。

ユーザーが移行リスクを明示的に受け入れない限り、メジャーアップグレードは避けてください。

ステップ 6：簡単な使用箇所をインライン化する

クロージャランキングを使って、使用箇所は小さく明白である一方、推移的コストが大きい直接依存関係を見つけます。

次の条件をすべて満たす場合に限り、インライン化します。

• 使用箇所がごく小さく、簡単に完全な仕様を把握できます。
• 同等のコードを使うほうが、依存関係を残すより短いか明確です。
• 動作がテストでカバーされているか、簡単な特性テストでカバーできます。
• その依存関係が、クロスプラットフォーム、セキュリティ、解析、Unicode、ロケール、または仕様準拠に関するエッジケースを解決するものではありません。

必要な動作が単純な場合は、新しい置き換え依存関係を追加するより、ネイティブ API を優先してください。

ステップ 7：e18e のガイダンスを適用する

# Pin @e18e/cli@<version> after freshness check; disable scripts on the dlx install
pnpm --config.ignore-scripts=true dlx @e18e/cli@<version> analyze
pnpm --config.ignore-scripts=true dlx @e18e/cli@<version> migrate --dry-run

https://e18e.dev/docs/replacements/ も確認します。推奨事項は必須ではなく候補として扱い、バンドル／ランタイムの動作を検証してテストを実行してください。ユーザーの承認を得てから、e18e の置き換えを Replace-with-Better に分類します。

報告

測定した影響とともに、結果を要約します。

• /check-npm の結果（PASS／FAIL の概要。FAIL の場合は修正へのリンク）。
• 削除または移動した直接依存関係。
• 重複を解消した直接依存関係のバージョン。
• ロックファイルの行数／エントリー数の削減。
• 利用可能な場合は、パッケージまたは node_modules の推定削減量。
• 見送りとした影響の大きい候補とその理由（承認待ちの置き換えを含む）。
• ベースラインで確認された安全でないプロトコル／CI／Renovate に関する指摘（該当する場合）。
• 実行した検証コマンドとその結果。
• サプライチェーン：最新性を確認した（または免除した）バージョン、すべての install/add での --ignore-scripts の使用、pnpm dlx での --config.ignore-scripts=true の使用。

削除の判断が実行時のカバレッジではなく静的解析に依存する場合は、リスクを明示してください。

報告形式

依存関係のクリーンアップに関する調査結果のみに使用してください。GitHub Actions ワークフローのトリアージには使用しないでください。

各調査結果について、次を記載します。

• 根拠：パッケージ名とバージョン／範囲、マニフェストのパスとセクション、裏付けとなるシグナル（インポート箇所、pnpm why、knip／depcheck の検出、クロージャの測定値、/check-npm の行、またはpnpm install ポリシーに限りワークフローファイルとステップ）。
• 判断：Dependency triage のラベルから1つ選びます。
• 提案する変更：正確なマニフェスト／ロックファイルのコマンドまたは編集内容。まだ適用していない場合は、その旨を明記します。
• 理由：フットプリント（排他的／合計のクロージャ）、サプライチェーン、メンテナンス、または検証のリスク。
• ユーザーによる確認が必要な事項：実行すべきテスト／ビルド／型チェック、peer／プラグイン／CLI の利用者、公開パッケージまたは動的インポートのリスク、Replace-with-Better または新しい直接依存関係の追加に必要な承認。

重要な調査結果では、1行の要約ではなく、パッケージごと（またはプロトコル／CI に関する指摘ごと）に1つのブロックを使用してください。