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