sizeverdict

sizeverdict

依存関係の追加には簡単に合意できますが、そのコストを見積もるのは困難です。 パッケージ一覧に表示されるサイズは、実際に支払うサイズではありません。新しいコードの一部は、すでに依存している依存関係によってバンドルに含まれている場合があります。 sizeverdict は、すでにある情報から実際のコストを算出します。候補パッケージのモジュールについて、それぞれのパスとバイトサイズを指定し、すでに同梱している依存関係についても同じ情報を指定します。必要に応じて、新たに追加できるバイト数の予算も指定できます。sizeverdict は、候補パッケージの合計バイト数、すでに同梱されているバイト数、新たに追加されるコスト、重複リスト、判定区分を返します。パッケージのダウンロード、インストール、測定は行わず、指定された情報だけを使って計算します。

候補パッケージのモジュールは、その正確なパスが、インストール済み依存関係のモジュールリストの少なくとも1つに含まれている場合、重複として扱われます。共有バイト数は候補側のサイズを使って合計され、同じパスを複数のインストール済み依存関係が含んでいても、各モジュールは1回だけ数えられます。そのパスについて、インストール済み依存関係側のサイズが使われることはありません。重複リストには、重複するモジュールごとに1つの項目が含まれます。各項目には候補側のサイズと、そのパスを含むインストール済み依存関係の重複しない名前が昇順で記載され、パス順に並びます。新規バイト数は、候補のバイト数から共有バイト数を差し引いた値です。

判定は新規コストに基づきます。新規バイト数が0の場合は free_overlap です。10240バイト以下は negligible、102400バイト以下は small、512000バイト以下は moderate、それを超える場合は large です。各しきい値は区分の上限に含まれます。10240は negligible のまま、10241は small となり、以下同様です。budget_bytes を指定した場合、結果には新規コストが予算を超えているかどうかも報告されます。予算とちょうど同じ場合は、超過とはみなされません。

不正な入力（候補の欠落、名前の欠落・空文字列・文字列以外、モジュールリストの欠落・空リスト、パスの欠落・空文字列、バイトサイズが負数または小数のモジュール、インストール済み依存関係内の同様の不備、不正な予算）は、該当するパスを示す検証エラーとなり、部分的な結果は返されません。1つのパッケージ内に同じパスのモジュールが複数ある場合、同じ名前のインストール済み依存関係が複数ある場合、候補の名前がインストール済み依存関係と一致する場合（candidate already installed: X）もエラーになります。 不明な追加フィールドは無視されます。

CLI

npx @reneturcios/sizeverdict assess --input args.json
npx @reneturcios/sizeverdict --version

args.json には引数オブジェクト全体を含めます。

{
  "candidate": {
    "name": "left-pad-plus",
    "modules": [
      { "path": "index.js", "bytes": 4000 },
      { "path": "lib/util.js", "bytes": 9000 },
      { "path": "lib/extra.js", "bytes": 2000 }
    ]
  },
  "installed": [
    {
      "name": "utils-kit",
      "modules": [
        { "path": "lib/util.js", "bytes": 8500 }
      ]
    }
  ],
  "budget_bytes": 10000
}

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

{
  "candidate": "left-pad-plus",
  "candidate_bytes": 15000,
  "shared_bytes": 9000,
  "net_new_bytes": 6000,
  "overlap": [
    { "path": "lib/util.js", "bytes": 9000, "also_in": ["utils-kit"] }
  ],
  "verdict": "negligible",
  "budget": {
    "budget_bytes": 10000,
    "net_new_bytes": 6000,
    "over_budget": false
  }
}

共有モジュールには、インストール済みコピーの8500バイトではなく、候補側の9000バイトが加算されることに注意してください。終了コード：成功時は 0、実行時エラー（読み取り不能または無効な入力ファイル、無効な入力を含む）では 1、使用方法のエラーでは 2 です。

MCP サーバー

npx -y @reneturcios/sizeverdict mcp

MCP クライアントの設定：

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

ツール

• assess_bundle_cost — 呼び出し元から提供されたモジュールサイズに基づいて、候補となる依存関係の実際のバンドルコストを評価します。合計バイト数、インストール済みの依存関係を通じてすでに配布されているモジュール（共有バイト数）、新たに追加される正味コスト、判定区分を返します。

  • candidate (object, required) — 評価対象の依存関係：
    • name (string, required, non-empty) — 候補パッケージ名
    • modules (array, required, at least 1 item) — 候補に含まれる配布済みモジュール。各項目：
      • path (string, required, non-empty) — パッケージ内のモジュールパス
      • bytes (integer, required, at least 0) — モジュールのサイズ（バイト単位）
  • installed (array, optional) — すでに配布されている依存関係。候補と同じ形式で、各項目は同じ形式の name と modules のリストを持ちます。省略した場合、配布済みの依存関係はありません。
  • budget_bytes (integer, optional, at least 0) — 照合する新規追加バイト数の予算

  {candidate, candidate_bytes, shared_bytes, net_new_bytes, overlap, verdict, budget} を返します。candidate には候補名がそのまま格納され、overlap には候補モジュールのうち重複するものごとに {path, bytes, also_in} が1つ格納され、パス順に並びます。verdict は free_overlap、negligible、small、moderate、large のいずれかです。budget は {budget_bytes, net_new_bytes, over_budget} となり、予算が指定されていない場合は null です。

Docker

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