freshcheck

freshcheck

依赖树会在不知不觉中变旧。有些软件包只落后一个补丁版本，可以毫不犹豫地升级；有些落后一个主版本，需要规划升级；还有些多年没有发布新版本，或者其代码仓库已被直接归档——无论当前使用哪个版本，都存在风险。freshcheck 接收现有依赖树——每个依赖的名称、已安装版本和最新可用版本，以及可选的弃用信号——并将其准确划分为这些风险组：

• 落后级别 — 对每个依赖，按组件逐一进行数值比较，比较 current 和 latest。第一个不同的组件决定级别：major、minor 或 patch。当 latest 不高于 current 时——无论两者相同还是更低——级别都是 none。版本必须符合严格的 MAJOR.MINOR.PATCH semver 格式：三个数字组件，不带前导零，也不带预发布或构建后缀。
• 已弃用 — 当依赖的代码仓库已归档，或至少 abandoned_days 天没有发布新版本时（默认 730 天，由可选的 days_since_last_release 提供），该依赖即视为已弃用。弃用状态优先于版本差距：落后两个主版本的归档软件包会被归入 abandoned，同时仍会报告其落后级别，以保留差距大小信息。
• 分组与计数 — 每个依赖都会归入一个分组：abandoned、major、minor、patch 或 current（落后级别为 none 且未弃用）；结果会列出各组中的名称、组内数量和总数。

结果中的每个列表都按升序排序，因此同一棵依赖树总会得出完全一致的评估。无效输入——缺失或为空的依赖列表、缺失、为空或重复的名称、不符合严格 semver 格式的版本、类型错误的信号——会触发验证错误，并指出出错路径（例如 dependencies[1].latest must be a strict MAJOR.MINOR.PATCH semver version），且不会生成部分评估结果。计算过程是纯本地的：不访问网络、不查询注册表，也不会读取你传入的输入之外的任何文件——freshcheck 只根据你提供的版本和信号进行评估。

CLI

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

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

{
  "dependencies": [
    { "name": "core", "current": "2.0.0", "latest": "2.0.0" },
    { "name": "lib", "current": "1.9.0", "latest": "1.10.2" },
    { "name": "old", "current": "0.8.1", "latest": "3.0.0", "archived": true }
  ]
}

每个依赖的 archived 默认值为 false，整个调用的 abandoned_days 默认值为 730。评估结果以 JSON 格式打印：

{
  "dependencies": [
    { "name": "core", "current": "2.0.0", "latest": "2.0.0", "behind": "none", "group": "current" },
    { "name": "lib", "current": "1.9.0", "latest": "1.10.2", "behind": "minor", "group": "minor" },
    { "name": "old", "current": "0.8.1", "latest": "3.0.0", "behind": "major", "group": "abandoned" }
  ],
  "groups": {
    "abandoned": ["old"],
    "major": [],
    "minor": ["lib"],
    "patch": [],
    "current": ["core"]
  },
  "counts": { "abandoned": 1, "major": 0, "minor": 1, "patch": 0, "current": 1, "total": 3 }
}

请注意：lib 从 1.9.0 升至 1.10.2 属于 minor 级别的变化，因为组件按数值而非字典序比较。

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

MCP 服务

npx -y @reneturcios/freshcheck mcp

MCP 客户端配置：

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

工具

• assess_freshness — 按风险分组，评估依赖树的陈旧程度。

  • dependencies（数组，必填，至少一个元素）— 依赖对象数组，格式为 {name, current, latest, archived?, days_since_last_release?}；name 在整个集合中必须唯一，且 current / latest 必须是严格的 MAJOR.MINOR.PATCH semver 版本
  • abandoned_days（整数，可选，默认值为 730，至少为 1）— 依赖达到多少天未发布新版本时视为已弃用

  返回 {dependencies, groups, counts}。

Docker

docker run -i ghcr.io/cloudcorprecords/freshcheck
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/freshcheck 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 — 版权所有 (c) 2026 Rene Turcios