wp-phpstan-review

WordPress PHPStan レビュースキル

概要

WordPress プロジェクトで PHPStan を利用する際の、体系的なレビューガイダンスです。基本原則： 静的解析は、実際のバグを検出できる厳密さを保ちながら、ノイズにならないようにします。また、WordPress 固有の拡張機能やスタブは、意図を持って組み込む必要があります。レビューでは、設定ファイル、インクルード、ベースライン、CI との統合、解析対象パス、ブートストラップファイル、WordPress スタブ、段階的な導入戦略を確認します。

使用するタイミング

次の場合に使用します：

• phpstan.neon、phpstan.neon.dist、または CI 設定をレビューするとき
• WordPress プラグインやテーマへの PHPStan 導入を計画するとき
• ベースラインの使用方法や無視されたエラーを監査するとき
• szepeviktor/phpstan-wordpress の設定をレビューするとき
• 解析範囲、ブートストラップファイル、スタブ設定を確認するとき

次の場合には使用しません：

• ランタイムのパフォーマンスレビュー
• 静的解析に焦点を当てない PHPUnit やブラウザーテストの戦略
• 解析設定と関係のない一般的な PHP のリファクタリング

コードレビューワークフロー

1. 解析のエントリーポイントを特定する

   • phpstan.neon / phpstan.neon.dist
   • Composer の require-dev
   • CI ワークフローとスクリプト
   • ブートストラップファイルまたはスタブファイル

2. まず基本設定を確認する

   • 設定ファイルの命名とインクルード
   • レベルと解析対象パス
   • 除外項目とブートストラップファイル
   • WordPress 固有の拡張機能やスタブが実際に読み込まれているか

3. ベースラインと無視の方針をレビューする

   • ベースラインは解析を段階的に導入するために使い、新たな問題を永久に埋もれさせない
   • 無視するエラーには明確な意図があり、レビュー可能である
   • 新しいコードには、引き続きより高い基準を適用する

4. CI の使いやすさをレビューする

   • 決定性のあるコマンド
   • 正しい設定ファイルのパス
   • 妥当な失敗時の動作
   • ローカル設定と CI 設定の意図しない乖離がないこと

5. 指摘事項を分類する

   • CRITICAL： PHPStan が設定されているように見えても、実際にはプロジェクトのコードを解析していない。WordPress 拡張機能がない。ベースラインがすべての問題を無期限に隠している
   • WARNING： 除外範囲が広すぎる。ベースラインの運用が古くなっている。設定の分割がわかりにくい。解析対象パスが狭すぎる
   • INFO： レベルを上げる、ブートストラップの動作を文書化する、または無視の範囲を絞り込む余地がある

ファイル種別ごとの確認事項

PHPStan 設定

• CRITICAL：設定で有意義なプロジェクトパスが解析されていない
• WARNING：ignoreErrors または除外の範囲が広すぎる
• WARNING：拡張機能がインストールされているのに、拡張機能インストーラーが存在しない場合に設定へ追加されていない
• INFO：コミット済みの .dist ファイルをベースに、ローカルのオーバーライドを phpstan.neon に分けられる

ベースラインファイル

• WARNING：意図的に問題を修正する代わりに、ベースラインを気軽に再生成している
• WARNING：解析設定がまだ不十分に見える段階でベースラインを使用している
• INFO：指摘事項を修正する場合と、ベースラインを更新する場合の判断基準を文書化できる

CI と Composer

• WARNING：CI コマンドが、文書化されたローカルコマンドと実質的に異なる
• WARNING：require-dev にスタブや拡張機能が含まれているが、設定で正しく使用されていない
• INFO：スクリプトや出力形式をより明確にできる

すばやく検出するための検索パターン（PST-21）

次の rg コマンドを使用すると、PHPStan の設定をすばやく見つけられます。

設定と CI の検出

rg -n "phpstan|phpstan\\.neon|phpstan\\.neon\\.dist|phpstan-baseline" . -g '*.{neon,php,json,md,yml,yaml}'
rg -n "vendor/bin/phpstan|composer .*phpstan|phpstan analyse" . -g '*.{json,md,yml,yaml,sh}'

WordPress 固有の設定

rg -n "szepeviktor/phpstan-wordpress|php-stubs/wordpress-stubs|extension\\.neon" . -g '*.{json,neon,md}'
rg -n "bootstrapFiles|scanFiles|scanDirectories|paths|ignoreErrors|includes:" . -g '*.neon*'

参照ファイル

• references/config-and-bootstrap.md - 設定の構造、インクルード、解析対象パス、ブートストラップファイル、WordPress 拡張機能の組み込み
• references/baseline-and-ci.md - ベースラインの方針、CI との統合、段階的な導入の目安
• references/wordpress-stubs-guide.md - phpstan-wordpress、WordPress スタブ、WordPress の静的解析における一般的なトレードオフ
• references/sample-phpstan.neon.dist - WordPress プラグインやテーマ向けの共有設定ファイルのサンプル

出力形式（PST-23）

指摘事項ごとに、次の内容を含めてください。

1. 重大度：CRITICAL、WARNING、または INFO
2. ファイルと行番号
3. 静的解析の問題の概要
4. WordPress の PHPStan によるカバレッジやシグナルの品質にとって、なぜ重要なのか
5. 推奨する修正方法

問題が見つからなかった場合は、その旨を明確に伝え、ベースラインの増加、狭い解析範囲、文書化されていないローカルオーバーライドなど、残るリスクがあれば言及してください。