dsh-dbhub-live 5.0.1 → 5.2.0-dev.3

package/scripts/docs-check.mjs

@@ -0,0 +1,214 @@
+// Documentation consistency gate for dsh-dbhub-live.
+//
+// The repository keeps its knowledge in layers: AGENTS.md holds conclusions and
+// points at `doc/` chapters that hold the reasoning. That only works while the
+// pointers are real. This gate makes drift mechanical:
+//
+//   1. every relative markdown link in AGENTS.md and doc/*.md resolves to an
+//      existing file (and, when it carries `#anchor`, to an existing heading);
+//   2. every `doc/` document AGENTS.md links is shipped in package.json `files`
+//      (the package contains AGENTS.md, so its links must not dangle);
+//   3. every shipped `doc/*.md` path in `files` exists on disk;
+//   4. AGENTS.md still points at the impact matrix, and every repo path quoted
+//      in that matrix (doc/IMPACT-MATRIX.md) exists.
+//
+// Usage: npm run check:docs   (exit 0 = consistent, exit 1 = drift)
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, posix, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const ENTRY = 'AGENTS.md'
+const DOC_DIR = 'doc'
+const MATRIX_DOC = 'doc/IMPACT-MATRIX.md'
+
+const findings = []
+const record = (where, message) => findings.push(`${where}: ${message}`)
+
+/** Repository-relative POSIX path for a native path. */
+const toPosix = (p) => p.split(sep).join('/')
+
+/**
+ * GitHub-style heading slug: lowercase, drop HTML and every character that is
+ * not a letter, a number, `-`, `_` or a space, then spaces become hyphens.
+ * @param heading - raw heading text without the leading `#`s.
+ */
+function slugify(heading) {
+  return heading
+    .replace(/<[^>]*>/g, '')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\-_ ]/gu, '')
+    .trim()
+    .replace(/\s+/g, '-')
+}
+
+/** @returns heading slugs of a markdown document. */
+function headingSlugs(text) {
+  const slugs = new Set()
+  for (const line of text.split('\n')) {
+    const match = /^#{1,6}\s+(.*)$/.exec(line.trimEnd())
+    if (!match) continue
+    slugs.add(slugify(match[1].replace(/#+\s*$/, '').trim()))
+  }
+  return slugs
+}
+
+/** @returns markdown links as `{ label, target }`. */
+function markdownLinks(text) {
+  const links = []
+  for (const match of text.matchAll(/\[([^\]]*)\]\(([^)\s]+)\)/g)) {
+    links.push({ label: match[1], target: match[2] })
+  }
+  return links
+}
+
+const fileCache = new Map()
+function readDoc(absPath) {
+  if (!fileCache.has(absPath)) fileCache.set(absPath, readFileSync(absPath, 'utf8'))
+  return fileCache.get(absPath)
+}
+
+// ── 1. link + anchor resolution ──────────────────────────────────────────────
+
+// Local-only drafts are gitignored and never shipped (see package.json `files`
+// and .gitignore), so the gate stays deterministic between a working copy and a
+// clean CI checkout by scanning only documented, distributable documents.
+const LOCAL_DOC_RE = /^(PLAN-.*\.md|implementation-notes\.md|RELEASE-NOTES-.*\.md)$/
+
+const scanned = [ENTRY]
+const docDirAbs = join(ROOT, DOC_DIR)
+if (existsSync(docDirAbs)) {
+  for (const name of readdirSync(docDirAbs)) {
+    if (!name.endsWith('.md') || LOCAL_DOC_RE.test(name)) continue
+    scanned.push(`${DOC_DIR}/${name}`)
+  }
+}
+
+let linkCount = 0
+for (const source of scanned) {
+  const abs = join(ROOT, source)
+  if (!existsSync(abs)) {
+    record(source, 'document is missing')
+    continue
+  }
+  for (const { target } of markdownLinks(readDoc(abs))) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(target)) continue // external URL
+    if (target.startsWith('<')) continue // placeholder
+
+    const [rawPath, anchor] = target.split('#')
+    const sameFile = rawPath === ''
+    const resolved = sameFile
+      ? abs
+      : join(dirname(abs), decodeURIComponent(rawPath))
+    const label = sameFile ? source : `${source} → ${toPosix(relative(ROOT, resolved))}`
+    linkCount += 1
+
+    if (!existsSync(resolved)) {
+      record(source, `link target "${target}" does not exist`)
+      continue
+    }
+    if (statSync(resolved).isDirectory()) continue
+    if (!anchor) continue
+    if (!resolved.endsWith('.md')) {
+      record(source, `link "${target}" carries an anchor but the target is not markdown`)
+      continue
+    }
+    const slugs = headingSlugs(readDoc(resolved))
+    const wanted = decodeURIComponent(anchor).replace(/^#/, '').toLowerCase()
+    if (!slugs.has(wanted)) {
+      record(label, `anchor "${wanted}" matches no heading`)
+    }
+  }
+}
+
+// ── 2 + 3. package.json `files` vs linked docs ───────────────────────────────
+
+const pkgPath = join(ROOT, 'package.json')
+let pkg
+try {
+  pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+} catch (error) {
+  record('package.json', `cannot be parsed (${error.message})`)
+}
+const shipped = new Set(Array.isArray(pkg?.files) ? pkg.files : [])
+
+const linkedDocs = new Set()
+for (const { target } of markdownLinks(readDoc(join(ROOT, ENTRY)))) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target)) continue
+  const clean = target.split('#')[0]
+  if (!clean.endsWith('.md')) continue
+  const normalized = posix.normalize(clean)
+  if (normalized.startsWith(`${DOC_DIR}/`)) linkedDocs.add(normalized)
+}
+for (const doc of linkedDocs) {
+  if (!existsSync(join(ROOT, doc))) {
+    record(ENTRY, `linked document "${doc}" is missing on disk`)
+    continue
+  }
+  if (!shipped.has(doc)) {
+    record(ENTRY, `linked document "${doc}" is not in package.json "files" — the published package would have a dangling link`)
+  }
+}
+for (const entry of shipped) {
+  if (!entry.startsWith(`${DOC_DIR}/`) || !entry.endsWith('.md')) continue
+  if (!existsSync(join(ROOT, entry))) {
+    record('package.json', `"files" lists "${entry}" but the file is missing`)
+  }
+}
+
+// ── 4. the impact matrix: pointed at, present, and honest about paths ───────
+
+const agentsText = readDoc(join(ROOT, ENTRY))
+if (!markdownLinks(agentsText).some(({ target }) => target.split('#')[0] === MATRIX_DOC)) {
+  record(ENTRY, `the reminder pointing at ${MATRIX_DOC} is missing — readers must be told where the impact matrix lives`)
+}
+
+const matrixAbs = join(ROOT, MATRIX_DOC)
+if (!existsSync(matrixAbs)) {
+  record(MATRIX_DOC, 'the impact matrix document is missing')
+} else {
+  const lines = readDoc(matrixAbs).split('\n')
+  const headerIndex = lines.findIndex((line) => line.trim().startsWith('| 改动'))
+  if (headerIndex === -1) {
+    record(MATRIX_DOC, 'the matrix table header "| 改动 |" is missing')
+  } else {
+    // Count only the contiguous table, but validate every table-looking row in
+    // the document: a row appended below the table must not escape the gate.
+    let contiguous = 0
+    for (const line of lines.slice(headerIndex)) {
+      if (!line.trim().startsWith('|')) break
+      contiguous += 1
+    }
+    if (contiguous < 5) record(MATRIX_DOC, `the matrix only has ${contiguous - 2} data row(s) — did it get truncated?`)
+
+    let pathTokens = 0
+    for (const line of lines) {
+      if (!line.trim().startsWith('|')) continue
+      for (const match of line.matchAll(/`([^`]+)`/g)) {
+        const token = match[1].trim()
+        if (token.includes('*') || token.includes('<') || token.includes('|')) continue
+        if (!/\.(md|mjs|cjs|js|json|yml|yaml)$/.test(token)) continue
+        pathTokens += 1
+        if (!existsSync(join(ROOT, token))) {
+          record(MATRIX_DOC, `matrix quotes "${token}" but it does not exist`)
+        }
+      }
+    }
+    if (pathTokens === 0) record(MATRIX_DOC, 'matrix quotes no repository paths — did the table change shape?')
+  }
+}
+
+// ── report ──────────────────────────────────────────────────────────────────
+
+if (findings.length > 0) {
+  console.error(`[check:docs] ${findings.length} problem(s):`)
+  for (const line of findings) console.error(`  - ${line}`)
+  console.error('\n[check:docs] fix the pointers (or the document they point at), then rerun.')
+  process.exit(1)
+}
+
+console.log(
+  `[check:docs] clean: ${scanned.length} document(s), ${linkCount} link(s), ` +
+    `${linkedDocs.size} shipped doc(s) — links, anchors, package contents and the impact matrix agree.`,
+)

package/scripts/release-preflight.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// Release preflight gate.
+//
+// Answers one question, with evidence rather than memory: may this exact commit
+// and version ship? It refuses unless a release test was run recently, against
+// this commit, with this matrix, with no claim drift, and an AI reviewer ruled
+// on it. Designed to be the step you cannot forget: it is wired into the release
+// commands and into a pre-push hook.
+//
+//   node scripts/release-preflight.mjs                 # the newest run
+//   node scripts/release-preflight.mjs --run <dir>     # a specific run
+//   node scripts/release-preflight.mjs --max-age-hours 12 --json
+import path from 'node:path'
+import { REPO_ROOT, readJson } from '../release-test/lib/util.mjs'
+import { run } from '../release-test/lib/proc.mjs'
+import { packageMeta } from '../release-test/lib/artifact.mjs'
+import { gitInfoAsync, dirtyFilesAsync } from '../release-test/lib/git.mjs'
+import { loadMatrix, matrixClaimWarnings, matrixHash } from '../release-test/lib/matrix.mjs'
+import { latestRun, runPath } from '../release-test/lib/runs.mjs'
+import { checkRun } from '../release-test/lib/verdict.mjs'
+import fs from 'node:fs'
+
+const argv = process.argv.slice(2)
+const arg = (name, fallback = null) => {
+  const index = argv.indexOf(`--${name}`)
+  return index === -1 ? fallback : argv[index + 1] ?? true
+}
+const has = (name) => argv.includes(`--${name}`)
+
+const MAX_AGE_HOURS = Number(arg('max-age-hours', 24))
+const JSON_OUT = has('json')
+const c = {
+  reset: '\u001b[0m', dim: '\u001b[2m', bold: '\u001b[1m', red: '\u001b[31m', green: '\u001b[32m', yellow: '\u001b[33m', cyan: '\u001b[36m',
+}
+const say = (text) => process.stdout.write(`${text}\n`)
+const ok = (text) => say(`  ${c.green}✓${c.reset} ${text}`)
+const bad = (text) => say(`  ${c.red}✗${c.reset} ${text}`)
+const warnline = (text) => say(`  ${c.yellow}!${c.reset} ${text}`)
+
+const problems = []
+const warnings = []
+const facts = {}
+
+async function main() {
+  const pkg = packageMeta()
+  const git = await gitInfoAsync()
+  const matrix = loadMatrix()
+  const currentMatrixHash = matrixHash(matrix)
+  const claims = matrixClaimWarnings(matrix)
+
+  facts.plugin = `${pkg.name}@${pkg.version}`
+  facts.commit = git.commit
+  facts.branch = git.branch
+  facts.dirty = git.dirty
+  facts.matrixHash = currentMatrixHash
+
+  // 1. A run must exist at all.
+  const explicit = arg('run')
+  const resolved = explicit ? runPath(String(explicit)) : latestRun()?.dir ?? null
+  if (!resolved) {
+    problems.push('没有找到任何发布测试报告 —— 先跑 `npm run test:release`')
+    return finish()
+  }
+  const reportDir = path.resolve(resolved)
+  const report = readJson(path.join(reportDir, 'report.json'))
+  facts.run = report.runId
+  facts.reportStatus = report.status
+
+  // 2. The report must be about THIS version, built from THIS commit, recently.
+  if (report.plugin?.version !== pkg.version) {
+    problems.push(`报告测的是 ${report.plugin?.version}，当前 package.json 是 ${pkg.version} —— 版本变了，必须重跑`)
+  }
+  // Compare TREE hashes: that is exactly the set of files the artifact was packed
+  // from. A squash/merge that lands the same content is fine; any real change is not.
+  // Generated documents are rewritten from the evidence of the run itself, so a
+  // report may legitimately be followed by a docs-only commit. Any other change
+  // means the artifact would differ and the report is stale.
+  // Generated docs (rewritten from this run's evidence) and test tooling (not
+  // shipped in the plugin's runtime path) cannot change what users execute.
+  const GENERATED = new Set(['doc/SUPPORT-MATRIX.md', 'README.md', 'README.en.md', 'release-test/mise.toml'])
+  const TOOLING_PREFIXES = ['release-test/', '.github/']
+  const TOOLING_FILES = new Set(['scripts/release-preflight.mjs'])
+  const isAllowedDiff = (file) => GENERATED.has(file) || TOOLING_FILES.has(file) || TOOLING_PREFIXES.some((prefix) => file.startsWith(prefix))
+  const sameTree = report.git?.tree && git.tree && report.git.tree === git.tree
+  if (!sameTree) {
+    const changed = report.git?.tree && git.tree ? await changedPaths(report.git.tree, git.tree) : null
+    if (changed && changed.length && changed.every(isAllowedDiff)) {
+      warnings.push(`报告之后只有生成文档变化（${changed.join(', ')}）—— 视为同一产物，有效`)
+    } else if (report.git?.commit !== git.commit) {
+      problems.push(`报告对应的提交是 ${String(report.git?.commit).slice(0, 8)}（tree ${String(report.git?.tree).slice(0, 8)}），当前 HEAD 是 ${String(git.commit).slice(0, 8)}（tree ${String(git.tree).slice(0, 8)}）—— 内容变了，必须重跑`)
+    } else {
+      problems.push('无法确认报告与当前工作树一致（缺少 tree 记录）—— 用当前版本的 harness 重跑')
+    }
+  } else if (report.git?.commit !== git.commit) {
+    warnings.push(`tree 相同但提交不同（报告 ${String(report.git?.commit).slice(0, 8)} → HEAD ${String(git.commit).slice(0, 8)}）：内容一致，视为有效`)
+  }
+  if (report.git?.dirty) {
+    problems.push('那次测试是在脏工作区跑的：产物可能不包含已提交的代码 —— 先提交，再在干净工作区重跑')
+  }
+  const ageHours = (Date.now() - Date.parse(report.generatedAt)) / 3_600_000
+  facts.reportAgeHours = Math.round(ageHours * 10) / 10
+  if (!(ageHours <= MAX_AGE_HOURS)) {
+    problems.push(`报告已过期：${Math.round(ageHours)} 小时前（上限 ${MAX_AGE_HOURS}）—— 重跑 \`npm run test:release\``)
+  }
+
+  // 3. The support matrix must not have changed since the run.
+  if (report.matrix?.hash !== currentMatrixHash) {
+    problems.push('matrix.json 在测试之后被改过 —— 矩阵变了旧报告不再有效，重跑')
+  }
+
+  // 4. Claim drift blocks the release even if tests are green.
+  if (claims.length) {
+    for (const claim of claims) problems.push(`声明偏差：${claim.detail}`)
+  }
+
+  // 5. No failing declared target, and every declared target was actually run.
+  const declared = matrix.targets.filter((t) => t.tier === 'declared').map((t) => t.version)
+  const tested = new Map((report.targets ?? []).map((t) => [t.version, t]))
+  for (const version of declared) {
+    const target = tested.get(version)
+    if (!target) problems.push(`声明支持的 ${version} 未出现在这次测试里（用了 --only/--tier 的局部运行不能作为发版依据）`)
+    else if (target.status === 'fail' || target.status === 'error') problems.push(`${version} 未通过：${target.status}${target.error ? ` — ${String(target.error).split('\n')[0]}` : ''}`)
+    else if (target.status === 'warn') warnings.push(`${version} 通过但有告警（见 AI 判定）`)
+  }
+  if (report.status === 'red') problems.push('报告总体为 red')
+
+  // 6. The AI reviewer must have ruled on this exact report.
+  const checked = checkRun(reportDir)
+  facts.verdictOverall = checked.verdict?.overall ?? null
+  if (!checked.ok) {
+    for (const problem of checked.problems) problems.push(`AI 判定无效：${problem}`)
+    problems.push('生成判定骨架并让 AI 复核：`node release-test/run.mjs verdict --template`')
+  } else {
+    for (const warning of checked.warnings) warnings.push(warning)
+    if (checked.verdict.overall === 'fail') problems.push('AI 判定为 fail —— 禁止发版')
+  }
+
+  // 7. Dirty tree now: the artifact the users get would include uncommitted code.
+  if (git.dirty) {
+    const files = await dirtyFilesAsync(5)
+    problems.push(`当前工作区不干净（${files.length} 个改动，例如 ${files.slice(0, 3).map((f) => f.trim()).join('；')}）—— 发版必须从干净提交出`)
+  }
+
+  return finish()
+}
+
+function finish() {
+  const pass = problems.length === 0
+  if (JSON_OUT) {
+    process.stdout.write(JSON.stringify({ pass, facts, problems, warnings }, null, 2) + '\n')
+  } else {
+    say(`${c.bold}Release preflight${c.reset} — ${facts.plugin} @ ${String(facts.commit).slice(0, 8)}${facts.dirty ? ' (dirty)' : ''}`)
+    say(`  run ${facts.run ?? '—'} · report ${facts.reportStatus ?? '—'} · age ${facts.reportAgeHours ?? '—'}h · verdict ${facts.verdictOverall ?? '—'}`)
+    if (pass) {
+      ok('可以发版：报告新鲜、矩阵一致、声明无偏差、AI 判定通过、工作区干净')
+      for (const warning of warnings) warnline(warning)
+    } else {
+      bad(`禁止发版（${problems.length} 项）:`)
+      for (const problem of problems) say(`    - ${problem}`)
+      for (const warning of warnings) warnline(warning)
+      say('')
+      say(`${c.dim}修完后重跑：npm run test:release && （AI 判定）node release-test/run.mjs verdict --check${c.reset}`)
+    }
+  }
+  process.exitCode = pass ? 0 : 1
+}
+
+await main()
+
+/** Files that differ between two tree hashes (null when git refuses). */
+async function changedPaths(treeA, treeB) {
+  const logFile = path.join(REPO_ROOT, '.release-test', 'preflight-git.log')
+  const result = await run('git', ['diff', '--name-only', treeA, treeB], { cwd: REPO_ROOT, logFile, timeoutMs: 30_000 })
+  if (result.code !== 0) return null
+  // run() captures output into the log with framing lines; keep only path lines.
+  return fs.readFileSync(logFile, 'utf8')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('=====') && !line.startsWith('[') && !line.startsWith('$'))
+}