@bushizhanghan/dsh-publish-gate 0.4.0 → 0.5.0

package/README.md

@@ -161,6 +161,20 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 
 两条都只是 warn：有可能你就是要发手改的产物（我干过）。但发之前你得知道自己在发什么。
 
+### 可追溯性：一周后你还能指出线上那包是哪份代码吗
+
+发布是字节唯一一次离开你机器的时刻。如果这些字节既不在任何 commit 里、也没有 tag，那么一周后——包括你自己在内——没人说得清 registry 上那包是从哪份源码来的。
+
+这不是假想：我发过一版 `1.2.7` 到 npm，仓库的 GitHub release 还停在 `1.2.6`，市场条目指向旧 tarball，维护者直接打回。
+
+| 规则 | 抓什么 |
+|---|---|
+| `git-uncommitted` | 会进 tarball 的文件有未提交改动。发出去的字节不在任何 commit 里，以后复现不出来、也没法 bisect |
+| `git-tag-missing` | HEAD 上没有 `v<version>` tag。发完之后这些字节的唯一记录就是 registry，GitHub release、changelog、市场条目都没法指向一个从没打过 tag 的 commit |
+| `git-tag-elsewhere` | tag 存在但不在 HEAD 上：tag 和 tarball 是两份不同的字节，从那个 tag 构建出来的东西不是你刚发的东西 |
+
+都是 warn：本地试发、私有包、发完再补 tag 都合理。但「发完之后指不出是哪份代码」这件事，事后补不回来。
+
 ## 一个真实的例子
 
 对一个刚从别人那儿接手、准备发布的插件跑 `publish_gate`：
@@ -196,7 +210,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 75 个引擎单测
+node --test                      # 80 个引擎单测
 node test/integration.test.mjs   # 26 条集成断言（9 个真实插件作 fixture）
 ```
 

package/lib/engine.js

@@ -1678,8 +1678,12 @@ export async function runArtifactChecks(dir, opts = {}) {
   const toolResult = opts.skipTools ? { findings: [], tools: null } : await checkToolRegistrations(dir, opts)
   const clientResult = opts.skipClient ? { findings: [], client: null } : await checkClientRuntime(dir, opts)
   const names = toolResult.tools ? toolResult.tools.map((t) => t.name).filter(Boolean) : null
+  const trace = await checkTraceability(dir, {
+    packFiles: packResult.pack?.files?.map((f) => f.path) || [],
+    ...opts,
+  })
   return {
-    findings: [...packResult.findings, ...toolResult.findings, ...clientResult.findings, ...checkReadmeTruth(dir, names)],
+    findings: [...packResult.findings, ...toolResult.findings, ...clientResult.findings, ...checkReadmeTruth(dir, names), ...trace],
     pack: packResult.pack,
     tools: toolResult.tools,
     client: clientResult.client,
@@ -1797,6 +1801,89 @@ export function checkDependencies(dir) {
   return out
 }
 
+// =====================================================================
+// Traceability: can you point at the exact bytes you are publishing?
+// =====================================================================
+
+const gitOut = async (dir, args) => {
+  try {
+    const { stdout } = await runFile('git', ['-C', dir, ...args], { timeout: 8000, windowsHide: true })
+    return String(stdout).trim()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Publishing is the one moment where the bytes leave your machine. If they are
+ * not in a commit and not under a tag, then a week later nobody — including you —
+ * can say which source produced the live tarball. This really happened: a 1.2.7
+ * went to npm while the repo's release still said 1.2.6, and the marketplace
+ * entry pointed at the old tarball.
+ *
+ * `status` / `atHead` / `tagExists` inject the git answers so the rules are
+ * testable without a repository.
+ */
+export async function checkTraceability(dir, opts = {}) {
+  const out = []
+  const json = readPkgJson(dir)
+  const version = typeof opts.version === 'string' ? opts.version : json?.version
+  if (!version) return out
+
+  const inside = opts.inside ?? (opts.status === undefined ? await gitOut(dir, ['rev-parse', '--is-inside-work-tree']) : 'true')
+  if (inside !== 'true') return out // checkGitState already reported no-git
+
+  // 1. Dirty tree: the tarball carries bytes that exist in no commit.
+  const status = opts.status === undefined ? await gitOut(dir, ['status', '--porcelain']) : opts.status
+  if (typeof status === 'string') {
+    const packed = new Set((opts.packFiles || []).map((p) => String(p).replace(/\\/g, '/')))
+    const dirty = status
+      .split('\n')
+      .map((line) => line.slice(3).trim())
+      .map((p) => (p.includes(' -> ') ? p.split(' -> ').pop().trim() : p))
+      .filter(Boolean)
+    // Without a tarball listing, lib/ is the honest proxy: that is the code.
+    const relevant = packed.size ? dirty.filter((p) => packed.has(p)) : dirty.filter((p) => p.startsWith('lib/'))
+    if (relevant.length) {
+      out.push(
+        F(
+          'git-uncommitted',
+          'warn',
+          `${relevant.length} file(s) going into the tarball are not committed`,
+          `The published bytes exist in no commit, so they can never be reproduced or bisected later. First: ${relevant.slice(0, 3).join(', ')}.`,
+          'Commit (or stash) them before publishing.',
+        ),
+      )
+    }
+  }
+
+  // 2. No tag on HEAD: nothing points at these bytes afterwards.
+  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 wanted = [`v${version}`, version]
+  if (typeof atHead === 'string' && !wanted.some((t) => tags.includes(t))) {
+    const exists = opts.tagExists === undefined ? await gitOut(dir, ['rev-parse', '--verify', '--quiet', `refs/tags/v${version}`]) : opts.tagExists ? 'sha' : null
+    out.push(
+      exists
+        ? F(
+            'git-tag-elsewhere',
+            'warn',
+            `tag v${version} exists but does not point at HEAD`,
+            'The tag and the tarball are different bytes. A release built from that tag would not be what you just published.',
+            `Move it: git tag -f v${version} && git push -f origin v${version}`,
+          )
+        : F(
+            'git-tag-missing',
+            'warn',
+            `no git tag v${version} on HEAD`,
+            '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
+}
+
 // =====================================================================
 // Orchestration
 // =====================================================================
@@ -1840,6 +1927,7 @@ const RULE_ORDER = [
   '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',
+  'git-uncommitted', 'git-tag-missing', 'git-tag-elsewhere',
   'readme-tool-undocumented', 'readme-test-count',
   'no-tests', 'no-test-files', 'no-test-script', 'no-engines', 'bad-repo-url', 'no-gitignore',
 ]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.4.0",
-  "description": "Pre-publish gate for DSH plugins, in five layers: manifest, dependencies, artifact, runtime and the browser half. 发布前的五层门禁：清单、依赖、产物、运行时、浏览器半边。",
+  "version": "0.5.0",
+  "description": "Pre-publish gate for DSH plugins in five layers: manifest, dependencies, artifact, runtime, browser half — plus traceability (can you point at the bytes you shipped?). 发布前门禁：清单、依赖、产物、运行时、浏览器半边，外加可追溯性。",
   "type": "module",
   "main": "lib/index.js",
   "exports": {