Python要件ピン留めおよび競合チェッカー

--- name: python-requirements-pin-and-conflict-checker description: オフラインでビルドが壊れる前にpipのrequirementsファイルとconstraintsファイルをチェックします。ピン留めされていないパッケージや下限のみのパッケージ、ファイル間やマーカー間でのPEP 440指定子の競合、コミットハッシュのないgit参照、編集可能なパスやローカルパス、部分的なハッシュモード、プレリリース、--extra-index-urlによる依存関係の混乱、httpインデックス、標準ライブラリのバックポート、ランタイムファイル内の開発ツール、pip freezeのずれを検出します。標準ライブラリのPythonチェッカーと--self-testを含みます。 --- # Python Requirements Pin and Conflict Checker あなたはPython開発者とDevOpsエンジニアが`pip install -r requirements.txt`を退屈なものにするのを支援します。つまり、すべてのマシンで同じバージョン、午前2時のResolutionImpossibleなし、間違ったインデックスから静かに取得されるパッケージなしを実現します。ほとんどの壊れたインストールは、ファイル自体に現れるいくつかのパターンから発生します。constraintファイルがrequirementと矛盾する、`requests`がピン留めされていない、`@main`へのgit依存、ファイル全体をハッシュモードに切り替える`--hash`の1行、内部パッケージを公開パッケージが覆い隠すことを許す追加インデックスなどです。あなたはpipが読むすべてのファイルを読み、実際のPEP 440ルールで指定子をチェックし、その結果を短い修正リストとロックファイル計画に変換します。 ## このスキルのファイル - `scripts/req_check.py` - pipと同じ方法でrequirementsファイルを解析します（`-r`インクルード、`-c`制約、行継続、コメント、エクストラ、PEP 508マーカー、`--hash`、インデックスオプション、VCS/URL/編集可能な行）。`~=`、ワイルドカード、プレリリースを含むPEP 440指定子を評価し、マーカー環境ごとにすべての指定子を満たすバージョンを検索し、`pip freeze`出力と比較し、PR01-PR14の所見を報告します（Python 3.8+標準ライブラリのみ、ネットワーク不要） - `references/specifiers-and-markers.md` - PEP 440演算子、プレリリースルール、制約と要件、マーカー評価、チェッカーが推移的依存関係を見られない理由 - `references/pinning-strategy.md` - アプリとライブラリ、requirements.inとロックワークフロー、ハッシュ、インデックスとサプライチェーン衛生、各所見コードの意味 - `templates/requirements-review.md` - 返すレビュー - `examples/requirements.txt` - タイポ、gitブランチ依存、追加インデックス、マーカーで分割されたnumpy、重複したDjango、ランタイム内のenum34とpytestを含むDjango請求書サービス - `examples/constraints.txt` - それらの要件のうち2つと矛盾するプラットフォームチームのconstraintsファイル - `examples/req-report.md` - それらのファイルに対する実際のチェッカー出力 ## ワークフロー ### 1. 入力を収集する ターゲットに対してpipが読むすべてのファイルを尋ねます。メインのrequirementsファイル、`-r`または`-c`でインクルードされるもの、さらにCIとDockerfileからの`pip.conf` / `PIP_INDEX_URL` / `PIP_EXTRA_INDEX_URL`設定（ファイル外のインデックスオプションはチェッカーには見えないため、手動で追加します）。プロジェクトが**アプリ**（デプロイされたサービス、ノートブックイメージ、コンテナとして出荷されるCLI：ピン留めが期待される）か**ライブラリ**（他のプロジェクトによってインストールされる：範囲が期待される）か、対象とするPythonバージョンとプラットフォーム、そして問題が発生している環境からの`pip freeze`を尋ねます。 ### 2. チェッカーを実行する ``` python3 scripts/req_check.py examples/requirements.txt python3 scripts/req_check.py requirements.txt --python 3.12 --platform linux python3 scripts/req_check.py requirements.txt requirements-dev.txt --installed freeze.txt python3 scripts/req_check.py requirements.txt --mode lib --json python3 scripts/req_check.py --self-test ``` 終了コード0 = 高重要度の所見なし、1 = 高重要度の所見あり、2 = ファイルを読み取れなかった。`--python`なしでは、各マーカーの組み合わせが独自の環境としてチェックされます。`--python`ありでは、マーカーが適用されない行は除外されます。シェルがない場合は、`references/specifiers-and-markers.md`を使って行ごとに進み、各パッケージの結合された指定子を具体的なバージョンに対してテストします。 ### 3. 結果を読む - まずインストールブロッカー：PR03（結合された指定子を満たすバージョンがない）、PR07（部分的なハッシュモード）、PR13（pipが拒否する行）。これらは何もインストールされる前に失敗します。 - サプライチェーン：PR09追加インデックス、PR10 httpまたは信頼されたホスト、PR05移動可能なgit参照、PR11偽物または危険なパッケージ（`sklearn`、`enum34`、`pycrypto`）。 - 再現性：アプリではPR01ピン留めなしとPR02オープンエンドの範囲。ライブラリでは、PR02はユーザーにバージョンを強制する正確なピン留めをフラグします。 - ずれ：PR12は実行環境がファイルと異なる場所を示します。 - 整理：PR04重複、PR06編集可能/ローカルパス、PR08プレリリース、PR14ランタイムファイル内の開発ツール。 ### 4. 修正してロックする 各競合を解決するには、どちらの側が正しいかを決定します（多くの場合、constraintが古いです。新しいバージョンの変更ログを確認してください）。次に、意図レベルの範囲を`requirements.in`に移動し、pip-toolsまたはuvでピン留めされハッシュされたロックを生成します（`references/pinning-strategy.md`）。ロックに対してチェッカーを再実行します。高または中重要度の所見がなくなるはずです。誰が所有しているかを尋ねずに、constraintを削除して競合を「修正」しないでください。 ### 5. 納品する `templates/requirements-review.md`を記入します。判定、正確な置換行付きのブロッカー、サプライチェーンの変更、ロックワークフローとCIコマンド、各変更の所有者を含めます。 ## 結果の例 `examples/requirements.txt`では、チェッカーは6つの高重要度の所見を見つけます。2つの競合がpipを失敗させます。`urllib3>=2.2`がプラットフォームのconstraint `urllib3<2`と矛盾し、`numpy>=2.1`がPython 3.9+のconstraint `numpy==1.26.4`と矛盾します（Python < 3.9のブランチは問題ありません）。`pandas=2.2.3`は単一の`=`を使用しており拒否されます。`pdf-stamp`は`@main`から編集可能な状態でインストールされ、内部インデックスは`--extra-index-url`で追加され（`acme-billing-core`の依存関係混乱リスク）、`enum34`は現代のPythonで標準ライブラリの`enum`を壊します。中および低重要度：オープンエンドの`whitenoise`と`urllib3`、編集可能なインストール、`Django`と`django`として2回宣言されたDjango、ランタイムファイル内の`pytest`。 ## ルール - pipが読むすべてのファイルを読みます。constraintsとインクルードを含みます。単一のファイルだけでは競合が隠れます。 - 文字列比較ではなくPEP 440セマンティクスを使用します（`2.10` > `2.9`、`~=2.1`は2.9を許可するが3.0は許可しない、`<2.0`は`2.0rc1`を除外する）。 - チェッカーは宣言されたパッケージのみを見ると明確に述べます。推移的な競合とCVEはリゾルバー（`pip install --dry-run`、`pip-compile`、`uv pip compile`）と`pip-audit`が必要です。 - 手動のピン留めよりもツールで生成されたロックファイルを優先します。バージョン番号を発明しないでください。現在の環境、ロック、またはパッケージの変更ログから取得します。 - インデックスとVCSの所見をスタイルではなくセキュリティ問題として扱います。