dsh-standards 0.0.3 → 1.0.1

package/40-checker/scripts/round-robin.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * round-robin.mjs — compare two independent runs against frozen known answers.
+ *
+ * A comparison is `comparable: true` only when:
+ *   - both runs produced a real status (not not-run/blocked/error);
+ *   - both statuses match the frozen expected status;
+ *   - the two runners are not the same identifier.
+ *
+ * Two machines both returning `not-run` prove nothing. It is not a proficiency
+ * test and not an accreditation.
+ *
+ * Usage:
+ *   node 40-checker/scripts/round-robin.mjs --a runner-a.json --b runner-b.json \
+ *     --expected 40-checker/fixtures/known-answer/expected.json --out rounds/2026Q4.json
+ */
+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 REAL = new Set(['pass', 'warn', 'fail', 'recognized', 'runtime', 'static', 'measured', 'manual'])
+
+export function compare({ a, b, expected }) {
+  const rows = []
+  const ids = new Set([...Object.keys(expected), ...Object.keys(a.results || {}), ...Object.keys(b.results || {})])
+  for (const id of [...ids].sort()) {
+    const ae = a.results?.[id]
+    const be = b.results?.[id]
+    const exp = expected[id]
+    const aStatus = ae?.status ?? 'missing'
+    const bStatus = be?.status ?? 'missing'
+    const ignored = exp?.ignored === true
+    const comparable = ignored ? true : Boolean(
+      exp && REAL.has(aStatus) && REAL.has(bStatus) &&
+      aStatus === bStatus && aStatus === exp.expected &&
+      a.runner !== b.runner,
+    )
+    const problems = []
+    if (!exp) problems.push('no frozen expected status')
+    if (!REAL.has(aStatus)) problems.push(`runner A status ${aStatus}`)
+    if (!REAL.has(bStatus)) problems.push(`runner B status ${bStatus}`)
+    if (aStatus !== bStatus) problems.push(`status mismatch: ${aStatus} vs ${bStatus}`)
+    if (a.runner === b.runner) problems.push('same runner identifier; not independent')
+    rows.push({ id, expected: exp?.expected ?? null, ignored, a: aStatus, b: bStatus, comparable, problems })
+  }
+  return {
+    schema: 'dsh-round-robin/1',
+    generatedAt: new Date().toISOString(),
+    a: { runner: a.runner, anchor: a.anchor ?? null },
+    b: { runner: b.runner, anchor: b.anchor ?? null },
+    comparable: rows.length > 0 && rows.every((r) => r.comparable),
+    rows,
+    note: 'Known-answer comparison only; not a proficiency test, not an accreditation, not a certification.',
+  }
+}
+
+function read(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+export function main(argv = process.argv.slice(2)) {
+  let a = null
+  let b = null
+  let expected = null
+  let out = path.join(ROOT, 'rounds', '2026Q4.json')
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--a') a = path.resolve(argv[++i])
+    else if (argv[i] === '--b') b = path.resolve(argv[++i])
+    else if (argv[i] === '--expected') expected = path.resolve(argv[++i])
+    else if (argv[i] === '--out') out = path.resolve(argv[++i])
+    else if (argv[i] === '--help' || argv[i] === '-h') { console.log('usage: round-robin.mjs --a <json> --b <json> --expected <json> [--out <file>]'); return 0 }
+    else { console.error(`unknown argument: ${argv[i]}`); return 2 }
+  }
+  if (!a || !b || !expected) { console.error('--a, --b, --expected are required'); return 2 }
+  const report = compare({ a: read(a), b: read(b), expected: read(expected) })
+  fs.mkdirSync(path.dirname(out), { recursive: true })
+  fs.writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`)
+  for (const row of report.rows) console.log(`${row.comparable ? 'PASS' : 'FAIL'} ${row.id}: expected=${row.expected} a=${row.a} b=${row.b}${row.problems.length ? ` (${row.problems.join('; ')})` : ''}`)
+  console.log(`${report.comparable ? 'PASS' : 'FAIL'} comparable=${report.comparable}; wrote ${path.relative(ROOT, out)}`)
+  return report.comparable ? 0 : 2
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = main()
+}

package/40-checker/scripts/sample-frame.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Build a reproducible sampling frame from the official dsh-plugin topic.
+ * This is a frame, not a pass/fail result: sampled repos may not be installable.
+ *
+ * Usage: node scripts/sample-frame.mjs [--out samples/frame.json] [--seed 20261031]
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(name)
+  return i >= 0 ? process.argv[i + 1] : fallback
+}
+const out = path.resolve(arg('--out', 'samples/frame.json'))
+const seed = Number(arg('--seed', '20261031'))
+const headers = { Accept: 'application/vnd.github+json', 'User-Agent': 'dsh-plugin-conformance' }
+if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`
+
+async function search(q, sort, order, page = 1, perPage = 100) {
+  const url = `https://api.github.com/search/repositories?q=${encodeURIComponent(q)}&sort=${sort}&order=${order}&per_page=${perPage}&page=${page}`
+  const res = await fetch(url, { headers })
+  if (!res.ok) throw new Error(`GitHub ${res.status}: ${(await res.text()).slice(0, 200)}`)
+  return res.json()
+}
+
+function hash(text) {
+  let h = 2166136261
+  for (const ch of text) { h ^= ch.charCodeAt(0); h = Math.imul(h, 16777619) }
+  return h >>> 0
+}
+
+async function main() {
+  const high = []
+  for (let page = 1; page <= 3; page += 1) {
+    const data = await search('topic:dsh-plugin stars:>50 size:<50000', 'stars', 'desc', page)
+    high.push(...data.items)
+  }
+  const low = []
+  for (let page = 1; page <= 2; page += 1) {
+    const data = await search('topic:dsh-plugin stars:1..50 size:<50000', 'stars', 'asc', page)
+    low.push(...data.items)
+  }
+  const pool = [...new Map([...high, ...low].map(repo => [repo.full_name, repo])).values()]
+  const pick = (items, n) => items.slice().sort((a, b) => hash(`${seed}:${a.full_name}`) - hash(`${seed}:${b.full_name}`)).slice(0, n)
+  const sample = pick(pool, 60)
+  const lowSample = pick(low, 20)
+  const result = {
+    schema: 'dsh-plugin-sample/1',
+    generatedAt: new Date().toISOString(),
+    source: 'GitHub search: topic:dsh-plugin',
+    query: { high: 'topic:dsh-plugin stars:>50 size:<50000', low: 'topic:dsh-plugin stars:1..50 size:<50000' },
+    seed,
+    frameSize: pool.length,
+    sampleSize: sample.length,
+    lowStarSize: lowSample.length,
+    sample: sample.map(repo => ({ fullName: repo.full_name, url: repo.html_url, stars: repo.stargazers_count, updatedAt: repo.updated_at })),
+    lowStar: lowSample.map(repo => ({ fullName: repo.full_name, url: repo.html_url, stars: repo.stargazers_count })),
+    negativeControls: [
+      'fixtures/negative/no-entry',
+      'fixtures/negative/no-patch',
+      'fixtures/negative/workspace-version',
+      'fixtures/negative/official-label',
+      'fixtures/negative/stale-result',
+    ],
+    caveat: 'Frame only. A sampled repo may be a listing/monorepo/no-plugin; not a pass/fail result.',
+  }
+  fs.mkdirSync(path.dirname(out), { recursive: true })
+  fs.writeFileSync(out, `${JSON.stringify(result, null, 2)}\n`)
+  console.log(`frame=${result.frameSize} sample=${result.sampleSize} low=${result.lowStarSize} -> ${out}`)
+}
+main().catch(error => { console.error(`sample-frame: ${error.message}`); process.exitCode = 3 })

package/40-checker/scripts/sample20-ci.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/** CI runner: clone 60 frame repos and run ENTRY static. */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+const STD = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..')
+const frame = JSON.parse(fs.readFileSync(path.join(STD, '40-checker/samples/frame.json'), 'utf8'))
+const out = path.join(STD, 'results/sample20-ci')
+fs.rmSync(out, { recursive: true, force: true }); fs.mkdirSync(out, { recursive: true })
+const rows = []
+for (const repo of frame.lowStar) {
+  const id = repo.fullName.replace(/[\\/]/g, '__')
+  const dir = path.join('/tmp/dsh-sample20-ci', id)
+  const clone = spawnSync('git', ['clone', '--depth', '1', `https://github.com/${repo.fullName}.git`, dir], { encoding: 'utf8', timeout: 120000 })
+  if (clone.status !== 0) { rows.push({ id, fullName: repo.fullName, clone: 'fail', error: (clone.stderr || '').slice(-200) }); continue }
+  const json = path.join(out, `${id}.json`)
+  const run = spawnSync('node', [path.join(STD, '40-checker/bin/dsh-plugin-verify.mjs'), dir, '--scope', 'entry', '--entry-claim', 'static', '--format', 'json', '--out', json], { encoding: 'utf8', timeout: 30000 })
+  let status = 'error', level = null
+  try { const r = JSON.parse(fs.readFileSync(json, 'utf8')); status = r.conclusion.status; level = r.conclusion.level } catch {}
+  rows.push({ id, fullName: repo.fullName, stars: repo.stars, clone: 'ok', status, level, exit: run.status })
+  fs.rmSync(dir, { recursive: true, force: true })
+}
+const summary = { schema: 'dsh-sample20-ci/1', generatedAt: new Date().toISOString(), frame: frame.lowStarSize, rows, status: { pass: rows.filter(r => r.status === 'pass').length, warn: rows.filter(r => r.status === 'warn').length, fail: rows.filter(r => r.status === 'fail').length, incomplete: rows.filter(r => r.status === 'incomplete').length, cloneFail: rows.filter(r => r.clone !== 'ok').length, error: rows.filter(r => r.status === 'error').length } }
+fs.writeFileSync(path.join(out, 'summary.json'), JSON.stringify(summary, null, 2) + '\n')
+console.log(JSON.stringify(summary.status))

package/40-checker/scripts/sample60-ci.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/** CI runner: clone 60 frame repos and run ENTRY static. */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+const STD = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..')
+const frame = JSON.parse(fs.readFileSync(path.join(STD, '40-checker/samples/frame.json'), 'utf8'))
+const out = path.join(STD, 'results/sample60-ci')
+fs.rmSync(out, { recursive: true, force: true }); fs.mkdirSync(out, { recursive: true })
+const rows = []
+for (const repo of frame.sample) {
+  const id = repo.fullName.replace(/[\\/]/g, '__')
+  const dir = path.join('/tmp/dsh-sample60-ci', id)
+  const clone = spawnSync('git', ['clone', '--depth', '1', `https://github.com/${repo.fullName}.git`, dir], { encoding: 'utf8', timeout: 120000 })
+  if (clone.status !== 0) { rows.push({ id, fullName: repo.fullName, clone: 'fail', error: (clone.stderr || '').slice(-200) }); continue }
+  const json = path.join(out, `${id}.json`)
+  const run = spawnSync('node', [path.join(STD, '40-checker/bin/dsh-plugin-verify.mjs'), dir, '--scope', 'entry', '--entry-claim', 'static', '--format', 'json', '--out', json], { encoding: 'utf8', timeout: 30000 })
+  let status = 'error', level = null
+  try { const r = JSON.parse(fs.readFileSync(json, 'utf8')); status = r.conclusion.status; level = r.conclusion.level } catch {}
+  rows.push({ id, fullName: repo.fullName, stars: repo.stars, clone: 'ok', status, level, exit: run.status })
+  fs.rmSync(dir, { recursive: true, force: true })
+}
+const summary = { schema: 'dsh-sample60-ci/1', generatedAt: new Date().toISOString(), frame: frame.sampleSize, rows, status: { pass: rows.filter(r => r.status === 'pass').length, warn: rows.filter(r => r.status === 'warn').length, fail: rows.filter(r => r.status === 'fail').length, incomplete: rows.filter(r => r.status === 'incomplete').length, cloneFail: rows.filter(r => r.clone !== 'ok').length, error: rows.filter(r => r.status === 'error').length } }
+fs.writeFileSync(path.join(out, 'summary.json'), JSON.stringify(summary, null, 2) + '\n')
+console.log(JSON.stringify(summary.status))

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

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * stale-check.mjs — recompute expiry in the reader's clock.
+ *
+ * The writer's `status: active` is not trusted. If `expiresAt` is in the past,
+ * the effective status is `expired` (and the display must show `stale`).
+ *
+ * Usage:
+ *   node 40-checker/scripts/stale-check.mjs [--index publish/attestations/index.json] [--now 2027-01-01] [--json]
+ */
+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 DEFAULT_INDEX = path.join(ROOT, 'publish', 'attestations', 'index.json')
+
+export function effective(entry, now = new Date()) {
+  const expires = Date.parse(`${entry.expiresAt}T23:59:59Z`)
+  const expired = Number.isFinite(expires) && expires < now.getTime()
+  if (entry.status === 'withdrawn') return { status: 'withdrawn', stale: true, reason: 'withdrawn' }
+  if (entry.status === 'expired' || expired) return { status: 'expired', stale: true, reason: expired ? 'expiresAt passed' : 'declared expired' }
+  if (entry.status === 'draft') return { status: 'draft', stale: false, reason: 'draft is not valid' }
+  return { status: entry.status, stale: false, reason: 'within validity' }
+}
+
+export function checkIndex(index, now = new Date()) {
+  const results = []
+  for (const entry of index.attestations || []) {
+    results.push({ attestationId: entry.attestationId, declared: entry.status, expiresAt: entry.expiresAt, ...effective(entry, now) })
+  }
+  return { checkedAt: now.toISOString(), results, stale: results.filter((r) => r.stale).length }
+}
+
+export function main(argv = process.argv.slice(2)) {
+  let index = DEFAULT_INDEX
+  let now = new Date()
+  let json = false
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--index') index = path.resolve(argv[++i])
+    else if (argv[i] === '--now') now = new Date(`${argv[++i]}T00:00:00Z`)
+    else if (argv[i] === '--json') json = true
+    else if (argv[i] === '--help' || argv[i] === '-h') { console.log('usage: stale-check.mjs [--index <file>] [--now YYYY-MM-DD] [--json]'); return 0 }
+    else { console.error(`unknown argument: ${argv[i]}`); return 2 }
+  }
+  if (!fs.existsSync(index)) { console.error(`index not found: ${index}`); return 2 }
+  const result = checkIndex(JSON.parse(fs.readFileSync(index, 'utf8')), now)
+  if (json) console.log(JSON.stringify(result, null, 2))
+  else {
+    for (const row of result.results) console.log(`${row.attestationId} declared=${row.declared} effective=${row.status}${row.stale ? ' STALE' : ''} — ${row.reason}`)
+    console.log(`${result.stale} stale/expired record(s) at ${result.checkedAt}`)
+  }
+  return result.stale > 0 ? 2 : 0
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = main()
+}

package/40-checker/scripts/surveillance.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * surveillance.mjs — quarterly read-only check of published attestations.
+ *
+ * It checks: ID uniqueness, expiresAt, declared status, verifyUrl, and evidence
+ * links (existence only unless --online). It does not punish, delist, or revoke.
+ *
+ * Usage:
+ *   node 40-checker/scripts/surveillance.mjs [--now 2027-01-01] [--out surveillance/2026Q4.json] [--online]
+ */
+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 INDEX = path.join(ROOT, 'publish', 'attestations', 'index.json')
+
+export function inspect(index, now = new Date(), { online = false } = {}) {
+  const issues = []
+  const records = []
+  const seen = new Set()
+  for (const entry of index.attestations || []) {
+    const record = { attestationId: entry.attestationId, status: entry.status, expiresAt: entry.expiresAt, issues: [] }
+    if (seen.has(entry.attestationId)) record.issues.push('duplicate attestationId')
+    seen.add(entry.attestationId)
+    if (!/^DSH-ATT-\d{4}-\d{3}$/.test(entry.attestationId || '')) record.issues.push('bad attestationId')
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.expiresAt || '')) record.issues.push('bad expiresAt')
+    else if (Date.parse(`${entry.expiresAt}T23:59:59Z`) < now.getTime()) record.issues.push('expired')
+    if (!/^https:\/\//.test(entry.verifyUrl || '')) record.issues.push('verifyUrl must be https')
+    if (!entry.claimLevel) record.issues.push('claimLevel missing')
+    if (record.issues.length > 0) issues.push({ attestationId: entry.attestationId, issues: record.issues })
+    records.push(record)
+  }
+  return {
+    schema: 'dsh-surveillance/1',
+    generatedAt: now.toISOString(),
+    checked: records.length,
+    issues,
+    records,
+    online,
+    note: 'Read-only. No delisting, no punishment, no security judgement.',
+  }
+}
+
+async function checkOnline(records, index, timeoutMs = 5000) {
+  for (const record of records) {
+    const entry = (index.attestations || []).find((item) => item.attestationId === record.attestationId)
+    if (!entry?.verifyUrl) continue
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      const response = await fetch(entry.verifyUrl, { method: 'HEAD', signal: controller.signal, redirect: 'follow' })
+      record.online = { status: response.status, ok: response.ok }
+      if (!response.ok) record.issues.push(`verifyUrl ${response.status}`)
+    } catch (error) {
+      record.online = { status: null, ok: false, error: error.name }
+      record.issues.push(`verifyUrl unreachable: ${error.name}`)
+    } finally { clearTimeout(timer) }
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  let now = new Date()
+  let out = path.join(ROOT, 'surveillance', '2026Q4.json')
+  let online = false
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--now') now = new Date(`${argv[++i]}T00:00:00Z`)
+    else if (argv[i] === '--out') out = path.resolve(argv[++i])
+    else if (argv[i] === '--online') online = true
+    else if (argv[i] === '--help' || argv[i] === '-h') { console.log('usage: surveillance.mjs [--now YYYY-MM-DD] [--out <file>] [--online]'); return 0 }
+    else { console.error(`unknown argument: ${argv[i]}`); return 2 }
+  }
+  const index = JSON.parse(fs.readFileSync(INDEX, 'utf8'))
+  const report = inspect(index, now, { online })
+  if (online) await checkOnline(report.records, index)
+  fs.mkdirSync(path.dirname(out), { recursive: true })
+  fs.writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`)
+  for (const issue of [...report.issues, ...report.records.flatMap((r) => r.issues.map((i) => ({ attestationId: r.attestationId, issues: [i] })))]) {
+    console.log(`WARN ${issue.attestationId}: ${issue.issues.join('; ')}`)
+  }
+  console.log(`${report.issues.length === 0 ? 'PASS' : 'WARN'} surveillance: ${report.checked} record(s), ${report.issues.length} issue group(s); wrote ${path.relative(ROOT, out)}`)
+  return 0
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().then((code) => { process.exitCode = code })
+}