dependency-doctor

Dependency Doctor

ユーザーのマシンにある依存関係マニフェストを1つ調べ、表面的で直接的な落とし穴を確認します。各項目をわかりやすく説明し、レビューしやすい小規模な修正を提案します。pip や uv の依存関係解決に失敗した原因を診断するものではありません。

これは、ユーザーが選んだプロジェクトで使うローカル開発ツールです。リポジトリ全体に適用する lint ルールでも、CI のゲートでも、無関係なアプリに依存関係ポリシーを強制するための提案でもありません。

使用する場合

• ユーザーが依存関係マニフェストの確認、監査、診断、検死を依頼した場合
• より詳細なインストールデバッグの前に、マニフェストに直接起因する問題がないかを確認したい場合
• 古いピン、バックポート、重複エントリ、依存関係の劣化を疑っている場合
• 依存関係に問題がないかを尋ねられた場合

使用しない場合

• 診断せずに現在の依存関係をインストールする場合
• すべてのパッケージをアップグレードしたり、新しいパッケージを追加したりする場合
• 脆弱性の完全な監査。CVE の確認には pip-audit、npm audit、またはプロジェクトで承認済みのセキュリティスキャナーを使用してください
• リポジトリ全体に適用する CI チェックを作成する場合。このスキルはユーザーがローカルで呼び出すものです

マニフェストを選ぶ

ユーザーが指定したパスを使用します。パスが指定されておらず、マニフェストが複数ある場合は、どれを調べるか尋ねてください。リポジトリ全体を調べたり、このスキルが呼び出されたというだけで何かを編集したりしてはいけません。

対応する入力：

• requirements.txt
• PEP 621 または一般的な Poetry の依存関係テーブルを使用する pyproject.toml
• package.json の依存関係セクション

オフライン診断を実行する

このスキルのディレクトリから実行します。

python3 scripts/dep_doctor.py /path/to/requirements.txt --json

デフォルトのパスは完全にオフラインです。選択されたマニフェストのみを読み取ります。レポートの形式は次のとおりです。

{
  "file": "/path/to/requirements.txt",
  "findings": [
    {
      "severity": "high",
      "kind": "stdlib-shadowing",
      "package": "pathlib",
      "line": 4,
      "why": "...",
      "fix": "..."
    }
  ],
  "summary": {
    "total": 1,
    "by_severity": {"high": 1},
    "by_kind": {"stdlib-shadowing": 1},
    "online": false
  }
}

オフラインチェックでは、次の項目を確認します。

• パッケージとして公開されている Python 標準ライブラリ名
• 対応する Python バージョンではインストールすべきでない既知のバックポート
• 使用可能なバージョン制約がない依存関係
• 繰り返し記載されたパッケージエントリ
• 同じパッケージに対する、互いに矛盾する正確なピン

package.json では、Python 固有の標準ライブラリとバックポートのチェックは適用されません。依存関係の未ピンおよび重複エントリのチェックは引き続き行います。

診断結果を説明する

結果を提示する前に、references/dependency-pitfalls.md を読んでください。重要度の高い項目から説明し、次に中、低の順に続けます。各項目には次の内容を含めてください。

1. パッケージとソースの行
2. 何が壊れる可能性があるか
3. 推奨する修正

すべての範囲指定を競合と呼んではいけません。決定論的なコアが競合する制約として報告するのは、正確なピンが食い違う場合だけです。複数行に分かれた互換性のある制約は重複エントリであり、まとめる必要があります。

該当項目がなければ、何を確認したかを述べ、確認範囲の限界にも触れてください。問題のないレポートであっても、CVE 監査や完全な依存関係リゾルバーの結果ではありません。

任意の PyPI yanked チェック

オンラインチェックでは、パッケージ名と正確にピンされたバージョンが pypi.org に送信されます。ユーザーが以前にオフライン診断を依頼していた場合でも、有効にする前に許可を求めてください。

python3 scripts/dep_doctor.py /path/to/requirements.txt --json --online

特定の Python リリースが報告されるのは、そのリリースのすべてのファイルが yanked とマークされている場合に限られます。ネットワーク障害はオフライン診断の結果を隠さず、重要度の低い項目として報告されます。

修正は提案し、黙って適用しない

レポートを説明した後、対象を絞った編集を提案してください。マニフェストを変更する前に、承認を待ちます。

• 対応対象の Python プロジェクトから標準ライブラリのパッケージを削除する
• 古いバックポートを削除する。または、古いランタイムで本当に必要な場合は Python バージョンマーカーを追加する
• 未ピンの依存関係について、作業環境にインストールされているバージョンを確認し、それが意図したものか確かめたうえで、レビュー済みの正確なピンを提案する
• 重複エントリは1つにまとめ、互換性のある制約を統合する
• 正確なピンが競合する場合は、バージョンを選ぶ前に依存元を確認する
• yanked されたピンを、テスト済みで yanked されていないリリースに置き換える

承認済みの編集を行った後は、オフライン診断を再実行し、プロジェクト既存のインストールまたはテストコマンドも実行します。新しい CI ゲートを導入してはいけません。

ファイル

• scripts/dep_doctor.py：標準ライブラリのみで動作するマニフェストパーサーと診断エンジン
• references/dependency-pitfalls.md：報告されたリスクの判断ガイド