dsh-tower 2.1.0 → 2.4.0

package/scripts/check-components.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// Component-surface policy gate (#120).
+//
+// Principle 11 says optional capabilities are switches and the core is not. This
+// gate is what makes that a rule instead of a slogan. It fails on:
+//
+//   1. a visible component without `title`, `summary` and `disables` in both
+//      locale/en.json and locale/zh.json;
+//   2. a forbidden-to-disable capability (host, health, recovery, review
+//      contract, merge gates) that any group, row or boolean key can disable;
+//   3. a component count that moved without a decision in
+//      scripts/surface-baseline.json (the same brake `surface:check` applies).
+//
+// It also refuses the quiet forms of the same drift: a shipped component row
+// missing from the single source of truth, a live config key without a
+// component-axis class, and a generated reference that is out of date.
+//
+// The single source of truth is `scripts/component-surface.json`; the generated
+// table is `docs/reference/component-surface.md`; the policy is recorded in
+// `docs/adr/0005-component-surface.md`.
+//
+// Usage:
+//   node scripts/check-components.mjs [--root <dir>] [--json]
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Config, configSurface } from '../domain/config/schema.js'
+import {
+  COMPONENT_REFERENCE_FILE,
+  COMPONENT_SURFACE_FILE,
+  LOCALE_FILES,
+  checkForbidden,
+  checkLocaleCoverage,
+  parseComponentSurface,
+  parseCordisPatch,
+  parseOperationalRegistry,
+  renderComponentSurface,
+  validateComponentSurface,
+} from '../domain/components.js'
+import { validateSurfaceBaselineKey } from '../domain/surface.js'
+import { readBaseline } from './lib/surface.mjs'
+import { parseArgs, runMain } from './lib/cli.mjs'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const REGISTRY_FILE = 'host/tool-registry.js'
+const PATCH_FILE = 'cordis.patch.yml'
+const USAGE = `usage: node scripts/check-components.mjs [--root <dir>] [--json]
+
+  --root   repository root to check (default: this package)
+  --json   print the report as JSON
+  --help   print this text
+
+Fails on a visible component without title/summary/disables in both locale files,
+a forbidden-to-disable capability disabled by a group, row or boolean key, a
+component count that moved without a scripts/surface-baseline.json decision,
+an unclassified config key or component row, and a stale generated reference.
+Regenerate the table with \`npm run docs:generate:components\`.`
+
+function finding(code, level, message) {
+  return { code, level, message }
+}
+
+/** The live boolean config keys, derived from the schemastery schema. */
+function liveBooleanKeys() {
+  const keys = []
+  for (const [key, schema] of Object.entries(Config.dict ?? {})) {
+    const dict = schema?.dict
+    if (dict && typeof dict === 'object') {
+      for (const [child, childSchema] of Object.entries(dict)) {
+        if (childSchema?.type === 'boolean') keys.push(`${key}.${child}`)
+      }
+    } else if (schema?.type === 'boolean') {
+      keys.push(key)
+    }
+  }
+  return keys
+}
+
+/**
+ * The static wiring that lets a boolean key remove a tool: the OPERATIONAL_TOOLS
+ * table in host/tool-registry.js. Parsing it (rather than importing the runtime)
+ * keeps the denylist check offline and free of a booted Host. The parser accepts
+ * both the tuple and the `Map.set(...)` forms, and a trailing comma (F11), so a
+ * reformatted table cannot fall out of the allowlist.
+ */
+function operationalRegistry(root) {
+  const file = path.join(root, REGISTRY_FILE)
+  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
+  return parseOperationalRegistry(text)
+}
+
+/** Read the live inputs the pure checks need: schema, patch, locales, registry. */
+export function componentCheckData(root) {
+  const config = configSurface()
+  const patchFile = path.join(root, PATCH_FILE)
+  const patch = fs.existsSync(patchFile)
+    ? parseCordisPatch(fs.readFileSync(patchFile, 'utf8'))
+    : { rows: [], visible: [] }
+  const locales = {}
+  for (const file of LOCALE_FILES) {
+    const localeFile = path.join(root, file)
+    locales[file] = fs.existsSync(localeFile) ? JSON.parse(fs.readFileSync(localeFile, 'utf8')) : null
+  }
+  return {
+    configKeys: config.keys,
+    sections: config.sections,
+    booleans: liveBooleanKeys(),
+    registry: operationalRegistry(root),
+    patch,
+    locales,
+  }
+}
+
+/**
+ * Run every component-surface rule against one repository root.
+ * @param {string} root
+ * @returns {{ ok: boolean, surface: any, live: any, findings: Array<{ code: string, level: string, message: string }> }}
+ */
+export function checkComponents(root) {
+  const findings = []
+  const live = componentCheckData(root)
+  const surfaceFile = path.join(root, COMPONENT_SURFACE_FILE)
+  if (!fs.existsSync(surfaceFile)) {
+    return {
+      ok: false,
+      surface: null,
+      live,
+      findings: [finding('surface-missing', 'error', `${COMPONENT_SURFACE_FILE} is missing`)],
+    }
+  }
+  let surface
+  try {
+    surface = parseComponentSurface(fs.readFileSync(surfaceFile, 'utf8'))
+  } catch (error) {
+    return {
+      ok: false,
+      surface: null,
+      live,
+      findings: [finding('surface-invalid', 'error', `${COMPONENT_SURFACE_FILE}: ${String(error?.message ?? error)}`)],
+    }
+  }
+  findings.push(...validateComponentSurface(surface, { configKeys: live.configKeys, patch: live.patch }))
+  findings.push(...checkLocaleCoverage(surface, live.locales))
+  findings.push(...checkForbidden(surface, { booleans: live.booleans, registry: live.registry, patch: live.patch }))
+
+  // #122: an empty OPERATIONAL_TOOLS table is the expected state. Every route
+  // that does exist must still match the `gateableTools` allowlist, which
+  // checkForbidden enforces above; there is no "unreadable registry" failure to
+  // raise when the correct count is zero.
+
+  // The decision record must exist: the ADR is where the policy is argued.
+  if (!fs.existsSync(path.join(root, surface.adr))) {
+    findings.push(finding('adr-missing', 'error', `component surface names ${surface.adr}, which does not exist`))
+  }
+  for (const capability of surface.forbidden) {
+    const decision = capability.acceptedSwitches?.decision
+    if (!decision) continue
+    if (!fs.existsSync(path.join(root, decision.ref))) {
+      findings.push(
+        finding(
+          'forbidden-decision',
+          'error',
+          `forbidden capability ${capability.id} records a decision in ${decision.ref}, which does not exist`,
+        ),
+      )
+    }
+  }
+
+  // Check 3: the component count is a baselined surface. `surface:check` runs
+  // the full baseline; this narrow call keeps the component brake available in
+  // this gate too, so a moved count fails here without re-measuring the rest.
+  const visible = live.patch.visible
+  let baseline = null
+  try {
+    baseline = readBaseline(root)
+    findings.push(
+      ...validateSurfaceBaselineKey(
+        baseline,
+        'components',
+        { components: visible.length, liveNames: { components: visible } },
+        { exists: (relative) => fs.existsSync(path.join(root, relative)) },
+      ),
+    )
+  } catch (error) {
+    findings.push(finding('baseline-unreadable', 'error', `scripts/surface-baseline.json is unreadable: ${String(error?.message ?? error)}`))
+  }
+
+  // The reference is a rendering, not prose. There is exactly one way to update
+  // it: edit the source of truth and run the generator.
+  try {
+    const expected = renderComponentSurface(surface, { baselineDate: baseline?.date })
+    const referenceFile = path.join(root, COMPONENT_REFERENCE_FILE)
+    const actual = fs.existsSync(referenceFile) ? fs.readFileSync(referenceFile, 'utf8') : ''
+    if (actual !== expected) {
+      findings.push(
+        finding('reference-stale', 'error', `${COMPONENT_REFERENCE_FILE} is stale; run npm run docs:generate:components`),
+      )
+    }
+  } catch (error) {
+    findings.push(finding('reference-unreadable', 'error', `${COMPONENT_REFERENCE_FILE} cannot be rendered: ${String(error?.message ?? error)}`))
+  }
+
+  return { ok: findings.every((entry) => entry.level !== 'error'), surface, live, findings }
+}
+
+function main(argv) {
+  const options = parseArgs(argv, {
+    initial: { root: PACKAGE_ROOT, json: false, help: false },
+    values: { '--root': { key: 'root', parse: path.resolve } },
+    flags: { '--json': 'json', '--help': 'help', '-h': 'help' },
+  })
+  if (options.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const root = path.resolve(options.root)
+  const report = checkComponents(root)
+  if (options.json) {
+    console.log(JSON.stringify({ root, ...report }, null, 2))
+    return report.ok ? 0 : 1
+  }
+  if (report.surface) {
+    const visible = report.surface.components.filter((component) => component.scope === 'visible').length
+    const internal = report.surface.components.length - visible
+    console.log(
+      `components: ${visible} visible, ${internal} internal, ${report.surface.keys.length} config keys classified (${COMPONENT_SURFACE_FILE})`,
+    )
+  }
+  for (const item of report.findings) console.log(`components: ${item.level} [${item.code}] ${item.message}`)
+  if (report.ok) console.log('components: ok — locale coverage, the forbidden denylist and the component baseline hold')
+  else console.log(`components: ${report.findings.length} problem(s); see docs/adr/0005-component-surface.md`)
+  return report.ok ? 0 : 1
+}
+
+await runMain(import.meta.url, () => main(process.argv.slice(2)), { errorPrefix: 'components', usage: USAGE })

package/scripts/check-docs.mjs

@@ -4,6 +4,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { EVENT_COUNT, LEGACY_TOOL_EVENT_NAMES } from '../domain/events.js'
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const read = (file) => fs.readFileSync(path.join(root, file), 'utf8')
@@ -15,7 +16,7 @@ const toolModuleSources = fs.existsSync(path.join(root, 'tools'))
       .map((name) => read(`tools/${name}`))
       .join('\n')
   : ''
-const toolsSource = read('tools/index.js') + toolModuleSources + read('lib/tool-registry.js') + read('index.js')
+const toolsSource = read('tools/index.js') + toolModuleSources + read('host/tool-registry.js') + read('index.js')
 const documentedTools = read('docs/reference/tools.md')
 const toolNames = [...new Set([...toolsSource.matchAll(/name: '(tower_[a-z_]+)'/g)].map((match) => match[1]))]
   .filter((name) => name !== 'tower-control')
@@ -62,37 +63,9 @@ for (const code of [
 ]) blockerCodes.add(code)
 const missingBlockers = [...blockerCodes].filter((code) => !blockersSource.includes(`\`${code}\``)).sort()
 
-const eventNames = [
-  'init',
-  'plan',
-  'mission',
-  'spawn',
-  'complete',
-  'review',
-  'merge',
-  'rebase',
-  'teardown',
-  'finding',
-  'findings',
-  'send',
-  'inbox',
-  'interrupt',
-  'diff',
-  'adopt',
-  'roster',
-  'status',
-  'preflight',
-  'doctor',
-  'recover',
-  'test',
-  'batch',
-  'resource',
-  'import_legacy',
-  'legacy_map',
-  'mode',
-  'control',
-  'reload',
-]
+// #75: the legacy alias list comes from the same event table the generated
+// reference and the runtime use, so a renamed alias fails here first.
+const eventNames = LEGACY_TOOL_EVENT_NAMES.map((name) => name.replace(/^tower\//, ''))
 const documentedEvents = read('docs/reference/events.md')
 const missingEvents = eventNames.filter((name) => !documentedEvents.includes(`\`tower/${name}\``))
 
@@ -128,8 +101,8 @@ if (!blockersDoc.includes(`${blockerCodes.size} stable blocker/failure codes`))
 if (!errorsDoc.includes(`${errorCodes.length} tool error codes`)) {
   problems.push(`docs/reference/errors.md must state ${errorCodes.length} tool error codes`)
 }
-if (!eventsDoc.includes(`${eventNames.length} process-local events`)) {
-  problems.push(`docs/reference/events.md must state ${eventNames.length} process-local events`)
+if (!eventsDoc.includes(`${EVENT_COUNT} process-local events`)) {
+  problems.push(`docs/reference/events.md must state ${EVENT_COUNT} process-local events`)
 }
 for (const required of [
   '| `tests.admission` | `off` |',
@@ -172,5 +145,5 @@ if (problems.length > 0) {
   process.exit(1)
 }
 console.log(
-  `docs ok: ${toolNames.length} tools, ${blockerCodes.size} blocker codes, ${errorCodes.length} error codes, ${eventNames.length} events, version ${packageJson.version}`,
+  `docs ok: ${toolNames.length} tools, ${blockerCodes.size} blocker codes, ${errorCodes.length} error codes, ${EVENT_COUNT} events, version ${packageJson.version}`,
 )

package/scripts/check-pack.mjs

@@ -1,49 +1,78 @@
 // Fail when the published file list drifts from the reviewed snapshot.
-// Run: node scripts/check-pack.mjs [--write]
+// Run: node scripts/check-pack.mjs [--write] [--root <dir>]
+//
+// #71: the optional Web client ships inside the main package, so the required
+// list asserts the client package manifest and its bundle patch — not just the
+// directory's index.js. `requiredMissing` is exported so a fixture can prove
+// that removing one of them fails the check; `--root` lets that fixture run the
+// real gate against a temporary package.
 import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const manifestFile = path.join(root, 'scripts', 'pack-manifest.txt')
-const write = process.argv.includes('--write')
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const REQUIRED_FILES = [
+  'cordis.patch.yml',
+  'index.js',
+  'locale/en.json',
+  'locale/zh.json',
+  'ui-bundle/index.js',
+  'ui-bundle/package.json',
+  'ui-bundle/cordis.patch.yml',
+  'COMPATIBILITY.md',
+]
 
-const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
-let parsed
-try {
-  const output = execFileSync(npm, ['pack', '--dry-run', '--json'], {
-    cwd: root,
-    encoding: 'utf8',
-    shell: process.platform === 'win32',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  })
-  parsed = JSON.parse(output)
-} catch (error) {
-  console.error(`pack check: npm pack failed: ${String(error?.message ?? error)}`)
-  process.exit(1)
+function requiredMissing(paths, required = REQUIRED_FILES) {
+  return required.filter((file) => !paths.includes(file))
 }
 
-const entry = Array.isArray(parsed) ? parsed[0] : parsed
-const paths = (entry?.files ?? []).map((file) => file.path).filter(Boolean).sort()
-if (write) {
-  fs.writeFileSync(manifestFile, `${paths.join('\n')}\n`)
-  console.log(`pack check: wrote ${paths.length} paths to ${path.relative(root, manifestFile)}`)
-  process.exit(0)
-}
-const expected = fs.readFileSync(manifestFile, 'utf8').split('\n').filter(Boolean).sort()
-const added = paths.filter((file) => !expected.includes(file))
-const removed = expected.filter((file) => !paths.includes(file))
-if (added.length > 0 || removed.length > 0) {
-  console.error('pack check: published file list changed; review and update scripts/pack-manifest.txt')
-  if (added.length > 0) console.error(`  added: ${added.join(', ')}`)
-  if (removed.length > 0) console.error(`  removed: ${removed.join(', ')}`)
-  process.exit(1)
-}
-const required = ['cordis.patch.yml', 'index.js', 'locale/en.json', 'locale/zh.json', 'ui-bundle/index.js', 'COMPATIBILITY.md']
-const missing = required.filter((file) => !paths.includes(file))
-if (missing.length > 0) {
-  console.error(`pack check: required runtime files missing: ${missing.join(', ')}`)
-  process.exit(1)
+function main() {
+  const rootArg = process.argv.indexOf('--root')
+  const root = rootArg > 0 ? path.resolve(process.argv[rootArg + 1]) : ROOT
+  const manifestFile = path.join(root, 'scripts', 'pack-manifest.txt')
+  const write = process.argv.includes('--write')
+
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+  let parsed
+  try {
+    const output = execFileSync(npm, ['pack', '--dry-run', '--json'], {
+      cwd: root,
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    parsed = JSON.parse(output)
+  } catch (error) {
+    console.error(`pack check: npm pack failed: ${String(error?.message ?? error)}`)
+    process.exit(1)
+  }
+
+  const entry = Array.isArray(parsed) ? parsed[0] : parsed
+  const paths = (entry?.files ?? []).map((file) => file.path).filter(Boolean).sort()
+  if (write) {
+    fs.writeFileSync(manifestFile, `${paths.join('\n')}\n`)
+    console.log(`pack check: wrote ${paths.length} paths to ${path.relative(root, manifestFile)}`)
+    process.exit(0)
+  }
+  const expected = fs.readFileSync(manifestFile, 'utf8').split('\n').filter(Boolean).sort()
+  const added = paths.filter((file) => !expected.includes(file))
+  const removed = expected.filter((file) => !paths.includes(file))
+  if (added.length > 0 || removed.length > 0) {
+    console.error('pack check: published file list changed; review and update scripts/pack-manifest.txt')
+    if (added.length > 0) console.error(`  added: ${added.join(', ')}`)
+    if (removed.length > 0) console.error(`  removed: ${removed.join(', ')}`)
+    process.exit(1)
+  }
+  const missing = requiredMissing(paths)
+  if (missing.length > 0) {
+    console.error(`pack check: required runtime files missing: ${missing.join(', ')}`)
+    process.exit(1)
+  }
+  console.log(`pack check: ${paths.length} files match scripts/pack-manifest.txt`)
 }
-console.log(`pack check: ${paths.length} files match scripts/pack-manifest.txt`)
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) main()
+
+export { REQUIRED_FILES, requiredMissing }