io.github.CloudCorpRecords/packcompare

packcompare

A package can change a lot between two versions without any single change looking dramatic: a file quietly grows, a dependency is swapped, an export path disappears. packcompare puts both snapshots side by side and reports the whole move at once, so a release review starts from the diff instead of from a hunch.

You supply two snapshots of the same package — a before and an after. Each one is a plain description, not a real package on disk: a version string, a files list of {path, size} entries, a dependencies map of name to version string, and an exports list of strings.

The file report splits into three sorted lists: paths only in after were added, paths only in before were removed, and paths present in both with different sizes are changed, each carrying size_before and size_after. File paths must be unique within a snapshot, and sizes may be zero — an empty file is still a file. Dependencies get the same treatment, sorted by name: added and removed entries carry the version from the side they exist on, and a name present in both with a different version string is changed, reported as {name, from, to}.

Exports are compared as sets, so mentioning the same export twice in one snapshot changes nothing. The headline numbers are the summed file sizes of each snapshot, their difference size_delta (which is negative when the package shrank), and the file counts on each side.

Breaking is deliberately narrow and pinned: a change is breaking exactly when at least one export was removed, and breaking_reasons spells each one out as removed export: <name> in the removed list's sorted order. Added files, resized files, and dependency bumps — however large — never make a change breaking on their own.

Malformed input is a validation error naming the offending path, with the snapshot named in the path: a duplicate file path is reported as before.files[1].path is a duplicate, for example. No partial diff is produced. Unknown extra fields are ignored. The computation is pure and local: no network, no configuration, and no real package is read.

CLI

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

args.json contains the full arguments object:

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

The result is printed as 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": []
}

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/packcompare mcp

MCP client config:

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

Tools

• compare_packages — Diff two versions of a package.

  • before (object, required) — the earlier package snapshot: {version, files, dependencies, exports}, where version is a non-empty string, files is a list of {path, size} entries with unique non-empty paths and integer sizes of at least 0, dependencies is a map of dependency name to non-empty version string, and exports is a list of non-empty strings
  • after (object, required) — the later package snapshot, with the same shape as before

  Returns {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

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