sizeverdict

sizeverdict

添加依赖很容易达成一致，却很难评估代价。 软件包列表中醒目的大小并非你 实际付出的代价：部分新增代码可能已经在你的 构建包中，由你已依赖的依赖项提供。 sizeverdict 根据你 已有的数据计算实际代价。你需要提供候选项的模块及其 路径和字节大小，并提供你已随应用发布的 依赖项的相同信息，还可以选择设置新增字节数的 预算。sizeverdict 会返回候选项的总字节数、 已随应用发布的字节数、净新增成本、重叠列表 和判定等级。它绝不会下载、安装或测量 软件包；它只根据你提供的数据进行计算。

当候选模块的确切 路径出现在至少一个已安装依赖项的模块列表中时，该模块就算重叠。 共享字节数按候选模块的大小求和，每个重叠模块只 计算一次，即使两个已安装依赖项都包含相同路径也是如此—— 绝不会使用已安装依赖项中该路径对应的大小。重叠 列表中每个重叠模块各有一项，按路径排序，每项包含 候选模块的大小，以及包含该路径的已安装依赖项的不同名称，并按升序排序。 净新增字节数等于候选项字节数减去共享字节数。

判定等级根据净新增成本得出。净新增字节数为零时是 free_overlap。 不超过 10240 字节时是 negligible，不超过 102400 字节时是 small，不超过 512000 字节时是 moderate，超过该值则是 large。每个 阈值都包含对应等级的上限：10240 仍属于 negligible，10241 则属于 small，以此类推。当你 提供 budget_bytes 时，结果还会报告净新增成本是否 超过预算；恰好达到预算不算超过。

格式错误的输入——缺少候选项，名称缺失、为空 或不是字符串，模块列表缺失或为空，模块缺少路径或路径为空，或者字节大小为负数或 小数；已安装依赖项中存在相同错误；或预算无效—— 都会导致验证错误，并指出有问题的路径，不会返回部分结果。同一软件包内有两个模块使用相同路径、两个 已安装依赖项名称相同，以及候选项名称与某个已安装依赖项相同 （candidate already installed: X），也都会报错。 未知的额外字段会被忽略。

命令行界面

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
  }
}

请注意，共享模块贡献的是候选项的 9000 字节，而不是已安装副本的 8500 字节。退出代码：成功时为 0，运行时错误（包括输入文件无法读取或无效，以及输入无效）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/sizeverdict mcp

MCP 客户端配置：

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

工具

• assess_bundle_cost — 根据调用方提供的模块大小，评估候选依赖的实际打包成本： 总字节数、已通过已安装依赖打包的模块（共享字节数）、新增净成本，以及评估等级。

  • candidate（对象，必填）— 正在评估的依赖：
    • name（字符串，必填，非空）— 候选包名称
    • modules（数组，必填，至少 1 项）— 候选依赖打包的模块；每项包含：
      • path（字符串，必填，非空）— 包内的模块路径
      • bytes（整数，必填，至少为 0）— 模块大小（字节）
  • installed（数组，可选）— 已打包的依赖，结构与候选依赖相同；每项包含 name 和格式相同的 modules 列表。未提供时表示没有已打包的依赖。
  • budget_bytes（整数，可选，至少为 0）— 用于检查新增净字节数的预算

  返回 {candidate, candidate_bytes, shared_bytes, net_new_bytes, overlap, verdict, budget}，其中 candidate 返回候选依赖的名称，overlap 包含每个重叠候选模块对应的 {path, bytes, also_in}，并按路径排序；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