io.github.CloudCorpRecords/sizeverdict

sizeverdict

Adding a dependency is easy to agree to and hard to price. The headline size in a package listing is not what you actually pay: part of the new code may already be in your bundle, shipped by dependencies you already depend on. sizeverdict works out the real price from numbers you already have. You supply the candidate's modules with a path and a byte size for each one, the same facts for any dependencies you already ship, and optionally a budget for net new bytes. sizeverdict hands back the candidate's total bytes, the bytes that are already shipped, the net new cost, an overlap list, and a verdict band. It never downloads, installs, or measures a package; it computes from the supplied facts only.

A candidate module counts as overlapping when its exact path appears in at least one installed dependency's module list. Shared bytes are summed at the candidate's sizes, and each overlapping module is counted once, even when two installed dependencies carry the same path — the installed dependencies' own sizes for that path are never used. The overlap list holds one entry per overlapping module, sorted by path, each with the candidate's size and the distinct names of the installed dependencies carrying that path, sorted ascending. Net new bytes are candidate bytes minus shared bytes.

The verdict is read off the net new cost. Zero net new bytes is free_overlap. Up to 10240 bytes is negligible, up to 102400 is small, up to 512000 is moderate, and anything above that is large. Each threshold is inclusive at the top of its band: 10240 is still negligible, 10241 is small, and so on. When you supply budget_bytes, the result also reports whether the net new cost is over it; landing exactly on the budget is not over.

Malformed input — a missing candidate, a missing, empty, or non-string name, a missing or empty module list, a module with a missing or empty path or a negative or fractional byte size, the same faults inside an installed dependency, or a bad budget — is a validation error naming the offending path, with no partial result. Two modules with the same path inside one package, two installed dependencies with the same name, and a candidate whose name matches an installed dependency (candidate already installed: X) are also errors. Unknown extra fields are ignored.

CLI

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

args.json contains the full arguments object:

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

The assessment is printed as 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
  }
}

Note the shared module contributes the candidate's 9000 bytes, not the installed copy's 8500. Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/sizeverdict mcp

MCP client config:

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

Tools

• assess_bundle_cost — Weigh a candidate dependency's real bundle cost from caller-supplied module sizes: total bytes, the modules already shipped via installed deps (shared bytes), the net new cost, and a verdict band.

  • candidate (object, required) — the dependency being weighed:
    • name (string, required, non-empty) — candidate package name
    • modules (array, required, at least 1 item) — the candidate's shipped modules; each item:
      • path (string, required, non-empty) — module path inside the package
      • bytes (integer, required, at least 0) — module size in bytes
  • installed (array, optional) — dependencies already shipped, same shape as the candidate; each item has a name and a modules list in the same form. Absent means none are shipped.
  • budget_bytes (integer, optional, at least 0) — net-new-bytes budget to check against

  Returns {candidate, candidate_bytes, shared_bytes, net_new_bytes, overlap, verdict, budget}, where candidate echoes the candidate's name, overlap holds one {path, bytes, also_in} per overlapping candidate module sorted by path, verdict is one of free_overlap, negligible, small, moderate, or large, and budget is {budget_bytes, net_new_bytes, over_budget} or null when no budget was supplied.

Docker

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

Development

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

License

MIT — Copyright (c) 2026 Rene Turcios