@tokensapi/dsh-plugin-check 0.3.3 → 0.4.0

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,44 +1,45 @@
-{
-  "name": "@tokensapi/dsh-plugin-check",
-  "version": "0.3.3",
-  "description": "TokensCowork/DSH \u63d2\u4ef6\u5408\u683c\u6027\u4f53\u68c0:CLI \u4e00\u6761\u547d\u4ee4\u5224\u5b9a\u63d2\u4ef6\u80fd\u5426\u5b89\u5168\u88c5\u5165\u5bbf\u4e3b;\u88c5\u5165 Cowork \u540e\u63d0\u4f9b\u4f1a\u8bdd\u5185 plugin_check \u5de5\u5177\u3002",
-  "type": "module",
-  "bin": {
-    "dsh-plugin-check": "bin/dsh-plugin-check.mjs"
-  },
-  "files": [
-    "bin",
-    "lib",
-    "cordis.patch.yml",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node --test \"tests/*.test.mjs\""
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "dependencies": {
-    "js-yaml": "^4.1.0",
-    "semver": "^7.6.0"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/TokensAPI/tokens_DshPluginCheck_code.git"
-  },
-  "main": "lib/cowork-plugin.mjs",
-  "exports": {
-    ".": "./lib/cowork-plugin.mjs"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "4.0.1 || 4.0.2",
-    "@deepseek-ai/dsh-tools": "0.1.0-rc.8 || 0.1.3-alpha.1"
-  },
-  "dsh": {
-    "engine": ">=0.1.0-rc.8 <0.2.0",
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  }
-}
+{
+  "name": "@tokensapi/dsh-plugin-check",
+  "version": "0.4.0",
+  "description": "TokensCowork/DSH 插件合格性体检:CLI 一条命令判定插件能否安全装入宿主;装入 Cowork 后提供会话内 plugin_check 工具。",
+  "type": "module",
+  "bin": {
+    "dsh-plugin-check": "bin/dsh-plugin-check.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "docs",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test \"tests/*.test.mjs\""
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "semver": "^7.6.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TokensAPI/tokens_DshPluginCheck_code.git"
+  },
+  "main": "lib/cowork-plugin.mjs",
+  "exports": {
+    ".": "./lib/cowork-plugin.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.1 || 4.0.2",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.8 || 0.1.3-alpha.1"
+  },
+  "dsh": {
+    "engine": ">=0.1.0-rc.8 <0.2.0",
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}