peerconflict

peerconflict

インストールがピア依存関係エラーで失敗し、出力が入れ子になった要件で埋め尽くされてしまうことがあります。peerconflict は解決済みのツリー、つまりインストール済みパッケージすべての名前とバージョン、および各パッケージが宣言するピア要件を受け取り、問題を読みやすいグラフとして示します。

• エッジ — ピア要件ごとに 1 つのエントリがあり、充足しているかどうかが示されます。ピアが実際にインストールされており、そのインストール済みバージョンが必須範囲に収まっている場合にのみ、エッジは充足しています。
• 競合 — 充足していないエッジです。ピアがまったくインストールされていない場合は missing、インストールされているものの範囲外の場合は version として分類されます。また、app requires peer react (^18.0.0) but 17.0.2 is installed のような 1 行の詳細が示されます。
• 解決策 — 競合しているピアごとに 1 つのエントリがあり、競合の原因となる要件、各範囲を満たす最低バージョン、変更を最小限に抑える提案が示されます。ピアが存在しない場合はインストールし、存在する場合はバージョンを変更します。提案は常に列挙されたすべての範囲に照らして説明されるため、そのピアを必要とするすべてのパッケージに一度に対応できます。

バージョンは MAJOR.MINOR.PATCH 形式で、それ以外は認められません。範囲はツールが定義する文法に従います。* はすべてのバージョンを許可し、完全一致のバージョンはそのバージョンのみを許可します。^x.y.z は、基準バージョンから次の破壊的変更境界（ただし、その境界は含みません）までを許可します。通常の 0.x 系の制約も適用されるため、^0.2.3 は 0.3.0 より前まで、^0.0.3 は 0.0.3 のみを許可します。~x.y.z は同じマイナーバージョン内のパッチレベルの変更を許可し、>=x.y.z は基準バージョン以上を許可します。この文法に含まれないものはすべて検証エラーです。また、パッケージ名の欠落や重複、不正な形式のバージョン、同じピアを重複して列挙するパッケージ、自身をピアとして宣言するパッケージもエラーになります。エラーには問題のあるパスが示され（例：packages[0].peers[1].range is not a supported range: "=>1.0.0"）、部分的な説明は生成されません。単にツリーに存在しないピアはエラーではなく、missing の競合として扱われます。処理は純粋かつローカルで行われ、ネットワークや設定は使用せず、渡された入力以外のファイルも読み込みません。

CLI

npx @reneturcios/peerconflict explain --input args.json
npx @reneturcios/peerconflict --version

args.json には、引数オブジェクト全体を格納します。

{
  "packages": [
    { "name": "react", "version": "17.0.2" },
    {
      "name": "app",
      "version": "1.0.0",
      "peers": [{ "name": "react", "range": "^18.0.0" }]
    }
  ]
}

各パッケージの peers は、デフォルトで [] です。説明は JSON として出力されます。

{
  "ok": false,
  "conflicts": [
    {
      "from": "app",
      "peer": "react",
      "range": "^18.0.0",
      "installed": "17.0.2",
      "type": "version",
      "detail": "app requires peer react (^18.0.0) but 17.0.2 is installed"
    }
  ],
  "edges": [
    { "from": "app", "to": "react", "range": "^18.0.0", "satisfied": false }
  ],
  "resolutions": [
    {
      "peer": "react",
      "installed": "17.0.2",
      "required_by": [{ "from": "app", "range": "^18.0.0", "lowest": "18.0.0" }],
      "suggestion": "change react from 17.0.2 to a version satisfying every listed range"
    }
  ]
}

終了コード：成功時は 0、実行時エラー（読み取り不能または無効な入力ファイル、無効な入力を含む）時は 1、使用方法のエラー時は 2 です。

MCP server

npx -y @reneturcios/peerconflict mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "peerconflict": {
      "command": "npx",
      "args": ["-y", "@reneturcios/peerconflict", "mcp"]
    }
  }
}

Tools

• explain_peer_conflict — インストール済みツリーにおけるピア依存関係の競合を説明します。
  • packages（配列、必須、1 件以上）— {name, version, peers?} オブジェクトとしてのパッケージです。name はセット内で一意で、version はインストール済みの MAJOR.MINOR.PATCH 形式のバージョンです。各 peers エントリは {name, range} 要件です。

{ok, conflicts, edges, resolutions} を返します。

Docker

docker run -i ghcr.io/cloudcorprecords/peerconflict
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/peerconflict explain --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios