dsh-standards 0.0.2 → 1.0.0

package/40-checker/scripts/dco-check.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * dco-check.mjs — enforce DCO 1.1 sign-off and the DSH contribution terms.
+ *
+ * Rules:
+ *   1. every commit has at least one `Signed-off-by: Name <email>`;
+ *   2. the author email matches one of the sign-off emails;
+ *   3. `AI-Assisted: yes` requires `AI-Tool:` and a human sign-off;
+ *   4. with --require-terms, at least one commit carries `DSH-Contribution: dsh-ct/1`
+ *      or the PR body contains the terms checkbox.
+ *
+ * This checks attestations, not identity. It cannot verify legal capacity,
+ * employment, or patent status.
+ *
+ * Usage:
+ *   node 40-checker/scripts/dco-check.mjs --range origin/main..HEAD --require-terms --pr-body-env PR_BODY
+ *   node 40-checker/scripts/dco-check.mjs --range HEAD~1..HEAD --json
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const DEFAULT_ROOT = path.resolve(HERE, '..', '..')
+const TERMS = 'dsh-ct/1'
+
+export function parseLog(text) {
+  return text
+    .split('\x1e')
+    .map((record) => record.trim())
+    .filter(Boolean)
+    .map((record) => {
+      const [sha, authorName, authorEmail, ...rest] = record.split('\x1f')
+      return { sha: (sha || '').trim(), authorName: authorName || '', authorEmail: authorEmail || '', body: rest.join('\x1f') }
+    })
+}
+
+export function checkCommit(commit) {
+  const errors = []
+  const warnings = []
+  const body = commit.body || ''
+  const signoffs = [...body.matchAll(/^Signed-off-by:\s*(.+?)\s*<([^>]+)>\s*$/gim)]
+    .map((m) => ({ name: m[1].trim(), email: m[2].trim().toLowerCase() }))
+  if (signoffs.length === 0) {
+    errors.push(`${commit.sha.slice(0, 8)}: missing Signed-off-by`)
+  } else {
+    const emails = new Set(signoffs.map((s) => s.email))
+    if (commit.authorEmail && !emails.has(commit.authorEmail.toLowerCase())) {
+      errors.push(`${commit.sha.slice(0, 8)}: author email ${commit.authorEmail} is not among the sign-offs`)
+    }
+  }
+  const aiAssisted = /^AI-Assisted:\s*yes\s*$/im.test(body) || /^AI-Generated:\s*yes\s*$/im.test(body)
+  if (aiAssisted) {
+    if (!/^AI-Tool:\s*\S+/im.test(body)) errors.push(`${commit.sha.slice(0, 8)}: AI-Assisted without AI-Tool`)
+    const human = signoffs.some((s) => !/\bbot\b|\[bot\]/i.test(s.name))
+    if (!human) errors.push(`${commit.sha.slice(0, 8)}: AI-Assisted needs a human sign-off`)
+  }
+  const terms = /^(?:DSH-Contribution|Contribution-Agreement):\s*dsh-ct\/1\s*$/im.test(body)
+  const entity = /^Entity-CLA:\s*(\S+)\s*$/im.exec(body)
+  const onBehalf = /^On-Behalf-Of:\s*(.+?)\s*$/im.exec(body)
+  const agent = /^AI-Agent:\s*(\S+)\s*$/im.exec(body)
+  if (onBehalf && !entity) warnings.push(`${commit.sha.slice(0, 8)}: On-Behalf-Of present; verify the Entity CLA manually`)
+  return {
+    sha: commit.sha,
+    errors,
+    warnings,
+    terms,
+    entityCla: entity ? entity[1] : null,
+    onBehalfOf: onBehalf ? onBehalf[1] : null,
+    aiAgent: agent ? agent[1] : null,
+  }
+}
+
+export function checkTerms({ commits, prBody, requireTerms }) {
+  if (!requireTerms) return { errors: [], warnings: [] }
+  const fromCommit = commits.some((c) => /^(?:DSH-Contribution|Contribution-Agreement):\s*dsh-ct\/1\s*$/im.test(c.body || ''))
+  const fromPr = /\[[xX]\]\s*I agree to the DSH Contribution Terms v1/i.test(prBody || '')
+    || /dsh-ct\/1/i.test(prBody || '')
+  if (!fromCommit && !fromPr) {
+    return { errors: ['no DSH Contribution Terms acceptance: add the PR checkbox or DSH-Contribution: dsh-ct/1'], warnings: [] }
+  }
+  return { errors: [], warnings: [] }
+}
+
+export function run({ root = DEFAULT_ROOT, range = 'HEAD~1..HEAD', prBody = '', requireTerms = false } = {}) {
+  const result = spawnSync('git', ['-C', root, 'log', '--format=%H%x1f%an%x1f%ae%x1f%B%x1e', range], { encoding: 'utf8' })
+  if (result.status !== 0) {
+    return { ok: false, errors: [`git log failed: ${(result.stderr || '').trim()}`], warnings: [], commits: [] }
+  }
+  const commits = parseLog(result.stdout)
+  if (commits.length === 0) {
+    return { ok: false, errors: [`no commits in range ${range}`], warnings: [], commits: [] }
+  }
+  const errors = []
+  const warnings = []
+  const checked = commits.map((commit) => {
+    const r = checkCommit(commit)
+    errors.push(...r.errors)
+    warnings.push(...r.warnings)
+    return { sha: commit.sha, terms: r.terms, entityCla: r.entityCla, aiAgent: r.aiAgent }
+  })
+  const terms = checkTerms({ commits, prBody, requireTerms })
+  errors.push(...terms.errors)
+  warnings.push(...terms.warnings)
+  if (checked.some((c) => c.entityCla)) warnings.push('Entity-CLA trailer present; verify the archived document manually')
+  return { ok: errors.length === 0, errors, warnings, commits: checked }
+}
+
+export function main(argv = process.argv.slice(2)) {
+  let root = DEFAULT_ROOT
+  let range = 'HEAD~1..HEAD'
+  let prBody = ''
+  let prBodyEnv = null
+  let requireTerms = false
+  let json = false
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--root') root = path.resolve(argv[++i])
+    else if (arg === '--range') range = argv[++i]
+    else if (arg === '--pr-body') prBody = fs.readFileSync(argv[++i], 'utf8')
+    else if (arg === '--pr-body-env') prBodyEnv = argv[++i]
+    else if (arg === '--require-terms') requireTerms = true
+    else if (arg === '--json') json = true
+    else if (arg === '--help' || arg === '-h') {
+      console.log('usage: dco-check.mjs [--root <dir>] [--range <git-range>] [--pr-body <file>] [--pr-body-env <ENV>] [--require-terms] [--json]')
+      return 0
+    } else {
+      console.error(`unknown argument: ${arg}`)
+      return 2
+    }
+  }
+  if (prBodyEnv) prBody = process.env[prBodyEnv] || ''
+  const result = run({ root, range, prBody, requireTerms })
+  if (json) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    for (const warning of result.warnings) console.log(`WARN ${warning}`)
+    for (const error of result.errors) console.log(`FAIL ${error}`)
+    console.log(`${result.ok ? 'PASS' : 'FAIL'} dco: ${result.commits.length} commit(s), ${result.errors.length} error(s), ${result.warnings.length} warning(s)`)
+  }
+  return result.ok ? 0 : 2
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = main()
+}

package/40-checker/scripts/dependabot-check.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * dependabot-check.mjs — enforce the owner policy: no Dependabot in this repo.
+ *
+ * Fails when `.github/dependabot.yml`/`.yaml` exists, or when a workflow still
+ * references Dependabot (for example an auto-merge job). The policy is recorded
+ * in `46`/`51`; this script makes it machine-checkable.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const ROOT = path.resolve(HERE, '..', '..')
+const errors = []
+
+for (const name of ['dependabot.yml', 'dependabot.yaml']) {
+  const file = path.join(ROOT, '.github', name)
+  if (fs.existsSync(file)) errors.push(`found ${path.relative(ROOT, file)}`)
+}
+
+const workflows = path.join(ROOT, '.github', 'workflows')
+if (fs.existsSync(workflows)) {
+  for (const name of fs.readdirSync(workflows)) {
+    if (!/\.ya?ml$/.test(name)) continue
+    const text = fs.readFileSync(path.join(workflows, name), 'utf8')
+    // Only automation references count. The policy guard itself lives in a
+    // workflow and must not trip this check.
+    if (/dependabot\[bot\]|dependabot\/fetch-metadata|dependabot-auto-merge|dependabot\/merge|dependabot\/.*action/i.test(text)) {
+      errors.push(`workflow ${name} references Dependabot automation`)
+    }
+  }
+}
+
+if (errors.length) {
+  for (const error of errors) console.error(`FAIL dependabot: ${error}`)
+  console.error(`FAIL dependabot: ${errors.length} error(s); owner policy is no Dependabot`)
+  process.exit(1)
+}
+console.log('PASS dependabot: no config or automation reference')

package/40-checker/scripts/doc-commands-check.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * doc-commands-check.mjs — keep the developer path first-party and runnable.
+ *
+ * Two checks:
+ *   1. Current developer docs must not send readers to `npx dsh-levels`,
+ *      `npx dsh-plugin-kit`, or `npx dsh-plugin-verify`; those bare npm names
+ *      belong to other projects, not this repository.
+ *   2. The first-party template in `examples/plugin-template` must still audit
+ *      to a non-`not-run` ENTRY state.
+ *
+ * This is a documentation/CLI guard, not a runtime or security claim.
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const STANDARDS = path.resolve(HERE, '..', '..')
+const DOCS = [
+  '45-三用途落地-官方市场开发者.md',
+  ...fs.readdirSync(path.join(STANDARDS, 'adoption', 'developer'))
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => path.join('adoption', 'developer', name)),
+]
+const FORBIDDEN = [
+  { re: /\bnpx\s+dsh-levels\b/, name: 'npx dsh-levels' },
+  { re: /\bnpx\s+dsh-plugin-kit\b/, name: 'npx dsh-plugin-kit' },
+  { re: /\bnpx\s+dsh-plugin-verify\b/, name: 'npx dsh-plugin-verify' },
+]
+
+let errors = 0
+for (const rel of DOCS) {
+  const text = fs.readFileSync(path.join(STANDARDS, rel), 'utf8')
+  const lines = text.split(/\r?\n/)
+  let inFence = false
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence
+      continue
+    }
+    if (!inFence) continue
+    for (const rule of FORBIDDEN) {
+      if (rule.re.test(line)) {
+        console.error(`FAIL ${rel}:${index + 1}: ${rule.name} resolves to a third-party npm package`)
+        errors += 1
+      }
+    }
+  }
+}
+if (errors === 0) console.log(`PASS docs: 0 third-party npx command(s) in ${DOCS.length} file(s)`)
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-doc-commands-'))
+try {
+  const out = path.join(tmp, 'audit.json')
+  const run = spawnSync(process.execPath, [
+    path.join(STANDARDS, '40-checker', 'bin', 'dsh-levels.mjs'),
+    'audit',
+    path.join(STANDARDS, 'examples', 'plugin-template'),
+    '--format', 'json',
+    '--out', out,
+  ], { encoding: 'utf8' })
+
+  if (run.status !== 0) {
+    console.error(`FAIL template: dsh-levels audit exited ${run.status}`)
+    if (run.stderr) console.error(run.stderr.trim())
+    errors += 1
+  } else {
+    const report = JSON.parse(fs.readFileSync(out, 'utf8'))
+    const state = report?.levels?.entry?.state
+    if (!['recognized', 'static', 'runtime'].includes(state)) {
+      console.error(`FAIL template: ENTRY state is ${JSON.stringify(state)}, expected recognized/static/runtime`)
+      errors += 1
+    } else {
+      console.log(`PASS template: ENTRY state=${state}`)
+    }
+  }
+} catch (error) {
+  console.error(`FAIL template check: ${error.message}`)
+  errors += 1
+} finally {
+  fs.rmSync(tmp, { recursive: true, force: true })
+}
+
+if (errors > 0) {
+  console.error(`FAIL doc-commands: ${errors} error(s)`)
+  process.exit(1)
+}
+console.log('PASS doc-commands: first-party developer path is runnable')

package/40-checker/scripts/entry-scan.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * entry-scan.mjs — read-only C1-C8 scan of public GitHub plugins.
+ *
+ * It fetches package.json and checks that the referenced patch/client/entry
+ * files exist via the GitHub contents API. It stores only package.json and
+ * placeholder files; it never executes plugin code. C3 is left not-run because
+ * a real install line was not tested on a host.
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const STD = path.resolve(HERE, '..', '..')
+const VALIDATOR = path.join(STD, '40-checker', 'scripts', 'entry-validate.mjs')
+const TOKEN = process.env.GH_TOKEN
+if (!TOKEN) throw new Error('GH_TOKEN is required')
+
+const headers = {
+  Authorization: `Bearer ${TOKEN}`,
+  Accept: 'application/vnd.github+json',
+  'User-Agent': 'dsh-entry-scan',
+  'X-GitHub-Api-Version': '2022-11-28',
+}
+
+function usage() {
+  console.log(`entry-scan — static C1-C8 scan of public DSH plugins
+
+Usage:
+  node 40-checker/scripts/entry-scan.mjs [--limit 10] [--out report.json] [--repos owner/repo,...]
+
+Without --repos, searches GitHub topic:dsh-plugin sorted by stars.
+It writes only package.json and placeholder files in a temp directory; no plugin code is executed.
+C3 is not-run because no real install line is tested.
+Exit: 0 scan completed, 3 input/API error.`)
+}
+
+function parseArgs(argv) {
+  const options = { limit: 10, out: null, repos: 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 === '--limit') options.limit = Number(next())
+    else if (arg === '--out') options.out = path.resolve(next())
+    else if (arg === '--repos') options.repos = next().split(',').map(s => s.trim()).filter(Boolean)
+    else if (arg === '--help' || arg === '-h') { usage(); process.exit(0) }
+    else throw new Error(`unknown argument: ${arg}`)
+  }
+  if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 30) throw new Error('--limit must be 1..30')
+  return options
+}
+
+async function api(pathname) {
+  const r = await fetch(`https://api.github.com${pathname}`, { headers })
+  if (r.status === 404) return { ok: false, status: 404, json: null }
+  const text = await r.text()
+  let json = null
+  try { json = JSON.parse(text) } catch { json = { raw: text } }
+  if (!r.ok) throw new Error(`${pathname} -> ${r.status}: ${text.slice(0, 300)}`)
+  return { ok: true, status: r.status, json }
+}
+
+async function fileExists(repo, ref, file) {
+  if (typeof file !== 'string' || file.length === 0) return false
+  const clean = file.replace(/^\.\//, '')
+  const encoded = clean.split('/').map(encodeURIComponent).join('/')
+  const r = await api(`/repos/${repo}/contents/${encoded}?ref=${encodeURIComponent(ref)}`)
+  return r.ok
+}
+
+function writePlaceholder(dir, file) {
+  const clean = file.replace(/^\.\//, '')
+  const full = path.resolve(dir, clean)
+  if (!full.startsWith(`${dir}${path.sep}`)) return
+  fs.mkdirSync(path.dirname(full), { recursive: true })
+  fs.writeFileSync(full, '// existence verified via GitHub contents API; content not stored\n')
+}
+
+async function scanRepo(repo, meta) {
+  const pkgRes = await api(`/repos/${repo}/contents/package.json?ref=${encodeURIComponent(meta.default_branch)}`)
+  if (!pkgRes.ok) return null
+  const pkg = JSON.parse(Buffer.from(pkgRes.json.content, 'base64').toString('utf8'))
+  if (!pkg.dsh || typeof pkg.dsh !== 'object') return null
+  if (!pkg.dsh.bundle && !pkg.dsh.client) return null
+  const commitRes = await api(`/repos/${repo}/commits?per_page=1`)
+  const commit = commitRes.json?.[0]?.sha ?? null
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-entry-scan-'))
+  try {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(pkg, null, 2))
+    const files = []
+    if (typeof pkg.dsh.bundle?.patch === 'string') files.push(pkg.dsh.bundle.patch)
+    else if (Array.isArray(pkg.dsh.bundle?.patch)) files.push(...pkg.dsh.bundle.patch.filter(item => typeof item === 'string'))
+    if (pkg.dsh.client) {
+      const client = typeof pkg.exports?.['./client'] === 'string'
+        ? pkg.exports['./client']
+        : pkg.exports?.['./client']?.import ?? pkg.exports?.['./client']?.default
+      if (typeof client === 'string') files.push(client)
+    }
+    const main = typeof pkg.main === 'string' ? pkg.main : typeof pkg.exports?.['.'] === 'string' ? pkg.exports['.'] : pkg.exports?.['.']?.import
+    if (typeof main === 'string') files.push(main)
+    const paths = new Set()
+    const treeRes = await api(`/repos/${repo}/git/trees/${encodeURIComponent(meta.default_branch)}?recursive=1`)
+    if (treeRes.ok && Array.isArray(treeRes.json.tree)) {
+      for (const item of treeRes.json.tree) paths.add(item.path)
+    }
+    for (const file of [...new Set(files)]) {
+      const clean = file.replace(/^\.\//, '')
+      if (paths.has(clean) || (!treeRes.ok && await fileExists(repo, meta.default_branch, file))) {
+        writePlaceholder(dir, file)
+      }
+    }
+    const metaFile = path.join(dir, 'meta.json')
+    fs.writeFileSync(metaFile, JSON.stringify({
+      repo,
+      topics: meta.topics ?? [],
+      archived: meta.archived === true,
+      commit,
+      pushedAt: String(meta.pushed_at ?? '').slice(0, 10),
+      claimLevel: 'reference',
+    }, null, 2))
+    const run = spawnSync(process.execPath, [VALIDATOR, dir, '--meta', metaFile, '--json'], { encoding: 'utf8', timeout: 30_000 })
+    const result = JSON.parse(run.stdout)
+    return {
+      repo,
+      stars: meta.stargazers_count,
+      package: pkg.name ?? null,
+      version: pkg.version ?? null,
+      filesChecked: [...new Set(files)],
+      conclusion: result.conclusion,
+      checks: result.checks,
+      exit: run.status,
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  let repos = options.repos
+  if (!repos) {
+    const search = await api(`/search/repositories?q=${encodeURIComponent('topic:dsh-plugin')}&sort=stars&order=desc&per_page=30`)
+    repos = (search.json.items ?? []).map(item => item.full_name)
+  }
+  const scanned = []
+  for (const repo of repos) {
+    if (scanned.length >= options.limit) break
+    const r = await api(`/repos/${repo}`)
+    if (!r.ok) continue
+    const row = await scanRepo(repo, r.json)
+    if (row) {
+      scanned.push(row)
+      console.log(`${repo}: ${row.conclusion.status}; ${row.conclusion.failed.join(',') || 'no fail'}${row.conclusion.notRun.length ? `; not-run ${row.conclusion.notRun.join(',')}` : ''}`)
+    }
+  }
+  const report = {
+    schema: 'dsh-entry-scan/1',
+    generatedAt: new Date().toISOString(),
+    method: 'static GitHub contents API; C3 not-run; no plugin code executed; file existence only for patch/client/main',
+    disclaimer: '非官方 · 非认证 · 非安全审计 · 非背书 · 无担保',
+    notClaimed: ['official standard', 'certification', 'security audit', 'ranking', 'market acceptance', 'external adoption'],
+    total: scanned.length,
+    summary: {
+      pass: scanned.filter(r => r.conclusion.status === 'pass').length,
+      passWithWarnings: scanned.filter(r => r.conclusion.status === 'pass-with-warnings').length,
+      incomplete: scanned.filter(r => r.conclusion.status === 'incomplete').length,
+      fail: scanned.filter(r => r.conclusion.status === 'fail').length,
+    },
+    repos: scanned,
+  }
+  const output = `${JSON.stringify(report, null, 2)}\n`
+  if (options.out) {
+    fs.mkdirSync(path.dirname(options.out), { recursive: true })
+    fs.writeFileSync(options.out, output)
+    console.log(`wrote ${options.out}`)
+  } else process.stdout.write(output)
+}
+
+main().catch(error => {
+  console.error(`entry-scan: ${error.message}`)
+  process.exit(3)
+})