@bushizhanghan/dsh-publish-gate 0.1.3 → 0.1.5

package/README.md

@@ -29,7 +29,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `publish_gate` | 全量门禁：静态检查 + 网络检查，返回 `safeToPublish` |
 | `publish_gate_patch` | 只查 `cordis.patch.yml`——「插件装了但工具没出现」的第一个怀疑对象 |
 | `publish_gate_market` | 校验市场条目 YAML（url/name/category/description 双语） |
-| `publish_gate_next_version` | 当前版本、是否已被 registry 占用、建议 bump 到多少 |
+| `publish_gate_next_version` | 当前版本、是否已被 registry 占用、建议 bump 到多少（本地比 npm 旧时从 npm 的 latest 往上加，不会推荐一个已被占用的版本） |
 | `publish_gate_doctor` | 扫整个目录，按 blocker 数排序，看哪个插件还不能发 |
 | `publish_gate_commands` | 按顺序列出发布命令，并标出这台机器已经走到哪一步 |
 
@@ -47,14 +47,15 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `no-exports` | 缺 `exports["."]`，宿主解析不到入口 |
 | `client-without-export` | 声明了 client 平台却没导出 `./client`，宿主半边在、侧栏永不出现 |
 | `not-esm` | 没 `"type": "module"`，`import` 在加载时炸 |
-| `insert-wrong-indent` | **insert 行没在 `- insert:` 底下**——顶层 `- id:` 是对已有条目的 patch，不是挂载 |
+| `no-insert-row` | patch 里只有 override，永远不挂载（页面报的仍然是这条——顶层 `- id:` 是 patch 不是挂载） |
+| `patch-not-mount` | info：这些顶层 `- id:` 是在覆盖已有条目，合法，但**不是**挂载 |
 | `insert-missing-name` / `insert-name-mismatch` | 挂载名缺失或与 package.json 不一致 |
-| `no-insert-row` | patch 里只有 override，永远不挂载 |
 | `no-patch-file` | 有 `lib/index.js` 但没有 `cordis.patch.yml` |
 | `no-name-export` / `no-apply-export` | 入口协议不完整 |
 | `require-in-esm` | ESM 里 `require()` → `ERR_AMBIGUOUS_MODULE_SYNTAX`，报错不带行号 |
 | `no-license` | 缺 LICENSE |
 | `version-taken` | 这个版本已经在 registry 上，再发是 403 |
+| `registry-unreachable` | registry 回了 500/429 —— 版本检查**没跑**，所以别把它当干净 |
 
 ### 值得在发布前知道的（warn / info）
 `unscoped-name`（granular token 的 403）、`repo-missing`、`patch-name-unresolvable`（junction 放错层级）、`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`，以及市场条目的 `market-*` 全系列。
@@ -69,9 +70,10 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
     fail with a parse error that never names the BOM.
 ✗ files does not include "lib"  [files-omits-lib]
     The published tarball will contain no code.
-✗ insert row "page-monitor" (line 173) is not inside an "- insert:" sequence  [insert-wrong-indent]
-    A top-level `- id:` row is a patch on an existing entry, not a mount. The
-    loader reports one stderr warning and boots without your plugin.
+✗ cordis.patch.yml has no insert row  [no-insert-row]
+    A patch with only overrides never mounts your plugin. This file has 1
+    top-level `- id:` row — those patch entries that already exist in the tree,
+    they do not add one.
 ✗ lib/index.js calls require() inside an ESM module  [require-in-esm]
 4 blocker(s) — fix before publishing
 ```
@@ -88,7 +90,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test    # 19 个单测（含 4 个真实插件作 fixture）+ 16 项集成测试
+node --test    # 26 个测试（含 4 个真实插件作 fixture）
 ```
 
 ## License

package/lib/engine.js

@@ -6,7 +6,7 @@
 // unscoped npm name that returned E403, a git push that failed on the network
 // while the REST API worked. All of them are silent until the moment they cost
 // you a publish, so they are all checkable before you spend it.
-import { existsSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { homedir } from 'node:os'
 
@@ -64,6 +64,9 @@ export function checkPackageJson(dir) {
   }
 
   for (const field of REQUIRED) {
+    // `main` is optional when the package resolves through exports["."]:
+    // an exports-only manifest is the modern shape and loads fine.
+    if (field === 'main' && json.exports?.['.']) continue
     if (json[field] === undefined || json[field] === null || json[field] === '') {
       out.push(F('missing-field', 'error', `package.json is missing "${field}"`, `npm warns but publishes; consumers then cannot resolve it.`, `Add "${field}".`))
     }
@@ -100,9 +103,15 @@ export function checkPackageJson(dir) {
     )
   }
 
-  // files — the classic: lib/ omitted, so the published tarball has no code
+  // files — the classic: lib/ omitted, so the published tarball has no code.
+  // "lib/", "./lib" and "lib/**/*.js" all pack lib/, so match the entry rather
+  // than the exact string "lib".
   if (Array.isArray(json.files)) {
-    if (!json.files.includes('lib')) {
+    const packsLib = json.files.some((f) => {
+      const norm = String(f).replace(/^\.\//, '').replace(/\/+$/, '')
+      return norm === 'lib' || norm === 'lib/**/*' || norm.startsWith('lib/')
+    })
+    if (!packsLib) {
       out.push(
         F(
           'files-omits-lib',
@@ -201,6 +210,7 @@ export function checkPatchYml(dir) {
 
   const lines = text.split('\n')
   const insertRows = []
+  const patchRows = []
   let inInsert = false
   let insertIndent = 0
   for (let i = 0; i < lines.length; i++) {
@@ -215,7 +225,12 @@ export function checkPatchYml(dir) {
     if (idMatch) {
       const indent = idMatch[1].length
       const id = idMatch[2].replace(/^['"]|['"]$/g, '')
-      insertRows.push({ line: i + 1, indent, id, underInsert: inInsert && indent > insertIndent })
+      // A row at column 0 is a patch on an existing entry — the shape every
+      // profile patch is made of. Only a row nested inside "- insert:" mounts
+      // a package, and calling the patch row a mis-indented insert told users
+      // to indent it, which would insert a duplicate of an existing id.
+      if (inInsert && indent > insertIndent) insertRows.push({ line: i + 1, indent, id })
+      else patchRows.push({ line: i + 1, indent, id })
       continue
     }
     // a top-level key (indent 0, no dash) closes the insert sequence
@@ -228,41 +243,37 @@ export function checkPatchYml(dir) {
         'no-insert-row',
         'error',
         'cordis.patch.yml has no insert row',
-        'A patch with only overrides never mounts your plugin.',
+        `A patch with only overrides never mounts your plugin.${patchRows.length > 0 ? ` This file has ${patchRows.length} top-level \`- id:\` row(s) — those patch entries that already exist in the tree, they do not add one.` : ''}`,
         'Add:\n- insert:\n    - id: <your-plugin-id>\n      name: "<package-name>"',
       ),
     )
     return out
   }
 
-  for (const row of insertRows) {
-    if (!row.underInsert) {
-      // the exact bug that kept page-monitor and weapp-loop from loading:
-      // an insert row written at column 0 becomes a top-level patch entry,
-      // which the loader applies to an id that is not in the tree.
-      out.push(
-        F(
-          'insert-wrong-indent',
-          'error',
-          `insert row "${row.id}" (line ${row.line}) is not inside an "- insert:" sequence`,
-          'A top-level `- id:` row is a patch on an existing entry, not a mount. The loader reports one stderr warning and boots without your plugin — installed, loaded, and silent.',
-          'Indent it under `- insert:`:\n- insert:\n    - id: <id>\n      name: "<pkg>"',
-        ),
-      )
-    }
+  // Patching is legitimate (that is how a profile overrides a model or a
+  // theme), but it must not be mistaken for a mount.
+  if (patchRows.length > 0) {
+    out.push(
+      F(
+        'patch-not-mount',
+        'info',
+        `${patchRows.length} top-level \`- id:\` row(s) patch existing entries (line ${patchRows.map((r) => r.line).join(', ')})`,
+        'These rows override an entry that is already in the tree. They are not mounts: if you meant to add this package, it needs an "- insert:" row.',
+        'Nothing to do if you are overriding. If not, move the row under "- insert:".',
+      ),
+    )
   }
 
   // every insert row must carry a name that matches package.json
-  for (let i = 0; i < lines.length; i++) {
-    const m = /^(\s*)-\s*id:\s*(.+?)\s*$/.exec(lines[i])
-    if (!m || m[1].length <= 2) continue
+  for (const row of insertRows) {
+    const i = row.line - 1
     const nameMatch = /^\s*name:\s*(.+?)\s*$/.exec(lines[i + 1] || '')
     if (!nameMatch) {
       out.push(
         F(
           'insert-missing-name',
           'error',
-          `insert row on line ${i + 1} has no name: field`,
+          `insert row on line ${row.line} has no name: field`,
           'The loader mounts by package name; without it the row resolves to nothing.',
           `Add the next line:      name: "${name || '<package-name>'}"`,
         ),
@@ -379,12 +390,28 @@ export function checkNpmState(dir, { token, registry = 'https://registry.npmjs.o
 }
 
 /** Version-collision check: the same version already on the registry. */
-export async function checkVersionTaken(name, version, { registry = 'https://registry.npmjs.org' } = {}) {
+export async function checkVersionTaken(name, version, { registry = 'https://registry.npmjs.org', timeoutMs = 8000 } = {}) {
   const out = []
   try {
-    const res = await fetch(`${registry.replace(/\/$/, '')}/${name.replace('/', '%2f')}`, { headers: { accept: 'application/vnd.npm.install-v1+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) return out
+    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
+    }
     const json = await res.json()
     if (json?.versions?.[version]) {
       out.push(
@@ -406,6 +433,33 @@ export function bumpPatch(v) {
   return m ? `${m[1]}.${m[2]}.${Number(m[3]) + 1}` : v
 }
 
+/** -1 / 0 / 1 by semver-ish comparison of the numeric part. */
+export function compareVersions(a, b) {
+  const pa = /^(\d+)\.(\d+)\.(\d+)/.exec(String(a))?.slice(1).map(Number) ?? [0, 0, 0]
+  const pb = /^(\d+)\.(\d+)\.(\d+)/.exec(String(b))?.slice(1).map(Number) ?? [0, 0, 0]
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1
+  return 0
+}
+
+/**
+ * The registry's `dist-tags.latest`, or null when it could not be read.
+ * next_version needs this: a local checkout that is BEHIND npm would otherwise
+ * be told to publish a version that is already taken.
+ */
+export async function latestPublished(name, { registry = 'https://registry.npmjs.org', timeoutMs = 8000 } = {}) {
+  try {
+    const res = await fetch(`${registry.replace(/\/$/, '')}/${name.replace('/', '%2f')}`, {
+      headers: { accept: 'application/vnd.npm.install-v1+json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!res.ok) return null
+    const json = await res.json()
+    return json?.['dist-tags']?.latest ?? null
+  } catch {
+    return null
+  }
+}
+
 export function checkGitState(dir) {
   const out = []
   const gitDir = join(dir, '.git')
@@ -489,8 +543,17 @@ export function checkTests(dir) {
     out.push(F('no-tests', 'warn', 'no test/ directory', 'A plugin with no tests ships rules nobody has run; the market does not require tests, but reviewers notice.', 'Add node --test tests.'))
     return out
   }
-  const hasTest = ['engine.test.mjs', 'integration.test.mjs'].some((f) => existsSync(join(testDir, f)))
-  if (!hasTest) out.push(F('no-test-files', 'warn', 'test/ has no *.test.mjs', 'Add at least an engine test so the rules are exercised.', 'Add test/engine.test.mjs.'))
+  // Any test file counts: naming is the author's business, and demanding
+  // engine.test.mjs specifically told authors to rename working tests.
+  const testFiles = (() => {
+    try {
+      return readdirSync(testDir).filter((f) => /\.(test|spec)\.(mjs|js|cjs)$/.test(f))
+    } catch {
+      return []
+    }
+  })()
+  const hasTest = testFiles.length > 0
+  if (!hasTest) out.push(F('no-test-files', 'warn', 'test/ has no *.test.mjs or *.spec.mjs', 'Add at least an engine test so the rules are exercised.', 'Add test/engine.test.mjs.'))
   const pkgJson = (() => {
     const t = safeText(join(dir, 'package.json'))
     try {
@@ -529,7 +592,7 @@ const RULE_ORDER = [
   'missing-field', 'not-esm', 'files-omits-lib', 'files-omits-patch', 'no-exports', 'client-without-export',
   'no-patch-file', 'no-insert-row', 'insert-wrong-indent', 'insert-missing-name', 'insert-name-mismatch',
   'patch-name-unresolvable', 'no-name-export', 'no-apply-export', 'no-inject', 'require-in-esm',
-  'no-license', 'license-mismatch', 'version-taken', 'market-empty', 'market-no-url', 'market-url-not-github',
+  'no-license', 'license-mismatch', 'version-taken', 'registry-unreachable', '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',
   'no-tests', 'no-test-files', 'no-test-script', 'no-engines', 'bad-repo-url', 'no-gitignore',

package/lib/index.js

@@ -18,6 +18,8 @@ import {
   checkPatchYml,
   checkTests,
   checkVersionTaken,
+  compareVersions,
+  latestPublished,
   renderReport,
   runStaticChecks,
 } from './engine.js'
@@ -168,23 +170,36 @@ export function apply(ctx, config = {}) {
         if (!dir) return { ok: false, error: 'no plugin directory given' }
         const json = readJson(join(dir, 'package.json'))
         if (!json?.version) return { ok: false, error: 'no version in package.json' }
-        const taken = (await checkVersionTaken(json.name, json.version, { registry: cfg.registry })).map((f) => f.title)
-        const [a, b, c] = /^(\d+)\.(\d+)\.(\d+)/.exec(json.version)?.slice(1).map(Number) ?? [0, 0, 0]
+        const taken = (await checkVersionTaken(json.name, json.version, { registry: cfg.registry, timeoutMs: cfg.networkTimeoutMs })).map((f) => f.title)
+        const latest = await latestPublished(json.name, { registry: cfg.registry, timeoutMs: cfg.networkTimeoutMs })
+        // A checkout that is behind npm must bump from npm's latest, or the
+        // "suggested" version is one that is already published.
+        const behind = latest && compareVersions(latest, json.version) > 0 ? latest : null
+        const base = behind ?? json.version
+        const [a, b, c] = /^(\d+)\.(\d+)\.(\d+)/.exec(base)?.slice(1).map(Number) ?? [0, 0, 0]
         const bump = args.bump || 'patch'
         const suggested =
           bump === 'major' ? `${a + 1}.0.0` : bump === 'minor' ? `${a}.${b + 1}.0` : `${a}.${b}.${c + 1}`
-        return { ok: true, current: json.version, taken, suggested, suggestedFor: bump }
+        return {
+          ok: true,
+          current: json.version,
+          latest,
+          behind,
+          taken,
+          suggested,
+          suggestedFor: bump,
+          note: behind ? `package.json is behind the registry (${behind} is live); the suggestion bumps from there.` : undefined,
+        }
       },
     },
     {
       name: 'publish_gate_doctor',
       description:
-        'Run the gate over every plugin in a directory tree (e.g. a workspace holding several plugin checkouts) and rank them by blocker count, so you can see which one is not ready to ship before you start a publish session. Returns {ok, plugins:[{dir,blockers,warns,notes,top}], totals}.',
+        'Run the gate over every plugin in a directory tree (e.g. a workspace holding several plugin checkouts) and rank them by blocker count, so you can see which one is not ready to ship before you start a publish session. Static checks only — no registry or GitHub calls, so it is fast and works offline. Returns {ok, plugins:[{dir,blockers,warns,notes,top}], totals}.',
       parameters: {
         type: 'object',
         properties: {
           root: { type: 'string', description: 'Directory containing plugin checkouts.' },
-          skipNetwork: { type: 'boolean', description: 'Skip registry/GitHub checks (default true for a multi-plugin sweep).' },
         },
       },
       async execute(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Helps DSH plugin AUTHORS publish their plugins: a one-command gate that turns every silent failure in the publish path into a deterministic check — package.json completeness, BOM, YAML/JSON parseability, junction and patch insert correctness, npm scope permissions, GitHub repo and token state, market entry format, LICENSE/README, test suite. 帮助插件作者一键发布：写完插件后跑一遍门禁，把发布链路上的每个静默坑变成确定性检查，然后 GitHub + npm + 市场一键三连。",
   "type": "module",
   "main": "lib/index.js",