upgradepath

upgradepath

依存関係のアップグレードが一度の変更で済むことはほとんどありません。現在のバージョンから目的のバージョンまでにある各リリースには、それぞれ互換性を破る変更があり、どの順序で進むかが重要です。upgradepath は、単一の依存関係について、その道筋を計画します。名前、現在のバージョン、目的のバージョン、および各リリースについて記録した互換性を破る変更と非推奨フラグを含む既知のリリース情報を指定すると、その間の順序付きステップ、各ステップで発生する変更、および経路全体の判定を返します。

外部から情報を取得することはありません。バージョンを検索することも、変更を推測することもありません。計画内のすべての情報は呼び出し元から提供されたものです。現在のバージョンより数値的に大きく、目的のバージョン以下のリリースのみがステップとなり、昇順に並べられます。バージョンは x.y.z 形式で記述され、数値として比較されるため、01.2.3 と 1.2.3 は同じバージョンです。これにより指定されたリリースが重複する場合もあり、その場合はエラーになります。目的のバージョンは現在のバージョンより大きくなければならず、そうでない場合はステップを選ぶ前に計画が拒否されます。

ステップに加えて、結果には、現在のバージョンから各ステップを順にたどったときに経由するメジャーバージョンの境界数が含まれ、最後のステップが実際に目的のバージョンに到達するかどうかも示されます。リリース一覧が目的のバージョンに届かずに終わっても計画は生成されますが、reaches_target に到達しないことが明示されます。判定は固定の優先順位で決まります。ステップがまったくない場合は no_path です。互換性を破る変更がない経路は clean です。互換性を破る変更の合計が3つ以下の場合は manageable、それを超える場合は major_effort です。そのため、ステップがない計画は互換性を破る変更の合計が0であっても no_path になります。

各ステップには、指定されたバージョンと互換性を破る変更がそのまま含まれ、それらの変更数と、リリースが非推奨かどうかが示されます（呼び出し元が指定していない場合は false）。不正な入力（name がない、空、または文字列でない場合、バージョンが x.y.z の形式に準拠していない場合、releases リストがない、配列でない、または空の場合、不正なリリース項目、リリースバージョンの重複、あるいは目的のバージョンが現在のバージョンより大きくない場合）は、該当するパスを示す検証エラーとなり、部分的な結果は返されません。リリース項目内を含む不明な追加フィールドは無視されます。

CLI

npx @reneturcios/upgradepath plan --input args.json
npx @reneturcios/upgradepath --version

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

{
  "name": "widgetlib",
  "current": "1.2.3",
  "target": "3.0.0",
  "releases": [
    { "version": "1.3.0" },
    {
      "version": "2.0.0",
      "breaking_changes": ["removed the legacy parser entry point"]
    },
    {
      "version": "2.4.1",
      "breaking_changes": ["renamed the configuration keys", "dropped Node 14 support"],
      "deprecated": true
    },
    { "version": "3.0.0" }
  ]
}

結果は JSON として出力されます。

{
  "name": "widgetlib",
  "current": "1.2.3",
  "target": "3.0.0",
  "steps": [
    {
      "version": "1.3.0",
      "breaking_changes": [],
      "breaking_count": 0,
      "deprecated": false
    },
    {
      "version": "2.0.0",
      "breaking_changes": ["removed the legacy parser entry point"],
      "breaking_count": 1,
      "deprecated": false
    },
    {
      "version": "2.4.1",
      "breaking_changes": ["renamed the configuration keys", "dropped Node 14 support"],
      "breaking_count": 2,
      "deprecated": true
    },
    {
      "version": "3.0.0",
      "breaking_changes": [],
      "breaking_count": 0,
      "deprecated": false
    }
  ],
  "step_count": 4,
  "total_breaking": 3,
  "majors_crossed": 2,
  "reaches_target": true,
  "verdict": "manageable"
}

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

MCP サーバー

npx -y @reneturcios/upgradepath mcp

MCP クライアントの設定：

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

ツール

• plan_upgrade_path — 呼び出し元が指定したリリース情報に基づいて、安全な依存関係のアップグレードを計画します。

  • name（文字列、必須、空でない）— 依存関係の名前
  • current（文字列、必須）— 現在インストールされているバージョン。x.y.z 形式
  • target（文字列、必須）— 目的のバージョン。x.y.z 形式で、current より大きくなければなりません
  • releases（配列、必須、1項目以上）— 依存関係の既知のリリース。それぞれの項目には以下が含まれます。
    • version（文字列、必須）— リリースバージョン。x.y.z 形式
    • breaking_changes（文字列の配列、任意）— このリリースで導入される互換性を破る変更。省略した場合は変更なし
    • deprecated（ブール値、任意）— このリリースが非推奨かどうか。省略した場合は false

  {name, current, target, steps, step_count, total_breaking, majors_crossed, reaches_target, verdict} を返します。各ステップは {version, breaking_changes, breaking_count, deprecated} です。

Docker

docker run -i ghcr.io/cloudcorprecords/upgradepath
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/upgradepath plan --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