dsh-deps 0.0.1 → 0.1.0

package/lib/deps.mjs

@@ -0,0 +1,152 @@
+/**
+ * 依赖收集与快照归一：只读，不联网。
+ *
+ * 数据来源只有三样，全部由调用方提供：
+ *   1) package.json 的 manifest（对象）；
+ *   2) 本地 registry 元数据快照 `{name: {latest, deprecated?, engines?, yanked?}}`；
+ *   3) 可选的 installed 快照 `{name: "1.2.3"}`（比如 lockfile 里解析出的实际版本）。
+ * 快照里没有的包 → 绝不猜 latest，一律 unknown。
+ */
+
+import { parseVersion } from './version.mjs'
+
+/** manifest 里会被收集的依赖段（按优先级排序）。 */
+export const DEP_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']
+
+/**
+ * 从 manifest 收集依赖（同名只保留第一段，并记下全部段）。
+ * @param {object} manifest package.json 对象
+ * @returns {Array<{name:string, range:string, section:string, sections:string[], dev:boolean, optional:boolean, peer:boolean}>} 依赖清单
+ */
+export function collectDependencies(manifest) {
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) return []
+  const found = new Map()
+  for (const section of DEP_SECTIONS) {
+    const table = manifest[section]
+    if (table === null || typeof table !== 'object' || Array.isArray(table)) continue
+    for (const [name, range] of Object.entries(table)) {
+      if (typeof range !== 'string') continue
+      if (found.has(name)) {
+        found.get(name).sections.push(section)
+        continue
+      }
+      found.set(name, {
+        name,
+        range: range.trim(),
+        section,
+        sections: [section],
+        dev: section === 'devDependencies',
+        optional: section === 'optionalDependencies',
+        peer: section === 'peerDependencies',
+      })
+    }
+  }
+  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * 归一化 registry 快照；形状不对的条目记入 problems，而不是猜。
+ * @param {unknown} snapshot 快照
+ * @returns {{entries:Map<string,object>, problems:string[]}} 归一化结果
+ */
+export function normalizeSnapshot(snapshot) {
+  const entries = new Map()
+  const problems = []
+  if (snapshot === null || snapshot === undefined) return { entries, problems: ['没有提供 registry 快照：所有依赖都会是 unknown'] }
+  if (typeof snapshot !== 'object' || Array.isArray(snapshot)) return { entries, problems: ['registry 快照不是对象'] }
+
+  for (const [name, raw] of Object.entries(snapshot)) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      problems.push(`${name} 的快照不是对象，已忽略`)
+      continue
+    }
+    const latest = parseVersion(raw.latest) ? raw.latest : null
+    if (raw.latest !== undefined && latest === null) problems.push(`${name}.latest 不是可解析的版本：${String(raw.latest)}`)
+    const engines = raw.engines && typeof raw.engines === 'object' && !Array.isArray(raw.engines) ? raw.engines : null
+    entries.set(name, {
+      latest,
+      deprecated: typeof raw.deprecated === 'string' ? raw.deprecated : raw.deprecated === true ? '已标记 deprecated' : null,
+      engines,
+      yankedVersions: normalizeYanked(raw.yanked),
+      hasEntry: true,
+    })
+  }
+  return { entries, problems }
+}
+
+/**
+ * 归一化 yanked 标记：`true` / 字符串 / 字符串数组。
+ * @param {unknown} yanked 标记
+ * @returns {string[]} 被 yanked 的版本列表（空数组表示没标）
+ */
+function normalizeYanked(yanked) {
+  if (yanked === true) return ['*']
+  if (typeof yanked === 'string' && yanked.trim().length > 0) return [yanked.trim()]
+  if (Array.isArray(yanked)) return yanked.filter((item) => typeof item === 'string' && item.trim().length > 0).map((item) => item.trim())
+  return []
+}
+
+/**
+ * 归一化 installed 快照（实际安装版本）。
+ * @param {unknown} installed 快照
+ * @returns {{versions:Map<string,string>, problems:string[]}} 归一化结果
+ */
+export function normalizeInstalled(installed) {
+  const versions = new Map()
+  const problems = []
+  if (installed === null || installed === undefined) return { versions, problems: [] }
+  if (typeof installed !== 'object' || Array.isArray(installed)) return { versions, problems: ['installed 快照不是对象'] }
+  for (const [name, version] of Object.entries(installed)) {
+    if (parseVersion(version)) versions.set(name, String(version))
+    else problems.push(`installed.${name} 不是可解析的版本：${String(version)}`)
+  }
+  return { versions, problems }
+}
+
+/**
+ * 统计「被依赖次数」：给多份 manifest（monorepo/工作区）时按声明计数；只给一份时每项计 1。
+ * @param {object[]} manifests manifest 列表（第一份视为根 manifest）
+ * @param {string[]} names 依赖名
+ * @returns {{counts:Map<string,number>, source:'manifests'|'single-manifest'}} 计数
+ */
+export function countDependents(manifests, names) {
+  const counts = new Map(names.map((name) => [name, 0]))
+  const list = Array.isArray(manifests) && manifests.length > 0 ? manifests : []
+  if (list.length <= 1) {
+    for (const name of names) counts.set(name, 1)
+    return { counts, source: 'single-manifest' }
+  }
+  for (const manifest of list) {
+    if (manifest === null || typeof manifest !== 'object') continue
+    const seen = new Set()
+    for (const section of DEP_SECTIONS) {
+      const table = manifest[section]
+      if (table === null || typeof table !== 'object' || Array.isArray(table)) continue
+      for (const name of Object.keys(table)) {
+        if (counts.has(name) && !seen.has(name)) {
+          counts.set(name, counts.get(name) + 1)
+          seen.add(name)
+        }
+      }
+    }
+  }
+  return { counts, source: 'manifests' }
+}
+
+
+/** 本地快照的形状（写进文档与 CLI `snapshot-shape`，避免调用方猜格式）。 */
+export const SNAPSHOT_SHAPE = {
+  shape: '{ "<package>": { "latest": "<x.y.z>", "deprecated"?: string | true, "engines"?: { "node": "<range>" }, "yanked"?: true | string | string[] } }',
+  latest: '必填才能判断升级；缺了就是 unknown（不猜）',
+  deprecated: '可选；真值表示该包已废弃',
+  engines: '可选；只读不猜，声明了才判断与当前 Node 的兼容性',
+  yanked: '可选；true=全部版本被撤，字符串/数组=指定版本被撤',
+}
+
+/**
+ * 快照形状说明。
+ * @returns {object} 形状
+ */
+export function describeSnapshotShape() {
+  return { ...SNAPSHOT_SHAPE }
+}

package/lib/engine.mjs

@@ -0,0 +1,143 @@
+/**
+ * dsh-deps 编排：依赖升级规划。plan / why / pin / audit。
+ *
+ * 只读、不联网、不跑 npm outdated：latest 只来自调用方给的本地快照 JSON。
+ * 快照里没有 → unknown（不猜）。
+ */
+
+import { collectDependencies, normalizeSnapshot, normalizeInstalled, countDependents } from './deps.mjs'
+import { classifyAll } from './classify.mjs'
+import { buildPlan, auditReport, explainEntry, ORDER_RATIONALE, PHASES } from './plan.mjs'
+import { buildPinSuggestions } from './pin.mjs'
+import { DepsError } from './errors.mjs'
+
+/** 包版本。 */
+export const VERSION = '0.1.0'
+
+/** 支持的动作。 */
+export const ACTIONS = ['plan', 'why', 'pin', 'audit']
+
+/** 固定能力边界声明：每次结果都带。 */
+export const LIMITATIONS = [
+  '不联网、不跑 npm outdated、不读 node_modules：latest 只来自调用方给的本地快照 JSON；快照里没有就 unknown，不猜。',
+  '当前版本默认取「声明范围下界」，不是 lock 里的实际安装版本；要实际版本请传 installed 快照（本包不重复 dsh-lockfile 的漂移检查）。',
+  'semver 是子集：支持 ^ ~ >= <= > < = *、x 范围、AND/OR、连字符；不支持 npm 别名、git/file/workspace 范围与 prerelease 特例，遇到就 unknown。',
+  '只做升级规划，不做依赖冲突、重复包、peer 求解（那是 dsh-pkg 的活），也不改 package.json / lockfile。',
+  '风险信号是静态判据（major / engines / deprecated / yanked / peer），不代表真实兼容性；升级前仍要跑测试。',
+  'pin 只生成 diff 文本，不写文件；没有 installed 快照就不猜锁版本。',
+]
+
+/**
+ * 解析输入 manifest。
+ * @param {object} options 选项
+ * @returns {object} manifest
+ */
+function resolveManifest(options) {
+  if (options.manifest && typeof options.manifest === 'object' && !Array.isArray(options.manifest)) return options.manifest
+  if (options.packageJson && typeof options.packageJson === 'object' && !Array.isArray(options.packageJson)) return options.packageJson
+  if (typeof options.packageJsonText === 'string' && options.packageJsonText.trim().length > 0) {
+    try {
+      const parsed = JSON.parse(options.packageJsonText)
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('根不是对象')
+      return parsed
+    } catch (error) {
+      throw new DepsError('invalid_manifest', `package.json 文本不是合法 JSON：${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  throw new DepsError('missing_manifest', '需要 manifest（package.json 解析后的对象）或 packageJsonText', {
+    hint: '插件里传 packageJson 对象；CLI 用 --package-json <路径>。',
+  })
+}
+
+/**
+ * 预处理：收集依赖 + 归一化快照 + 分类。
+ * @param {object} options 选项
+ * @returns {object} 上下文
+ */
+function prepare(options) {
+  const manifest = resolveManifest(options)
+  const deps = collectDependencies(manifest)
+  const snapshot = normalizeSnapshot(options.snapshot)
+  const installed = normalizeInstalled(options.installed)
+  const problems = [...snapshot.problems, ...installed.problems]
+
+  const manifestsForCount = Array.isArray(options.manifests) && options.manifests.length > 0 ? options.manifests : [manifest]
+  const { counts, source } = countDependents(manifestsForCount, deps.map((dep) => dep.name))
+
+  // 调用方显式给的 dependents 覆盖自动计数
+  if (options.dependents && typeof options.dependents === 'object' && !Array.isArray(options.dependents)) {
+    for (const [name, value] of Object.entries(options.dependents)) {
+      const number = Number(value)
+      if (counts.has(name) && Number.isFinite(number) && number >= 0) counts.set(name, Math.trunc(number))
+    }
+  }
+
+  const nodeVersion = typeof options.nodeVersion === 'string' && options.nodeVersion.length > 0 ? options.nodeVersion : process.versions.node
+  const { entries } = classifyAll(manifest, { deps, snapshot: snapshot.entries, installed: installed.versions, dependents: counts, nodeVersion, problems })
+
+  return { manifest, entries, snapshot, installed, counts, countSource: source, nodeVersion, problems }
+}
+
+/**
+ * 处理一个动作。
+ * @param {string} action 动作
+ * @param {object} [options] 选项
+ * @returns {object} 结果（纯 JSON、只读标记）
+ */
+export function runAction(action, options = {}) {
+  if (!ACTIONS.includes(action)) {
+    throw new DepsError('invalid_action', `不认识的动作 ${JSON.stringify(action)}`, { hint: `可选：${ACTIONS.join(' / ')}` })
+  }
+
+  const context = prepare(options)
+  const base = {
+    tool: 'dsh_deps',
+    version: VERSION,
+    readOnly: true,
+    wroteFiles: [],
+    limitations: [...LIMITATIONS],
+  }
+  const plan = buildPlan(context.entries, { countSource: context.countSource })
+
+  const common = {
+    ...base,
+    manifestName: typeof context.manifest.name === 'string' ? context.manifest.name : '',
+    nodeVersion: context.nodeVersion,
+    snapshotProvided: context.snapshot.entries.size > 0,
+    installedProvided: context.installed.versions.size > 0,
+    versionSourceNote: context.installed.versions.size > 0 ? '当前版本优先取 installed 快照' : '当前版本取声明范围下界（不是 lock 实际版本）',
+    entries: context.entries,
+    plan,
+    notes: [...context.problems],
+    rationale: ORDER_RATIONALE,
+    phaseOrder: [...PHASES],
+  }
+
+  if (action === 'plan') return { ...common, action: 'plan' }
+
+  if (action === 'why') {
+    const name = typeof options.name === 'string' ? options.name.trim() : ''
+    if (name.length === 0) throw new DepsError('missing_name', 'why 需要 name（要解释的依赖名）')
+    const explanation = explainEntry(name, context.entries, {
+      snapshot: context.snapshot.entries,
+      installed: context.installed.versions,
+      nodeVersion: context.nodeVersion,
+      manifest: context.manifest,
+    })
+    return { ...common, action: 'why', ...explanation }
+  }
+
+  if (action === 'pin') {
+    const pin = buildPinSuggestions(context.entries, { packageJsonText: options.packageJsonText })
+    return { ...common, action: 'pin', ...pin, notes: [...context.problems, ...pin.notes] }
+  }
+
+  // audit
+  const audit = auditReport(context.entries, plan, context.problems, {
+    nodeVersion: context.nodeVersion,
+    snapshotProvided: context.snapshot.entries.size > 0,
+  })
+  return { ...common, action: 'audit', audit }
+}
+
+export { describeSnapshotShape, SNAPSHOT_SHAPE } from './deps.mjs'

package/lib/errors.mjs

@@ -0,0 +1,31 @@
+/**
+ * 稳定错误码：按 code 分支，不靠猜文案。
+ *
+ * 「快照里没有 latest」不是异常，是正常结论（bump=unknown）；
+ * 异常只留给「manifest 缺失/不合法 / 动作不认识 / 快照文件读不了」这类。
+ */
+
+/** 本插件错误基类。 */
+export class DepsError extends Error {
+  /**
+   * @param {string} code 稳定错误码
+   * @param {string} message 中文人话
+   * @param {{hint?:string, cause?:unknown}} [init] 附加
+   */
+  constructor(code, message, init = {}) {
+    super(message, init.cause === undefined ? undefined : { cause: init.cause })
+    this.name = 'DepsError'
+    this.code = code
+    this.hint = init.hint
+  }
+}
+
+/**
+ * 把任意异常转成结构化错误。
+ * @param {unknown} error 异常
+ * @returns {{code:string, message:string, hint?:string}} 结构化错误
+ */
+export function describeError(error) {
+  if (error instanceof DepsError) return { code: error.code, message: error.message, hint: error.hint }
+  return { code: 'internal', message: error instanceof Error ? error.message : String(error) }
+}

package/lib/format.mjs

@@ -0,0 +1,162 @@
+/**
+ * 结果 → 文本：工具 render 与 CLI 共用。
+ *
+ * 排版口径：先结论，再建议顺序（每步带依据），最后是 unknown / blocked / pinned 的分流。
+ * 所有动作都只读，文本里不出现「已修改」这种话。
+ */
+
+/**
+ * 渲染任意动作结果。
+ * @param {object} report 结果
+ * @param {{detail?:'brief'|'full'}} [options] 选项
+ * @returns {string} 文本
+ */
+export function renderReport(report, options = {}) {
+  const full = (options.detail ?? 'full') === 'full'
+  const lines = [`dsh-deps ${report.version} · ${report.action}`]
+
+  switch (report.action) {
+    case 'plan': renderPlan(lines, report, full); break
+    case 'why': renderWhy(lines, report, full); break
+    case 'pin': renderPin(lines, report, full); break
+    case 'audit': renderAudit(lines, report, full); break
+    default: lines.push('（未知动作）')
+  }
+
+  if (full && Array.isArray(report.notes) && report.notes.length > 0) {
+    lines.push('')
+    lines.push('【说明】')
+    for (const note of report.notes) lines.push(`- ${note}`)
+  }
+  if (full && Array.isArray(report.limitations) && report.limitations.length > 0) {
+    lines.push('')
+    lines.push('【已知限制】')
+    for (const item of report.limitations) lines.push(`- ${item}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * plan 渲染。
+ * @param {string[]} lines 输出行
+ * @param {object} report 结果
+ * @param {boolean} full 是否完整
+ * @returns {void}
+ */
+function renderPlan(lines, report, full) {
+  const plan = report.plan
+  lines.push('')
+  lines.push(`【结论】共 ${plan.counts.total} 个依赖 ｜ 可升 ${plan.counts.actionable} 个 ｜ patch ${plan.counts.byBump.patch} / minor ${plan.counts.byBump.minor} / major ${plan.counts.byBump.major} ｜ pinned ${plan.counts.byBump.pinned} ｜ unknown ${plan.counts.byBump.unknown} ｜ blocked ${plan.counts.byRisk.blocked}`)
+  if (full) lines.push(`理由：${plan.rationale}`)
+
+  if (plan.order.length === 0) {
+    lines.push('')
+    lines.push('没有需要按顺序执行的升级。')
+  } else {
+    lines.push('')
+    lines.push('【建议顺序】')
+    for (const item of plan.order) {
+      lines.push(`${item.step}. ${item.name}  ${item.currentVersion} → ${item.latest}（${item.bump}，risk=${item.risk}，被依赖 ${item.dependents} 次）建议 ${item.suggested}`)
+      if (full) lines.push(`   ${item.orderReason}`)
+    }
+  }
+
+  for (const [label, list] of [
+    ['被阻塞（不进队列）', plan.blocked],
+    ['未判定（不猜）', plan.unknown],
+    ['无需升级', plan.pinned],
+  ]) {
+    if (list.length === 0) continue
+    lines.push('')
+    lines.push(`【${label}】`)
+    for (const item of list.slice(0, 20)) lines.push(`- ${item.name}：${item.reason}${item.action ? ` → ${item.action}` : ''}`)
+    if (list.length > 20) lines.push(`- …还有 ${list.length - 20} 个`)
+  }
+}
+
+/**
+ * why 渲染。
+ * @param {string[]} lines 输出行
+ * @param {object} report 结果
+ * @param {boolean} full 是否完整
+ * @returns {void}
+ */
+function renderWhy(lines, report, full) {
+  lines.push('')
+  lines.push(`【结论】${report.conclusion}`)
+  if (!report.found) return
+  lines.push('')
+  lines.push('【判定依据】')
+  for (const check of report.checks) lines.push(`- ${check.id}：${JSON.stringify(check.value)} —— ${check.detail}`)
+  if (full && report.entry.signals.length > 0) {
+    lines.push('')
+    lines.push('【风险信号】')
+    for (const signal of report.entry.signals) lines.push(`- ${signal.signal}（${signal.severity}）：${signal.detail} → ${signal.action}`)
+  }
+}
+
+/**
+ * pin 渲染。
+ * @param {string[]} lines 输出行
+ * @param {object} report 结果
+ * @param {boolean} full 是否完整
+ * @returns {void}
+ */
+function renderPin(lines, report, full) {
+  lines.push('')
+  lines.push(`【结论】${report.summary}`)
+  if (report.changes.length > 0) {
+    lines.push('')
+    lines.push('【收紧清单】')
+    for (const change of report.changes) lines.push(`- ${change.name}（${change.section}）：${change.from} → ${change.to}（锁版本 ${change.locked}）`)
+    lines.push('')
+    lines.push('【建议 diff（未写入，复制后自行应用）】')
+    lines.push(report.diff.trimEnd())
+  }
+  if (full && report.notes.length > 0) {
+    lines.push('')
+    lines.push('【跳过说明】')
+    for (const note of report.notes) lines.push(`- ${note}`)
+  }
+}
+
+/**
+ * audit 渲染。
+ * @param {string[]} lines 输出行
+ * @param {object} report 结果
+ * @param {boolean} full 是否完整
+ * @returns {void}
+ */
+function renderAudit(lines, report, full) {
+  const audit = report.audit
+  lines.push('')
+  lines.push(`【结论 ${audit.verdict}】${audit.summary}`)
+  lines.push(`Node ${audit.nodeVersion ?? '(未知)'} ｜ 快照${audit.snapshotProvided ? '已提供' : '未提供（所有 latest 都会 unknown）'}`)
+  lines.push('')
+  lines.push('【计数】' + Object.entries(audit.counts.byBump).map(([key, value]) => `${key} ${value}`).join(' ｜ '))
+  const signals = Object.entries(audit.signals).sort((a, b) => b[1] - a[1])
+  if (signals.length > 0) {
+    lines.push('')
+    lines.push('【风险信号】')
+    for (const [signal, count] of signals) lines.push(`- ${signal} × ${count}`)
+  }
+  if (full && audit.recommendations.length > 0) {
+    lines.push('')
+    lines.push('【建议动作】')
+    for (const item of audit.recommendations) lines.push(`- ${item}`)
+  }
+  if (full && report.plan?.order?.length > 0) {
+    lines.push('')
+    lines.push('【建议顺序】')
+    for (const item of report.plan.order) lines.push(`${item.step}. ${item.name} ${item.currentVersion} → ${item.latest}（${item.bump}）`)
+  }
+}
+
+/**
+ * JSON 渲染。
+ * @param {object} report 结果
+ * @returns {string} JSON
+ */
+export function renderJson(report) {
+  return JSON.stringify(report, null, 2)
+}

package/lib/index.mjs

@@ -0,0 +1,30 @@
+/**
+ * 公开 API：plugin.mjs、CLI、别人的程序共用同一套实现。
+ */
+
+export {
+  runAction, VERSION, ACTIONS, LIMITATIONS, describeSnapshotShape, SNAPSHOT_SHAPE,
+} from './engine.mjs'
+
+export {
+  parseVersion, compareVersions, versionEquals, parseRange, satisfiesRange, rangeFloor, bumpType, checkEngines,
+  SemverError, UNSUPPORTED_RANGE_PREFIXES,
+} from './version.mjs'
+
+export {
+  collectDependencies, normalizeSnapshot, normalizeInstalled, countDependents, DEP_SECTIONS,
+} from './deps.mjs'
+
+export {
+  classifyDependency, classifyAll, deriveRisk, suggestRange, BUMPS, RISKS, RISK_RANK, RISK_LABEL,
+} from './classify.mjs'
+
+export {
+  buildPlan, auditReport, explainEntry, PHASES, PHASE_LABEL, ORDER_RATIONALE,
+} from './plan.mjs'
+
+export { buildPinSuggestions } from './pin.mjs'
+
+export { renderReport, renderJson } from './format.mjs'
+
+export { DepsError, describeError } from './errors.mjs'

package/lib/pin.mjs

@@ -0,0 +1,142 @@
+/**
+ * pin：把声明范围收紧到「已锁版本」的 patch 建议。
+ *
+ * 只生成 diff 文本，**不写任何文件**（返回 wroteFiles: []）。
+ * 没有 installed 快照的依赖不猜锁版本，列入 notes。
+ */
+
+import { rangeFloor, satisfiesRange, parseVersion } from './version.mjs'
+import { suggestRange } from './classify.mjs'
+
+/**
+ * 生成 pin 建议。
+ * @param {object[]} entries 分类后的条目
+ * @param {{packageJsonText?:string}} [options] 选项
+ * @returns {object} 建议（含 diff 文本）
+ */
+export function buildPinSuggestions(entries, options = {}) {
+  const changes = []
+  const notes = []
+
+  for (const entry of entries) {
+    if (entry.versionSource !== 'installed') {
+      notes.push(`${entry.name} 没有 installed 快照：无法给出 pin 建议（不猜锁版本）`)
+      continue
+    }
+    const floor = rangeFloor(entry.current)
+    const installed = entry.currentVersion
+    if (!floor || !parseVersion(installed)) {
+      notes.push(`${entry.name} 的范围 ${entry.current} 不可判定：跳过`)
+      continue
+    }
+    if (floor === installed) continue // 范围下界已经是锁版本，无需收紧
+    const satisfied = satisfiesRange(installed, entry.current)
+    if (!satisfied.supported) {
+      notes.push(`${entry.name} 的范围不受支持（${entry.current}）：跳过`)
+      continue
+    }
+    if (!satisfied.satisfies) {
+      notes.push(`${entry.name} 的锁版本 ${installed} 不满足声明范围 ${entry.current}：这是 drift，不是 pin 能修的（交给 lockfile 检查）`)
+      continue
+    }
+    changes.push({
+      name: entry.name,
+      section: entry.section,
+      from: entry.current,
+      to: suggestRange(entry.current, installed),
+      locked: installed,
+    })
+  }
+
+  const diff = changes.length === 0
+    ? ''
+    : options.packageJsonText
+      ? diffAgainstText(options.packageJsonText, changes)
+      : syntheticDiff(changes)
+
+  return {
+    changes,
+    diff,
+    applied: false,
+    wroteFiles: [],
+    notes: notes.length > 0 ? notes : [],
+    summary: changes.length === 0
+      ? '没有可收紧的范围（要么没有 installed 快照，要么范围下界已经是锁版本）。'
+      : `建议收紧 ${changes.length} 个依赖的范围到已锁版本（仅 diff 文本，不写文件）。`,
+  }
+}
+
+/**
+ * 对真实 package.json 文本生成 unified diff（hunk 带行号）。
+ * @param {string} text 文件内容
+ * @param {Array<object>} changes 变更
+ * @returns {string} diff
+ */
+function diffAgainstText(text, changes) {
+  const lines = text.split('\n')
+  const edits = []
+  for (const change of changes) {
+    const escaped = escapeRegExp(change.name)
+    const pattern = new RegExp(`^(\\s*)"${escaped}"(\\s*:\\s*)"${escapeRegExp(change.from)}"(\\s*,?\\s*)$`)
+    const index = lines.findIndex((line) => pattern.test(line))
+    if (index === -1) continue
+    edits.push({ index, before: lines[index], after: lines[index].replace(pattern, `$1"${change.name}"$2"${change.to}"$3`) })
+  }
+  if (edits.length === 0) return syntheticDiff(changes)
+  edits.sort((a, b) => a.index - b.index)
+
+  const hunks = []
+  let current = null
+  for (const edit of edits) {
+    const start = Math.max(0, edit.index - 1)
+    const end = Math.min(lines.length - 1, edit.index + 1)
+    if (current && start <= current.end + 1) {
+      current.edits.push(edit)
+      current.end = Math.max(current.end, end)
+    } else {
+      current = { start, end, edits: [edit] }
+      hunks.push(current)
+    }
+  }
+
+  const output = ['--- package.json', '+++ package.json (suggested, not written)']
+  for (const hunk of hunks) {
+    const count = hunk.end - hunk.start + 1
+    output.push(`@@ -${hunk.start + 1},${count} +${hunk.start + 1},${count} @@`)
+    const edited = new Map(hunk.edits.map((edit) => [edit.index, edit]))
+    for (let i = hunk.start; i <= hunk.end; i++) {
+      const edit = edited.get(i)
+      if (edit) {
+        output.push(`-${edit.before}`)
+        output.push(`+${edit.after}`)
+      } else {
+        output.push(` ${lines[i]}`)
+      }
+    }
+  }
+  return `${output.join('\n')}\n`
+}
+
+/**
+ * 没有原文时的合成 diff。
+ * @param {Array<object>} changes 变更
+ * @returns {string} diff
+ */
+function syntheticDiff(changes) {
+  const output = ['--- package.json', '+++ package.json (suggested, not written)']
+  for (const change of changes) {
+    output.push(`@@ ${change.section} @@`)
+    output.push(`-    "${change.name}": "${change.from}",`)
+    output.push(`+    "${change.name}": "${change.to}",`)
+  }
+  return `${output.join('\n')}\n`
+}
+
+/**
+ * 正则转义。
+ * @param {string} text 文本
+ * @returns {string} 转义结果
+ */
+function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}