Avouch: Git対応のASTリンターで、変更したPythonコードだけをレビュー

ほとんどのPythonリンターはリポジトリ全体を対象にします。コードベース内のすべての問題をフラグします。継承したレガシーコードも含めてです。Avouchは異なるアプローチを取ります。Gitに次回のコミットで触れるファイルを問い合わせ、標準のastモジュールでそれらのファイルだけを解析し、avouch.tomlで設定した制限値に対する構造上の問題を報告します。

デーモンも、ネットワークも、維持すべきパスリストもありません。git pushの数秒前に実行し、フラグされたものを修正して、プッシュするだけです。

存在理由

Avouchの核となる考え方は、レビュー対象はリポジトリではなく差分であるということです。実行時にGitからレビュー対象を計算します（git diff HEAD --name-onlyに加えて未追跡ファイル）。したがって、すべての発見は、これからプッシュしようとしている作業に起因するものであり、継承したレガシーコードに起因するものではありません。

メトリクスは正確です。パラメータ数、ネストの深さ、行の範囲は、正規表現ではなくASTから取得されます。メトリクスを正確に計算できない場合、Avouchはそれを主張しません。

エラーはデータです。読み取れない、または構文的に壊れたファイルは、レポートのERRORエントリになります。1つの壊れたファイルが他のファイルのレビューをキャンセルすることはありません。

Avouchはレビューしますが、ゲートはしません。終了コードは結果を示します — 0はクリーン、1は違反が見つかった、2はAvouchエラー — ただし、強制はオプトインのインターフェースに属するものであり、毎回のプッシュ前に実行するツールに属するものではありません。

ランタイムは標準ライブラリです。gitサブプロセスの呼び出しが3回とast/tomllib。維持すべきデーモンはありません。ランタイムはリポジトリではなく、差分のサイズによって制限されます。

インストールとクイックスタート

Python 3.10+（ルールはast.Matchを使用、設定はtomllibを使用）とPATH上のGitが必要です。pip install avouchでインストールします。

インターフェースは、小さなオプションフラグのセットを持つ1つのコマンドです：

cd your-repo
# ... 変更を加える ...
avouch            # 人間向けレポート
avouch --json     # stdoutに1つのJSONドキュメント
avouch --docs     # 組み込みドキュメント。レビューは実行されません
avouch --version  # バージョンを表示して終了
avouch --verbose  # stderrにステップバイステップのレビュー詳細
avouch --quiet    # 解析し、レポートを印刷せず、終了コードのみ
avouch --changed  # HEADと比較した変更ファイルのコンパクトな追加/削除ビュー
avouch --staged   # 次のコミットのためにステージされたファイルのみをレビュー
avouch --all-files  # 差分だけでなく、対象となるすべてのPythonファイルをレビュー
avouch --not-git  # ディスク上の対象となるすべての.pyファイルをレビュー。Gitリポジトリは不要
avouch --help     # すべてのフラグ

レビュー対象はGitによって定義されるため、呼び出し時に設定するものはありません。Avouchは、HEADと比較して変更された追跡ファイルと、未追跡の.pyファイルをレビューします。削除されたパスと非.pyファイルはスキップされます。コミットされ、触れられていないファイルは出力に表示されません。生成されたように見えるファイル（generated.py、*_generated.py、codegen.py、autogen.pyなど）もスキップされます。

出力とCI統合

自動化とCIのために、--jsonはレビューをstdoutに単一のJSONドキュメントとして印刷します。人間が読めるテキストは混在しません。各違反には、ルールID、重大度、メッセージ、ファイル、コンポーネント名、種類（func、class、またはfile）、行が含まれます。ドキュメントは安定したバージョン管理された契約です：versionはスキーマバージョン、toolはエミッタを識別し、同じ入力は常に同じJSONを生成します — 色、タイムスタンプ、診断情報は漏れません。

終了コードは通常モードとまったく同じように動作するため、avouch --jsonはCIをゲートできます：stdoutを解析して発見事項を取得し、終了ステータス（0クリーン、1違反、2Avouchエラー）に反応します。

色は、stdoutがTTYの場合にのみ出力されるANSIコードです。パイプされた出力はプレーンなので、avouch | tee review.logとCIキャプチャはきれいに機能します。ランタイムエラーはstderrに書き込まれるため、stdoutはパイプと--jsonキャプチャのためにクリーンなままです。

設定とルール

Avouchはavouch.tomlを介して設定されます。ここで、最大パラメータ数、ネストの深さ、行の長さなどの制限値を設定します。ルールはSCR002（裸のexcept）やSCR014（パラメータが多すぎる）などのIDで識別されます。このツールは拡張可能になるように設計されています — 独自のルールを追加できます。

AvouchはPythonのリンティングに対する新鮮なアプローチです。実際に変更したものだけをレビューすることで時間を尊重し、既存の問題に溺れさせないことでコードベースを尊重します。プッシュ前に高速で差分に焦点を当てたフィードバックを求めるPython開発者にとって、Avouchは一見の価値があります。