dsh-primer 0.4.4 → 0.4.6

package/scripts/check-facts.mjs

@@ -30,37 +30,44 @@ const read = (p) => readFileSync(join(root, p), 'utf8')
 /** Count `## ` sections in a document. */
 const sections = (text) => text.split(/\r?\n/).filter((l) => /^##\s/.test(l)).length
 
-/** Count top-level bullets inside the section starting at `heading`. */
-function bulletsIn(text, heading) {
+/** Count top-level bullets inside the H2 section at `ordinal` (0 = preamble). */
+function bulletsInSection(text, ordinal) {
   const lines = text.split(/\r?\n/)
-  const start = lines.findIndex((l) => l.trim() === `## ${heading}`)
-  if (start < 0) return -1
-  let end = lines.length
-  for (let i = start + 1; i < lines.length; i++) {
-    if (/^##\s/.test(lines[i])) { end = i; break }
+  let index = 0
+  let inside = false
+  let count = 0
+  for (const line of lines) {
+    if (/^##\s/.test(line)) {
+      index++
+      inside = index === ordinal
+      continue
+    }
+    if (inside && /^- \S/.test(line)) count++
   }
-  return lines.slice(start + 1, end).filter((l) => /^- \S/.test(l)).length
+  return count
 }
 
 // ---- 1. README structure claims -------------------------------------------------
+// The five READMEs no longer share ENGLISH headings: README.md is the Chinese
+// source and README.<lang>.md translate the headings, so a frozen section count
+// in data/facts.json is not comparable across files. What must hold — and what
+// this checks now — is cross-file equality: every translation carries the same
+// H2 count and the same number of entries in the capabilities section (the
+// fourth H2 of the family layout: preamble, what-it-is, setup, capabilities).
 {
-  const text = read('README.md')
-  const got = sections(text)
-  if (got !== facts.readme.sections) bad('README sections', `${got} in README.md vs ${facts.readme.sections} in facts.json`)
-  else ok('README sections', String(got))
-
-  const wyg = bulletsIn(text, 'What you get')
-  if (wyg !== facts.readme.whatYouGetEntries) bad('What you get entries', `${wyg} vs ${facts.readme.whatYouGetEntries}`)
-  else ok('What you get entries', String(wyg))
-
-  // Every translation must match too; the parity gate covers structure, but this
-  // catches the case where a translation lost entries AND facts.json was not updated.
-  for (const f of ['README-zh.md', 'README-es.md', 'README-pt.md', 'README-hi.md']) {
-    let t
-    try { t = read(f) } catch { continue }
-    const n = bulletsIn(t, 'What you get')
-    if (n !== facts.readme.whatYouGetEntries) bad(`${f} "What you get"`, `${n} vs ${facts.readme.whatYouGetEntries}`)
-  }
+  const files = ['README.md', 'README.en.md', 'README.es.md', 'README.pt.md', 'README.hi.md']
+  const texts = files.map((f) => read(f))
+  const sectionCounts = texts.map((t) => sections(t))
+  const sectionRef = sectionCounts[0]
+  const sectionDrift = files.filter((f, i) => sectionCounts[i] !== sectionRef)
+  if (sectionDrift.length > 0) bad('README sections', `${sectionDrift.join(', ')} do not carry ${sectionRef} sections like README.md`)
+  else ok('README sections', `${sectionRef} in all ${files.length} languages`)
+
+  const capabilityCounts = texts.map((t) => bulletsInSection(t, 3))
+  const capabilityRef = capabilityCounts[0]
+  const capabilityDrift = files.filter((f, i) => capabilityCounts[i] !== capabilityRef)
+  if (capabilityDrift.length > 0) bad('README capabilities entries', `${capabilityDrift.join(', ')} do not carry ${capabilityRef} entries like README.md`)
+  else ok('README capabilities entries', `${capabilityRef} in all ${files.length} languages`)
 }
 
 // ---- 2. Knowledge-base inventory -------------------------------------------------
@@ -82,6 +89,12 @@ function bulletsIn(text, heading) {
   if (commit !== facts.mirror.pinnedCommit) bad('mirror pinned commit', `${commit} in SNAPSHOT.md vs ${facts.mirror.pinnedCommit} in facts.json`)
   else ok('mirror pinned commit', commit.slice(0, 7))
 
+  // A snapshot pinned to a release tag must say so: the old 'origin/master' ref is what let a
+  // master sync commit get labelled as a release tag.
+  const ref = /^\|\s*Source ref\s*\|\s*`([^`]+)`\s*\|/m.exec(snap)?.[1]
+  if (ref !== facts.mirror.pinnedTag) bad('mirror pinned tag', `${ref} in SNAPSHOT.md vs ${facts.mirror.pinnedTag} in facts.json`)
+  else ok('mirror pinned tag', ref)
+
   // Count the mirrored markdown pages and the zh pairs independently.
   let md = 0
   let zh = 0
@@ -110,7 +123,60 @@ function bulletsIn(text, heading) {
   }
 }
 
-// ---- 4. CLI check counts ---------------------------------------------------------
+// ---- 4. Host line and the rc.3 upgrade-guide counts -------------------------------
+// The facts.json host block is the one home for the published line. Two things drift:
+// the dist-tags are restated in six prose files, and the "46 guides in rc.3" count only
+// holds if the 13 v0.2.2-rc.2 guides stay out of it.
+{
+  const host = facts.host
+  const guideDir = join(root, 'references', 'official-docs', 'docs', 'upgrade-guide')
+  const counts = {}
+  for (const version of Object.keys(host.rc3GuideCounts).filter((v) => v !== 'total')) {
+    let dirs = []
+    try {
+      dirs = readdirSync(join(guideDir, `v${version}`), { withFileTypes: true })
+    } catch {
+      bad('rc.3 guide directories', `missing docs/upgrade-guide/v${version} in the mirror`)
+      continue
+    }
+    counts[version] = dirs.filter((e) => e.isDirectory()).length
+    const want = host.rc3GuideCounts[version]
+    if (counts[version] !== want) bad(`rc.3 guides v${version}`, `${counts[version]} dirs vs ${want} in facts.json`)
+    else ok(`rc.3 guides v${version}`, String(counts[version]))
+  }
+  const total = Object.values(counts).reduce((a, b) => a + b, 0)
+  if (total !== host.rc3GuideCounts.total) bad('rc.3 guides total', `${total} vs ${host.rc3GuideCounts.total} in facts.json`)
+  else ok('rc.3 guides total', String(total))
+
+  // The next-version guides are master-only; they must not be in the mirror at all.
+  const nextDir = join(guideDir, `v${host.nextVersion.authoredAt}`)
+  let nextPresent = false
+  try { readdirSync(nextDir); nextPresent = true } catch { /* absent, as expected */ }
+  if (nextPresent) bad('next-version guides in mirror', `docs/upgrade-guide/v${host.nextVersion.authoredAt} is present but belongs after the rc.3 tag`)
+  else ok('next-version guides absent from mirror', host.nextVersion.authoredAt)
+
+  // Every prose file that states the host line must restate these exact tokens.
+  const docFiles = ['README.md', 'README.en.md', 'README.es.md', 'README.pt.md', 'README.hi.md', 'SKILL.md', 'guide/version-matrix.md']
+  const tokens = [host.npmLatest, host.npmNext, host.npmAlpha, host.newestTag, String(host.npmVersionCount), String(host.githubReleaseCount)]
+  for (const f of docFiles) {
+    const t = read(f)
+    const missing = tokens.filter((token) => !t.includes(token))
+    if (missing.length) bad(`${f} host line`, `missing ${missing.join(', ')}`)
+    else ok(`${f} host line`, `${host.npmLatest}/${host.npmNext}/${host.npmAlpha}`)
+  }
+
+  // The mirror pin and its counts are restated in the same places.
+  const pinFiles = ['README.md', 'README.en.md', 'README.es.md', 'README.pt.md', 'README.hi.md', 'SKILL.md', 'references/sources.md', 'references/official-docs/README.md', 'guide/quick-reference.md', 'guide/quick-reference.zh-CN.md', 'guide/quick-reference.es.md', 'guide/quick-reference.pt.md', 'guide/quick-reference.hi.md']
+  const pinTokens = [facts.mirror.pinnedCommit.slice(0, 8), String(facts.mirror.mdPages), String(facts.mirror.zhPairs)]
+  for (const f of pinFiles) {
+    const t = read(f)
+    const missing = pinTokens.filter((token) => !t.includes(token))
+    if (missing.length) bad(`${f} mirror pin`, `missing ${missing.join(', ')}`)
+    else ok(`${f} mirror pin`, facts.mirror.pinnedCommit.slice(0, 8))
+  }
+}
+
+// ---- 5. CLI check counts ---------------------------------------------------------
 {
   const src = read('src/cli/skill-sections.ts')
   const n = [...src.matchAll(/^\s*'[a-z0-9-]+':\s*\{/gm)].length
@@ -118,7 +184,7 @@ function bulletsIn(text, heading) {
   else ok('CLI static checks', String(n))
 }
 
-// ---- 5. Seam index consistency ---------------------------------------------------
+// ---- 6. Seam index consistency ---------------------------------------------------
 {
   const idx = JSON.parse(read('data/seams/index.json'))
   const corridor = idx.seams.filter((s) => /^L\d+$/.test(s.id)).length
@@ -136,9 +202,28 @@ function bulletsIn(text, heading) {
   else ok('statically detectable seams', String(detectable))
   if (advisory !== facts.seams.advisoryOnly) bad('advisory-only seams', `${advisory} vs ${facts.seams.advisoryOnly}`)
   else ok('advisory-only seams', String(advisory))
+
+  // The 0.2.2 line covered by the rc.3 tag: 46 K seams, and the 13 master-only rc.2 guides
+  // recorded separately rather than smuggled into the rc.3 count.
+  const kSeams = idx.seams.filter((s) => /^K\d+$/.test(s.id))
+  if (kSeams.length !== facts.seams.corridorK) bad('corridor K seams', `${kSeams.length} vs ${facts.seams.corridorK}`)
+  else ok('corridor K seams', String(kSeams.length))
+  const kDetectable = kSeams.filter((s) => s.detectable).length
+  if (kDetectable !== facts.seams.corridorKDetectable) bad('corridor K detectable', `${kDetectable} vs ${facts.seams.corridorKDetectable}`)
+  else ok('corridor K detectable', String(kDetectable))
+  const kAdvisory = kSeams.length - kDetectable
+  if (kAdvisory !== facts.seams.corridorKAdvisory) bad('corridor K advisory', `${kAdvisory} vs ${facts.seams.corridorKAdvisory}`)
+  else ok('corridor K advisory', String(kAdvisory))
+  const unreleased = Array.isArray(idx.unreleased) ? idx.unreleased.length : -1
+  if (unreleased !== facts.seams.unreleased) bad('unreleased seams', `${unreleased} vs ${facts.seams.unreleased}`)
+  else ok('unreleased seams', String(unreleased))
+
+  // The seam index must baseline on the same release the mirror is pinned to.
+  if (idx.hostBaseline !== facts.mirror.pinnedTag) bad('seam host baseline', `${idx.hostBaseline} vs ${facts.mirror.pinnedTag}`)
+  else ok('seam host baseline', idx.hostBaseline)
 }
 
-// ---- 6. Release consistency ------------------------------------------------------
+// ---- 7. Release consistency ------------------------------------------------------
 {
   const pkg = JSON.parse(read('package.json'))
   const changelog = read('CHANGELOG.md')

package/scripts/check-readme-parity.mjs

@@ -22,12 +22,12 @@ const json = process.argv.includes('--json')
 const maxArg = process.argv.indexOf('--max-drift')
 const maxDrift = maxArg >= 0 ? Number(process.argv[maxArg + 1] ?? 0) : 0
 
-/** The English source and its translations, for each family. */
+/** The Chinese source and its translations, for each family. */
 const FAMILIES = [
   {
     name: 'README',
     base: 'README.md',
-    variants: ['README-zh.md', 'README-es.md', 'README-pt.md', 'README-hi.md'],
+    variants: ['README.en.md', 'README.es.md', 'README.pt.md', 'README.hi.md'],
   },
   {
     name: 'quick-reference',

package/scripts/check-readme-sync.mjs

@@ -1,28 +1,35 @@
 #!/usr/bin/env node
-// Five-language README sync gate: the English file is the source of truth.
+// Five-language README sync gate: the Chinese file is the source of truth.
 //
-// The READMEs keep ENGLISH `## ` headings in every language (only the prose is
-// translated), so heading TEXT is not compared — a translation that legitimately
-// localises a heading would fail for no reason, and `check-readme-parity.mjs`
-// already compares block-level structure. What this gate owns is:
-//   * the NUMBER and ORDER of `## ` sections (a section added to English must be
-//     added everywhere), and
-//   * the configuration-table keys, which are API names and must match verbatim.
-// The quick references are the opposite convention (translated headings); they
-// are covered by the parity gate instead.
+// The READMEs translate their `## ` headings into each language (the family
+// standard: README.md is Simplified Chinese, README.<lang>.md are the
+// translations), so heading TEXT is not compared — a translation that
+// localises a heading must not fail for no reason, and
+// `check-readme-parity.mjs` already compares block-level structure. What this
+// gate owns is:
+//   * the NUMBER and ORDER of `## ` sections (a section added to the Chinese
+//     source must be added everywhere), and
+//   * the configuration-table keys, which are API names and must match
+//     verbatim (the Configuration / 配置 / Configuración / Configuração /
+//     कॉन्फ़िगरेशन section, whichever language spells it).
+// The quick references keep the opposite convention (English headings in every
+// language); they are covered by the parity gate instead.
 import { readFileSync, existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
 const LANGUAGES = [
-  ['README.md', 'en'],
-  ['README-zh.md', 'zh'],
-  ['README-es.md', 'es'],
-  ['README-pt.md', 'pt'],
-  ['README-hi.md', 'hi'],
+  ['README.md', 'zh'],
+  ['README.en.md', 'en'],
+  ['README.es.md', 'es'],
+  ['README.pt.md', 'pt'],
+  ['README.hi.md', 'hi'],
 ]
 
+/** The configuration section heading, in any of the five README languages. */
+const CONFIG_HEADING = /^##\s+(?:Configuration|配置|Configuración|Configuração|कॉन्फ़िगरेशन)\s*$/u
+
 const headingsOf = (text) => text.split(/\r?\n/u)
   .map(line => /^##\s+(.+)$/u.exec(line)?.[1]?.trim())
   .filter((heading) => heading !== undefined)
@@ -31,7 +38,7 @@ const headingsOf = (text) => text.split(/\r?\n/u)
 // "Configuration" section (until the next `## ` heading).
 const configKeysOf = (text) => {
   const lines = text.split(/\r?\n/u)
-  const start = lines.findIndex(line => /^##\s+Configuration\s*$/u.test(line))
+  const start = lines.findIndex(line => CONFIG_HEADING.test(line))
   if (start === -1) return []
   const end = lines.findIndex((line, index) => index > start && line.startsWith('## '))
   const section = lines.slice(start, end === -1 ? undefined : end)