@bushizhanghan/dsh-publish-gate 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.14.0
+
+- New test layer: `checkTestRun` runs `node --test` in the plugin directory and reports `tests-fail`
+  (error), `tests-timeout` (warn) and `tests-not-run` (warn). Every other layer reads the paperwork —
+  the manifest, the tarball, the registry — while nine of my own plugins shipped
+  `"test": "node --test test/"`, which throws MODULE_NOT_FOUND on Node 22+ and would have been caught
+  by simply running it. The child drops the inherited NODE_TEST_CONTEXT, because a gate that runs
+  inside `node --test` would otherwise start the suite in test-child mode and see no summary at all.
+
+## 0.13.1
+
+- The tag check now asks `git ls-remote origin` instead of `git tag --points-at HEAD`. When the commit is pushed
+  through the GitHub API the local HEAD is not the remote one, so the local form reported `git-tag-missing` on
+  seven of my nine plugins whose tag existed all along. It now compares the tag against the shipped branch
+  head and stays silent when the remote cannot be reached — a check that cannot see the truth must not claim
+  a defect.
 ## 0.13.0
 
 - `market-fork-of-listed` / `market-fork-undisclosed` (warn): the repo is a GitHub fork whose parent is

package/README.md

@@ -8,6 +8,10 @@
 
 门禁分三层：**清单层**看 package.json / patch / 入口源码，**产物层**真的跑一遍 `npm pack --dry-run` 看 npm 到底会发出什么，**运行时层**在独立子进程里 `import()` 入口并 `apply(ctx)` 一遍，看它到底注册了什么。
 
+### 测试层：门禁真的会跑一遍你的测试
+
+`tests-fail` / `tests-timeout` / `tests-not-run` 三条规则会以 `node --test` 在插件目录里真跑一次（不经过 `npm test`，因为脚本内容由作者决定、可能 shell 出去）。子进程会去掉继承来的 `NODE_TEST_CONTEXT`——否则当门禁本身跑在 `node --test` 里时，子进程进入 test-child 模式、一个摘要都不打印，看起来像"没有测试"。
+
 ## 典型用法（写完插件后）
 
 ```
@@ -223,7 +227,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 107 个引擎单测
+node --test                      # 110 个引擎单测
 node test/integration.test.mjs   # 27 条集成断言（9 个真实插件作 fixture）
 ```
 

package/lib/engine.js

@@ -1044,7 +1044,70 @@ export function checkTests(dir) {
   // while the tests themselves are fine. Auto-discovery needs no argument.
   const testScript = pkgJson?.scripts?.test || ''
   const dirArg = testScript.match(/\bnode\s+--test\s+(?!-)(\S+)/)
-  if (dirArg) out.push(F('test-script-dir-arg', 'warn', `test script passes a path to node --test ("${dirArg[1]}")`, 'Node 22+ treats that argument as a module path, not a directory to glob: `node --test test/` throws MODULE_NOT_FOUND, so npm test can never pass even though the tests are fine.', 'Drop the path — "test": "node --test" auto-discovers test/**/*.test.mjs.'))
+  if (dirArg) out.push(F('test-script-dir-arg',
+  'tests-fail',
+  'tests-timeout',
+  'tests-not-run', 'warn', `test script passes a path to node --test ("${dirArg[1]}")`, 'Node 22+ treats that argument as a module path, not a directory to glob: `node --test test/` throws MODULE_NOT_FOUND, so npm test can never pass even though the tests are fine.', 'Drop the path — "test": "node --test" auto-discovers test/**/*.test.mjs.'))
+  return out
+}
+
+/**
+ * `checkTests` reads the test setup; this one runs it. The gap is not academic:
+ * nine of my own plugins shipped `"test": "node --test test/"`, which dies with
+ * MODULE_NOT_FOUND on Node 22+, and no rule noticed because none of them ever
+ * executed anything. A gate that does not run the suite reports on paperwork.
+ *
+ * Runs `node --test` directly instead of the package script: the script is
+ * whatever the author typed (and may shell out to a runner that is not
+ * installed), while auto-discovery is the convention the ecosystem settled on.
+ */
+export async function checkTestRun(dir, opts = {}) {
+  const out = []
+  if (!existsSync(join(dir, 'test'))) return out // checkTests owns no-tests
+  const timeoutMs = Math.max(1000, Number(opts.timeoutMs) || 180_000)
+  const started = Date.now()
+  let stdout = ''
+  let code = 0
+  let timedOut = false
+  // NODE_TEST_CONTEXT is inherited from whoever called us: when this gate runs
+  // inside `node --test` itself, the child starts in test-child mode and prints
+  // no summary at all, which reads as "no tests" — a false alarm.
+  const env = { ...process.env }
+  delete env.NODE_TEST_CONTEXT
+  try {
+    const r = await runFile(process.execPath, ['--test'], { cwd: dir, env, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, windowsHide: true })
+    stdout = String(r.stdout || '')
+  } catch (error) {
+    stdout = String(error.stdout || '')
+    timedOut = error.killed === true || /timed out/i.test(String(error.message || ''))
+    code = timedOut ? 1 : typeof error.code === 'number' ? error.code : 1
+  }
+  const durationMs = Date.now() - started
+  // Node prints the summary as `ℹ pass 12` (spec reporter) or `# pass 12` (tap).
+  const count = (label) => {
+    const m = new RegExp(`(?:^|\\n)\\s*(?:#|ℹ|i)\\s*${label}\\s+(\\d+)`).exec(stdout)
+    return m ? Number(m[1]) : null
+  }
+  const pass = count('pass')
+  const fail = count('fail')
+  const tests = { pass, fail, durationMs, exitCode: code }
+  const failures = stdout
+    .split('\n')
+    .filter((line) => /^\s*(?:✖|not ok)\s/.test(line))
+    .slice(0, 3)
+    .map((line) => line.trim().slice(0, 160))
+  if (timedOut) {
+    out.push(F('tests-timeout', 'warn', `the suite did not finish in ${Math.round(timeoutMs / 1000)} s`, 'A suite that never finishes blocks every publish and every CI run; the gate gave up waiting.', 'Speed up or split the slow test, or raise Config.testTimeoutMs.'))
+    return out
+  }
+  if (code !== 0 || (fail || 0) > 0) {
+    const shown = failures.length ? ` — ${failures.join(' ; ')}` : ''
+    out.push(F('tests-fail', 'error', `${fail ?? 'some'} test(s) failed in ${Math.round(durationMs / 1000)} s${shown}`, 'The published package is exactly the code whose own tests do not pass; a consumer finds out instead of you.', 'Run `node --test` and fix the failures before publishing.'))
+    return out
+  }
+  if (pass === null && fail === null) {
+    out.push(F('tests-not-run', 'warn', 'node --test exited 0 without reporting a single test', 'Either test/ holds no file node recognises, or the suite is skipped behind a condition — publishing then relies on a green light nobody earned.', 'Check that `node --test` really runs the files you expect.'))
+  }
   return out
 }
 
@@ -2303,11 +2366,43 @@ export async function checkTraceability(dir, opts = {}) {
     }
   }
 
-  // 2. No tag on HEAD: nothing points at these bytes afterwards.
+  // 2. A tag on the bytes that actually shipped. When the commit was pushed
+  // through the GitHub API the local HEAD is not the remote one, so a local
+  // `git tag --points-at HEAD` reports a missing tag that exists — ask the
+  // remote instead, and say nothing when it cannot be reached.
+  const remote = opts.remote === undefined ? await readRemoteRefs(dir) : opts.remote
   const atHead = opts.atHead === undefined ? await gitOut(dir, ['tag', '--points-at', 'HEAD']) : opts.atHead
-  const tags = typeof atHead === 'string' ? atHead.split('\n').map((t) => t.trim()).filter(Boolean) : []
+  const localTags = typeof atHead === 'string' ? atHead.split('\n').map((t) => t.trim()).filter(Boolean) : []
   const wanted = [`v${version}`, version]
-  if (typeof atHead === 'string' && !wanted.some((t) => tags.includes(t))) {
+  const tagOnRemote = remote ? remote.tags[`v${version}`] || remote.tags[version] || null : null
+  const tagIsOnShipped = Boolean(remote && tagOnRemote && tagOnRemote === remote.head)
+  const localHasIt = wanted.some((t) => localTags.includes(t))
+
+  if (remote) {
+    // The remote is the truth: the tag either points at the shipped commit or not.
+    if (tagIsOnShipped) return out
+    const exists = Boolean(tagOnRemote) || (opts.tagExists !== undefined ? Boolean(opts.tagExists) : Boolean(await gitOut(dir, ['rev-parse', '--verify', '--quiet', `refs/tags/v${version}`])))
+    out.push(
+      exists
+        ? F(
+            'git-tag-elsewhere',
+            'warn',
+            `tag v${version} does not point at the shipped commit`,
+            `The tag is on ${String(tagOnRemote || 'another commit').slice(0, 12)} but the branch head is ${String(remote.head).slice(0, 12)}. A release built from that tag is not what you just published.`,
+            `Move it: git tag -f v${version} <shipped-sha> && git push -f origin v${version}`,
+          )
+        : F(
+            'git-tag-missing',
+            'warn',
+            `no git tag v${version} on the shipped commit`,
+            'After publishing, the only record of these bytes is the registry. A GitHub release, a changelog entry or a market listing cannot point at a commit that was never tagged.',
+            `git tag v${version} && git push origin v${version}`,
+          ),
+    )
+    return out
+  }
+
+  if (typeof atHead === 'string' && !localHasIt) {
     const exists = opts.tagExists === undefined ? await gitOut(dir, ['rev-parse', '--verify', '--quiet', `refs/tags/v${version}`]) : opts.tagExists ? 'sha' : null
     out.push(
       exists
@@ -2330,6 +2425,22 @@ export async function checkTraceability(dir, opts = {}) {
   return out
 }
 
+/** `{ head, tags }` from one `git ls-remote`, or null when it cannot be read. */
+async function readRemoteRefs(dir) {
+  const raw = await gitOut(dir, ['ls-remote', '--heads', '--tags', 'origin'])
+  if (typeof raw !== 'string' || raw.length === 0) return null
+  const tags = {}
+  let head = null
+  for (const line of raw.split('\n')) {
+    const [sha, ref] = line.split('\t')
+    if (!sha || !ref) continue
+    if (ref === 'refs/heads/main' || ref === 'refs/heads/master') head = sha
+    const m = /^refs\/tags\/(.+?)(?:\^\{\})?$/.exec(ref)
+    if (m) tags[m[1]] = sha // a dereferenced annotated tag overwrites the tag object, which is what we want
+  }
+  return head ? { head, tags } : null
+}
+
 // =====================================================================
 // Orchestration
 // =====================================================================

package/lib/index.js

@@ -28,7 +28,8 @@ import {
   compareVersions,
   latestPublished,
   renderReport,
-  runArtifactChecks,
+  runArtifactChecks,
+  checkTestRun,
   runStaticChecks,
 } from './engine.js'
 
@@ -94,7 +95,7 @@ export function apply(ctx, config = {}) {
     {
       name: 'publish_gate',
       description:
-        '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}.',
+        '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. (5) Tests: runs `node --test` in the plugin directory and reports a suite that fails, hangs, or exits 0 without running anything — the only layer that reads the code instead of the paperwork. (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: {
@@ -102,7 +103,8 @@ export function apply(ctx, config = {}) {
           skipNetwork: { type: 'boolean', description: 'Skip the npm registry and GitHub checks (default false).' },
           skipPack: { type: 'boolean', description: 'Skip `npm pack --dry-run` (default false). Faster, but says nothing about the real tarball.' },
           skipTools: { type: 'boolean', description: 'Skip the isolated import of the plugin entry (default false).' },
-          skipClient: { type: 'boolean', description: 'Skip the isolated load of the browser bundle (default false).' },
+          skipClient: { type: 'boolean', description: 'Skip the isolated load of the browser bundle (default false).' },
+          skipTests: { type: 'boolean', description: 'Skip running the test suite (default false). The suite is the only check that reads the code rather than the paperwork.' },
         },
       },
       async execute(args) {
@@ -111,6 +113,8 @@ export function apply(ctx, config = {}) {
         const findings = runStaticChecks(dir)
         const artifact = await runArtifactChecks(dir, { skipPack: args.skipPack, skipTools: args.skipTools, skipClient: args.skipClient })
         findings.push(...artifact.findings)
+        const tests = args.skipTests ? null : await checkTestRun(dir, { timeoutMs: cfg.testTimeoutMs })
+        if (tests) findings.push(...tests)
         if (!args.skipNetwork) findings.push(...(await networkGate(dir)))
         const counts = {
           error: findings.filter((f) => f.severity === 'error').length,
@@ -124,6 +128,7 @@ export function apply(ctx, config = {}) {
           findings,
           tools: artifact.tools,
           client: artifact.client,
+          tests: args.skipTests ? null : findings.filter((f) => f.rule.startsWith("tests-")),
           unpackedSize: artifact.pack?.unpackedSize ?? null,
           report: renderReport(findings, { title: `publish gate · ${dir}` }),
           safeToPublish: counts.error === 0,
@@ -454,7 +459,7 @@ export function apply(ctx, config = {}) {
         description: t.description,
         parameters: t.parameters,
         output: { schema: OUTPUT_SCHEMA, render: outRender },
-        timeoutMs: 120_000,
+        timeoutMs: 240_000,
         isConcurrencySafe: () => false,
         presentCall: (args) => ({ card: 'generic', title: t.name, kind: 'read', rawInput: args }),
         execute: t.execute,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Pre-publish gate for DSH plugins: manifest, dependencies, artifact, runtime, browser half, traceability and market readiness — plus an input fuzzer that drives every declared parameter with the wrong type. 发布前的七层门禁 + 入参模糊测试。",
   "type": "module",
   "main": "lib/index.js",