dsh-plugin-guide 0.3.31 → 0.3.33

package/scripts/check-facts.mjs

@@ -0,0 +1,162 @@
+// Assert that the numbers this project states about itself match reality.
+//
+// Why this exists: the audits found the same class of defect repeatedly, always
+// a number stated in prose that no longer matched the thing it described.
+//   * the family roster was written four different ways in four files;
+//   * the pitfall list was "30+" in English and "20+" in three translations;
+//   * the mirror was described as "215 pages" long after it reached 429;
+//   * `unfixed-issues.md` carried four separate arithmetic slips ("4 items ...
+//     5 items").
+// None of those are content errors — they are drift between a claim and its
+// source. `data/facts.json` is the single home for the numbers; this script
+// checks the claims a machine can verify.
+//
+// Usage: node scripts/check-facts.mjs [--json]
+
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const root = process.cwd()
+const asJson = process.argv.includes('--json')
+const facts = JSON.parse(readFileSync(join(root, 'data', 'facts.json'), 'utf8'))
+
+const failures = []
+const checked = []
+const ok = (name, detail) => checked.push(`${name}: ${detail}`)
+const bad = (name, detail) => failures.push(`${name}: ${detail}`)
+
+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) {
+  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 }
+  }
+  return lines.slice(start + 1, end).filter((l) => /^- \S/.test(l)).length
+}
+
+// ---- 1. README structure claims -------------------------------------------------
+{
+  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}`)
+  }
+}
+
+// ---- 2. Knowledge-base inventory -------------------------------------------------
+{
+  const guide = readdirSync(join(root, 'guide')).filter((f) => f.endsWith('.md')).length
+  if (guide !== facts.knowledgeBase.guideDocuments) bad('guide/ documents', `${guide} vs ${facts.knowledgeBase.guideDocuments}`)
+  else ok('guide/ documents', String(guide))
+
+  const refs = readdirSync(join(root, 'references'))
+    .filter((f) => f.endsWith('.md') && statSync(join(root, 'references', f)).isFile()).length
+  if (refs !== facts.knowledgeBase.referenceDocuments) bad('references/ documents', `${refs} vs ${facts.knowledgeBase.referenceDocuments}`)
+  else ok('references/ documents', String(refs))
+}
+
+// ---- 3. Mirror claims ------------------------------------------------------------
+{
+  const snap = read('references/official-docs/SNAPSHOT.md')
+  const commit = /^\|\s*Source commit\s*\|\s*`([0-9a-f]{40})`\s*\|/m.exec(snap)?.[1]
+  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))
+
+  // Count the mirrored markdown pages and the zh pairs independently.
+  let md = 0
+  let zh = 0
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.name.endsWith('.md')) {
+        md++
+        if (e.name.endsWith('.zh.md')) zh++
+      }
+    }
+  }
+  walk(join(root, 'references', 'official-docs', 'docs'))
+  if (md !== facts.mirror.mdPages) bad('mirror md pages', `${md} counted vs ${facts.mirror.mdPages} in facts.json`)
+  else ok('mirror md pages', String(md))
+  if (zh !== facts.mirror.zhPairs) bad('mirror zh pairs', `${zh} counted vs ${facts.mirror.zhPairs} in facts.json`)
+  else ok('mirror zh pairs', String(zh))
+
+  // Any document quoting a page count must quote the current one.
+  for (const f of ['guide/quick-reference.md', 'guide/quick-reference.zh-CN.md', 'references/sources.md']) {
+    let t
+    try { t = read(f) } catch { continue }
+    const stale = /\b(215|369|182)\s*(?:md|pages|篇)/i.exec(t)
+    if (stale) bad(`${f} stale page count`, `states "${stale[0]}" but the mirror has ${facts.mirror.mdPages} pages`)
+  }
+}
+
+// ---- 4. CLI check counts ---------------------------------------------------------
+{
+  const src = read('src/cli/skill-sections.ts')
+  const n = [...src.matchAll(/^\s*'[a-z0-9-]+':\s*\{/gm)].length
+  if (n !== facts.cli.staticChecks) bad('CLI static checks', `${n} citations vs ${facts.cli.staticChecks} in facts.json`)
+  else ok('CLI static checks', String(n))
+}
+
+// ---- 5. Seam index consistency ---------------------------------------------------
+{
+  const idx = JSON.parse(read('data/seams/index.json'))
+  const corridor = idx.seams.filter((s) => /^L\d+$/.test(s.id)).length
+  if (corridor !== facts.seams.corridorL) bad('corridor L seams', `${corridor} vs ${facts.seams.corridorL}`)
+  else ok('corridor L seams', String(corridor))
+
+  const areas = idx.capabilities.filter((c) => /^A\d+$/.test(c.id)).length
+  if (areas !== facts.seams.capabilityAreas) bad('capability areas', `${areas} vs ${facts.seams.capabilityAreas}`)
+  else ok('capability areas', String(areas))
+
+  const corridorSeams = idx.seams.filter((s) => /^L\d+$/.test(s.id))
+  const detectable = corridorSeams.filter((s) => s.detectable).length
+  const advisory = corridorSeams.length - detectable
+  if (detectable !== facts.seams.staticallyDetectable) bad('statically detectable seams', `${detectable} vs ${facts.seams.staticallyDetectable}`)
+  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))
+}
+
+// ---- 6. Release consistency ------------------------------------------------------
+{
+  const pkg = JSON.parse(read('package.json'))
+  const changelog = read('CHANGELOG.md')
+  if (!changelog.includes(`## [${pkg.version}]`)) {
+    bad('CHANGELOG section', `no "## [${pkg.version}]" section for the current package.json version`)
+  } else ok('CHANGELOG section', pkg.version)
+}
+
+if (asJson) {
+  console.log(JSON.stringify({ facts: facts.schema, checked, failures }, null, 2))
+} else {
+  for (const c of checked) console.log(`  ok    ${c}`)
+  if (failures.length) {
+    console.error('\ncheck-facts: FAIL')
+    for (const f of failures) console.error(`  - ${f}`)
+    console.error('\nEvery number above has one home: data/facts.json. Update it, then update the prose.')
+  } else {
+    console.log(`\ncheck-facts OK (${checked.length} assertions against data/facts.json)`)
+  }
+}
+process.exit(failures.length ? 1 : 0)

package/scripts/measure-mirror-references.mjs

@@ -0,0 +1,117 @@
+// Measure how much of the offline mirror is actually referenced.
+//
+// `references/mirror-scope-decision.md` records a rejected proposal: drop the
+// mirror content that no authored document references, to save ~80% of the
+// published package. This script is the evidence. Run it before reviving that
+// proposal — the answer depends on whether directory globs count as references,
+// and this repository declares several broad ones.
+//
+// Usage: node scripts/measure-mirror-references.mjs [--json]
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const root = process.cwd()
+const mirrorRoot = join(root, 'references', 'official-docs')
+const json = process.argv.includes('--json')
+
+/** Documents that count as "the knowledge base" when looking for references. */
+function authoredFiles() {
+  const out = []
+  const add = (p) => {
+    try { if (statSync(p).isFile()) out.push(p) } catch { /* optional */ }
+  }
+  add(join(root, 'SKILL.md'))
+  add(join(root, 'llms.txt'))
+  for (const dir of ['guide', 'references']) {
+    try {
+      for (const f of readdirSync(join(root, dir))) add(join(root, dir, f))
+    } catch { /* optional */ }
+  }
+  for (const f of readdirSync(root)) if (/^README.*\.md$/.test(f)) add(join(root, f))
+  return out.filter((p) => !p.includes('official-docs') && !p.includes('mirror-scope'))
+}
+
+const authored = authoredFiles()
+const corpus = authored.map((p) => readFileSync(p, 'utf8'))
+
+// Everything the corpus names: full paths, bare basenames, and directory globs.
+const paths = new Set()
+const names = new Set()
+const globDirs = new Set()
+for (const text of corpus) {
+  for (const m of text.matchAll(/references\/official-docs\/([A-Za-z0-9._/-]+)/g)) paths.add(m[1])
+  for (const m of text.matchAll(/\bdocs\/[A-Za-z0-9._/-]+/g)) paths.add(m[0])
+  for (const m of text.matchAll(/([A-Za-z0-9._-]+)\.(md|json|ya?ml|png)\b/g)) names.add(`${m[1]}.${m[2]}`)
+  for (const m of text.matchAll(/([A-Za-z0-9._/-]+)\/\*\*/g)) globDirs.add(m[1])
+}
+
+function walk(dir, base = '') {
+  const out = []
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const rel = base ? `${base}/${e.name}` : e.name
+    if (e.isDirectory()) out.push(...walk(join(dir, e.name), rel))
+    else out.push(rel)
+  }
+  return out
+}
+
+/**
+ * How the corpus reaches this mirror path.
+ *
+ * A glob only covers a path when the glob directory is a PREFIX of it:
+ * `docs/persistence-changes/**` covers `docs/persistence-changes/x.json`, but a
+ * bare `docs/**` does not imply everything under `docs/`. Matching a segment name
+ * anywhere inflates the referenced count and produced a wrong "80% unreferenced"
+ * figure in the original audit.
+ */
+function referencedBy(rel) {
+  if (paths.has(rel) || paths.has(`docs/${rel}`)) return 'exact'
+  const parts = rel.split('/')
+  for (let i = 1; i <= parts.length; i++) {
+    if (globDirs.has(parts.slice(0, i).join('/'))) return 'dir-glob'
+  }
+  if (names.has(parts[parts.length - 1])) return 'basename'
+  return null
+}
+
+const SKIP = new Set(['README.md', 'SNAPSHOT.md', 'LICENSE', 'CLAUDE.md'])
+const buckets = { exact: [], 'dir-glob': [], basename: [], unreferenced: [] }
+for (const rel of walk(mirrorRoot).sort()) {
+  if (SKIP.has(rel)) continue
+  const size = statSync(join(mirrorRoot, rel)).size
+  buckets[referencedBy(rel) ?? 'unreferenced'].push({ rel, size })
+}
+
+const MB = (n) => (n / 1048576).toFixed(2) + ' MB'
+const sum = (a) => a.reduce((s, x) => s + x.size, 0)
+
+if (json) {
+  console.log(JSON.stringify({
+    authoredDocuments: authored.length,
+    buckets: Object.fromEntries(Object.entries(buckets).map(([k, v]) => [k, { files: v.length, bytes: sum(v) }])),
+  }, null, 2))
+} else {
+  console.log(`authored documents scanned: ${authored.length}`)
+  console.log('\nmirror files by reference strength:')
+  for (const k of ['exact', 'dir-glob', 'basename', 'unreferenced']) {
+    console.log(`  ${k.padEnd(14)} ${String(buckets[k].length).padStart(4)} files  ${MB(sum(buckets[k])).padStart(10)}`)
+  }
+  const unreferenced = buckets.unreferenced
+  console.log(`\ngenuinely unreferenced: ${unreferenced.length} files, ${MB(sum(unreferenced))}`)
+  for (const x of unreferenced) console.log(`  ${MB(x.size).padStart(10)}  ${x.rel}`)
+
+  const byExt = new Map()
+  for (const x of buckets['dir-glob']) {
+    const ext = x.rel.slice(x.rel.lastIndexOf('.'))
+    const g = byExt.get(ext) ?? { n: 0, b: 0 }
+    g.n++
+    g.b += x.size
+    byExt.set(ext, g)
+  }
+  console.log('\nreachable only through a declared directory glob, by extension:')
+  for (const [ext, g] of [...byExt].sort((a, b) => b[1].b - a[1].b)) {
+    console.log(`  ${ext.padEnd(12)} ${String(g.n).padStart(4)} files  ${MB(g.b).padStart(10)}`)
+  }
+  console.log('\nSee references/mirror-scope-decision.md before acting on these numbers.')
+}

package/scripts/verify-artifacts.mjs

@@ -32,6 +32,43 @@ check(existsSync(join(root, 'bin', 'dsh-plugin-dev.js')), 'bin/dsh-plugin-dev.js
 check(existsSync(join(root, 'templates', 'ts')), 'templates/ts exists')
 check(existsSync(join(root, 'templates', 'js')), 'templates/js exists')
 
+// Files a subcommand reads at RUNTIME but that nothing else asserts are shipped.
+// `data/seams/index.json` was missing from package.json `files[]` while the
+// `seams` command already depended on it: the command worked from the source
+// tree and would have failed for every installed user with "seam index not
+// found". Reading the file in-repo cannot catch that, so assert the manifest
+// declares it.
+{
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+  const declared = (p) => pkg.files.some((f) => f === p || f.startsWith(`${p}/`) || f === `${p}`)
+  const runtimeInputs = [
+    ['data', 'data/seams/index.json read by `seams`'],
+    ['data', 'data/facts.json read by check-facts'],
+    ['SKILL.md', 'SKILL.md registered as the agent skill'],
+  ]
+  for (const [entry, why] of runtimeInputs) {
+    check(declared(entry), `package.json files[] ships ${why}`)
+  }
+  const seamIndex = JSON.parse(readFileSync(join(root, 'data', 'seams', 'index.json'), 'utf8'))
+  check(Array.isArray(seamIndex.seams) && seamIndex.seams.length > 0, 'seam index parses and is non-empty')
+}
+
+// The `seams` command must resolve its data through the BUILT bundle, since that
+// is what ships; a source-tree-only path resolution works in tests and fails in
+// the published artifact.
+{
+  const seams = runNode(['dist/dsh-plugin-dev.js', 'seams', 'L3', '--json'], { stdio: ['ignore', 'pipe', 'pipe'] })
+  let parsed = null
+  try { parsed = JSON.parse(seams.stdout) } catch { parsed = null }
+  check(seams.status === 0 && parsed?.state === 'found', `bundled \`seams L3\` resolves its data (exit ${seams.status})`)
+
+  // The third state must survive bundling: an unmatched query reports unknown.
+  const unknown = runNode(['dist/dsh-plugin-dev.js', 'seams', 'zzz-nothing', '--json'], { stdio: ['ignore', 'pipe', 'pipe'] })
+  let u = null
+  try { u = JSON.parse(unknown.stdout) } catch { u = null }
+  check(unknown.status === 3 && u?.state === 'unknown', `bundled \`seams\` reports unknown with exit 3 (exit ${unknown.status})`)
+}
+
 // 2. Version + dogfood self-check.
 const version = runNode(['dist/dsh-plugin-dev.js', '--version'])
 check(version.status === 0 && /\d+\.\d+\.\d+/.test(version.stdout.trim()), `--version prints a semver (${version.stdout.trim()})`)