dsh-deps 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 he fangsheng (https://github.com/dongsheng123132)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,148 @@
-# dsh-deps · 依赖治理
+# dsh-deps · 依赖升级规划（五档分级 + 风险信号 + 建议顺序）
 
-> **定义**：审计依赖树：许可证风险、重复包、无人维护包、版本漂移，并按包给出可执行的升级计划。
->
-> **English**: Audit dependency trees for license risk, dupes, abandoned packages and version drift, with an actionable upgrade plan per package.
+dsh-deps 是一个 DSH（DeepSeek Harness）插件，用于把「这堆依赖该怎么升」变成一份可执行计划：它注册工具 `dsh_deps`，读 `package.json` 与调用方给的**本地** registry 快照，算出每个依赖的五档分级（`patch` / `minor` / `major` / `pinned` / `unknown`）、具体风险信号与建议动作，再给出先 patch 后 minor 再 major、同组按被依赖次数降序的升级顺序。**latest 只来自本地快照，快照里没有就 `unknown`，绝不联网猜**；全程只读，`pin` 只生成 diff 文本，不改任何文件。安装：`dsh plugin --profile web add dsh-deps`。
 
-状态：**0.0.1 名称占位**（name reservation）。实现中；能力说明即本包目标范围，完成前请勿依赖。
+包 `dsh-deps@0.1.0` · 已实测宿主 DSH 0.2.2-rc.1、Node 23.11.0 · 许可 MIT · 作者主页 https://github.com/dongsheng123132 · 仓库 https://github.com/dongsheng123132/dsh-deps（发布时创建）
 
-## 它补上 DSH 的哪一块
+**分工**：`dsh-pkg` 查依赖冲突、`dsh-lockfile` 查 lock 漂移，本包只做**升级规划**（能不能升、升了有什么风险、按什么顺序升），不重复它们的 dupes / peer 求解逻辑。
 
-审计依赖树：许可证风险、重复包、无人维护包、版本漂移，并按包给出可执行的升级计划。
+## dsh-deps 是什么？
 
-## 安装（可用版本发布后）
+一个挂在 DSH 里的工具 `dsh_deps` + 一个零依赖 CLI。四个动作：
+
+| 动作 | 做什么 | 会不会写盘 |
+|---|---|---|
+| `plan` | 升级清单 + 五档分级 + 风险信号 + 建议顺序 | 只读 |
+| `why` | 解释某个依赖为什么被这么判（逐条依据） | 只读 |
+| `pin` | 把声明范围收紧到已锁版本，**只输出 diff 文本** | 只读 |
+| `audit` | 一次体检：结论、信号计数、建议动作、顺序 | 只读 |
+
+## 五档分级（写死）
+
+| 档位 | 判据 | 例子 | risk |
+|---|---|---|---|
+| `patch` | 同 major 同 minor，patch 变大 | 1.2.3 → 1.2.9 | low |
+| `minor` | 同 major，minor 变大 | 1.2.3 → 1.9.0 | medium |
+| `major` | major 变大（breaking 风险） | 1.2.3 → 2.0.0 | high |
+| `pinned` | 当前版本已不低于快照 latest | 1.2.9 且 latest 1.2.9 | none |
+| `unknown` | 无从判断：快照缺包 / 范围不可解析 / 没有当前版本 | `git+https://…` | unknown |
+
+每条都给 `current`（声明范围）、`currentVersion`（当前版本）、`latest`（仅来自快照）、`bump`、`risk`、`reason`、`suggested`、`signals`。**只有快照里真的有 latest 且能确定当前版本，才会给 patch/minor/major**；其余一律 unknown 并写清为什么。
+
+## 快照：latest 的唯一来源
+
+```json
+{
+  "react": { "latest": "19.2.0", "engines": { "node": ">=20" } },
+  "old-lib": { "latest": "2.0.0", "deprecated": "use new-lib instead" },
+  "risky": { "latest": "3.1.0", "yanked": ["3.0.0"] }
+}
+```
+
+- 支持 `latest`（必填才有分级）、`deprecated`（字符串或 true）、`engines`（只读，不猜）、`yanked`（`true` / 版本字符串 / 版本数组）；
+- **快照里没有的包 → `unknown`**，并建议先用 `npm view <name> version` 取事实再写进快照；
+- 本包**不联网、不跑 `npm outdated`、不读 node_modules**，也不替你维护快照。
+
+当前版本默认取「声明范围下界」（`^1.2.3` → `1.2.3`），这不是 lock 里的实际版本；要准确请传 `installed` 快照（例如从 lockfile 解析）。`versionSource` 会写明用的是哪一种。
+
+## 风险信号（每条给 signal + 建议动作）
+
+| signal | 触发条件 | 建议动作 |
+|---|---|---|
+| `major-bump` | 升级跨大版本 | 读 CHANGELOG/迁移指南，单独 PR，升级前跑完整测试 |
+| `engines-incompatible` | 目标版本声明 `engines.node` 与当前 Node 不兼容 | 先升 Node 或选兼容版本，别在现环境硬升（risk=blocked，不进队列） |
+| `deprecated` | 快照标记该包已废弃 | 优先迁移到替代包，而不是继续升级 |
+| `yanked-current` | 当前版本被快照标为 yanked | 立即升级/回退到安全版本（risk=blocked） |
+| `yanked-target` | 快照把 latest 本身标为 yanked | 不要升到被撤版本，等快照更新或选上一稳定版 |
+| `peer-breaking` | 是 peerDependency，且 latest 落在声明的 peer 范围外 | 先确认宿主支持，再同步放宽 peer 范围 |
+| `prerelease-target` | latest 是预发布版本 | 不默认进生产，确认需要再升并固定版本 |
+| `unknown-latest` | 快照缺这个包 / 缺 latest | 先取事实写进快照，不猜 |
+| `unsupported-range` | 范围不是可判定的 semver（git/file/workspace/npm 别名） | 改成 semver 范围或人工确认 |
+| `no-current-version` | 范围无法得到当前版本（如 `*`） | 传 installed 快照或用具体范围 |
+
+## 建议顺序：为什么先 patch？
+
+**先 patch，再 minor，最后 major**：小步先行，每一步都能单独测试与回滚，出问题容易二分定位。**同组内按被依赖次数降序**：被依赖越多，升级收益越大，也越早暴露兼容问题，先升它能让后续升级更安全。`blocked`（engines 不兼容 / 当前版本被 yanked）不进入队列；`unknown` 不猜、不排队，单独列出来等你补数据。
+
+被依赖次数默认按给定 manifest 统计（只给一份时每项为 1）；传 `manifests`（工作区里的多份 package.json）或显式 `dependents` 才会出现真实差异。
+
+## 它和 npm outdated / npm-check-updates / Renovate 有什么区别？
+
+| 方案 | 它解决什么 | 代价与盲区 |
+|---|---|---|
+| `npm outdated` | 联网查最新版与 wanted | 必须联网、输出是表格；没有风险分级、没有顺序、没有 peer/engines 语义 |
+| `npm-check-updates` | 批量把范围改到最新 | 会改 package.json；默认不区分「该不该升」，也没有基于快照的审计口径 |
+| Renovate / Dependabot | 持续开 PR 升级 | 需要托管平台与仓库配置；本机离线场景用不上，且不解释「为什么先升这个」 |
+| dsh-pkg / dsh-lockfile | 依赖冲突、lock 漂移 | 不回答「能不能升、升了有什么风险、按什么顺序升」 |
+| dsh-deps（本包） | 本地快照驱动的五档分级 + 风险信号 + 顺序 + pin diff，供模型/CI 消费 | latest 依赖你提供快照；不解析真实 node_modules，也不替你执行升级 |
+
+## 怎么装、怎么用？
+
+```sh
+dsh plugin --profile web add dsh-deps
+```
+
+装好后在会话里说需求，模型会调 `dsh_deps`：
+
+```text
+按这份快照给我一份依赖升级计划
+为什么 host 被判成高风险
+把范围收紧到已锁版本的 patch，给我 diff
+这个项目依赖健康吗，先升哪些
+```
+
+不装插件也能用 CLI（零依赖，只要 Node ≥22）：
+
+```sh
+node lib/cli.js plan   --package-json package.json --snapshot snapshot.json --installed installed.json
+node lib/cli.js why    host --package-json package.json --snapshot snapshot.json
+node lib/cli.js pin    --package-json package.json --installed installed.json
+node lib/cli.js audit  --package-json package.json --snapshot snapshot.json --json
+node lib/cli.js snapshot-shape
+```
+
+退出码：`0` 无高危、`1` 参数/输入错误、`3` 有 high/blocked 升级项。只读：不写 `package.json`/lockfile，`pin` 的 diff 需要你自己复制应用。
+
+## 三个常见问题
+
+### 为什么不直接跑 `npm outdated`？
+
+因为那要联网，而且它只给「最新版是什么」，不给「该不该升、升了会不会破坏 peer/engines、先升哪个」。本包把「事实」（latest）和「判断」（分级/风险/顺序）拆开：事实由你提供本地快照，判断写死在代码里、可测试、可复核。快照里没有的包，本包说 `unknown`，不编一个 latest 出来。
+
+### 为什么 current 不是 lock 里的实际版本？
+
+`package.json` 只有声明范围，没有实际安装版本。本包默认取范围下界（`^1.2.3` → `1.2.3`）并在 `reason` 里注明；把 lockfile 解析出的版本作为 `installed` 传进来，才会用真实版本。lock 一致性/漂移是 `dsh-lockfile` 的职责，本包不重复。
+
+### pin 会改我的 package.json 吗？
+
+不会。`pin` 只返回 `changes` 与一段 unified diff 文本（`applied:false`、`wroteFiles:[]`），复制后你自己决定是否应用。没有 `installed` 快照时它不会猜锁版本，只写说明。
+
+## 事实
+
+- 源码 **1738 行**（`plugin.mjs` + `lib/` 共 10 个文件），**零运行时依赖**，没有编译步骤
+- 测试 **61 条**、**8 个测试文件**：五档分级 / 快照缺失 → unknown / engines 不兼容 / deprecated / peer 破坏 / yanked / 排序与理由 / pin diff / audit 汇总 / 空依赖 / 命名同源
+- 所有测试数据在内存或 /tmp 造，**不联网、不跑 npm outdated、不读真实 node_modules**
+- 已实测：宿主 DSH 0.2.2-rc.1、Node 23.11.0、macOS
+- `npm pack` 实测：发布 **16 个文件**、tarball **26 KB**、解包 **82 KB**（`test/` 与 `scripts/` 不进包）
+- 工具名 `dsh_deps`；命名清单见 `dsh-plugin.naming.json`（`npm run check` 校验五处同源）
+
+## 已知限制
+
+- latest 只来自你给的快照：快照过期，结论就过期；本包不联网校验快照新鲜度。
+- semver 是子集：不支持 npm 别名、git/file/workspace 范围与 prerelease 特例，遇到就 unknown。
+- 当前版本默认取范围下界，不等于实际安装版本；需要准确请传 installed 快照。
+- 只做升级规划，不做依赖冲突 / 重复包 / peer 求解（dsh-pkg 的职责），也不改文件。
+- 风险信号是静态判据，不代表真实兼容性；升级前仍要跑测试。
+- 被依赖次数依赖你传的 manifests / dependents；只给一份 manifest 时每项都是 1，排序退化为按名字。
+
+## 开发与自检
 
 ```sh
-dsh plugin --profile desktop add dsh-deps
+node --test test/            # 或 node --test test/*.test.mjs（61 条）
+npm test                     # 同上（npm script 版本）
+npm run check                # 包结构 + 语法 + 命名五处同源 + 假 ctx 真加载 + 宿主 schema 校验 + 只读/不联网红线
+node scripts/host-smoke.mjs  # 宿主注册表 + 执行管道冒烟
+node lib/cli.js snapshot-shape
 ```
 
 ## 许可

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-deps：往宿主挂一个 host 侧插件，注册模型可调用工具 dsh_deps。
+# 行 id 与包名同名（三个名字同源），避免「行 id ≠ 包名」两个命名空间带来的重复注册。
+- insert:
+    - id: dsh-deps
+      name: dsh-deps
+      config:
+        # 默认本地 registry 元数据快照（{name:{latest,deprecated?,engines?,yanked?}}）；留空 = 调用时传
+        snapshot: null
+        # 默认 installed 快照（{name:"x.y.z"}）；留空 = 用声明范围下界当当前版本
+        installed: null
+        # 默认 Node 版本；留空 = 取运行时版本
+        nodeVersion: ''

package/dsh-plugin.naming.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "policy": "dsh-plugin-naming/v1",
+  "plugin": {
+    "namespace": "hfshfg",
+    "name": "deps",
+    "coordinate": "hfshfg/deps",
+    "packageName": "dsh-deps"
+  },
+  "names": {
+    "pluginNames": [
+      "dsh-deps"
+    ],
+    "loaderIds": [
+      "dsh-deps"
+    ],
+    "services": [],
+    "tools": [
+      "dsh_deps"
+    ],
+    "commands": [],
+    "skills": [],
+    "skillProviders": [],
+    "events": [],
+    "settingsNamespaces": [],
+    "routes": []
+  }
+}

package/lib/classify.mjs

@@ -0,0 +1,250 @@
+/**
+ * 五档分级 + 风险信号。判据写死，不联网、不猜 latest：
+ *
+ *   bump（五档，写死）：patch / minor / major / pinned / unknown
+ *   risk：none / low / medium / high / blocked / unknown
+ *
+ * 只有「快照里真的有 latest」且「能确定当前版本」时才会给 patch/minor/major；
+ * 其余一律 unknown 并写清原因（快照缺失 / 范围不可解析 / 没有当前版本）。
+ */
+
+import { compareVersions, bumpType, rangeFloor, satisfiesRange, checkEngines, parseVersion, parseRange } from './version.mjs'
+
+/** 五档（顺序即风险由低到高，unknown 单列）。 */
+export const BUMPS = ['patch', 'minor', 'major', 'pinned', 'unknown']
+
+/** 风险档（由轻到重；unknown 单列）。 */
+export const RISKS = ['none', 'low', 'medium', 'high', 'blocked', 'unknown']
+
+/** 风险排序权重。 */
+export const RISK_RANK = { none: 0, low: 1, medium: 2, high: 3, blocked: 4, unknown: 5 }
+
+/** 风险中文说明（README / 报告共用）。 */
+export const RISK_LABEL = {
+  none: '无需动作',
+  low: '低风险',
+  medium: '中风险',
+  high: '高风险',
+  blocked: '被阻塞',
+  unknown: '未判定',
+}
+
+/**
+ * 保留原范围的运算符，把版本替换成 latest。
+ * @param {string} range 原范围
+ * @param {string} latest 目标版本
+ * @returns {string} 建议范围
+ */
+export function suggestRange(range, latest) {
+  const text = String(range ?? '').trim()
+  if (text.startsWith('^')) return `^${latest}`
+  if (text.startsWith('~')) return `~${latest}`
+  if (text.startsWith('>=')) return `>=${latest}`
+  if (text.startsWith('>')) return `>${latest}`
+  if (parseVersion(text)) return latest
+  return `^${latest}`
+}
+
+/**
+ * 分类单个依赖。
+ * @param {object} dep collectDependencies 的一项
+ * @param {object} context 上下文
+ * @param {Map<string,object>} context.snapshot 快照
+ * @param {Map<string,string>} context.installed installed 快照
+ * @param {number} [context.dependents] 被依赖次数
+ * @param {string} context.nodeVersion 当前 Node 版本
+ * @param {object} context.manifest 根 manifest
+ * @returns {object} 条目
+ */
+export function classifyDependency(dep, context) {
+  const snapshotEntry = context.snapshot.get(dep.name)
+  const installedVersion = context.installed.get(dep.name) ?? null
+  const floor = rangeFloor(dep.range)
+  const currentVersion = installedVersion ?? floor
+  const versionSource = installedVersion ? 'installed' : floor ? 'range-floor' : 'unknown'
+  const dependents = context.dependents ?? 1
+  const signals = []
+
+  const latest = snapshotEntry?.latest ?? null
+  let bump
+  let reason
+
+  if (parseRange(dep.range) === null) {
+    bump = 'unknown'
+    reason = `声明范围 ${dep.range || '(空)'} 不是可判定的 semver 范围（git/file/workspace/npm 别名等），不猜`
+    signals.push({
+      signal: 'unsupported-range',
+      severity: 'unknown',
+      detail: `范围 ${dep.range} 不在本包支持的 semver 子集里`,
+      action: '改成语义化版本范围（如 ^1.2.3），或人工确认该依赖的升级路径；本包不猜。',
+    })
+  } else if (!snapshotEntry || latest === null) {
+    bump = 'unknown'
+    reason = snapshotEntry
+      ? `快照里 ${dep.name} 没有可解析的 latest：不能判断（不猜）`
+      : `快照里没有 ${dep.name}：不能判断 latest（不猜）`
+    signals.push({
+      signal: 'unknown-latest',
+      severity: 'unknown',
+      detail: snapshotEntry ? '快照条目缺少可解析的 latest' : '没有该包的快照条目',
+      action: `先取事实再规划：npm view ${dep.name} version，把结果写进本地快照 JSON 后重跑；本包不联网、不跑 npm outdated。`,
+    })
+  } else if (!currentVersion) {
+    bump = 'unknown'
+    reason = `声明范围 ${dep.range || '(空)'} 无法得到当前版本（如 * / 非 semver 范围），不猜`
+    signals.push({
+      signal: 'no-current-version',
+      severity: 'unknown',
+      detail: `范围 ${dep.range} 没有可判定的下界`,
+      action: '传 installed 快照（例如从 lockfile 解析出的实际版本），或用具体版本范围重跑。',
+    })
+  } else if (compareVersions(latest, currentVersion) <= 0) {
+    bump = 'pinned'
+    reason = `当前 ${currentVersion} 已不低于快照 latest（${latest}），无需升级`
+    signals.push({ signal: 'up-to-date', severity: 'info', detail: `latest ${latest} 不高于当前 ${currentVersion}`, action: '无需动作；如果 latest 更低，检查是否被 yanked 或快照过期。' })
+  } else {
+    bump = bumpType(currentVersion, latest)
+    const sourceNote = versionSource === 'installed' ? '（当前版本来自 installed 快照）' : '（当前版本取自声明范围下界；实际安装版本请传 installed 快照）'
+    reason = `当前 ${currentVersion} → 快照 latest ${latest}（${bump}）${sourceNote}`
+    if (bump === 'major') {
+      signals.push({
+        signal: 'major-bump',
+        severity: 'high',
+        detail: `${currentVersion} → ${latest} 跨大版本（breaking 风险）`,
+        action: '先读 CHANGELOG / 迁移指南，单独开 PR，升级前跑完整测试；必要时找 codemod。',
+      })
+    }
+    if (latest.includes('-')) {
+      signals.push({
+        signal: 'prerelease-target',
+        severity: 'medium',
+        detail: `快照 latest ${latest} 是预发布版本`,
+        action: '预发布不默认进生产；确认确实需要再升，并固定到具体版本。',
+      })
+    }
+  }
+
+  // engines 兼容性：快照声明了 engines.node 才判；没声明就明确「未声明」，不猜
+  if (snapshotEntry?.engines) {
+    const engines = checkEngines(snapshotEntry.engines, context.nodeVersion)
+    if (engines.declared && engines.compatible === false) {
+      signals.push({
+        signal: 'engines-incompatible',
+        severity: 'blocked',
+        detail: `目标版本声明 engines.node=${engines.range}，当前 Node ${context.nodeVersion} 不满足`,
+        action: '先升级 Node（或选择兼容 Node 的版本），不要在现环境硬升。',
+      })
+    } else if (engines.declared && engines.compatible === null) {
+      signals.push({
+        signal: 'engines-unsupported',
+        severity: 'info',
+        detail: `engines.node=${engines.range} 无法判定（非本包支持的 semver 子集）`,
+        action: '人工确认 Node 版本是否满足；本包不猜。',
+      })
+    }
+  }
+
+  // deprecated
+  if (snapshotEntry?.deprecated) {
+    signals.push({
+      signal: 'deprecated',
+      severity: 'high',
+      detail: `快照标记 deprecated：${snapshotEntry.deprecated}`,
+      action: '优先迁移到替代包/替代 API，而不是升级到已废弃版本。',
+    })
+  }
+
+  // yanked：当前版本被撤，或目标 latest 被撤
+  if (snapshotEntry?.yankedVersions?.length > 0) {
+    const yankedAll = snapshotEntry.yankedVersions.includes('*')
+    const currentYanked = currentVersion && (yankedAll || snapshotEntry.yankedVersions.includes(currentVersion))
+    const latestYanked = latest && (yankedAll || snapshotEntry.yankedVersions.includes(latest))
+    if (currentYanked) {
+      signals.push({
+        signal: 'yanked-current',
+        severity: 'blocked',
+        detail: `当前版本 ${currentVersion} 在快照里被标记 yanked`,
+        action: '立即升级到未 yanked 的版本（或回退到安全版本），并查明撤回原因。',
+      })
+    } else if (latestYanked) {
+      signals.push({
+        signal: 'yanked-target',
+        severity: 'medium',
+        detail: `快照把 latest ${latest} 标为 yanked`,
+        action: '不要升到被撤版本；等快照更新到安全版本，或选择上一稳定版。',
+      })
+    }
+  }
+
+  // peer：升级后 latest 落在声明的 peer 范围外 → 会破坏宿主/消费方约束
+  if (dep.peer && latest) {
+    const peerRange = context.manifest?.peerDependencies?.[dep.name] ?? dep.range
+    const satisfied = satisfiesRange(latest, peerRange)
+    if (satisfied.supported && !satisfied.satisfies) {
+      signals.push({
+        signal: 'peer-breaking',
+        severity: 'high',
+        detail: `latest ${latest} 不满足声明 peerDependencies["${dep.name}"]=${peerRange}`,
+        action: '先确认宿主支持该版本，再同步放宽 peer 范围；不要只升依赖不改 peer 约束。',
+      })
+    }
+  }
+
+  const risk = deriveRisk(bump, signals)
+  return {
+    name: dep.name,
+    section: dep.section,
+    sections: dep.sections,
+    current: dep.range,
+    currentVersion,
+    versionSource,
+    latest,
+    latestSource: latest ? 'snapshot' : null,
+    bump,
+    risk,
+    dependents,
+    dev: dep.dev,
+    optional: dep.optional,
+    peer: dep.peer,
+    suggested: latest && bump !== 'unknown' && bump !== 'pinned' ? suggestRange(dep.range, latest) : null,
+    reason,
+    signals,
+    known: bump !== 'unknown',
+  }
+}
+
+/**
+ * 由 bump + 信号推风险（取最重的那条，信号可以升级风险）。
+ * @param {string} bump 五档
+ * @param {Array<object>} signals 信号
+ * @returns {string} 风险档
+ */
+export function deriveRisk(bump, signals) {
+  let risk = bump === 'unknown' ? 'unknown' : bump === 'pinned' ? 'none' : bump === 'major' ? 'high' : bump === 'minor' ? 'medium' : 'low'
+  for (const signal of signals) {
+    const mapped = signal.severity === 'blocked' ? 'blocked'
+      : signal.severity === 'high' ? 'high'
+        : signal.severity === 'medium' ? 'medium'
+          : null
+    if (mapped && RISK_RANK[mapped] > RISK_RANK[risk]) risk = mapped
+  }
+  return risk
+}
+
+/**
+ * 批量分类。
+ * @param {object} manifest 根 manifest
+ * @param {object} context 上下文（snapshot / installed / manifests）
+ * @returns {{entries:Array<object>, problems:string[]}} 结果
+ */
+export function classifyAll(manifest, context) {
+  const deps = context.deps ?? []
+  const entries = deps.map((dep) => classifyDependency(dep, {
+    snapshot: context.snapshot,
+    installed: context.installed,
+    dependents: context.dependents?.get(dep.name) ?? 1,
+    nodeVersion: context.nodeVersion,
+    manifest,
+  }))
+  return { entries, problems: context.problems ?? [] }
+}

package/lib/cli.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * `dsh-deps` 命令行：依赖升级规划（只读、不联网）。
+ *
+ * 用法：
+ *   node lib/cli.js plan   --package-json <path> [--snapshot <快照.json>] [--installed <json>] [--json]
+ *   node lib/cli.js why    <name> --package-json <path> [--snapshot <快照.json>] [--json]
+ *   node lib/cli.js pin    --package-json <path> --installed <json> [--json]
+ *   node lib/cli.js audit  --package-json <path> [--snapshot <快照.json>] [--json]
+ *   node lib/cli.js snapshot-shape
+ *
+ * 退出码：0 = 无高危（或查询成功）、1 = 参数/输入错误、3 = 有 high/blocked 升级项。
+ * 只读：不写 package.json / lockfile，不联网，不跑 npm outdated。
+ */
+
+import { realpathSync, readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { resolve } from 'node:path'
+
+import { runAction, VERSION, describeSnapshotShape } from './engine.mjs'
+import { renderReport, renderJson } from './format.mjs'
+import { describeError } from './errors.mjs'
+
+const USAGE = `dsh-deps ${VERSION} —— 依赖升级规划（五档分级 + 风险信号 + 建议顺序；只读、不联网）
+
+用法：
+  node lib/cli.js plan   --package-json <path> [--snapshot <json>] [--installed <json>] [--manifests a,b]
+  node lib/cli.js why    <name> --package-json <path> [--snapshot <json>] [--installed <json>]
+  node lib/cli.js pin    --package-json <path> --installed <json>
+  node lib/cli.js audit  --package-json <path> [--snapshot <json>] [--installed <json>]
+  node lib/cli.js snapshot-shape
+
+选项：
+  --package-json <路径>   要规划的 package.json（只读，不改）
+  --snapshot <路径>       本地 registry 元数据快照 {name: {latest, deprecated?, engines?, yanked?}}
+  --installed <路径>      installed 快照 {name: "x.y.z"}（例如从 lockfile 解析；不传就用声明范围下界）
+  --manifests <a,b>       额外的 manifest 路径（用于统计「被依赖次数」；第一个仍是根）
+  --node-version <x.y.z>  当前 Node 版本（默认取运行时版本）
+  --json / --brief        输出 JSON / 只给结论
+  --help, -h / --version, -v
+
+latest 只来自 --snapshot；快照里没有的包一律 unknown，本包不会联网去猜。
+退出码：0 无高危、1 参数/文件错误、3 有 high/blocked 升级项`
+
+/** 参数错误。 */
+class UsageError extends Error {}
+
+/**
+ * 解析 argv。
+ * @param {string[]} argv 参数
+ * @returns {object} flags
+ */
+export function parseArgs(argv) {
+  const flags = { json: false, brief: false, positionals: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    const takeValue = (name) => {
+      const next = argv[++i]
+      if (next === undefined) throw new UsageError(`${name} 需要一个值`)
+      return next
+    }
+    switch (arg) {
+      case '--help': case '-h': flags.help = true; break
+      case '--version': case '-v': flags.version = true; break
+      case '--json': flags.json = true; break
+      case '--brief': flags.brief = true; break
+      case '--package-json': flags.packageJsonPath = takeValue('--package-json'); break
+      case '--snapshot': flags.snapshotPath = takeValue('--snapshot'); break
+      case '--installed': flags.installedPath = takeValue('--installed'); break
+      case '--manifests': flags.manifestPaths = takeValue('--manifests').split(',').map((item) => item.trim()).filter(Boolean); break
+      case '--node-version': flags.nodeVersion = takeValue('--node-version'); break
+      default:
+        if (arg.startsWith('--')) throw new UsageError(`未知参数 ${arg}`)
+        flags.positionals.push(arg)
+    }
+  }
+  return flags
+}
+
+/**
+ * 读 JSON 文件（失败给稳定错误码）。
+ * @param {string} path 路径
+ * @param {string} code 错误码
+ * @returns {any} 解析结果
+ */
+function readJson(path, code) {
+  let text
+  try {
+    text = readFileSync(resolve(path), 'utf8')
+  } catch (error) {
+    throw new UsageError(`读 ${path} 失败：${error instanceof Error ? error.message : String(error)}`)
+  }
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new UsageError(`${path} 不是合法 JSON：${error instanceof Error ? error.message : String(error)}（${code}）`)
+  }
+}
+
+/**
+ * CLI 主流程。
+ * @param {string[]} argv 参数
+ * @returns {Promise<number>} 退出码
+ */
+export async function main(argv) {
+  let flags
+  try { flags = parseArgs(argv) } catch (error) {
+    process.stderr.write(`${error.message}\n\n${USAGE}\n`)
+    return 1
+  }
+  if (flags.help) { process.stdout.write(`${USAGE}\n`); return 0 }
+  if (flags.version) { process.stdout.write(`${VERSION}\n`); return 0 }
+
+  const [action, ...rest] = flags.positionals
+  if (!action) { process.stderr.write(`必须给动作（plan / why / pin / audit / snapshot-shape）\n\n${USAGE}\n`); return 1 }
+
+  if (action === 'snapshot-shape') {
+    const shape = describeSnapshotShape()
+    if (flags.json) process.stdout.write(`${JSON.stringify(shape, null, 2)}\n`)
+    else {
+      process.stdout.write('本地 registry 快照形状：\n')
+      for (const [key, value] of Object.entries(shape)) process.stdout.write(`- ${key}: ${value}\n`)
+    }
+    return 0
+  }
+
+  if (!['plan', 'why', 'pin', 'audit'].includes(action)) {
+    process.stderr.write(`不认识的动作 ${JSON.stringify(action)}（可选：plan / why / pin / audit / snapshot-shape）\n\n${USAGE}\n`)
+    return 1
+  }
+
+  try {
+    const name = action === 'why' ? rest[0] : undefined
+    if (action === 'why' && !name) throw new UsageError('why 需要 <name> 参数')
+    if (action !== 'why' && rest.length > 0) throw new UsageError(`多余的参数 ${rest.join(' ')}`)
+    if (!flags.packageJsonPath) throw new UsageError('必须给 --package-json <路径>')
+
+    let packageJsonText
+    let manifest
+    try {
+      packageJsonText = readFileSync(resolve(flags.packageJsonPath), 'utf8')
+      manifest = JSON.parse(packageJsonText)
+    } catch (error) {
+      throw new UsageError(`读/解析 ${flags.packageJsonPath} 失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+
+    const snapshot = flags.snapshotPath ? readJson(flags.snapshotPath, 'snapshot_invalid') : undefined
+    const installed = flags.installedPath ? readJson(flags.installedPath, 'installed_invalid') : undefined
+    const manifests = flags.manifestPaths?.length ? flags.manifestPaths.map((path) => readJson(path, 'manifest_invalid')) : undefined
+
+    const report = runAction(action, {
+      manifest,
+      packageJsonText,
+      snapshot,
+      installed,
+      manifests,
+      nodeVersion: flags.nodeVersion,
+      name,
+    })
+    process.stdout.write(flags.json ? `${renderJson(report)}\n` : `${renderReport(report, { detail: flags.brief ? 'brief' : 'full' })}\n`)
+
+    if (action === 'plan' || action === 'audit') {
+      const serious = report.entries.some((entry) => entry.risk === 'high' || entry.risk === 'blocked')
+      return serious ? 3 : 0
+    }
+    return 0
+  } catch (error) {
+    const info = describeError(error)
+    if (error instanceof UsageError) info.code = 'invalid_args'
+    if (flags.json) process.stderr.write(`${JSON.stringify({ ok: false, error: info }, null, 2)}\n`)
+    else {
+      process.stderr.write(`✗ ${info.message}\n`)
+      if (info.hint) process.stderr.write(`  → ${info.hint}\n`)
+    }
+    return 1
+  }
+}
+
+/**
+ * 是否直接执行。
+ * @returns {boolean} 是否直接执行
+ */
+function isInvokedDirectly() {
+  const entry = process.argv[1]
+  if (!entry) return false
+  const self = fileURLToPath(import.meta.url)
+  try { return realpathSync(entry) === realpathSync(self) } catch { return resolve(entry) === self }
+}
+
+if (isInvokedDirectly()) {
+  main(process.argv.slice(2))
+    .then((code) => { process.exitCode = code })
+    .catch((error) => {
+      process.stderr.write(`✗ 未捕获异常：${error instanceof Error ? error.stack ?? error.message : String(error)}\n`)
+      process.exitCode = 1
+    })
+}