packcompare

packcompare

两个版本之间的软件包可能发生很多变化，但其中没有任何单项变化显得特别显著：某个文件悄然变大、某个依赖被替换、某条导出路径消失。packcompare 会并排展示两个快照，并一次性报告全部变化，让你在审查版本发布时从差异入手，而不是凭直觉判断。

你需要提供同一软件包的两个快照：before 和 after。每个快照都是普通描述，并非磁盘上的真实软件包：包含一个 version 字符串、一个由 {path, size} 条目组成的 files 列表、一个从名称映射到版本字符串的 dependencies 映射，以及一个字符串列表 exports。

文件报告分为三个排序列表：仅存在于 after 中的路径为新增文件，仅存在于 before 中的路径为已移除文件，同时存在于两者中但大小不同的路径为已更改文件，每个条目都包含 size_before 和 size_after。同一快照中的文件路径必须唯一，大小可以为零——空文件仍然是文件。依赖项采用相同的处理方式，并按名称排序：新增和移除条目包含其所在一侧的版本；两侧都存在但版本字符串不同的名称则列为已更改，格式为 {name, from, to}。

导出项按集合进行比较，因此同一快照中重复列出相同导出项不会产生变化。概要数据包括每个快照的文件总大小、差值 size_delta（软件包缩小时为负数），以及两侧的文件数量。

破坏性变更的定义刻意收窄且明确：仅当至少有一个导出项被移除时，变更才具有破坏性；breaking_reasons 会按已移除列表的排序顺序，逐项列出 removed export: <name>。新增文件、文件大小变更和依赖项升级，无论变化多大，都不会单独导致变更具有破坏性。

格式错误的输入会产生验证错误，并指出出错路径，同时在路径中标明对应的快照：例如，重复文件路径会报告为 before.files[1].path is a duplicate。不会生成部分差异结果。未知的额外字段会被忽略。计算过程纯粹且在本地进行：不访问网络、不需要配置，也不会读取真实软件包。

命令行

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

args.json 包含完整的参数对象：

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

结果以 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": []
}

退出码：成功时为 0，发生运行时错误（包括无法读取或无效的输入文件，或输入无效）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/packcompare mcp

MCP 客户端配置：

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

工具

• compare_packages — 对比软件包的两个版本。

  • before（对象，必填）— 较早的软件包快照：{version, files, dependencies, exports}，其中 version 是非空字符串，files 是由 {path, size} 条目组成的列表，路径必须唯一且非空，大小必须是大于或等于 0 的整数；dependencies 是从依赖项名称映射到非空版本字符串的映射；exports 是非空字符串列表
  • after（对象，必填）— 较新的软件包快照，结构与 before 相同

  返回 {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

开发

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