@bushizhanghan/dsh-publish-gate 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+## 0.6.0
+
+- New rule `tool-undeclared-param`: a tool whose `execute` reads `args.x` that
+  `parameters.properties` never declares. The host renders `parameters` into the
+  prompt and passes the model nothing else, so that value is undefined on every
+  real call — the code path exists and never runs, and nothing throws.
+  Covers `args.x`, `args['x']` and `const { x } = args`.
+
+## 0.5.0
+
+- New layer: traceability. `git-uncommitted` (files that ship in the tarball are
+  not committed), `git-tag-missing` (no `v<version>` tag on HEAD),
+  `git-tag-elsewhere` (the tag exists but points at another commit).
+- The incident behind it: a 1.2.7 went to npm while the GitHub release still
+  said 1.2.6 and the market entry still pointed at the old tarball.
+
+## 0.4.0
+
+- New layer: dependency truth. `undeclared-import` (lib/ imports a package
+  package.json never declares), `dep-in-dev-only` (only devDependencies satisfy
+  it — npm never installs those for the consumer), `unused-dependency` (info).
+- New rule `version-behind-latest`: publishing under the live `latest` is
+  accepted by npm and reaches nobody.
+
+## 0.3.4
+
+- `tool-call-slow` split from `tool-call-throws`: a timeout is not a defect.
+
+## 0.3.3
+
+- `publish_gate_tools` accepts `call: ["name"]` to really invoke a tool, opt-in
+  because some tools open applications or write files.
+
+## 0.3.2
+
+- New rule `node-too-old`: `engines.node` says one thing, `lib/` uses an API from
+  a newer Node. npm only warns on `engines`, so the plugin installs and then
+  throws at import.
+
+## 0.3.1
+
+- `publish_gate_commands` emits commands that actually run on this machine
+  (`cmd /c "npm publish --access public"` on Windows) and pairs the publish step
+  with a `publish_gate_verify` shasum check.
+
+## 0.3.0
+
+- New layer: the browser half. `checkClientHalf` / `checkClientRuntime` load the
+  bundle against a fake `window.__ModuleLoader__` and report a bundle that never
+  loads, never returns `apply`, throws, registers nothing, or uses a service its
+  `inject` array does not declare.
+- New layer: market readiness — the repo is already listed, another entry
+  publishes the same npm name, or the repo is under 24 hours old (the gate fails
+  and reruns itself).
+- New rules: `client-without-platform`, `pack-omits-client`, `pack-ships-secret`,
+  `private-field-set`, `publish-config-registry`, `tool-bad-parameter-type`,
+  `entry-path-missing`, `bundle-patch-not-declared`, `inject-unused-service`.
+- New tool `publish_gate_client` (9 tools).
+
+## 0.2.0
+
+- New layers: artifact (`npm pack --dry-run` — what npm will really ship) and
+  runtime (import the entry in an isolated child process, call `apply`, report a
+  throwing import, a throwing apply, missing execute, duplicate tool names, a
+  throwing `presentCall`, and card kinds the host does not render).
+- New tools `publish_gate_tools` and `publish_gate_verify`.
+- Fixed: `bad-repo-url` never fired for the object form of `repository`.
+
+## 0.1.0
+
+- First release: manifest rules, `cordis.patch.yml` insert checks, README and
+  test presence, npm name and registry state.

package/README.md

@@ -102,6 +102,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `tool-present-call-throws` | `presentCall` 抛——调用记录渲染时炸 |
 | `tool-bad-card-kind` | `card: 'generic'` 的 `kind` 不在宿主认识的那一组里（`other` / `execute` / `search` / `read` / `edit` / `delete` / `fetch`）。注册不报错，卡片渲染坏掉——我五个插件一起踩过 |
 | `tool-bad-parameter-type` | `parameters` 里某个 `type` 写错（`"strin"`）。宿主把 `parameters` 渲染进 prompt、但**从不校验**调用值，所以这个 typo 只是悄悄把类型提示弄丢 |
+| `tool-undeclared-param` | `execute` 读了 `args.x`，但 `parameters.properties` 里没有 `x`。模型只能传 schema 声明过的参数，所以这个值在真实调用里永远是 `undefined`——代码在，永远不跑，也不报错。`args.x`、`args['x']`、`const { x } = args` 三种写法都认 |
 
 ### 浏览器半边：侧栏面板到底会不会出现
 
@@ -161,6 +162,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 +211,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 75 个引擎单测
+node --test                      # 83 个引擎单测
 node test/integration.test.mjs   # 26 条集成断言（9 个真实插件作 fixture）
 ```
 

package/lib/engine.js

@@ -1057,6 +1057,31 @@ const walkParams = (schema, path) => {
   }
   if (schema.items) walkParams(schema.items, path + '[]')
 }
+// The model only ever sends the arguments \`parameters\` declares — the host
+// renders that schema into the prompt and passes nothing else. So an execute
+// that reads args.dir while the schema never mentions dir is unreachable code:
+// every call sees undefined, and the tool looks broken with no error anywhere.
+const ARG_DOT = /\\bargs\\s*\\??\\.\\s*([A-Za-z_$][\\w$]*)/g
+const ARG_INDEX = /\\bargs\\s*\\[\\s*['"]([^'"]+)['"]\\s*\\]/g
+const ARG_DESTRUCTURE = /\\{\\s*([^{}]+?)\\s*\\}\\s*=\\s*args\\b/g
+const undeclaredArgs = (def) => {
+  const props = def?.parameters?.properties
+  if (!props || typeof props !== 'object') return []
+  const declared = Object.keys(props)
+  if (typeof def.execute !== 'function') return []
+  let src = ''
+  try { src = def.execute.toString() } catch { return [] }
+  const reads = []
+  for (const m of src.matchAll(ARG_DOT)) reads.push(m[1])
+  for (const m of src.matchAll(ARG_INDEX)) reads.push(m[1])
+  for (const m of src.matchAll(ARG_DESTRUCTURE)) {
+    for (const part of m[1].split(',')) {
+      const key = part.split(':')[0].split('=')[0].replace(/\\.\\.\\./, '').trim()
+      if (/^[A-Za-z_$][\\w$]*$/.test(key)) reads.push(key)
+    }
+  }
+  return [...new Set(reads)].filter((r) => !declared.includes(r))
+}
 const noopService = () => new Proxy(function () {}, {
   get: (target, prop) => {
     // Own properties win, or ctx.tools would resolve to another no-op proxy
@@ -1086,6 +1111,7 @@ ctx.tools = {
       hasExecute: typeof def?.execute === 'function',
       hasOutputSchema: Boolean(def && def.output && def.output.schema),
       cardKind: card,
+      undeclaredParams: undeclaredArgs(def),
       run: typeof def?.execute === 'function' ? def.execute : null,
     })
     walkParams(def?.parameters, typeof def?.name === 'string' ? def.name : '(unnamed)')
@@ -1229,6 +1255,21 @@ export async function checkToolRegistrations(dir, opts = {}) {
         ),
       )
     }
+
+    // The model only sends what `parameters` declares, so a read of anything
+    // else is unreachable: args.dir is undefined on every real call, and the
+    // tool looks broken while nothing throws.
+    for (const name of Array.isArray(t.undeclaredParams) ? t.undeclaredParams : []) {
+      out.push(
+        F(
+          'tool-undeclared-param',
+          'warn',
+          `tool "${label}" reads args.${name}, which parameters never declares`,
+          'The host renders parameters into the prompt and passes the model nothing else, so this value is always undefined on a real call. The code path exists and never runs.',
+          `Add "${name}" to parameters.properties, or stop reading it.`,
+        ),
+      )
+    }
   }
   const badParams = Array.isArray(payload.badParamTypes) ? payload.badParamTypes : []
   for (const where of badParams) {
@@ -1678,8 +1719,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 +1842,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
 // =====================================================================
@@ -1831,7 +1959,7 @@ 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-call-throws', 'tool-call-slow',
+  'tool-bad-card-kind', 'tool-missing-output-schema', 'tool-none-registered', 'tool-bad-parameter-type', 'tool-undeclared-param', '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',
@@ -1840,6 +1968,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.6.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": {
@@ -13,7 +13,8 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "dsh",