@tokensapi/dsh-plugin-check 0.3.4 → 0.4.0

package/lib/registry-check.mjs

@@ -1,206 +1,78 @@
-/* ============================================================
- * 已发布包体检(注册表版,零依赖纯函数)
- * ============================================================
- * 对 npm registry 的版本文档跑清单规则,与目录体检(manifest-check)
- * 同一套语义,但不需要文件系统 —— 供 Cowork 插件进程内使用。
- *
- * 两个入口:
- *  - checkPublishedManifest 纯同步零依赖,只看清单字段;
- *  - checkPublishedPackage 额外取 tarball 读出 cordis.patch.yml,
- *    补上 M4/M5 —— 只看清单会漏掉"补丁行 name 写成插件名"这类
- *    装上即让整棵插件树崩溃的缺陷。
- * 冒烟阶段无法在宿主进程执行,完整体检走 CLI 或 Plugin Check
- * workflow。
- * ============================================================ */
-import { checkPatchContent } from './patch-rows.mjs'
-import { fetchTarEntry } from './tarball.mjs'
-import { LIFECYCLE_SCRIPTS, lifecycleMessage } from './contract.mjs'
-
-const isIdentityCore = (name) =>
-  name === '@deepseek-ai/cordis' || name.startsWith('@deepseek-ai/cordis-') || name.startsWith('@deepseek-ai/dsh')
-
-/* ------------------------- 迷你 SemVer ------------------------- */
-// 只实现体检需要的子集:比较 + 范围判定(空格=且、||=或、^、~、
-// >=、>、<=、<、=、裸版本),预发布参与比较;识别不了的范围返回
-// null 由调用方按"范围不合法"处理。
-
-function parseVersion(input) {
-  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(String(input).trim())
-  if (!match) return null
-  return {
-    parts: [Number(match[1]), Number(match[2]), Number(match[3])],
-    prerelease: match[4] === undefined ? [] : match[4].split('.'),
-  }
-}
-
-function compareVersions(a, b) {
-  for (let index = 0; index < 3; index += 1) {
-    if (a.parts[index] !== b.parts[index]) return a.parts[index] < b.parts[index] ? -1 : 1
-  }
-  if (a.prerelease.length === 0 && b.prerelease.length === 0) return 0
-  if (a.prerelease.length === 0) return 1
-  if (b.prerelease.length === 0) return -1
-  const length = Math.max(a.prerelease.length, b.prerelease.length)
-  for (let index = 0; index < length; index += 1) {
-    const left = a.prerelease[index]
-    const right = b.prerelease[index]
-    if (left === undefined) return -1
-    if (right === undefined) return 1
-    const leftNumeric = /^\d+$/u.test(left)
-    const rightNumeric = /^\d+$/u.test(right)
-    if (leftNumeric && rightNumeric) {
-      if (Number(left) !== Number(right)) return Number(left) < Number(right) ? -1 : 1
-    } else if (leftNumeric !== rightNumeric) {
-      return leftNumeric ? -1 : 1
-    } else if (left !== right) {
-      return left < right ? -1 : 1
-    }
-  }
-  return 0
-}
-
-function comparatorHolds(version, operator, boundary) {
-  const cmp = compareVersions(version, boundary)
-  if (operator === '>') return cmp > 0
-  if (operator === '>=') return cmp >= 0
-  if (operator === '<') return cmp < 0
-  if (operator === '<=') return cmp <= 0
-  return cmp === 0
-}
-
-export function versionSatisfies(versionInput, rangeInput) {
-  const version = parseVersion(versionInput)
-  if (version === null) return null
-  const alternatives = String(rangeInput).split('||')
-  let recognized = false
-  for (const alternative of alternatives) {
-    const comparators = alternative.trim().split(/\s+/u).filter(Boolean)
-    if (comparators.length === 0) continue
-    let holds = true
-    let valid = true
-    for (const comparator of comparators) {
-      if (comparator === '*' || comparator === 'x') continue
-      const match = /^(>=|<=|>|<|=|\^|~)?(.+)$/u.exec(comparator)
-      const boundary = parseVersion(match[2])
-      if (boundary === null) { valid = false; break }
-      const operator = match[1] ?? '='
-      if (operator === '^') {
-        const upper = boundary.parts[0] > 0
-          ? { parts: [boundary.parts[0] + 1, 0, 0], prerelease: ['0'] }
-          : boundary.parts[1] > 0
-            ? { parts: [0, boundary.parts[1] + 1, 0], prerelease: ['0'] }
-            : { parts: [0, 0, boundary.parts[2] + 1], prerelease: ['0'] }
-        holds = holds && comparatorHolds(version, '>=', boundary) && comparatorHolds(version, '<', upper)
-      } else if (operator === '~') {
-        const upper = { parts: [boundary.parts[0], boundary.parts[1] + 1, 0], prerelease: ['0'] }
-        holds = holds && comparatorHolds(version, '>=', boundary) && comparatorHolds(version, '<', upper)
-      } else {
-        holds = holds && comparatorHolds(version, operator, boundary)
-      }
-      if (!holds) break
-    }
-    if (!valid) continue
-    recognized = true
-    if (holds) return true
-  }
-  return recognized ? false : null
-}
-
-/* --------------------------- 规则 --------------------------- */
-
-/**
- * 对一份 npm 版本清单跑体检规则。
- * @param {object} manifest - registry 版本文档(scripts/dependencies/
- *   peerDependencies/dsh/engines/license/version)。
- * @param {string} runtime - 目标 DSH 运行时版本。
- * @returns {Array<{level: 'error'|'warning', rule: string, message: string}>}
- */
-export function checkPublishedManifest(manifest, runtime) {
-  const findings = []
-  const error = (rule, message) => findings.push({ level: 'error', rule, message })
-  const warning = (rule, message) => findings.push({ level: 'warning', rule, message })
-
-  const scripts = manifest.scripts ?? {}
-  for (const script of LIFECYCLE_SCRIPTS) {
-    if (typeof scripts[script] === 'string') warning('M2-lifecycle', lifecycleMessage(script))
-  }
-
-  for (const name of Object.keys(manifest.dependencies ?? {})) {
-    if (isIdentityCore(name)) {
-      error('M3-core-peer', `${name} 出现在 dependencies;核心运行时必须是 peerDependencies,否则双内核实例会让 Cowork 启动失败`)
-    }
-  }
-
-  const bundle = manifest.dsh?.bundle ?? {}
-  if (typeof bundle.patch !== 'string' || bundle.patch === '') {
-    error('M4-bundle', 'dsh.bundle.patch 缺失;宿主靠它把插件挂进加载树')
-  }
-
-  const engine = typeof manifest.dsh?.engine === 'string' ? manifest.dsh.engine : undefined
-  if (engine === undefined) {
-    warning('M6-engine', 'dsh.engine 未声明(目标运行时 SemVer 范围);'
-      + '上游目前不强制读取该字段,但声明之后体检才能判断你与目标运行时是否相容')
-  } else {
-    const satisfied = versionSatisfies(runtime, engine)
-    if (satisfied === null) error('M6-engine', `dsh.engine 不是可识别的 SemVer 范围: ${engine}`)
-    else if (!satisfied) error('M6-engine', `dsh.engine "${engine}" 不覆盖当前运行时 ${runtime}`)
-  }
-
-  for (const [name, range] of Object.entries(manifest.peerDependencies ?? {})) {
-    if (!name.startsWith('@deepseek-ai/dsh')) continue
-    const satisfied = versionSatisfies(runtime, String(range))
-    if (satisfied === null) error('M7-peer-range', `peer ${name} 的范围不可识别: ${range}`)
-    else if (!satisfied) warning('M7-peer-range', `peer ${name}@"${range}" 不含当前运行时 ${runtime};宿主升级后可能运行时断裂`)
-  }
-
-  if (manifest.engines?.node === undefined) warning('M8-node-engines', 'engines.node 未声明;宿主运行在 Node 22+')
-  if (manifest.license === undefined) warning('M9-license', 'license 未声明')
-
-  const parsed = parseVersion(typeof manifest.version === 'string' ? manifest.version : '')
-  if (parsed !== null && parsed.prerelease.length > 0) {
-    warning('M1-manifest', `version ${manifest.version} 是预发布版;`
-      + `市场受控安装只认稳定的精确版(上游 stableExactVersion),npm latest 停在预发布版时`
-      + `用户端只会看到手动安装命令。预发布请发在 next 之类的 dist-tag 上`)
-  }
-
-  return findings
-}
-
-/**
- * 已发布包的完整清单侧体检:清单规则 + 包内补丁行检查。
- * 取不到 tarball(离线、超时、体积过大)时降级为 warning 并如实
- * 标注未检查,绝不因网络问题把插件判成不合格。
- * @param {object} manifest - registry 版本文档(需含 dist.tarball)。
- * @param {string} runtime - 目标 DSH 运行时版本。
- * @param {{ maxBytes?: number, timeoutMs?: number }} [options]
- * @returns {Promise<{ findings: object[], inspectedPatch: boolean }>}
- */
-export async function checkPublishedPackage(manifest, runtime, options = {}) {
-  const findings = checkPublishedManifest(manifest, runtime)
-  const patch = typeof manifest.dsh?.bundle?.patch === 'string' ? manifest.dsh.bundle.patch : ''
-  const tarball = typeof manifest.dist?.tarball === 'string' ? manifest.dist.tarball : ''
-  // 补丁未声明时 M4 已在清单阶段报错,无需再取包。
-  if (patch === '' || tarball === '') return { findings, inspectedPatch: false }
-
-  const relative = patch.replace(/^\.?\//u, '')
-  const result = await fetchTarEntry(tarball, entry => entry === relative, options)
-  if (result.error !== undefined) {
-    findings.push({
-      level: 'warning',
-      rule: 'M4-bundle',
-      message: `未能读取包内 ${relative}(${result.error});本次跳过补丁行检查,完整体检请走 CLI`,
-    })
-    return { findings, inspectedPatch: false }
-  }
-  if (result.content === undefined) {
-    findings.push({
-      level: 'error',
-      rule: 'M4-bundle',
-      message: `dsh.bundle.patch 指向的文件不在发布内容里: ${patch};宿主取不到补丁就挂不上插件(检查 files 白名单)`,
-    })
-    return { findings, inspectedPatch: true }
-  }
-  const packageName = typeof manifest.name === 'string' ? manifest.name : ''
-  findings.push(...checkPatchContent(packageName, result.content).findings)
-  return { findings, inspectedPatch: true }
-}
+/* ============================================================
+ * 已发布包体检(注册表版)
+ * ============================================================
+ * 对 npm registry 的版本文档跑清单规则,与目录体检(manifest-check)
+ * **同一份实现** —— 不是"同一套语义"而已:清单侧规则全部来自
+ * checkManifestFields,两条路径不可能再对同一个包给出不同结论。
+ *
+ * 这里曾经自带一套手写的迷你 SemVer,理由是"会话内要零依赖";
+ * 那个前提本来就不成立(semver 是本包的 dependencies,宿主进程里
+ * 早就通过 cowork-plugin → manifest-check 加载了),代价却是把
+ * ">=0.1 <0.2"、"1.x"、"1.2.0 - 2.0.0" 这些完全合法的 npm 范围判成
+ * "不可识别" → error,合格插件被判不合格。已删除。
+ *
+ * 两个入口:
+ *  - checkPublishedManifest 只看清单字段;
+ *  - checkPublishedPackage 额外取 tarball 读出 cordis.patch.yml,
+ *    补上 M4/M5/M11 —— 只看清单会漏掉"补丁行 name 写成插件名"
+ *    这类装上即让整棵插件树崩溃的缺陷。
+ * 冒烟阶段无法在宿主进程执行,完整体检走 CLI 或 Plugin Check
+ * workflow。
+ * ============================================================ */
+import { checkPatchContent } from './patch-rows.mjs'
+import { fetchTarEntry } from './tarball.mjs'
+import { checkManifestFields } from './manifest-check.mjs'
+
+export { versionSatisfies } from './semver-rules.mjs'
+
+/**
+ * 对一份 npm 版本清单跑体检规则。
+ * @param {object} manifest - registry 版本文档(scripts/dependencies/
+ *   peerDependencies/dsh/engines/license/version)。
+ * @param {string} [runtime] - 目标 DSH 运行时版本;省略时只判范围合法性,
+ *   不判是否覆盖(以前这是必填位置参数且无 guard,传 undefined 会产生
+ *   一批凭空的 M6/M7 error)。
+ * @returns {Array<{level: 'error'|'warning', rule: string, message: string}>}
+ */
+export function checkPublishedManifest(manifest, runtime) {
+  return checkManifestFields(manifest, runtime)
+}
+
+/**
+ * 已发布包的完整清单侧体检:清单规则 + 包内补丁行检查。
+ * 取不到 tarball(离线、超时、体积过大)时降级为 warning 并如实
+ * 标注未检查,绝不因网络问题把插件判成不合格。
+ * @param {object} manifest - registry 版本文档(需含 dist.tarball)。
+ * @param {string} [runtime] - 目标 DSH 运行时版本。
+ * @param {{ maxBytes?: number, timeoutMs?: number }} [options]
+ * @returns {Promise<{ findings: object[], inspectedPatch: boolean }>}
+ */
+export async function checkPublishedPackage(manifest, runtime, options = {}) {
+  const findings = checkPublishedManifest(manifest, runtime)
+  const patch = typeof manifest.dsh?.bundle?.patch === 'string' ? manifest.dsh.bundle.patch : ''
+  const tarball = typeof manifest.dist?.tarball === 'string' ? manifest.dist.tarball : ''
+  // 补丁未声明时 M4 已在清单阶段报错,无需再取包。
+  if (patch === '' || tarball === '') return { findings, inspectedPatch: false }
+
+  const relative = patch.replace(/^\.?\//u, '')
+  const result = await fetchTarEntry(tarball, entry => entry === relative, options)
+  if (result.error !== undefined) {
+    findings.push({
+      level: 'warning',
+      rule: 'M4-bundle',
+      message: `未能读取包内 ${relative}(${result.error});本次跳过补丁行检查,完整体检请走 CLI`,
+    })
+    return { findings, inspectedPatch: false }
+  }
+  if (result.content === undefined) {
+    findings.push({
+      level: 'error',
+      rule: 'M4-bundle',
+      message: `dsh.bundle.patch 指向的文件不在发布内容里: ${patch};宿主取不到补丁就挂不上插件(检查 files 白名单)`,
+    })
+    return { findings, inspectedPatch: true }
+  }
+  const packageName = typeof manifest.name === 'string' ? manifest.name : ''
+  findings.push(...checkPatchContent(packageName, result.content).findings)
+  return { findings, inspectedPatch: true }
+}

package/lib/semver-rules.mjs

@@ -0,0 +1,129 @@
+/* ============================================================
+ * 版本相关规则(M1 / M6 / M7)的唯一实现
+ * ============================================================
+ * 这三条规则以前在两处各写一遍:CLI 走 manifest-check.mjs(用真
+ * semver),会话内 package= 走 registry-check.mjs(用一套手写的迷你
+ * SemVer)。迷你版只认完整三段版本号,把 ">=0.1 <0.2"、"1.x"、
+ * "1.2.0 - 2.0.0" 这些完全合法的 npm 范围判成"不可识别"→ error,
+ * 于是同一个包在两条路径上会拿到相反的结论,而且合格插件被判不合格。
+ *
+ * 现在统一到真 semver,并且只此一份:两条路径调同一个函数,再想漂
+ * 也漂不了(tests/cross-path.test.mjs 是这条约束的闸门)。
+ *
+ * 判定口径:一律带 includePrerelease —— 目标运行时本身就长期是
+ * 0.1.3-alpha.1 这种预发布版,不带这个选项 semver 会把它排除在
+ * 任何范围之外,得出"谁都不兼容"的荒谬结论。
+ * ============================================================ */
+import semver from 'semver'
+import { isIdentityCore, isRuntimeVersioned } from './contract.mjs'
+
+const OPTIONS = { includePrerelease: true }
+
+/**
+ * 版本是否落在范围内。
+ * @param {string} version - 具体版本。
+ * @param {string} range - SemVer 范围。
+ * @returns {boolean | null} 范围不合法时返回 null(保持既有对外契约)。
+ */
+export function versionSatisfies(version, range) {
+  if (semver.valid(version) === null) return null
+  if (semver.validRange(range, OPTIONS) === null) return null
+  return semver.satisfies(version, range, OPTIONS)
+}
+
+/**
+ * M1:name 与 version 的基本合法性。
+ * @param {object} manifest - package.json / registry 版本文档。
+ * @returns {Array<{level: string, rule: string, message: string}>}
+ */
+export function checkIdentity(manifest) {
+  const findings = []
+  if (typeof manifest.name !== 'string' || manifest.name === '') {
+    findings.push({ level: 'error', rule: 'M1-manifest', message: 'name 缺失' })
+  }
+  if (typeof manifest.version !== 'string' || semver.valid(manifest.version) === null) {
+    findings.push({ level: 'error', rule: 'M1-manifest', message: 'version 不是合法 SemVer' })
+  } else if (semver.prerelease(manifest.version) !== null) {
+    findings.push({
+      level: 'warning',
+      rule: 'M1-manifest',
+      message: `version ${manifest.version} 是预发布版;`
+        + `市场受控安装只认稳定的精确版(上游 stableExactVersion),npm latest 若停在预发布版,`
+        + `用户端拿不到一键安装按钮,只会看到手动命令。预发布请发在 next 之类的 dist-tag 上`,
+    })
+  }
+  return findings
+}
+
+/**
+ * M6:dsh.engine 声明的目标运行时范围。
+ * @param {object} manifest
+ * @param {string | undefined} runtime - 目标 DSH 运行时;未给时只判范围合法性。
+ * @returns {Array<{level: string, rule: string, message: string}>}
+ */
+export function checkEngine(manifest, runtime) {
+  const engine = typeof manifest.dsh?.engine === 'string' ? manifest.dsh.engine : undefined
+  if (engine === undefined) {
+    return [{
+      level: 'warning',
+      rule: 'M6-engine',
+      message: 'dsh.engine 未声明(目标 DSH 运行时 SemVer 范围,如 ">=0.1.3-alpha.1 <0.2");'
+        + '上游目前不强制读取该字段,但声明之后体检才能判断你与目标运行时是否相容',
+    }]
+  }
+  if (semver.validRange(engine, OPTIONS) === null) {
+    return [{ level: 'error', rule: 'M6-engine', message: `dsh.engine 不是合法 SemVer 范围: ${engine}` }]
+  }
+  if (runtime !== undefined && runtime !== '' && !semver.satisfies(runtime, engine, OPTIONS)) {
+    return [{ level: 'error', rule: 'M6-engine', message: `dsh.engine "${engine}" 不覆盖目标运行时 ${runtime}` }]
+  }
+  return []
+}
+
+/**
+ * M7:核心 peer 的范围。
+ *
+ * 两层判定的口径**故意不同**:
+ *  - 范围合法性:全部 isIdentityCore 的包。以前只看 @deepseek-ai/dsh
+ *    前缀,@deepseek-ai/cordis 的范围写坏了完全不报,偏偏它正是 S2 冒烟
+ *    真正要装的那个包,范围写坏下一步必然装不出来。
+ *  - 是否含目标运行时:只对 isRuntimeVersioned 的包。cordis 自成 4.x
+ *    版本线,拿它跟运行时 0.1.3-alpha.1 比是范畴错误(详见 contract.mjs)。
+ * @param {object} manifest
+ * @param {string | undefined} runtime
+ * @returns {Array<{level: string, rule: string, message: string}>}
+ */
+export function checkPeerRanges(manifest, runtime) {
+  const findings = []
+  for (const [name, range] of Object.entries(manifest.peerDependencies ?? {})) {
+    if (!isIdentityCore(name)) continue
+    if (semver.validRange(String(range), OPTIONS) === null) {
+      findings.push({ level: 'error', rule: 'M7-peer-range', message: `peer ${name} 的范围不合法: ${range}` })
+      continue
+    }
+    if (!isRuntimeVersioned(name)) continue
+    if (runtime === undefined || runtime === '') continue
+    if (!semver.satisfies(runtime, String(range), OPTIONS)) {
+      findings.push({
+        level: 'warning',
+        rule: 'M7-peer-range',
+        message: `peer ${name}@"${range}" 不含目标运行时 ${runtime};宿主升级后此插件可能在运行时断裂(接口错配类故障)`,
+      })
+    }
+  }
+  return findings
+}
+
+/**
+ * 三条一起跑,供两条执行路径直接复用。
+ * @param {object} manifest
+ * @param {string | undefined} runtime
+ * @returns {Array<{level: string, rule: string, message: string}>}
+ */
+export function checkVersionRules(manifest, runtime) {
+  return [
+    ...checkIdentity(manifest),
+    ...checkEngine(manifest, runtime),
+    ...checkPeerRanges(manifest, runtime),
+  ]
+}

package/lib/smoke-check.mjs

@@ -193,7 +193,19 @@ export function checkSmoke(pluginDir, manifest, rows, options = {}) {
       error('S4-apply', `冒烟子进程异常: ${reason}`)
       return { findings, workspace: options.keepWorkspace ? workspace : undefined }
     }
-    const results = JSON.parse(readFileSync(resultPath, 'utf8'))
+    // 子进程写出的结果文件理论上总是合法 JSON,但它可能被入口代码
+    // 的 stdout 污染、被磁盘写满截断、或者被入口自己覆盖掉。那种时候
+    // 崩掉整个 CLI 等于把"这个插件冒烟失败"变成"体检工具坏了",
+    // 作者拿不到任何可用结论 —— 按 S4-apply error 如实报出来。
+    let results
+    try {
+      results = JSON.parse(readFileSync(resultPath, 'utf8'))
+      if (!Array.isArray(results)) throw new TypeError('结果不是数组')
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause)
+      error('S4-apply', `冒烟结果文件不可解析: ${reason}(多半是插件入口往 stdout/结果文件里写了东西)`)
+      return { findings, workspace: options.keepWorkspace ? workspace : undefined }
+    }
     const passed = results.filter(result => result.status === 'ok').length
     findings.push({ level: 'info', rule: 'S4-apply', message: `隔离冒烟: ${passed}/${results.length} 行通过(解析→import→应用)` })
     for (const result of results) {

package/lib/tarball.mjs

@@ -88,7 +88,11 @@ export async function fetchTarEntry(url, match, options = {}) {
     if (declared > maxBytes) return { error: `tarball 超过 ${Math.round(maxBytes / 1024 / 1024)}MB,跳过包内检查` }
     const raw = Buffer.from(await response.arrayBuffer())
     if (raw.length > maxBytes) return { error: `tarball 超过 ${Math.round(maxBytes / 1024 / 1024)}MB,跳过包内检查` }
-    return { content: readTarEntry(gunzipSync(raw), match) }
+    // 上面两道闸只管住了**压缩后**的字节数,解压后的体积不受它约束
+    // —— 一个几百 KB 的 gzip 可以解成几 GB。maxOutputLength 让 zlib
+    // 在超限时抛错(ERR_BUFFER_TOO_LARGE)而不是把内存吃干。
+    const tar = gunzipSync(raw, { maxOutputLength: maxBytes })
+    return { content: readTarEntry(tar, match) }
   } catch (cause) {
     const reason = cause instanceof Error ? cause.message : String(cause)
     return { error: cause?.name === 'AbortError' ? '下载 tarball 超时' : `读取 tarball 失败: ${reason}` }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokensapi/dsh-plugin-check",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "TokensCowork/DSH 插件合格性体检:CLI 一条命令判定插件能否安全装入宿主;装入 Cowork 后提供会话内 plugin_check 工具。",
   "type": "module",
   "bin": {