@bushizhanghan/dsh-publish-gate 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.20.0
+
+- `publish_gate_commands` now agrees with the rules: a prerelease version gets `npm publish --tag next`
+  instead of a bare publish that would move `latest`.
+- New step `tag the shipped commit` (`git tag v<version> && git push origin v<version>`). The gate has
+  warned about a missing tag since 0.5.0 and the command list never mentioned tagging — I wrote a
+  separate script to do it because the instructions never said to.
+
+## 0.19.0
+
+- `prerelease-published-as-latest` (warn): a `-beta` / `-rc` version with no `publishConfig.tag`.
+  npm publishes to `latest` whatever the suffix says, so `npm i <name>` starts handing everyone an
+  unfinished build and nothing warns.
+- `publish-tag-not-latest` (warn): the version is on the registry but `dist-tags.latest` points at an
+  older one. That is what `--tag next` does when you meant to release: the release looks shipped and
+  is not what anyone installs.
+- README: dropped a made-up `test/…` example path — `readme-path-missing` caught my own prose.
+
 ## 0.18.0
 
 - `readme-path-missing` (warn): a README that names `test/…`, `lib/…`, `scripts/…` files that no longer

package/README.md

@@ -45,7 +45,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `publish_gate_market` | 校验市场条目 YAML（url/name/category/description 双语）；传 `dir` 则改查只有线上才能回答的三件事：这个仓库**已经在目录里**（再开 PR 就是重复条目）、另一个条目也在发同一个 npm 包、仓库还**不满 24 小时**（提交门禁会失败并自己重跑） |
 | `publish_gate_next_version` | 当前版本、是否已被 registry 占用、建议 bump 到多少（本地比 npm 旧时从 npm 的 latest 往上加，不会推荐一个已被占用的版本） |
 | `publish_gate_doctor` | 扫整个目录，按 blocker 数排序，附带每个插件的真实包体积，看哪个还不能发 |
-| `publish_gate_commands` | 按顺序列出发布命令，并标出这台机器已经走到哪一步。命令是**这台机器上真能跑的形式**：Windows 下 `npm publish` 走 `cmd /c`（PowerShell 的 `npm.ps1` 常被执行策略拦掉），`npm publish` 后面紧跟一条 `publish_gate_verify` |
+| `publish_gate_commands` | 按顺序列出发布命令，并标出这台机器已经走到哪一步。命令是**这台机器上真能跑的形式**：Windows 下 `npm publish` 走 `cmd /c`（PowerShell 的 `npm.ps1` 常被执行策略拦掉），`npm publish` 后面紧跟一条 `publish_gate_verify`；版本是预发版时命令自带 `--tag next`；最后一步是给发出去的 commit 打 tag |
 
 ## 检查清单
 
@@ -75,12 +75,14 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `no-license` | 缺 LICENSE |
 | `version-taken` | 这个版本已经在 registry 上，再发是 403 |
 | `version-behind-latest` | 本地版本比 registry 上的 `latest` **旧**。npm 会照收，但 `latest` 继续指向新版本——包上传了，按名字装的人永远拿不到，且没有任何报错 |
+| `publish-tag-not-latest` | 版本已经在 registry 上了，但 `dist-tags.latest` 还指着旧的。`--tag next` 发出去的版本就是这样：看着发出去了，按名字装的人拿到的还是旧的 |
+| `prerelease-published-as-latest` | 版本是 `-beta` / `-rc`，却没写 `publishConfig.tag`。npm 不看后缀，照样发到 `latest`——所有人 `npm i` 装到的都是没做完的构建 |
 | `registry-unreachable` | registry 回了 500/429 —— 版本检查**没跑**，所以别把它当干净 |
 | `npm-not-logged-in` | 这台机器上 npm 没有可用登录（`npm whoami` 报 ENEEDAUTH）。`npm publish` 会在 tarball 打好之后才失败 |
 | `readme-wrong-package` | README 的安装命令写的是**另一个包名**（从别的插件抄过来没改）。照着装的人装到别的插件上，而且不会报错——那个包真的存在 |
 
 ### 值得在发布前知道的（warn / info）
-`npm-scope-mismatch`（登录的账号不是包 scope 的所有者，PUT 会 403，而错误里既不说 token 也不说 scope——我为一个 403 花了一小时）、`unscoped-name`（granular token 的 403）、`repo-missing`、`patch-name-unresolvable`（junction 放错层级）、`inject-unused-service`（`inject` 里写了个拼错的服务名，cordis 一直等它，插件静默不激活）、`no-publish-config-access`（scoped 包没写 `publishConfig.access`，只是提醒，因为命令里本来就带 `--access public`）、`publish-config-registry`（`publishConfig.registry` 指到内网 registry，版本发到别人装不到的地方）、`no-readme` / `readme-no-install` / `readme-no-profile`、`license-mismatch`、`no-tests` / `no-test-files` / `no-test-script`、`no-engines`、`bad-repo-url`、`no-git` / `no-gitignore`、`readme-path-missing`（README 里写的 `test/xxx.mjs` 这类路径已经不存在了，照着敲就是 ENOENT）、`readme-tool-undocumented`（README 没提这个工具）/ `readme-test-count`（README 写的测试数和真实数不一致）、`changelog-missing-version`（要发的这个版本号在 CHANGELOG 里没有对应标题，npm 照样发，发布说明就永远落后一版）、`changelog-no-versions`（CHANGELOG 里没有版本标题，读者对不上自己装的那版）、`no-changelog`（只是提醒）、`changelog-not-shipped`（CHANGELOG 在本地但没进 tarball——npm 只强制带 README 和 LICENSE，你一直更新的那份文件在 registry 页面上看不见），以及市场条目的 `market-*` 全系列。
+`npm-scope-mismatch`（登录的账号不是包 scope 的所有者，PUT 会 403，而错误里既不说 token 也不说 scope——我为一个 403 花了一小时）、`unscoped-name`（granular token 的 403）、`repo-missing`、`patch-name-unresolvable`（junction 放错层级）、`inject-unused-service`（`inject` 里写了个拼错的服务名，cordis 一直等它，插件静默不激活）、`no-publish-config-access`（scoped 包没写 `publishConfig.access`，只是提醒，因为命令里本来就带 `--access public`）、`publish-config-registry`（`publishConfig.registry` 指到内网 registry，版本发到别人装不到的地方）、`no-readme` / `readme-no-install` / `readme-no-profile`、`license-mismatch`、`no-tests` / `no-test-files` / `no-test-script`、`no-engines`、`bad-repo-url`、`no-git` / `no-gitignore`、`readme-path-missing`（README 里点名的仓库内文件路径已经不存在了，照着敲就是 ENOENT）、`readme-tool-undocumented`（README 没提这个工具）/ `readme-test-count`（README 写的测试数和真实数不一致）、`changelog-missing-version`（要发的这个版本号在 CHANGELOG 里没有对应标题，npm 照样发，发布说明就永远落后一版）、`changelog-no-versions`（CHANGELOG 里没有版本标题，读者对不上自己装的那版）、`no-changelog`（只是提醒）、`changelog-not-shipped`（CHANGELOG 在本地但没进 tarball——npm 只强制带 README 和 LICENSE，你一直更新的那份文件在 registry 页面上看不见），以及市场条目的 `market-*` 全系列。
 
 ### 产物层：npm 到底会发出什么
 
@@ -233,8 +235,8 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 118 个引擎单测
-node test/integration.test.mjs   # 27 条集成断言（9 个真实插件作 fixture）
+node --test                      # 120 个引擎单测
+node test/integration.test.mjs   # 28 条集成断言（9 个真实插件作 fixture）
 ```
 
 ## License

package/lib/engine.js

@@ -191,6 +191,21 @@ export function checkPackageJson(dir) {
     out.push(F('invalid-version', 'error', `version "${json.version}" is not semver`, 'npm publish rejects it.', 'Use MAJOR.MINOR.PATCH.'))
   }
 
+
+  // npm publishes to `latest` unless told otherwise, and a prerelease version
+  // does not change that. `npm i <name>` then resolves to a beta and every user
+  // is on an unfinished build; nothing warns, and the author sees a green publish.
+  if (json.version && /^\d+\.\d+\.\d+-/.test(json.version) && (!json.publishConfig?.tag || json.publishConfig.tag === 'latest')) {
+    out.push(
+      F(
+        'prerelease-published-as-latest',
+        'warn',
+        `version "${json.version}" is a prerelease but it will be published to \`latest\``,
+        'npm publishes to `latest` by default and a `-beta`/`-rc` suffix does not change that, so `npm i <name>` starts handing everyone an unfinished build.',
+        'Publish with `npm publish --tag next`, or set publishConfig.tag to next.',
+      ),
+    )
+  }
   // type: module — the whole plugin surface is ESM
   if (json.type !== 'module') {
     out.push(
@@ -767,11 +782,27 @@ export async function checkVersionTaken(name, version, { registry = 'https://reg
       )
     }
 
+
+    // A publish with `--tag next` leaves `latest` where it was: the new version
+    // is on the registry, `npm i <name>` still gets the old one, and nothing
+    // fails. The release looks shipped and is not what anyone installs.
+    const latestTag = json?.['dist-tags']?.latest
+    if (json?.versions?.[version] && latestTag && latestTag !== version) {
+      out.push(
+        F(
+          'publish-tag-not-latest',
+          'warn',
+          `${name}@${version} is published but \`latest\` still points at ${latestTag}`,
+          'Installing by name keeps getting the old version. This is what `--tag next` (or publishConfig.tag) does when you meant to release.',
+          `Move it: npm dist-tag add ${name}@${version} latest`,
+        ),
+      )
+    }
     // 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
+    const latest = latestTag
     if (latest && compareVersions(version, latest) < 0) {
       out.push(
         F(
@@ -2564,7 +2595,7 @@ export function runStaticChecks(dir) {
 }
 
 const RULE_ORDER = [
-  'missing-file', 'unreadable', 'utf8-bom', 'json-parse', 'yaml-bom', 'invalid-name', 'invalid-version',
+  'missing-file', 'unreadable', 'utf8-bom', 'json-parse', 'yaml-bom', 'invalid-name', 'invalid-version', 'prerelease-published-as-latest',
   'missing-field', 'not-esm', 'files-omits-lib', 'files-omits-patch', 'no-exports', 'client-without-export', 'client-without-platform',
   'entry-path-missing', 'bundle-patch-not-declared', 'no-publish-config-access', 'private-field-set', 'publish-config-registry',
   'client-file-missing', 'client-no-module-loader', 'client-parse-failed', 'client-load-not-called',
@@ -2581,7 +2612,7 @@ const RULE_ORDER = [
   '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-ships-junk', 'pack-script-build', 'pack-unavailable',
-  'no-license', 'license-mismatch', 'version-taken', 'version-behind-latest', 'npm-not-logged-in', 'npm-scope-mismatch', 'npm-whoami-unavailable', 'registry-unreachable', 'publish-not-served',
+  'no-license', 'license-mismatch', 'version-taken', 'version-behind-latest', 'publish-tag-not-latest', 'npm-not-logged-in', 'npm-scope-mismatch', 'npm-whoami-unavailable', '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', 'readme-wrong-package', 'readme-path-missing',
   'market-no-repo', 'market-unavailable', 'market-duplicate-entry', 'market-npm-name-collision', 'market-repo-too-new', 'market-release-behind',

package/lib/index.js

@@ -28,8 +28,8 @@ import {
   compareVersions,
   latestPublished,
   renderReport,
-  runArtifactChecks,
-  checkTestRun,
+  runArtifactChecks,
+  checkTestRun,
   straySeverities,
   runStaticChecks,
 } from './engine.js'
@@ -104,7 +104,7 @@ 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.' },
         },
       },
@@ -114,21 +114,21 @@ 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)
+        const tests = args.skipTests ? null : await checkTestRun(dir, { timeoutMs: cfg.testTimeoutMs })
+        if (tests) findings.push(...tests)
         if (!args.skipNetwork) findings.push(...(await networkGate(dir)))
-        // A finding with an unexpected severity is invisible to the counters
-        // below, so the rule silently never reports. Make that loud instead.
-        const stray = straySeverities(findings)
-        if (stray.length > 0) {
-          findings.push({
-            rule: 'internal-bad-severity',
-            severity: 'error',
-            title: `these rules built a finding with an unknown severity: ${stray.join(", ")}`,
-            detail: 'The gate counted them as nothing, so they never appeared in a report. This is a bug in publish-gate, not in the plugin being gated.',
-            fix: 'Report it: the severity slot of F(...) took something other than error/warn/info.',
-          })
-        }
+        // A finding with an unexpected severity is invisible to the counters
+        // below, so the rule silently never reports. Make that loud instead.
+        const stray = straySeverities(findings)
+        if (stray.length > 0) {
+          findings.push({
+            rule: 'internal-bad-severity',
+            severity: 'error',
+            title: `these rules built a finding with an unknown severity: ${stray.join(", ")}`,
+            detail: 'The gate counted them as nothing, so they never appeared in a report. This is a bug in publish-gate, not in the plugin being gated.',
+            fix: 'Report it: the severity slot of F(...) took something other than error/warn/info.',
+          })
+        }
         const counts = {
           error: findings.filter((f) => f.severity === 'error').length,
           warn: findings.filter((f) => f.severity === 'warn').length,
@@ -412,6 +412,11 @@ export function apply(ctx, config = {}) {
         const repo = json.repository?.url?.match(/github\.com[:/]([^/]+)\/([^/.]+)/)?.[2] || json.name.replace(/^@[^/]+\//, '')
         const { existsSync } = await import('node:fs')
         const hasGit = existsSync(join(dir, '.git'))
+        // npm publishes to `latest` whatever the version suffix says, so a
+        // prerelease needs an explicit tag or it goes out to everyone.
+        const preTag = /^\d+\.\d+\.\d+-/.test(json.version || '')
+        const tag = preTag ? (json.publishConfig?.tag && json.publishConfig.tag !== 'latest' ? json.publishConfig.tag : 'next') : null
+        const publishCmd = `npm publish --access public${tag ? ` --tag ${tag}` : ''}`
         const steps = [
           {
             name: 'git init and commit',
@@ -433,7 +438,7 @@ export function apply(ctx, config = {}) {
           },
           {
             name: 'npm publish',
-            command: process.platform === 'win32' ? 'cmd /c "npm publish --access public"' : 'npm publish --access public',
+            command: process.platform === 'win32' ? `cmd /c "${publishCmd}"` : publishCmd,
             done: false,
             note:
               `a bare (unscoped) name can return 403 with a granular token — "${json.name}" is ${json.name.startsWith('@') ? 'scoped, fine' : 'UNSCOPED, rename it'}` +
@@ -447,7 +452,14 @@ export function apply(ctx, config = {}) {
             command: `publish_gate_verify({ dir: "${dir.replace(/\\/g, '\\\\')}" })`,
             done: false,
             note: 'the registry answers 202 and then 404s for about a minute, so a mismatch right after publish is normal; the shasum comparison is exact once it settles',
-          },          {
+          },
+          {
+            name: 'tag the shipped commit',
+            command: `git tag v${json.version} && git push origin v${json.version}`,
+            done: false,
+            note: 'a GitHub release, a changelog entry and the market listing all point at a commit — none of them can point at one that was never tagged',
+          },
+          {
             name: 'market entry',
             command: `write data/plugins/${owner}__${repo}.yml with url / name / category / description{en,zh}`,
             done: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.18.0",
+  "version": "0.20.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",