【要約】PHPStan×GitHub Pagesで始める『コードベース健康診断』― 認知複雑度を定点観測して負債を可視化するダッシュボード構築 [Qiita_Trend] | Summary by TechDistill
> Source: Qiita_Trend
Execute Primary Source
// Problem
開発チームがコード品質を維持しようとする際、個別のプルリクエスト（PR）単位のチェックだけでは不十分な状況に直面した。PRでのチェックは「今書いたコード」の品質には有効だが、プロジェクト全体の負債がどのように推移しているかが見えない。具体的には以下の課題がある。
- ・違反件数の増減が把握できない。
- ・どの関数やクラスが特に複雑かを特定できない。
- ・過去の計測結果と比較して、蓄積状況を可視化できない。
// Approach
著者は、外部サービスへの依存を排除し、GitHub Pagesのみで動作する軽量な可視化パイプラインを構築した。PHPStanの拡張機能で計測したデータを、Pythonスクリプトで加工・蓄積する構成である。
- ・
tomasvotruba/cognitive-complexityを用いて認知複雑度を計測。 - ・PythonでJSONを解析し、閾値に対する比率（ratio）で重大度を分類。
- ・
update_history.pyにより、時系列データをhistory.jsonに蓄積。 - ・
history.js（JSON-as-JSパターン）を用いてCORS問題を回避。 - ・Chart.jsを用いて、リポジトリ別の推移グラフを生成。
// Result
この仕組みの導入により、開発チームはコードベースの健康状態を「コンパス」として利用できるようになった。プロジェクト全体の複雑度の推移が可視化され、リファクタリングの優先順位を客観的に判断できる環境が整った。
- ・複雑度の推移を折れ線グラフで把握可能。
- ・重大度（Critical/High/Medium）別の積み上げ棒グラフを提供。
- ・AIコメント機能により、前回比の洞察をダッシュボードに表示。
Senior Engineer Insight
> 非常に実戦的かつ賢明な設計である。高価な外部SaaSに頼らず、既存のCI/CDとGitHub Pagesという「既に持っている資産」を組み合わせることで、導入コストと運用負荷を極限まで抑えている。特に、閾値に対する比率（ratio）で重大度を判定する手法は、リポジトリ間での比較を可能にする優れた抽象化だ。ただし、計測スクリプトの保守や、計測結果をいかに具体的な改善アクション（リファクタリング工数の確保など）に結びつけるかという、組織的な運用設計が真の成功の鍵となる。