packcompare

packcompare

2 つのバージョン間で、パッケージは目立った変更がひとつもなくても大きく変わることがあります。ファイルがいつの間にか大きくなったり、依存関係が入れ替わったり、エクスポートパスがなくなったりします。packcompare は両方のスナップショットを並べて、変更全体をまとめて報告するため、リリースレビューを勘ではなく差分から始められます。

同じパッケージの 2 つのスナップショット、つまり before と after を指定します。それぞれはディスク上にある実際のパッケージではなく、単純な説明データです。version 文字列、{path, size} エントリーの files リスト、名前からバージョン文字列への dependencies マップ、文字列の exports リストで構成されます。

ファイルレポートは、ソートされた 3 つのリストに分かれます。after にのみ存在するパスは追加、before にのみ存在するパスは削除、両方に存在してサイズが異なるパスは変更済みとして扱われ、それぞれ size_before と size_after を持ちます。ファイルパスはスナップショット内で一意である必要があります。サイズには 0 を指定できます。空のファイルもファイルです。依存関係も同様に名前順でソートされます。追加・削除されたエントリーは、存在する側のバージョンを持ちます。両方に存在してバージョン文字列が異なる名前は変更済みとして扱われ、{name, from, to} の形式で報告されます。

エクスポートはセットとして比較されるため、ひとつのスナップショット内で同じエクスポートを複数回指定しても結果は変わりません。概要の数値は、各スナップショットのファイルサイズ合計、その差 size_delta（パッケージが小さくなった場合は負の値になります）、および各側のファイル数です。

破壊的変更の判定は意図的に限定されており、条件も明確です。エクスポートが 1 つ以上削除された場合に限り、破壊的変更と判定されます。breaking_reasons には、削除リストのソート順に、それぞれ removed export: <name> として理由が記載されます。ファイルの追加、サイズ変更、依存関係の更新は、どれほど大きな変更でも、それだけでは破壊的変更になりません。

不正な入力は、該当するパス（パスにはスナップショット名も含まれます）を示す検証エラーになります。たとえば、ファイルパスの重複は before.files[1].path is a duplicate として報告されます。部分的な差分は生成されません。未定義の追加フィールドは無視されます。計算は純粋かつローカルで行われ、ネットワークや設定は不要で、実際のパッケージが読み込まれることもありません。

CLI

npx @reneturcios/packcompare compare --input args.json
npx @reneturcios/packcompare --version

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

{
  "before": {
    "version": "1.0.0",
    "files": [{ "path": "index.js", "size": 1200 }],
    "dependencies": { "left-pad": "1.3.0" },
    "exports": ["./index.js"]
  },
  "after": {
    "version": "1.1.0",
    "files": [{ "path": "index.js", "size": 1400 }],
    "dependencies": { "left-pad": "1.3.0" },
    "exports": ["./index.js"]
  }
}

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

{
  "version_before": "1.0.0",
  "version_after": "1.1.0",
  "files": {
    "added": [],
    "removed": [],
    "changed": [{ "path": "index.js", "size_before": 1200, "size_after": 1400 }]
  },
  "dependencies": { "added": [], "removed": [], "changed": [] },
  "exports": { "added": [], "removed": [] },
  "size_before": 1200,
  "size_after": 1400,
  "size_delta": 200,
  "file_count_before": 1,
  "file_count_after": 1,
  "breaking": false,
  "breaking_reasons": []
}

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

MCP サーバー

npx -y @reneturcios/packcompare mcp

MCP クライアントの設定：

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

ツール

• compare_packages — パッケージの 2 つのバージョンの差分を比較します。

  • before（object、必須）— 以前のパッケージのスナップショット：{version, files, dependencies, exports}。version は空でない文字列、files は空でない一意のパスと 0 以上の整数サイズを持つ {path, size} エントリーのリスト、dependencies は依存関係名から空でないバージョン文字列へのマップ、exports は空でない文字列のリストです。
  • after（object、必須）— 後のパッケージのスナップショット。before と同じ形式です。

  {version_before, version_after, files, dependencies, exports, size_before, size_after, size_delta, file_count_before, file_count_after, breaking, breaking_reasons} を返します。

Docker

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