@bushizhanghan/dsh-publish-gate 0.3.3 → 0.4.0

package/README.md

@@ -30,7 +30,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | 工具 | 作用 |
 |---|---|
 | `publish_gate` | 全量门禁：清单 + 产物 + 运行时 + 浏览器半边 + 网络，返回 `safeToPublish`（`skipPack` / `skipTools` / `skipClient` / `skipNetwork` 可逐层跳过） |
-| `publish_gate_tools` | 只跑运行时层：在子进程里 `apply(ctx)`，看注册了哪些工具、有没有缺 `execute`、重名、`presentCall` 抛错、`card` 用了宿主不认识的值 | 传 `call: ["工具名"]` 可以**真的调一次**（空参数）：注册永远不会执行 `execute`，所以「一调就抛 ReferenceError」这类 bug 只有这一条能看见。默认不调——有些工具会开程序或写文件，你点名才算同意。 |
+| `publish_gate_tools` | 只跑运行时层：在子进程里 `apply(ctx)`，看注册了哪些工具、有没有缺 `execute`、重名、`presentCall` 抛错、`card` 用了宿主不认识的值 | 传 `call: ["工具名"]` 可以**真的调一次**（空参数）：注册永远不会执行 `execute`，所以「一调就抛 ReferenceError」这类 bug 只有这一条能看见。默认不调——有些工具会开程序或写文件，你点名才算同意。超时单独算 `tool-call-slow`（warn），不跟「真的抛了」混在一起：`of_env` 这种要起 WSL 的工具本来就慢。 |
 | `publish_gate_client` | 只跑浏览器半边：在子进程里假造 `window.__ModuleLoader__`，看 bundle 会不会加载、`apply` 会不会抛、到底往哪个服务注册了东西、`inject` 有没有漏 |
 | `publish_gate_verify` | 发后校验：`npm pack --dry-run` 的 shasum 和 registry 上的 `dist.shasum` 逐字节比，比版本号猜准 |
 | `publish_gate_patch` | 只查 `cordis.patch.yml`——「插件装了但工具没出现」的第一个怀疑对象 |
@@ -66,6 +66,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `require-in-esm` | ESM 里 `require()` → `ERR_AMBIGUOUS_MODULE_SYNTAX`，报错不带行号 |
 | `no-license` | 缺 LICENSE |
 | `version-taken` | 这个版本已经在 registry 上，再发是 403 |
+| `version-behind-latest` | 本地版本比 registry 上的 `latest` **旧**。npm 会照收，但 `latest` 继续指向新版本——包上传了，按名字装的人永远拿不到，且没有任何报错 |
 | `registry-unreachable` | registry 回了 500/429 —— 版本检查**没跑**，所以别把它当干净 |
 
 ### 值得在发布前知道的（warn / info）
@@ -137,6 +138,18 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 
 `lib-debugger`（error）、`lib-console-log`、`lib-hardcoded-path`（`C:\Users\...` 硬编码）、`lib-url-pathname`（`new URL(...).pathname` 在中文路径上会百分号编码，得用 `fileURLToPath`）、`node-too-old`（`engines.node` 写着 `>=18`，`lib/` 里却用了 `Object.groupBy`（21）或 `Promise.withResolvers`（22）。npm 对 `engines` 只是警告，照样装上，然后在 import 那一刻抛——用户看到的是「插件坏了」，不是版本不匹配）。字符串和注释里的同名文字不算。
 
+### 依赖真实性：`lib/` 里 import 的东西，消费者那边真的会装上吗
+
+`npm install` 装一个包时只装它的 `dependencies`，**永远不装 `devDependencies`**。所以在你自己仓库里 `import 'x'` 能跑（依赖树是完整的），到了用户那边 `ERR_MODULE_NOT_FOUND`——插件装上了，然后加载失败，用户看到的是「这个插件坏了」。
+
+| 规则 | 抓什么 |
+|---|---|
+| `undeclared-import` | `lib/` 里 import 了某个包，`package.json` 三个依赖字段里都没有。它在你机器上能解析，只是因为别的包把它提升（hoist）到了 `node_modules` |
+| `dep-in-dev-only` | 只在 `devDependencies` 里声明。这是最常见的一种：写代码时 `npm i -D` 装上了，测试也全绿 |
+| `unused-dependency` | `dependencies` 里声明了，`lib/` 里从没 import。每个装你的人都白下一份（info，因为有些包是运行时动态加载的） |
+
+内置模块（`node:fs`、`fs/promises`）、相对路径、以及浏览器半边从宿主 `require` 拿到的 `react` 都不算。工具描述里那句 `require("react")` 是散文，也不是依赖——这条规则最早就是被它自己误报出来的。
+
 ### 构建产物：`src/` 和 `lib/` 谁更新
 
 有 `src/` 的插件（TypeScript 源码 + 构建出来的 `lib/`）最容易在这件事上翻车，而且两种翻车的表现一模一样——**发出去的字节没人跑过**：
@@ -183,7 +196,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 66 个引擎单测
+node --test                      # 75 个引擎单测
 node test/integration.test.mjs   # 26 条集成断言（9 个真实插件作 fixture）
 ```
 

package/lib/engine.js

@@ -8,6 +8,7 @@
 // you a publish, so they are all checkable before you spend it.
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
+import { builtinModules } from 'node:module'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 
@@ -555,30 +556,36 @@ export function checkNpmState(dir) {
   return out
 }
 
-/** Version-collision check: the same version already on the registry. */
-export async function checkVersionTaken(name, version, { registry = 'https://registry.npmjs.org', timeoutMs = 8000 } = {}) {
+/**
+ * Version-collision check: the same version already on the registry.
+ * `doc` injects a registry document so the rule is testable without the network.
+ */
+export async function checkVersionTaken(name, version, { registry = 'https://registry.npmjs.org', timeoutMs = 8000, doc } = {}) {
   const out = []
   try {
-    const res = await fetch(`${registry.replace(/\/$/, '')}/${name.replace('/', '%2f')}`, {
-      headers: { accept: 'application/vnd.npm.install-v1+json' },
-      signal: AbortSignal.timeout(timeoutMs),
-    })
-    if (res.status === 404) return out // never published: fine
-    if (!res.ok) {
-      // A 500 or a rate limit is not proof the version is free. Saying nothing
-      // here made the gate report "clean" for a check that never ran.
-      out.push(
-        F(
-          'registry-unreachable',
-          'warn',
-          `could not read ${name} from the registry (HTTP ${res.status})`,
-          'The version-taken check did not run, so this is NOT a clean version check. npm itself will still refuse a duplicate on publish.',
-          'Re-run the gate later, or check https://www.npmjs.com/package/' + name + '?activeTab=versions by hand.',
-        ),
-      )
-      return out
+    let json = doc ?? null
+    if (!json) {
+      const res = await fetch(`${registry.replace(/\/$/, '')}/${name.replace('/', '%2f')}`, {
+        headers: { accept: 'application/vnd.npm.install-v1+json' },
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+      if (res.status === 404) return out // never published: fine
+      if (!res.ok) {
+        // A 500 or a rate limit is not proof the version is free. Saying nothing
+        // here made the gate report "clean" for a check that never ran.
+        out.push(
+          F(
+            'registry-unreachable',
+            'warn',
+            `could not read ${name} from the registry (HTTP ${res.status})`,
+            'The version-taken check did not run, so this is NOT a clean version check. npm itself will still refuse a duplicate on publish.',
+            'Re-run the gate later, or check https://www.npmjs.com/package/' + name + '?activeTab=versions by hand.',
+          ),
+        )
+        return out
+      }
+      json = await res.json()
     }
-    const json = await res.json()
     if (json?.versions?.[version]) {
       out.push(
         F(
@@ -590,6 +597,23 @@ export async function checkVersionTaken(name, version, { registry = 'https://reg
         ),
       )
     }
+
+    // npm accepts a publish of an OLDER version without a word. It lands in
+    // `versions`, but `dist-tags.latest` keeps pointing at the newer one, so
+    // anyone installing by name never receives it. The tarball is uploaded and
+    // invisible — which reads exactly like "my update did not reach anyone".
+    const latest = json?.['dist-tags']?.latest
+    if (latest && compareVersions(version, latest) < 0) {
+      out.push(
+        F(
+          'version-behind-latest',
+          'error',
+          `${name}@${version} is older than the published latest ${latest}`,
+          'npm will accept this publish and leave `latest` on the newer version, so install-by-name keeps resolving to the old code. Nothing errors; the release simply never reaches anyone.',
+          `Publish ${bumpPatch(latest)} or higher instead.`,
+        ),
+      )
+    }
   } catch {}
   return out
 }
@@ -1079,17 +1103,21 @@ try {
   // bug the author cannot see any other way - registration never runs execute.
   stage = 'call'
   const wanted = new Set(JSON.parse(process.env.PG_CALLS || '[]'))
+  const budget = Number(process.env.PG_CALL_MS || 8000)
   const calls = []
   for (const entry of registered) {
     if (!wanted.has(entry.name) || !entry.run) continue
     try {
       await Promise.race([
         Promise.resolve(entry.run({}, { signal: undefined })),
-        new Promise((_, reject) => setTimeout(() => reject(new Error('timed out after 8s')), 8000)),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('timed out')), budget)),
       ])
       calls.push({ name: entry.name, ok: true })
     } catch (error) {
-      calls.push({ name: entry.name, ok: false, error: String((error && error.message) || error) })
+      const message = String((error && error.message) || error)
+      // A slow tool is not a broken tool: of_env shells out to WSL and takes
+      // seconds by design. Only a real throw is a defect.
+      calls.push({ name: entry.name, ok: false, timedOut: message === 'timed out', error: message })
     }
   }
   emit({ ok: true, tools: registered.map(({ run, ...rest }) => rest), badParamTypes, calls })
@@ -1107,7 +1135,11 @@ export async function checkToolRegistrations(dir, opts = {}) {
       timeout: opts.timeoutMs ?? 20_000,
       maxBuffer: 4 * 1024 * 1024,
       windowsHide: true,
-      env: { ...process.env, PG_CALLS: JSON.stringify(Array.isArray(opts.calls) ? opts.calls : []) },
+      env: {
+        ...process.env,
+        PG_CALLS: JSON.stringify(Array.isArray(opts.calls) ? opts.calls : []),
+        PG_CALL_MS: String(opts.callTimeoutMs ?? 8000),
+      },
     })
     const line = String(stdout).split('\n').filter((l) => l.startsWith('@@PG@@')).pop()
     if (!line) throw new Error('the child printed no result')
@@ -1154,6 +1186,18 @@ export async function checkToolRegistrations(dir, opts = {}) {
   const seen = new Set()
   for (const c of Array.isArray(payload.calls) ? payload.calls : []) {
     if (c.ok) continue
+    if (c.timedOut) {
+      out.push(
+        F(
+          'tool-call-slow',
+          'warn',
+          `tool "${c.name}" did not answer within the call budget`,
+          'A slow tool is not a broken one — this may shell out or wait on a service. Reported so a hang is not mistaken for a pass, and NOT counted as a defect.',
+          'Raise callTimeoutMs if the tool is legitimately slow, or check that it returns at all.',
+        ),
+      )
+      continue
+    }
     out.push(
       F(
         'tool-call-throws',
@@ -1642,6 +1686,117 @@ export async function runArtifactChecks(dir, opts = {}) {
   }
 }
 
+// =====================================================================
+// Dependency truth
+// =====================================================================
+
+// A package specifier never contains whitespace, so the capture is whitespace-
+// excluding on purpose: a greedy [^'"]+ matched across a whole template block
+// and reported the runner's own source as a dependency name.
+const SPECIFIER_RE =
+  /\b(?:import|export)\s[^'"]*?from\s*['"]([^'"\s]+)['"]|\bimport\s*\(\s*['"]([^'"\s]+)['"]\s*\)|\bimport\s*['"]([^'"\s]+)['"]|\brequire\s*\(\s*['"]([^'"\s]+)['"]\s*\)/g
+
+const BUILTINS = new Set(builtinModules)
+
+// The client half runs inside the host's module loader, which resolves these
+// itself (CLIENT_RUNNER's fakeRequire mirrors it). They are provided, not
+// installed by the plugin, so importing them is not a missing dependency.
+const HOST_PROVIDED = new Set(['react', 'react-dom'])
+
+/** '@scope/pkg/sub' -> '@scope/pkg', 'pkg/sub' -> 'pkg', relative/builtin -> null. */
+export const packageOf = (spec) => {
+  if (!spec || spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('node:')) return null
+  const parts = spec.split('/')
+  const name = spec.startsWith('@') ? (parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null) : parts[0]
+  return name && !BUILTINS.has(name) ? name : null
+}
+
+// A tool description that says `require("react")` is prose, not an import — this
+// rule fired on this plugin's own description until it was dropped. Only quoted
+// strings that CONTAIN a call are removed, so a real specifier survives.
+const dropProse = (code) =>
+  code
+    .replace(/'(?:[^'\\\n]|\\.)*'/g, (s) => (/\b(?:require|import)\s*\(/.test(s) ? "''" : s))
+    .replace(/"(?:[^"\\\n]|\\.)*"/g, (s) => (/\b(?:require|import)\s*\(/.test(s) ? '""' : s))
+
+/**
+ * Every bare specifier lib/ imports, checked against what package.json declares.
+ *
+ * A published package installs its own `dependencies` — devDependencies are never
+ * fetched by whoever installs the tarball. So an import that only devDependencies
+ * satisfies works in your repo (where everything is installed) and throws
+ * ERR_MODULE_NOT_FOUND in theirs, after they have already installed you.
+ */
+export function checkDependencies(dir) {
+  const out = []
+  const json = readPkgJson(dir)
+  if (!json) return out
+  const deps = new Set(Object.keys(json.dependencies || {}))
+  const dev = new Set(Object.keys(json.devDependencies || {}))
+  const provided = new Set([
+    ...Object.keys(json.peerDependencies || {}),
+    ...Object.keys(json.optionalDependencies || {}),
+  ])
+
+  const used = new Map() // package name -> the first lib/ file that imports it
+  const clientRel = clientTarget(json)
+  const isClientFile = (file) =>
+    Boolean(clientRel) && relative(dir, file).replace(/\\/g, '/') === String(clientRel).replace(/^\.\//, '')
+  for (const file of walkFiles(join(dir, 'lib'), /\.(?:js|mjs|cjs)$/)) {
+    const text = safeText(file)
+    if (text === null) continue
+    // Backtick strings go first: a runner template literal embeds code that
+    // contains the word `import`, and a greedy specifier match used to swallow
+    // a whole block of it. A real specifier is always a plain quoted string.
+    const code = dropProse(text.split('\n').map(stripComment).join('\n').replace(/`(?:[^`\\]|\\.)*`/g, '``'))
+    for (const m of code.matchAll(SPECIFIER_RE)) {
+      const name = packageOf(m[1] ?? m[2] ?? m[3] ?? m[4])
+      if (!name) continue
+      if (isClientFile(file) && HOST_PROVIDED.has(name)) continue
+      if (!used.has(name)) used.set(name, relative(dir, file))
+    }
+  }
+
+  for (const [name, file] of used) {
+    if (deps.has(name) || provided.has(name)) continue
+    if (dev.has(name)) {
+      out.push(
+        F(
+          'dep-in-dev-only',
+          'error',
+          `${file} imports "${name}", which is only in devDependencies`,
+          'npm installs a package\'s dependencies for the consumer, never its devDependencies. The import resolves on your machine and fails with ERR_MODULE_NOT_FOUND on theirs — the plugin installs fine and then does not load.',
+          `Move "${name}" into dependencies.`,
+        ),
+      )
+      continue
+    }
+    out.push(
+      F(
+        'undeclared-import',
+        'error',
+        `${file} imports "${name}", which package.json does not declare`,
+        'It resolves locally only because some other package happens to hoist it into node_modules. The consumer has no such package, so the import fails at load time.',
+        `Add "${name}" to dependencies (or drop the import).`,
+      ),
+    )
+  }
+
+  for (const name of deps) {
+    if (used.has(name)) continue
+    out.push(
+      F(
+        'unused-dependency',
+        'info',
+        `dependencies lists "${name}" but lib/ never imports it`,
+        'Every consumer downloads and installs it for nothing. Sometimes that is deliberate (a peer you only load dynamically), which is why this is a note rather than a defect.',
+        `Remove "${name}", or ignore this line if it is loaded at runtime only.`,
+      ),
+    )
+  }
+  return out
+}
+
 // =====================================================================
 // Orchestration
 // =====================================================================
@@ -1655,6 +1810,7 @@ export function runStaticChecks(dir) {
     ...checkLibHygiene(dir),
     ...checkNodeVersion(dir),
     ...checkBuildFreshness(dir),
+    ...checkDependencies(dir),
     ...checkDocs(dir),
     ...checkTests(dir),
     ...checkNpmState(dir),
@@ -1675,11 +1831,12 @@ const RULE_ORDER = [
   'inject-missing-tools', 'inject-missing-web', 'inject-missing-webServer', 'inject-missing-timer',
   'inject-unused-service',
   'tool-missing-name', 'tool-duplicate-name', 'tool-missing-execute', 'tool-present-call-throws',
-  'tool-bad-card-kind', 'tool-missing-output-schema', 'tool-none-registered', 'tool-bad-parameter-type',
+  'tool-bad-card-kind', 'tool-missing-output-schema', 'tool-none-registered', 'tool-bad-parameter-type', 'tool-call-throws', 'tool-call-slow',
   'lib-debugger', 'lib-console-log', 'lib-hardcoded-path', 'lib-url-pathname', 'node-too-old', 'stale-build', 'hand-edited-build',
+  'undeclared-import', 'dep-in-dev-only', 'unused-dependency',
   'pack-omits-lib', 'pack-omits-patch', 'pack-omits-client', 'pack-oversize', 'pack-omits-readme', 'pack-omits-license', 'pack-ships-secret',
   'pack-unexpected-dir', 'pack-script-build', 'pack-unavailable',
-  'no-license', 'license-mismatch', 'version-taken', 'registry-unreachable', 'publish-not-served',
+  'no-license', 'license-mismatch', 'version-taken', 'version-behind-latest', 'registry-unreachable', 'publish-not-served',
   'publish-served-mismatch', 'publish-served', 'market-empty', 'market-no-url', 'market-url-not-github',
   'market-no-name', 'market-name-shape', 'market-no-category', 'market-bad-category', 'market-no-desc', 'market-no-en', 'market-no-zh', 'unscoped-name', 'no-git', 'no-readme', 'readme-no-install', 'readme-no-profile',
   'market-no-repo', 'market-unavailable', 'market-duplicate-entry', 'market-npm-name-collision', 'market-repo-too-new',

package/lib/index.js

@@ -91,7 +91,7 @@ export function apply(ctx, config = {}) {
     {
       name: 'publish_gate',
       description:
-        'Run the full pre-publish gate over a DSH plugin directory. Three layers. (1) Manifest: missing exports["."], files omitting lib/, no "type": "module", UTF-8 BOM, JSON/YAML parse errors, cordis.patch.yml insert rows at the wrong indent (the bug that makes a plugin install and never mount), insert name mismatches, missing entry exports, an entry path that points at no file, a cordis.patch.yml the manifest never declares (inert), missing LICENSE or README install line, missing tests, unscoped npm names (the 403 you cannot diagnose). (2) Artifact: runs `npm pack --dry-run` and reads what npm will actually ship — lib/ missing from the tarball, a dsh.bundle.patch that never gets packed, oversize tarballs (test fixtures are the usual cause), dev directories shipping, and a prepack hook that means the dry run did not build. (3) Runtime: imports the entry in an isolated child process, calls apply(ctx) with a fake ctx, and reports a throwing import, a throwing apply, tools with no execute, duplicate tool names, a presentCall that throws, and card kinds the host does not render; then, if the package declares exports["./client"], loads the browser bundle against a fake window.__ModuleLoader__ and reports a bundle that never loads, never returns apply, throws, or registers nothing. Deterministic: every rule is a file, subprocess or API check, no LLM. Returns {ok, report, findings:[{rule,severity,title,detail,fix}], counts}.',
+        'Run the full pre-publish gate over a DSH plugin directory. Four layers. (1) Manifest: missing exports["."], files omitting lib/, no "type": "module", UTF-8 BOM, JSON/YAML parse errors, cordis.patch.yml insert rows at the wrong indent (the bug that makes a plugin install and never mount), insert name mismatches, missing entry exports, an entry path that points at no file, a cordis.patch.yml the manifest never declares (inert), missing LICENSE or README install line, missing tests, unscoped npm names (the 403 you cannot diagnose). (2) Dependencies: every bare import in lib/ resolved against package.json — an import nothing declares, an import only devDependencies satisfy (npm never installs those for whoever installs you), an unused dependency. (3) Artifact: runs `npm pack --dry-run` and reads what npm will actually ship — lib/ missing from the tarball, a dsh.bundle.patch that never gets packed, oversize tarballs (test fixtures are the usual cause), dev directories shipping, and a prepack hook that means the dry run did not build. (4) Runtime: imports the entry in an isolated child process, calls apply(ctx) with a fake ctx, and reports a throwing import, a throwing apply, tools with no execute, duplicate tool names, a presentCall that throws, and card kinds the host does not render; then, if the package declares exports["./client"], loads the browser bundle against a fake window.__ModuleLoader__ and reports a bundle that never loads, never returns apply, throws, or registers nothing. Deterministic: every rule is a file, subprocess or API check, no LLM. Returns {ok, report, findings:[{rule,severity,title,detail,fix}], counts}.',
       parameters: {
         type: 'object',
         properties: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.3.3",
-  "description": "Helps DSH plugin AUTHORS publish their plugins: a gate that turns every silent failure in the publish path into a deterministic check. Manifest layer — package.json completeness, BOM, YAML/JSON parseability, entry paths that point at no file, a patch the manifest never declares, patch insert correctness, a build whose lib/ is older than src/, inject services that are missing or misspelled, npm scope permissions, GitHub repo and token state, market entry format, LICENSE/README, tests. Artifact layer — runs `npm pack --dry-run` and reads what npm will really ship: code missing from the tarball, an unpacked patch, oversize packages, dev directories. Runtime layer — imports the entry in an isolated child process, calls apply(ctx), and reports tools that never register, missing execute, duplicate names, throwing presentCall and card kinds the host does not render. Browser half — loads the client bundle against a fake window.__ModuleLoader__ and reports a bundle that never loads, returns no apply, throws, registers nothing, or uses a service its own inject array omits, because a panel that never appears looks like a UI bug, not a packaging one. Then GitHub + npm + market, and a post-publish shasum check that proves the registry holds these exact bytes. 帮助插件作者一键发布：写完插件后跑一遍门禁（清单 / 产物 / 运行时 / 浏览器半边），把发布链路上的每个静默坑变成确定性检查，然后 GitHub + npm + 市场一键三连。",
+  "version": "0.4.0",
+  "description": "Pre-publish gate for DSH plugins, in five layers: manifest, dependencies, artifact, runtime and the browser half. 发布前的五层门禁：清单、依赖、产物、运行时、浏览器半边。",
   "type": "module",
   "main": "lib/index.js",
   "exports": {