PHP ローカル変数酷使度ツールに閾値チェック機能を追加しました

GitHub Copilot(Claude 3.7 Sonnet)に草稿を書いてもらった記事です。

はじめに

PHPプロジェクトの品質管理において、コード品質の定量的な測定は重要な要素です。これまで開発してきた「PHPローカル変数酷使度」は、ローカル変数の使用パターンを解析し、コードの可読性や保守性に影響を与える変数の使用状況を評価するツールです。

今回、このツールにCI/CD環境との統合をより簡単にする新機能「checkモード」を追加しました。この記事では、この新機能の概要と活用方法について紹介します。

変数酷使度とは

ローカル変数酷使度（Variable Hard Usage）とは、関数やメソッド内でローカル変数がどれだけ複雑に使用されているかを測る指標です。変数の参照範囲が広かったり、更新頻度が高かったりすると、コードの理解や保守が難しくなります。

これまでのツールでは、この指標を計算して表示するだけでしたが、今回の機能追加により「一定の閾値を超えるローカル変数酷使度が検出された場合に自動的にエラーとして扱う」機能を追加しました。

新機能: checkモード

機能概要

新しく追加された「checkモード」には以下の特徴があります：

1. 閾値の設定: --threshold=<数値> オプションでローカル変数酷使度の許容上限を設定できます
2. エラーコード返却: 指定した閾値を超えるローカル変数酷使度が検出された場合、終了コード 2 を返します
3. 詳細レポート: 閾値、結果ステータス、閾値を超えたスコープの一覧を含むJSONレポートを出力

使用方法

# デフォルト閾値(200)でチェック
$ vendor/bin/php-variable-hard-usage check src/


# カスタム閾値でチェック
$ vendor/bin/php-variable-hard-usage check --threshold=500 src/ tests/


# 特定のファイルやディレクトリをチェック
$ vendor/bin/php-variable-hard-usage check --threshold=300 src/Command.php config/

終了コード

終了コード 0: 成功 – 解析エラーなし、閾値を超えるスコープなし
終了コード 1: 解析失敗 – ファイル解析中にエラー発生
終了コード 2: 閾値超過 – 指定したローカル変数酷使度閾値を超えるスコープあり

出力例

{
    "threshold": 500,
    "result": "failure",
    "scopes": [
        {
            "file": "src/Parse/VariableParser.php",
            "namespace": "Smeghead\\PhpVariableHardUsage\\Parse",
            "name": "VariableParser::collectParseResultPerFunctionLike",
            "variableHardUsage": 655
        },
        {
            "file": "src/Command/SingleCommand.php",
            "namespace": "Smeghead\\PhpVariableHardUsage\\Command",
            "name": "SingleCommand::execute",
            "variableHardUsage": 530
        }
    ]
}

CI/CD環境との統合

この新機能は、CI/CD環境での自動チェックに特に役立ちます。例えば、GitHub Actionsで以下のようなワークフローを設定できます：

name: Code Quality Check

on: [push, pull_request]

jobs:
  variable-usage-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress
      - name: Check variable hard usage
        run: vendor/bin/php-variable-hard-usage check --threshold=500 src/

このワークフローでは、コードがプッシュされるたびにローカル変数酷使度チェックが実行され、閾値を超える変数が見つかった場合はビルドが失敗します。

実装の工夫点

今回の機能追加にあたり、いくつかの設計上の工夫を行いました：

トレイトの活用: 共通コードを ScopesTrait に抽出し、コードの重複を避けつつ柔軟な拡張を可能にしました
閾値のデフォルト値: 閾値が指定されない場合は、デフォルト値（200）を使用します
明確なエラーコード: エラーの種類によって異なる終了コードを返すことで、問題の特定を容易にしました

まとめ

今回追加した「checkモード」により、ローカル変数酷使度の基準を明確に設定し、それを自動的に検証することができるようになりました。これはコード品質の継続的な維持に役立ち、特にチーム開発において一定の品質基準を保つのに効果的です。この機能を活用することで、プロジェクトの早い段階で変数の使用パターンに関する問題を検出し、より読みやすく保守しやすいコードベースを維持することができます。今後も、ツールの機能拡張や使いやすさの向上に取り組んでいきます。皆さんのフィードバックや貢献をお待ちしています！

ぜひ試してみて、あなたのプロジェクトのローカル変数酷使度をチェックしてみてください。GitHub上のプロジェクトリポジトリは https://github.com/smeghead/php-variable-hard-usage で、フィードバックやコントリビューションを歓迎しています。

週記くらい