dsh-standards 1.2.2 → 1.3.0

package/40-checker/README.md

@@ -19,6 +19,17 @@ node bin/dsh-plugin-verify.mjs /path/to/plugin --format json --out report.json
 node bin/dsh-plugin-verify.mjs /path/to/plugin --format sarif --out report.sarif
 ```
 
+### 作者入口：`dsh-standards check [dir]`
+
+```bash
+dsh-standards check                 # 默认 cwd，输出 Markdown
+dsh-standards check ./my-plugin --scope entry --entry-claim static --no-exec
+dsh-standards check ./my-plugin --json            # 原始 dsh-conformance/1
+dsh-standards check ./my-plugin --html out.html   # 单文件、内联 CSS、零外部资源、全转义
+```
+
+Markdown = 一句结论（`conclusion.headline`）+ ≤3 条优先修复 + `buckets` 三栏全表 + advice + 免责声明/「没查什么」。exit code 与底层检查器一致（0/1/2/3），不在这里改写。`--json` 与 `--html` 互斥；`--format`/`--out` 不转发（由 `check` 自己决定输出）。其余 flag 原样转发（`--scope`、`--runtime-version`、`--market-index` 等）。advice 的公开 schema 是 `spec/schemas/advice.schema.json`（`dsh-advice/1`，13 个必填字段，`why`/`fix`/`docsUrl` 可 null，`evidence` ≤ 10，`gate`/`severity` ∈ {FAIL,WARN}）。
+
 `buildReport()` 与 `--format json` 默认带**加性** `advice[]`（来自 `spec/remediation.json` 的 68 条规则；FAIL/WARN detail 优先，无 detail 的运行时 FAIL 用 `check.clause` 兜底）。每条 advice 的 `gate` 是该 check 的最终结果（PASS/WARN/FAIL），`severity` 跟随 `gate`：被降级为 WARN 的 check 即使 detail 仍是 FAIL，也只给 WARN，detail 原因保留在 `reason`。`--no-advice` 可关闭；它不改变任何 check 的结果或 exit code。
 
 ## 2. 检查项
@@ -142,6 +153,8 @@ node bin/dsh-flow-collect.mjs --package ./my-plugin --sandbox --out flow-evidenc
 - `--sandbox` 在临时 HOME/DSH_HOME 下跑 `dsh plugin add` + boot：先试 `unshare -n`，不行再试 `unshare -Urn`；用 `prlimit` 设 `nproc`/`as` 并从 `/proc/self/limits` 回读实际生效项；超时 SIGKILL 整个进程组（Windows `taskkill /T /F`）。硬断言 `GH_TOKEN`/`NPM_TOKEN`/`GITHUB_TOKEN` 不在子进程 env，发现即中止。
 - 只有**所有**隔离项都生效才写 `producer.kind=sandbox` / `claims.claimLevel=sandbox-attested`；任何一项缺失（`unshare-missing`、`prlimit-missing`、`env-token-present`、`home-not-isolated`）写 `sandbox-degraded` + `sandbox.degraded[]`，仍是 self-attested，`level-audit` 永不判 runtime。`--sandbox-no-network` / `--sandbox-no-limits` 用于强制验证降级路径。
 - 前置缺失（无 dsh、无 `--previous`、宿主兼容门禁拒绝）记 `blocked` + reason，出口码 0；真失败出口码 1，并打印五要素提示（子检查 / 命令 / exitCode / stderr 末 20 行 / 日志绝对路径 + 条款锚）。
+- `level-audit --flow-evidence ... --dir <pkg>` 会把证据主体绑定到目录：`package.json` 的 name/version、重算的 `treeSha256`、`npm pack --ignore-scripts` 的 tarball sha256/integrity 必须与 `subject` 一致，否则 FLOW 直接 `invalid`，结果里输出 `subject.{declared,recomputed,mismatches}`。省略 `--dir` 时不做重绑定（旧行为）。
+- **CI 归属不是证明**：runner 上存在 `GITHUB_RUN_ID`/`GITHUB_REPOSITORY`/`GITHUB_SHA` 时，collector 把它们写进 `producer.runUrl/repository/commit`，`level-audit` 输出 `attestation: ci | self-declared`。这些字段来自环境变量、是自我声明，既不升级 `claims.claimLevel`，也不证明命令真的在 CI 里跑过。
 - 本地证据默认 `self-attested`：结构自洽 + 绑定此包 + 未过期，**不证明真跑过**。即使 `--sandbox` 通过，它也只是 containment（无 seccomp/cgroup/OCI 镜像/签名），不是认证或安全审计。`level-audit` 只有见到 `claims.claimLevel=sandbox-attested` 或 `producer.kind=sandbox` 才判 `runtime`；self/ci/degraded 证据保留 `passed` 计数但记 `not-run`。
 
 ## 4. 运行 L1–L3
@@ -151,7 +164,7 @@ node bin/dsh-flow-collect.mjs --package ./my-plugin --sandbox --out flow-evidenc
 ```bash
 node bin/dsh-plugin-verify.mjs ./my-plugin \
   --runtime /path/to/deepseek-harness/vendor/cordis/lib/index.js \
-  --runtime-version 0.2.2-alpha.2 \
+  --runtime-version 0.2.1-rc.5 \   # 省略时自动取 `dsh --version`（宿主实际版本）
   --cordis-version 4.0.6-alpha.1
 ```
 
@@ -179,6 +192,10 @@ node bin/dsh-plugin-verify.mjs ./my-plugin \
 
 **结论门**：`--scope ds-c` 只有在 profile 对应的强制项全部 `coverage: full`（允许显式 NA）时才给 `level`；否则 `status: incomplete`、exit 2。WARN 仍给 `level`，但写 `DS-C (profile, warnings)`，不冒充干净通过。
 
+**覆盖度与分桶（加性）**：`coverage` 统计报告携带的**全部**检查（完整跑是 14 项）——`pass/warn/fail/na/notRun/error` 都按 `checks[]` 实算，`total` 是总数；`coverage.notRun` 含 ERROR/未跑与缺失的强制项，`na` 再单列。`metrics = {checked, total, declaredFields}` 中的 `declaredFields` 是 5 个可选声明面（capabilities/labels/commitments/disclosure/engines.dsh）中实际声明的个数，只作上下文、不进结论。`buckets.blocking`（FAIL）、`buckets.hygiene`（WARN，`DSC-11/12/13` 标 `declaration`）、`buckets.notChecked`（NA/not-run/ERROR）是 text 的渲染顺序。`entryBlocking` 增加 `checked`/`notChecked`：`pass` 仅在 6 个阻断前提（C-1.1/1.2/1.4、C-3.1/3.2/3.5；runtime claim 再加 C-2.2/2.3）**都**产出 detail 且无 FAIL 时为 true——没给 `--install-spec`/`--market-index` 时 C-3.x 未查，`pass` 必为 false。
+
+**锚**：`anchor.dsh` 默认取宿主 `dsh --version`（`anchor.runtimeSource=host`）；显式 `--runtime-version` 时 `runtimeSource=cli`，与宿主不一致则 `anchor.suspect=true`；找不到 dsh 才回退常量并标 `fallback`。
+
 ## 6. 已知限制
 
 1. **C-3 只在 listing 模式可判**；package 模式是 NA，仅附供应链 advisory 证据。

package/40-checker/scripts/build-offline-kit.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * build-offline-kit — one .tgz for air-gapped / intranet users.
+ *
+ * The kit carries:
+ *   - the dsh-standards npm tarball (zero runtime dependencies)
+ *   - adoption/market (rev1 label schema, revocation, disclaimer, ...)
+ *   - market-contract (rev2 proposal, validate.mjs, examples)
+ *   - examples/ (the shipped example plugins)
+ *   - README.md (offline instructions) + OFFLINE-KIT.json (content manifest)
+ *
+ * It does not download anything. `market-contract` is not part of this repo
+ * yet, so the source directory can be passed explicitly (--market-contract);
+ * otherwise the usual sibling locations are probed and a clear error is
+ * raised when none is found.
+ *
+ * Usage:
+ *   node 40-checker/scripts/build-offline-kit.mjs \
+ *     --out publish/dsh-standards-offline-1.2.2.tgz \
+ *     --tarball /tmp/dsh-standards-1.2.2.tgz \
+ *     --market-contract /path/to/00-live/market-contract
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const ROOT = path.resolve(HERE, '..', '..')
+
+function usage() {
+  console.log(`build-offline-kit — bundle a self-contained offline kit
+
+Usage:
+  node 40-checker/scripts/build-offline-kit.mjs [options]
+
+Options:
+  --out <file>              output .tgz, default publish/dsh-standards-offline-<version>.tgz
+  --tarball <file>          existing dsh-standards npm .tgz; default pack the current tree
+  --root <dir>              source tree, default this repository
+  --market-contract <dir>   market-contract source (rev2 proposal + validate.mjs + examples)
+  --version <version>       kit/package version, default package.json version
+  --today <YYYY-MM-DD>      fixed manifest/README date
+  --help                    show this help
+
+The output is a gzip tar with README.md, OFFLINE-KIT.json, the npm tarball,
+adoption/market, market-contract and examples at its root.`)
+}
+
+function readJson(file, label) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`${label} is not readable JSON (${file}): ${error.message}`)
+  }
+}
+
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')
+}
+
+function parseArgs(argv) {
+  const options = {
+    out: null, tarball: null, root: ROOT, marketContract: null,
+    version: null, today: null,
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    const next = () => {
+      const value = argv[i + 1]
+      if (value === undefined) throw new Error(`${arg} needs a value`)
+      i += 1
+      return value
+    }
+    if (arg === '--out') options.out = next()
+    else if (arg === '--tarball') options.tarball = next()
+    else if (arg === '--root') options.root = next()
+    else if (arg === '--market-contract') options.marketContract = next()
+    else if (arg === '--version') options.version = next()
+    else if (arg === '--today') {
+      const day = next()
+      const parsed = new Date(`${day}T00:00:00.000Z`)
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== day) {
+        throw new Error(`--today must be a real YYYY-MM-DD, got ${JSON.stringify(day)}`)
+      }
+      options.today = day
+    } else if (arg === '--help' || arg === '-h') {
+      usage()
+      process.exit(0)
+    } else {
+      throw new Error(`unknown option: ${arg}`)
+    }
+  }
+  options.root = path.resolve(options.root)
+  return options
+}
+
+function findMarketContract(root, explicit) {
+  const candidates = []
+  if (explicit) candidates.push(path.resolve(explicit))
+  if (process.env.DSH_MARKET_CONTRACT) candidates.push(path.resolve(process.env.DSH_MARKET_CONTRACT))
+  candidates.push(
+    path.join(root, 'market-contract'),
+    path.join(root, '..', 'deepseek-community-hub', '00-live', 'market-contract'),
+    path.join(root, '..', '..', 'deepseek-community-hub', '00-live', 'market-contract'),
+    path.join(root, '..', 'market-contract'),
+    path.join(root, '..', '..', '00-live', 'market-contract'),
+    path.join(root, '00-live', 'market-contract'),
+  )
+  for (const candidate of candidates) {
+    if (!fs.existsSync(path.join(candidate, 'validate.mjs'))) continue
+    if (!fs.existsSync(path.join(candidate, 'label.schema.rev2.json'))) continue
+    return candidate
+  }
+  throw new Error(
+    'market-contract not found. Pass --market-contract <dir> (it must contain validate.mjs and label.schema.rev2.json). ' +
+    `Tried: ${candidates.join(', ')}`,
+  )
+}
+
+function findTarball(root, explicit, version) {
+  if (explicit) {
+    const file = path.resolve(explicit)
+    if (!fs.existsSync(file)) throw new Error(`--tarball not found: ${file}`)
+    return { file, temporary: false }
+  }
+  for (const name of [`dsh-standards-${version}.tgz`, `dsh-standards-${version}.tar.gz`]) {
+    const candidate = path.join(root, name)
+    if (fs.existsSync(candidate)) return { file: candidate, temporary: false }
+  }
+  const packDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-standards-pack-'))
+  const run = spawnSync('npm', ['pack', '--ignore-scripts', '--pack-destination', packDir], {
+    cwd: root,
+    encoding: 'utf8',
+  })
+  if (run.status !== 0) {
+    throw new Error(`npm pack failed (exit ${run.status}): ${(run.stderr || '').slice(-500)}`)
+  }
+  const produced = fs.readdirSync(packDir).filter(name => name.endsWith('.tgz'))
+  if (produced.length !== 1) throw new Error(`npm pack produced ${produced.length} tarballs, expected 1`)
+  return { file: path.join(packDir, produced[0]), temporary: true, packDir }
+}
+
+function copyDir(source, destination, label) {
+  if (!fs.existsSync(source)) throw new Error(`${label} not found: ${source}`)
+  if (!fs.statSync(source).isDirectory()) throw new Error(`${label} is not a directory: ${source}`)
+  fs.cpSync(source, destination, { recursive: true, force: true })
+}
+
+function listFiles(directory, prefix = '') {
+  const files = []
+  for (const name of fs.readdirSync(directory).sort()) {
+    const full = path.join(directory, name)
+    const relative = prefix ? `${prefix}/${name}` : name
+    if (fs.statSync(full).isDirectory()) files.push(...listFiles(full, relative))
+    else files.push(relative)
+  }
+  return files
+}
+
+function makeReadme({ version, day, tarballName }) {
+  return `# dsh-standards 离线包 ${version}
+
+> 生成于 ${day}。**不需要联网**，不含遥测，不执行被检查插件的代码。
+
+## 内容
+
+| 路径 | 用途 |
+|---|---|
+| \`${tarballName}\` | dsh-standards npm 包（零运行时依赖，含 \`dsh-standards\` / \`dsh-levels\`） |
+| \`adoption/market/\` | 市场标签 rev1 schema、撤回说明、免责声明、渲染规则 |
+| \`market-contract/\` | rev2 提案 schema + \`validate.mjs\` + 4 个可校验样张 |
+| \`examples/\` | 仓库自带的示例插件 |
+| \`OFFLINE-KIT.json\` | 本包文件清单、npm tarball 的 sha256 与大小 |
+
+## 快速开始（断网）
+
+\`\`\`sh
+tar -xzf dsh-standards-offline-${version}.tgz -C dsh-standards-offline
+cd dsh-standards-offline
+npm install --offline --no-audit --no-fund ./${tarballName}
+node node_modules/dsh-standards/bin/dsh-levels.mjs <plugin-dir> --format json
+\`\`\`
+
+\`dsh-levels\` 默认只做静态 ENTRY 检查；FLOW 没有证据文件就是 \`not-run\`，
+BOOST 没有证据卡就是 \`not-measured\`。静态 \`recognized\` **不等于** runtime。
+
+## 校验市场契约
+
+\`\`\`sh
+node market-contract/validate.mjs --examples   # 期望 4/4 样张符合预期
+\`\`\`
+
+rev2 仍是提案（\`x-dsh-effective:false\`），现行市场记录仍按 \`adoption/market/label.schema.json\` 的 rev1 校验。
+sidecar 是索引缓存，不是签发记录；本离线包不内置 \`publish/sidecar.json\`。
+
+## 边界
+
+- 不是官方标准、不是认证、不是安全审计、不排序、不比较、不做担保。
+- 离线包不联网、不下载、不安装被检查插件的依赖。
+- 许可证见 npm tarball 内的 \`LICENSE\` / \`LICENSE-APACHE\` / \`LICENSE-CC-BY\`。
+`
+}
+
+function makeTar(staging, outFile) {
+  const write = (flags) => spawnSync('tar', [...flags, '-czf', outFile, '-C', staging, '.'], {
+    encoding: 'utf8',
+  })
+  let run = write(['--sort=name', '--mtime=@0', '--owner=0', '--group=0', '--numeric-owner'])
+  if (run.status !== 0) {
+    fs.rmSync(outFile, { force: true })
+    run = write([])
+  }
+  if (run.status !== 0) {
+    throw new Error(`tar failed (exit ${run.status}): ${(run.stderr || '').slice(-500)}`)
+  }
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const rootPkg = readJson(path.join(options.root, 'package.json'), 'package.json')
+  const version = options.version ?? rootPkg.version
+  if (typeof version !== 'string' || version === '') throw new Error('cannot determine kit version')
+  const day = options.today ?? new Date().toISOString().slice(0, 10)
+  const outFile = path.resolve(options.out ?? path.join(options.root, 'publish', `dsh-standards-offline-${version}.tgz`))
+
+  const marketContract = findMarketContract(options.root, options.marketContract)
+  const tarball = findTarball(options.root, options.tarball, version)
+  const tarballName = `dsh-standards-${version}.tgz`
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-offline-kit-'))
+  try {
+    const kit = path.join(staging, 'kit')
+    fs.mkdirSync(kit, { recursive: true })
+    copyDir(path.join(options.root, 'adoption', 'market'), path.join(kit, 'adoption', 'market'), 'adoption/market')
+    copyDir(marketContract, path.join(kit, 'market-contract'), 'market-contract')
+    copyDir(path.join(options.root, 'examples'), path.join(kit, 'examples'), 'examples')
+    fs.copyFileSync(tarball.file, path.join(kit, tarballName))
+
+    const tarballSha256 = sha256File(tarball.file)
+    fs.writeFileSync(path.join(kit, 'README.md'), makeReadme({ version, day, tarballName }))
+
+    const contents = listFiles(kit).filter(file => file !== 'OFFLINE-KIT.json')
+    const manifest = {
+      schema: 'dsh-offline-kit/1',
+      name: 'dsh-standards-offline',
+      version,
+      generatedAt: options.today ? `${day}T00:00:00.000Z` : new Date().toISOString(),
+      package: {
+        name: rootPkg.name,
+        version,
+        tarball: tarballName,
+        sha256: tarballSha256,
+        bytes: fs.statSync(tarball.file).size,
+      },
+      marketContract: { source: 'market-contract', files: listFiles(path.join(kit, 'market-contract')).length },
+      contents,
+    }
+    fs.writeFileSync(path.join(kit, 'OFFLINE-KIT.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+
+    fs.mkdirSync(path.dirname(outFile), { recursive: true })
+    makeTar(kit, outFile)
+    const bytes = fs.statSync(outFile).size
+    console.log(JSON.stringify({
+      out: outFile,
+      bytes,
+      sha256: sha256File(outFile),
+      kit: { version, package: tarballName, files: contents.length + 1 },
+      marketContract,
+      tarball: { file: tarball.file, sha256: tarballSha256, bytes: manifest.package.bytes },
+    }, null, 2))
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true })
+    if (tarball.packDir) fs.rmSync(tarball.packDir, { recursive: true, force: true })
+  }
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(`build-offline-kit: ${error.message}`)
+  process.exitCode = 3
+}