dsh-vibe-math 2.8.0 → 2.8.2

package/scripts/release-check.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * RELEASE CHECK (task-8 follow-up) — the checks a maintainer had to run BY HAND for 2.8.0, in one command.
+ *
+ * `docs/release-playbook.md` lists them as prose across §1/§2/§6; this script makes them mechanical, so the
+ * next release cannot ship a drifted version, a missing release note, an unregistered note, a manifest that
+ * lies about the tarball, or CRLF line endings inside the package.
+ *
+ * Usage:
+ *   node scripts/release-check.mjs                # static checks + a real `npm pack` + tarball EOL scan
+ *   node scripts/release-check.mjs --skip-pack    # static checks only (no packing, no temp extraction)
+ *   node scripts/release-check.mjs --registry     # ALSO compare the published shasum (post-publish only)
+ *   node scripts/release-check.mjs --self-test    # prove the predicates below are not vacuous
+ *
+ * Exit 0 = every check passed. Exit 1 = at least one FAIL (printed with a `FAIL ` prefix).
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = join(HERE, '..')
+const TMP = process.env.RELEASE_CHECK_TMP || join(process.env.TEMP || process.env.TMPDIR || '/tmp', 'release-check')
+
+// ---------------------------------------------------------------- pure predicates (fixture-testable)
+/** The version must agree in all three places the market guard reads (playbook §1). */
+export function versionProblems({ pkgVersion, lockTop, lockEmpty }) {
+  const out = []
+  if (!pkgVersion) out.push('package.json has no version')
+  if (lockTop !== pkgVersion) out.push('package-lock.json top-level version ' + lockTop + ' != package.json ' + pkgVersion)
+  if (lockEmpty !== pkgVersion) out.push('package-lock.json packages[""].version ' + lockEmpty + ' != package.json ' + pkgVersion)
+  return out
+}
+
+/** Release notes must carry the template's sections, in the template's order (playbook §1 / TEMPLATE.md). */
+export const SECTIONS = {
+  zh: ['## 概述', '## 新增', '## 变更', '## 修复', '## 兼容性与迁移', '## 已知限制', '## 验证方式', '## 依赖'],
+  en: ['## Overview', '## Added', '## Changed', '## Fixed', '## Compatibility & Migration', '## Known Limitations', '## Verification', '## Dependencies'],
+}
+export function sectionProblems(headings, lang) {
+  const want = SECTIONS[lang]
+  if (!want) return ['unknown language ' + lang]
+  const got = (headings || []).map((h) => String(h).trim())
+  const out = []
+  if (got.length !== want.length) out.push('expected ' + want.length + ' sections, found ' + got.length)
+  for (let i = 0; i < want.length; i++) if (got[i] !== want[i]) out.push('section ' + (i + 1) + ' is ' + JSON.stringify(got[i]) + ', expected ' + JSON.stringify(want[i]))
+  return out
+}
+
+/** Every declared file must exist in the packed tarball (playbook §2/§6.2). */
+export function manifestProblems(declared, packed) {
+  const have = new Set(packed || [])
+  return (declared || []).filter((f) => !have.has(f)).map((f) => 'declared but missing from the tarball: ' + f)
+}
+
+/** Nothing may ship that is repository-only tooling (playbook §6.4). */
+export function devOnlyProblems(packed, devOnly = ['.gitattributes']) {
+  const have = new Set(packed || [])
+  return devOnly.filter((f) => have.has(f)).map((f) => 'repository-only file shipped in the tarball: ' + f)
+}
+
+/** Packaged text must be LF-only so the tarball is byte-reproducible (playbook §7). */
+export function crlfProblems(files) {
+  const out = []
+  for (const { path, crlf } of files || []) if (Number(crlf) > 0) out.push('CRLF in the packaged file: ' + path + ' (' + crlf + ' lines)')
+  return out
+}
+
+/** `compatNote` is user-visible and must name the version being released (playbook §2). */
+export function compatNoteProblems(compatNote, version) {
+  if (!compatNote) return ['dsh.compatNote is missing']
+  return String(compatNote).includes(version) ? [] : ['dsh.compatNote does not mention the current version ' + version]
+}
+
+// ---------------------------------------------------------------- self-test (the family mutates these)
+if (process.argv.includes('--self-test')) {
+  const failures = []
+  const check = (cond, label) => { console.log((cond ? 'PASS ' : 'FAIL - ') + label); if (!cond) failures.push(label) }
+
+  check(versionProblems({ pkgVersion: '9.9.9', lockTop: '9.9.9', lockEmpty: '9.9.9' }).length === 0,
+    'RELEASE-CHECK: a consistent version triple passes')
+  check(versionProblems({ pkgVersion: '9.9.9', lockTop: '9.9.8', lockEmpty: '9.9.9' }).some((p) => /top-level/.test(p)),
+    'RELEASE-CHECK: a drifted lock top-level version is caught')
+  check(versionProblems({ pkgVersion: '9.9.9', lockTop: '9.9.9', lockEmpty: '9.9.8' }).some((p) => /packages/.test(p)),
+    'RELEASE-CHECK: a drifted packages[""] version is caught')
+
+  check(sectionProblems(SECTIONS.zh, 'zh').length === 0 && sectionProblems(SECTIONS.en, 'en').length === 0,
+    'RELEASE-CHECK: the canonical section lists pass their own check')
+  check(sectionProblems(['## 概述', '## 新增'], 'zh').some((p) => /expected 8 sections/.test(p)),
+    'RELEASE-CHECK: a truncated note is caught by its section count')
+  check(sectionProblems([...SECTIONS.en].reverse(), 'en').length > 0, 'RELEASE-CHECK: a reordered note is caught')
+
+  check(manifestProblems(['a.js', 'b.md'], ['a.js', 'b.md', 'package.json']).length === 0, 'RELEASE-CHECK: a fully packed manifest passes')
+  check(manifestProblems(['a.js', 'gone.md'], ['a.js']).length === 1, 'RELEASE-CHECK: a declared-but-missing file is caught')
+
+  check(devOnlyProblems(['README.md'], ['.gitattributes']).length === 0, 'RELEASE-CHECK: repository-only tooling stays out')
+  check(devOnlyProblems(['.gitattributes'], ['.gitattributes']).length === 1, 'RELEASE-CHECK: a shipped repository-only file is caught')
+
+  check(crlfProblems([{ path: 'a.js', crlf: 0 }]).length === 0, 'RELEASE-CHECK: LF-only content passes')
+  check(crlfProblems([{ path: 'a.js', crlf: 3 }]).length === 1, 'RELEASE-CHECK: CRLF inside the package is caught')
+
+  check(compatNoteProblems('v9.9.9 功能版：…', '9.9.9').length === 0, 'RELEASE-CHECK: a compatNote naming the version passes')
+  check(compatNoteProblems('v9.9.8 补丁版：…', '9.9.9').length === 1, 'RELEASE-CHECK: a stale compatNote is caught')
+
+  console.log('release-check self-test: ' + (failures.length ? failures.length + ' failure(s)' : 'all checks passed'))
+  process.exit(failures.length ? 1 : 0)
+}
+
+// ---------------------------------------------------------------- the real run
+const argv = process.argv.slice(2)
+const has = (n) => argv.includes('--' + n)
+const problems = []
+const fail = (p) => { for (const x of p) problems.push(x) }
+const readJson = (rel) => JSON.parse(readFileSync(join(REPO, rel), 'utf8'))
+
+const pkg = readJson('package.json')
+const lock = readJson('package-lock.json')
+const version = pkg.version
+console.log('release-check: ' + pkg.name + '@' + version)
+
+fail(versionProblems({ pkgVersion: version, lockTop: lock.version, lockEmpty: ((lock.packages || {})[''] || {}).version }))
+fail(compatNoteProblems((pkg.dsh || {}).compatNote, version))
+
+const notes = { zh: 'docs/release-notes/RELEASE-NOTES-' + version + '.md', en: 'docs/release-notes/RELEASE-NOTES-' + version + '.en.md' }
+for (const [lang, rel] of Object.entries(notes)) {
+  if (!existsSync(join(REPO, rel))) { problems.push('missing release note (' + lang + '): ' + rel); continue }
+  const text = readFileSync(join(REPO, rel), 'utf8')
+  fail(sectionProblems((text.match(/^## .*$/gm) || []), lang).map((p) => rel + ': ' + p))
+  if (!(pkg.files || []).includes(rel)) problems.push('release note not listed in package.json#files: ' + rel)
+}
+
+if (has('skip-pack')) {
+  console.log('release-check: --skip-pack, skipping the tarball checks')
+} else {
+  rmSync(TMP, { recursive: true, force: true })
+  mkdirSync(TMP, { recursive: true })
+  const out = execFileSync('npm', ['pack', '--dry-run', '--json'], { cwd: REPO, encoding: 'utf8', shell: true })
+  const packed = JSON.parse(out)[0].files.map((f) => f.path)
+  console.log('release-check: tarball would contain ' + packed.length + ' files; declared ' + (pkg.files || []).length)
+  fail(manifestProblems(pkg.files, packed))
+  fail(devOnlyProblems(packed, ['.gitattributes']))
+
+  // Real pack + extract, so the EOL check reads the bytes a user would download.
+  const tgzName = String(execFileSync('npm', ['pack', '--pack-destination', TMP], { cwd: REPO, encoding: 'utf8', shell: true })).trim().split(/\r?\n/).pop()
+  const tgz = join(TMP, tgzName)
+  if (!existsSync(tgz)) {
+    problems.push('npm pack produced no tarball at ' + tgz)
+  } else {
+    execFileSync('tar', ['-xzf', tgz, '-C', TMP], { stdio: 'pipe' })
+    const root = join(TMP, 'package')
+    const eol = []
+    const walk = (d, prefix) => {
+      for (const e of readdirSync(d, { withFileTypes: true })) {
+        const p = join(d, e.name)
+        if (e.isDirectory()) { walk(p, prefix + e.name + '/'); continue }
+        if (!/\.(js|mjs|cjs|json|md|yml|yaml|txt|svg)$/.test(e.name)) continue      // binaries are not text
+        const text = readFileSync(p, 'utf8')
+        eol.push({ path: prefix + e.name, crlf: (text.match(/\r\n/g) || []).length })
+      }
+    }
+    walk(root, '')
+    fail(crlfProblems(eol))
+    const sha1 = createHash('sha1').update(readFileSync(tgz)).digest('hex')
+    console.log('release-check: local tarball sha1 = ' + sha1 + ' (' + eol.length + ' text files scanned for CRLF)')
+    if (has('registry')) {
+      try {
+        const published = String(execFileSync('npm', ['view', pkg.name + '@' + version, 'dist.shasum'], { cwd: REPO, encoding: 'utf8', shell: true })).trim()
+        if (published !== sha1) problems.push('registry dist.shasum ' + published + ' != local tarball sha1 ' + sha1)
+        else console.log('release-check: registry shasum matches the local tarball (byte-reproducible)')
+      } catch (e) { problems.push('registry lookup failed: ' + String((e && e.message) || e).slice(0, 120)) }
+    }
+    rmSync(TMP, { recursive: true, force: true })
+  }
+}
+
+console.log('')
+for (const p of problems) console.log('FAIL ' + p)
+console.log(problems.length ? 'release-check: ' + problems.length + ' problem(s)' : 'release-check: ALL CHECKS PASSED')
+process.exit(problems.length ? 1 : 0)

package/tests/e2e-v5-round2.test.mjs

@@ -1299,6 +1299,13 @@ console.log('\n[24] manual paper, office editor: parts → cross-review → cons
   console.log('    [task-9] v5 detection evidence: compile=' + String(meta && meta.compile && meta.compile.status) + ' triedPaths=' + JSON.stringify((meta && meta.compile && meta.compile.triedPaths) || null))
   assert(Array.isArray(meta && meta.compile && meta.compile.triedPaths) && meta.compile.triedPaths.length > 0,
     '★ [task-9] the durable meta records the probed TeX paths (triedPaths)')
+  // task-18 (v4 got this in 2.8.1): the DELIVERED artifacts must state why no PDF was produced — the body is
+  // composed before the compile runs, so the note is written afterwards, exactly once each (idempotent).
+  // The note follows paperLanguage, so the check is language-agnostic and still requires EXACTLY one.
+  const noteHits = (t) => t.split('本机未检测到 LaTeX 引擎：只产出 tex+md').length - 1
+    + t.split('No LaTeX engine detected: tex+md only').length - 1
+  assert(noteHits(md) === 1 && noteHits(tex) === 1,
+    '★ [task-18/v5] the DELIVERED paper.md and paper.tex state that no engine was detected (once each; md=' + noteHits(md) + ' tex=' + noteHits(tex) + ')')
   const warnText = (meta && Array.isArray(meta.warnings) ? meta.warnings : []).join(' | ')
   assert(warnText.indexOf('只交付 paper.tex 与 paper.md。') !== -1 && warnText.indexOf('已探测 PATH 与文档化的常见 TeX 根；可用 paperLatexCommand 指定绝对路径') !== -1,
     '★ [task-9] the not-detected warning keeps its tail AND says where it looked and how to pin an engine')
@@ -1437,6 +1444,13 @@ console.log('\n[27] fake LaTeX compiler: repair path and persistent-failure degr
   const metap = JSON.parse(readFileSync(join(dp, 'paper.meta.json'), 'utf8'))
   assert(metap.compile.status === 'not-detected',
     '★ [task-10/v5] an unresolvable explicit paperLatexCommand degrades (never falls through to another engine) — got ' + JSON.stringify(metap.compile.status))
+  // task-17 (found on a real host with 2.8.1): the explicit value must be probed ALONE. Probing it as a bare
+  // command name let the known-root stage build impossible paths like `<MiKTeX root>/Z:/…/xelatex.exe`, which
+  // made `triedPaths` — the very field that says WHERE it looked — report paths that cannot exist.
+  const tp = metap.compile.triedPaths || []
+  const joined = tp.filter((p) => /[\\/][A-Za-z]:[\\/]/.test(String(p).replace(/^[A-Za-z]:[\\/]/, '')))
+  assert(tp.length >= 1 && joined.length === 0,
+    '★ [task-17/v5] an ABSOLUTE explicit paperLatexCommand is probed ALONE — triedPaths never joins it onto a known TeX root (triedPaths=' + JSON.stringify(tp) + ')')
 }
 
 // ---------- 28. office-only surface + id normalisation ----------

package/tests/release-check.mutants.mjs

@@ -0,0 +1,78 @@
+// Falsifiability driver for scripts/release-check.mjs: a SINGLE-SITE edit must turn its own guard
+// (`--self-test`) NAMED-red, while the unmutated control stays green. The mutated copy is written as a
+// dot-sibling inside scripts/ so relative paths still resolve, and it is always removed in `finally`.
+import { spawnSync } from 'node:child_process'
+import { readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = join(HERE, '..')
+const SRC = join(REPO, 'scripts', 'release-check.mjs')
+
+const FAMILIES = [
+  {
+    // Without this, a lockfile that drifted away from package.json would ship and the market guard would
+    // be the only thing that notices.
+    name: 'the version-triple check is dropped (a drifted lockfile would ship)',
+    from: 'if (lockTop !== pkgVersion) out.push(',
+    to: 'if (false) out.push(',
+    expect: /drifted lock top-level version is caught/,
+  },
+  {
+    // Without this, a release note missing half its sections would ship.
+    name: 'the section-count check is dropped (a truncated release note would ship)',
+    from: 'if (got.length !== want.length) out.push(',
+    to: 'if (false) out.push(',
+    expect: /truncated note is caught by its section count/,
+  },
+  {
+    // Without this, a note whose sections are in the wrong order would ship.
+    name: 'the section-order check is dropped (a reordered release note would ship)',
+    from: 'if (got[i] !== want[i]) out.push(',
+    to: 'if (false) out.push(',
+    expect: /reordered note is caught/,
+  },
+  {
+    // Without this, a package containing CRLF would ship - the exact defect this whole line of work fixed.
+    name: 'the CRLF scan is dropped (a CRLF package would ship)',
+    from: 'if (Number(crlf) > 0) out.push(',
+    to: 'if (false) out.push(',
+    expect: /CRLF inside the package is caught/,
+  },
+]
+
+function runSelftest(scriptPath) {
+  const r = spawnSync(process.execPath, [scriptPath, '--self-test'], { cwd: REPO, encoding: 'utf8', timeout: 60000 })
+  return { code: r.status, out: String(r.stdout || '') + String(r.stderr || '') }
+}
+
+const control = runSelftest(SRC)
+console.log('control (unmutated release-check): exit=' + control.code + (control.code === 0 ? '  green, as required' : '  NOT GREEN'))
+if (control.code !== 0) console.log(control.out.split(/\r?\n/).filter((l) => /FAIL/.test(l)).slice(0, 4).join('\n'))
+
+let red = 0
+for (const f of FAMILIES) {
+  const dest = join(REPO, 'scripts', '.tmp-release-check-' + Math.random().toString(36).slice(2, 10) + '.mjs')
+  let ok = false
+  try {
+    let text = readFileSync(SRC, 'utf8').replace(/\r\n?/g, '\n')
+    if (/\r/.test(text)) { console.error('SETUP-FAIL - the anchor source was not EOL-normalised (a lone CR leaked in)'); process.exit(1) }
+    const hits = text.split(f.from).length - 1
+    if (hits !== 1) { console.error('SETUP-FAIL - anchor ' + JSON.stringify(f.from) + ' matched ' + hits + ' time(s), expected exactly 1'); process.exit(1) }
+    writeFileSync(dest, text.replace(f.from, f.to), 'utf8')
+    const r = runSelftest(dest)
+    const named = r.out.split(/\r?\n/).filter((l) => /^\s*FAIL - /.test(l) && f.expect.test(l)).map((l) => l.trim())
+    ok = r.code !== 0 && named.length > 0
+    console.log((ok ? '  ok - ' : '  FAIL - ') + f.name + ' [exit=' + r.code + ']' + (named.length ? ' :: ' + named[0].slice(0, 140) : ' :: no named red (exit=' + r.code + ')'))
+    if (ok) red++
+  } finally {
+    try { rmSync(dest, { force: true }) } catch (e) { /* best effort */ }
+  }
+}
+
+console.log('')
+console.log('mutant families reddening the release-check guard by name: ' + red + '/' + FAMILIES.length)
+console.log('control green: ' + (control.code === 0))
+if (red !== FAMILIES.length || control.code !== 0) process.exit(1)
+console.log('ALL MUTANTS RED AS REQUIRED')

package/tests/v4-final-paper.mutants.mjs

@@ -95,6 +95,14 @@ const FAMILIES = [
     to: 'const order=(prefer?[prefer]:[]).concat(base.filter(x=>x!==prefer))',
     expect: /\[task-10\/v4\]/,
   },
+  {
+    // The delivered artifacts must state WHY no PDF was produced (the body is composed BEFORE compilation,
+    // so this note is written after it). Blunting the zh note must redden that guard BY NAME.
+    name: 'deliverable/v4: the delivered paper stops stating that no engine was detected',
+    from: "zh?'本机未检测到 LaTeX 引擎：只产出 tex+md'",
+    to: "zh?''",
+    expect: /\[deliverable\/v4\]/,
+  },
 ]
 let red = 0
 for (const f of FAMILIES) { const t0 = Date.now(); const ok = runFamily(f); const ms = Date.now() - t0; if (ok) red++ }