@nanisoft/prism-ui 0.7.0 → 0.9.0

package/gates/cli.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * The consumer's gate chain. One program, one configuration file, one exit code.
+ *
+ * A consumer's repository holds data: its roots, its sheet, its pack map, its
+ * coverage floors, its destinations it knows are broken. It does not hold the
+ * wording of a rule, because a wording held in four places is four rules that will
+ * disagree, and the version they disagree at is the version nobody chose.
+ *
+ *     pnpm prism-gates                       # every gate the configuration names
+ *     pnpm prism-gates --gate=links          # one gate
+ *     pnpm prism-gates --gate=links --json   # machine-readable, for a test
+ *
+ * `--json` exists because the assertion that matters about a gate is not that it
+ * passed: it is that it went red on a defect it can see. A test cannot watch a
+ * human-readable exit code and be sure it saw the failure it planted, so the
+ * machine form carries the findings and the coverage the run achieved.
+ *
+ * **The exit code is the contract.** 0 means every named gate ran and found
+ * nothing. 1 means a gate found something. 2 means a gate could not read what it
+ * was pointed at, which is a different answer from "clean" and is never reported
+ * as 0. A gate that read nothing and exited 0 is the failure this program exists
+ * to make impossible, and it is why the coverage floors live in the gates rather
+ * than in the consumer's expectations.
+ */
+import process from 'node:process'
+import path from 'node:path'
+
+import { GATE_IDS, GATE_KIT_VERSION, gate, laws } from './index.mjs'
+import { CoverageError, readJson } from './run.mjs'
+
+const CONFIG_NAME = 'prism-gates.json'
+
+const flag = (name) => process.argv.find((argument) => argument.startsWith(`--${name}=`))?.slice(name.length + 3)
+const has = (name) => process.argv.includes(`--${name}`)
+
+async function main() {
+  const root = path.resolve(process.cwd())
+  const configPath = flag('config') ?? CONFIG_NAME
+  const json = has('json')
+  const only = flag('gate')
+
+  let config
+  try {
+    config = readJson(root, configPath)
+  } catch (cause) {
+    return fail(`error prism-gates: ${cause.message}`)
+  }
+  if (!config) {
+    return fail(
+      `error prism-gates: ${path.join(root, configPath)} does not resolve.\n` +
+        '  A gate chain with no configuration is a chain that runs nothing, and nothing looks like a pass.\n' +
+        '  The configuration holds this repository\'s own data only: its roots, its sheet, its pack map, its\n' +
+        '  coverage floors. The laws are not in it, because they are in the package.',
+    )
+  }
+
+  const named = only ? [only] : (config.gates ?? [])
+  if (named.length === 0) {
+    return fail(
+      `error prism-gates: ${configPath} names no gates, so this run enforced nothing.\n` +
+        `  A chain that runs nothing exits the same as a chain that found nothing, which is the answer this\n` +
+        `  program exists to stop giving. The kit ships: ${GATE_IDS.join(', ')}.`,
+    )
+  }
+
+  const results = []
+  let findings = 0
+  let unreadable = 0
+
+  for (const id of named) {
+    const settings = config[id] ?? {}
+    try {
+      const { run } = await gate(id)
+      const result = await run({ root, config: settings })
+      findings += result.findings.length
+      results.push({ gate: id, law: result.law.id, ok: result.findings.length === 0, findings: result.findings, notes: result.notes, also: (result.also ?? []).map((l) => l.id) })
+    } catch (cause) {
+      unreadable += 1
+      const message =
+        cause instanceof CoverageError
+          ? `error prism-gates: ${id}: ${cause.message}`
+          : `error prism-gates: ${id} could not run: ${cause.stack ?? cause.message}`
+      if (json) {
+        results.push({ gate: id, ok: false, unreadable: true, findings: [], notes: [message] })
+      } else {
+        console.error(message)
+      }
+    }
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { gateKit: GATE_KIT_VERSION, laws: laws().map((l) => l.id), results },
+        null,
+        2,
+      ),
+    )
+    return findings > 0 || unreadable > 0 ? 1 : 0
+  }
+
+  for (const result of results) {
+    if (result.unreadable) continue
+    for (const line of result.notes) console.log(line)
+    for (const line of result.findings) console.error(line)
+    if (result.findings.length > 0) {
+      const law = laws().find((l) => l.id === result.law)
+      console.error(`\n${law.title}`)
+      console.error(law.message)
+      console.error(`  It is here because: ${law.why}`)
+    }
+  }
+
+  console.log(
+    `\nprism-gates: gate kit ${GATE_KIT_VERSION}, ${named.length} gate(s) run, ${findings} finding(s), ` +
+      `${unreadable} unreadable`,
+  )
+  console.log(`prism-gates: the laws this run enforced: ${laws().map((l) => l.id).join(', ')}`)
+  console.log(
+    'prism-gates: the wording of every law above is in the package you pinned, not in this repository. A change\n' +
+      '  to it reaches this repository in one release and cannot be declined here.',
+  )
+
+  return findings > 0 || unreadable > 0 ? 1 : 0
+}
+
+function fail(message) {
+  console.error(message)
+  return 2
+}
+
+process.exitCode = await main()

package/gates/hidden-state.mjs

@@ -0,0 +1,243 @@
+/**
+ * The hidden-state law: a CSS-authored hidden state can dismiss itself, and its
+ * exit is not a clock.
+ *
+ * The defect this replaces is not a bug report; it is a page nobody can read. A
+ * sheet carried
+ *
+ *     .site [data-reveal]        { opacity: 0; transform: translateY(12px); }
+ *     .site [data-reveal].is-in  { opacity: 1; transform: none; }
+ *
+ * and `is-in` was added by an IntersectionObserver in a client effect. That is the
+ * only exit. There is no timeout, so there is nothing to wait for and nothing to
+ * give up on: a reader with scripting disabled, a reader whose browser has no
+ * IntersectionObserver, a reader whose JavaScript failed to parse, and a crawler
+ * that never executes any of it all received `opacity: 0` and nothing else. The
+ * whole body of the page, below the header, was invisible.
+ *
+ * Exactly two shapes are allowed. An escapable condition, which is a media query
+ * or a `:not()` that the reader's own capability satisfies. Or a script-armed
+ * ancestor attribute, where the arming is written by exactly one script and by
+ * nothing else, so a reader whose scripting is off never receives it and the
+ * hidden state does not exist for them. A reader whose scripting fails midway
+ * might, and the `(scripting: none)` block is the guard for that case: it is a
+ * statement about capability rather than about health, and it does not care why
+ * the script did not finish. The two are complementary and neither is a timeout.
+ *
+ * **The clock is banned rather than shortened.** A fallback animation's clock
+ * starts at first style resolution rather than at scroll, so by the time the
+ * class lands there is nothing left to cancel, and a reader on a slow connection
+ * looks at a blank page for three seconds of a timer measuring the wrong
+ * interval. Cancellability was never the load-bearing property; having an exit
+ * that does not depend on a clock was.
+ *
+ * **A gate that only read the stylesheet would pass a site that renders nothing.**
+ * That is why a consumer that ships a hidden state also has a test that renders
+ * with scripting off, and this gate's job is to make the stylesheet half true
+ * enough for that test to be the only half left. A consumer with no hidden state
+ * runs this gate too and passes vacuously, and the run prints the rule count it
+ * read so the reader can tell the difference between a vacuous pass and a scan of
+ * nothing.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+import { law } from './laws.mjs'
+import { CoverageError, blankComments, cssBlocks, finding, floor, read } from './run.mjs'
+
+/** A declaration that makes an element not painted. */
+const HIDES = /^\s*(?:opacity\s*:\s*(?:0|0%)\b|visibility\s*:\s*hidden\b|display\s*:\s*none\b)/
+
+/** A clock. Any of the three is a mechanism with its own failure mode. */
+const CLOCK = /(?:^|[;\s])animation(?:-[a-z-]+)?\s*:|@keyframes/
+
+export function run({ root, config }) {
+  const l = law('hidden-state')
+  const findings = []
+  const notes = []
+  const sheets = config.sheets ?? ['app/globals.css']
+  const minRules = config.minRules ?? 25
+  const marker = config.marker ?? 'data-reveal'
+  const armed = config.armed ?? 'data-reveal-armed'
+  const sourceRoots = config.sourceRoots ?? ['app', 'components', 'lib']
+
+  const missing = sheets.filter((sheet) => read(root, sheet) === null)
+  if (missing.length > 0) {
+    throw new CoverageError(
+      `${missing.length} of ${sheets.length} configured stylesheets do not resolve: ${missing.join(', ')}.\n` +
+        '  A gate that read nothing reports a clean sheet, so an unresolved root fails the run.',
+    )
+  }
+
+  const markerSelector = new RegExp(`\\[${marker}\\b`)
+  const armedSelector = new RegExp(`\\[${armed}\\]`)
+
+  let rules = 0
+  let declarations = 0
+  let hiding = 0
+
+  for (const sheet of sheets) {
+    for (const block of cssBlocks(read(root, sheet))) {
+      rules += 1
+      for (const declaration of block.body.split(';')) {
+        if (/^[a-z-]+\s*:/.test(declaration.trim())) declarations += 1
+      }
+      const selectors = block.selectors.join(', ')
+
+      if (CLOCK.test(block.body)) {
+        findings.push(
+          finding(
+            `${sheet}:${block.line}`,
+            'clock',
+            `${selectors} carries an animation clock. A fallback animation's clock starts at first style\n` +
+              '      resolution rather than at scroll, so by the time the class lands there is nothing left to\n' +
+              '      cancel, and a slow connection sees a blank page for a timer that measures the wrong interval.',
+          ),
+        )
+      }
+
+      if (!block.body.split(';').some((declaration) => HIDES.test(declaration))) continue
+      if (!markerSelector.test(selectors)) {
+        // A rule that hides nothing through the marked selector is not the law's
+        // subject. It is still a rule this gate read, and it is still counted.
+        continue
+      }
+      hiding += 1
+
+      if (!armedSelector.test(selectors)) {
+        findings.push(
+          finding(
+            `${sheet}:${block.line}`,
+            'unarmed',
+            `${selectors} hides content with no armed ancestor. A reader whose scripting is switched off never\n` +
+              `      receives \`${armed}\`, so this declaration is the last thing they are shown.`,
+          ),
+        )
+      }
+      if (!/\(scripting\s*:\s*none\)/.test(read(root, sheet))) {
+        findings.push(
+          finding(
+            sheet,
+            'no-scripting-guard',
+            `the sheet hides content and declares no \`(scripting: none)\` guard. A reader whose scripting\n` +
+              '      started and stopped would receive the arming attribute and nothing that withdraws it.',
+          ),
+        )
+      }
+    }
+  }
+
+  floor('rule(s) read', rules, minRules)
+
+  /*
+   * A second writer of the arming attribute is a second owner of a state whose exit
+   * depends on every path withdrawing it, so the writer is counted.
+   *
+   * Counted by the WRITE, not by the name. A module that explains the mechanism in a
+   * comment names the attribute and writes nothing, and a gate that counted names
+   * would read its own subject's documentation as a second writer. The write is
+   * matched on a code line with the comments blanked, so a comment that shows the
+   * call as an example is a record and a call is a call.
+   *
+   * The withdrawal is counted separately and separately required: an arming with no
+   * withdrawal anywhere is a hidden state whose only exit is the scripting-media
+   * query, which does not see the reader whose scripting started and stopped.
+   */
+  const sources = sourceFiles(root, sourceRoots)
+  const writer = new RegExp(`setAttribute\\(\\s*['"\`]${armed}['"\`]`)
+  const withdrawer = new RegExp(`removeAttribute\\(\\s*['"\`]${armed}['"\`]`)
+  const writers = sources.filter((file) =>
+    writer.test(blankComments(readFileSync(file, 'utf8'))),
+  )
+  const withdrawers = sources.filter((file) =>
+    withdrawer.test(blankComments(readFileSync(file, 'utf8'))),
+  )
+  const clientModules = sources.filter((file) =>
+    /^\s*['"]use client['"]/m.test(readFileSync(file, 'utf8')),
+  )
+  const relative = (file) => path.relative(root, file).split(path.sep).join('/')
+  if (writers.length === 0 && hiding > 0) {
+    findings.push(
+      finding(
+        sheets.join(', '),
+        'unwritten',
+        `a rule hides content through \`[${marker}]\` and no module writes \`${armed}\`. The attribute is the\n` +
+          '      whole of the exit for a reader whose scripting works, so a sheet that hides with nothing to\n' +
+          '      arm it hides for everyone.',
+      ),
+    )
+  }
+  if (writers.length > 1) {
+    findings.push(
+      finding(
+        writers.slice(1).map(relative).join(', '),
+        'second-writer',
+        `more than one module writes \`${armed}\`, at ${writers.map(relative).join(' and ')}. The attribute has one\n` +
+          '      writer, and a second writer is a second owner of a state whose exit depends on every path\n' +
+          '      withdrawing it.',
+      ),
+    )
+  }
+  if (withdrawers.length === 0 && writers.length > 0) {
+    findings.push(
+      finding(
+        writers.map(relative).join(', '),
+        'no-withdrawal',
+        `\`${armed}\` is written and never removed, so a reader whose scripting started and then\n` +
+          '      stopped has the attribute and no path that takes it away. The (scripting: none) guard\n' +
+          "      cannot see them, because their scripting is enabled.",
+      ),
+    )
+  }
+
+  notes.push(
+    `${l.id}: ${findings.length} finding(s) across ${sheets.length} sheet(s), ${rules} rule(s) and ${declarations} declaration(s) read; floor ${minRules} rule(s)`,
+  )
+  notes.push(`${l.id}: sheets read: ${sheets.join(', ')}`)
+  notes.push(
+    `${l.id}: ${hiding} rule(s) hide content through \`[${marker}]\`; the escape shapes are an escapable condition\n` +
+      `      or an armed ancestor \`[${armed}]\` written by exactly one script.`,
+  )
+  notes.push(
+    `${l.id}: ${sources.length} source file(s) read; ${writers.length} write the arming attribute` +
+      `${writers.length === 0 ? '' : ` (${writers.map(relative).join(', ')})`} and ${withdrawers.length} withdraw it` +
+      `${withdrawers.length === 0 ? '' : ` (${withdrawers.map(relative).join(', ')})`}. Counted by the call, not by the name, so a comment explaining the mechanism is not a writer.`,
+  )
+  if (hiding === 0) {
+    notes.push(
+      `${l.id}: this run passed vacuously. No rule in ${sheets.join(', ')} hides content through the marker, so this\n` +
+        '      repository has nothing to exit and no runtime to exit it with. That is a real answer rather than a\n' +
+        '      scan of nothing: the rule count above says how much was read, and a repository that acquired a\n' +
+        '      hidden state would produce a finding here rather than a pass.',
+    )
+  }
+  notes.push(`${l.id}: ${clientModules.length} module(s) carry a client directive.`)
+  notes.push(
+    `${l.id}: a stylesheet half is not enough. A consumer that ships a hidden state needs a test that renders\n` +
+      '      with scripting switched off and asserts the content is present and the arming attribute is absent.',
+  )
+
+  return { law: l, findings, notes }
+}
+
+/** Every source file the declared roots hold, so a second writer is findable. */
+function sourceFiles(root, roots) {
+  const found = []
+  const skip = new Set(['node_modules', '.next', 'out', '.git', '.wrangler', '.source'])
+  const visit = (dir) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (skip.has(entry.name)) continue
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory() || statSync(full).isDirectory()) visit(full)
+      else if (/\.(tsx?|mjs)$/.test(entry.name)) found.push(full)
+    }
+  }
+  for (const declared of roots) visit(path.join(root, declared))
+  return found
+}

package/gates/index.mjs

@@ -0,0 +1,81 @@
+/**
+ * The gate kit's registry: which law is which program, and which version of this
+ * kit a consumer is running.
+ *
+ * The registry exists so that "the laws" is a list rather than a folder. A gate
+ * that is not in `GATES` is a program nobody runs, and a law with no gate is a
+ * sentence, which is the thing this kit was written to remove. `check-gate-kit.mjs`
+ * asserts the two are the same set in both directions, and the assertion runs in
+ * this repository's own `check`, so the registry cannot rot without the build
+ * failing.
+ *
+ * `GATE_KIT_VERSION` is the version of the *contract*, not of the package. A
+ * consumer names it in its configuration so that a consumer's own gate chain can
+ * say which generation of the law it is holding itself to, and so that a law
+ * rewritten in a later release is visible as a version the consumer has not moved
+ * to rather than as a silent change of wording underneath it.
+ */
+import { LAW_IDS, law } from './laws.mjs'
+
+/** The contract generation. Bump it when a law's wording or its gate's surface changes. */
+export const GATE_KIT_VERSION = 1
+
+/** Every gate, keyed by the id a consumer names. The value is the module's `run`. */
+export const GATES = {
+  'retired-line': () => import('./retired-line.mjs'),
+  'stylesheet-ownership': () => import('./stylesheet-ownership.mjs'),
+  links: () => import('./links.mjs'),
+  'pack-boundary': () => import('./pack-boundary.mjs'),
+  'hidden-state': () => import('./hidden-state.mjs'),
+  'runtime-token-read': () => import('./runtime-token-read.mjs'),
+  pin: () => import('./pin.mjs'),
+}
+
+/**
+ * Which gate holds which law, in both directions.
+ *
+ * The token-read law is held by the stylesheet-ownership gate because it reads the
+ * same sheet with the same parser and the same reference; splitting it would mean
+ * parsing a stylesheet twice to assert one property of it, and the two runs could
+ * disagree about what a declaration is. It is a separate law because its failure is
+ * a different failure: an unlayered declaration that wins the cascade is not the
+ * same defect as a read that erases itself.
+ */
+export const GATE_LAWS = {
+  'retired-line': ['retired-line'],
+  'stylesheet-ownership': ['stylesheet-ownership', 'token-read'],
+  links: ['links'],
+  'pack-boundary': ['pack-boundary'],
+  'hidden-state': ['hidden-state'],
+  'runtime-token-read': ['runtime-token-read'],
+  pin: ['pin'],
+}
+
+/** The gate ids, in the order a report prints them. */
+export const GATE_IDS = Object.keys(GATES)
+
+/** One gate by id, loaded. A throw naming the ones that exist, because a misspell must not pass. */
+export async function gate(id) {
+  const load = GATES[id]
+  if (!load) {
+    throw new Error(`prism-gates: unknown gate "${id}". The kit ships: ${GATE_IDS.join(', ')}.`)
+  }
+  const module = await load()
+  if (typeof module.run !== 'function') {
+    throw new Error(`prism-gates: the gate "${id}" exports no run(), so it cannot be run rather than skipped.`)
+  }
+  return module
+}
+
+/**
+ * Every law the kit enforces, resolved, so a consumer can print them without
+ * knowing which program holds which.
+ */
+export function laws() {
+  return LAW_IDS.map(law)
+}
+
+/** The laws a named gate holds. */
+export function lawsOf(gateId) {
+  return (GATE_LAWS[gateId] ?? []).map(law)
+}

package/gates/laws.mjs

@@ -0,0 +1,170 @@
+/**
+ * The laws, defined once.
+ *
+ * For four years the cross-repository contract between the five NaniSoft
+ * repositories was a prose document mirrored in four files, and it decayed in
+ * the only way a mirror can: the two sites that mattered drifted into three
+ * implementations of one rule and one of the three rules was false. A prose law
+ * cannot fail, so it stays true until the day it is not, and nobody is told.
+ *
+ * So a law here is not a sentence a reader is asked to believe. It is the text a
+ * gate prints when the build fails, and it lives in the package every consumer
+ * pins exactly. A consumer's own repository holds data: its roots, its sheet, its
+ * pack map, its coverage floors. It does not hold the wording of a rule, because
+ * a wording held in four places is four rules that will disagree.
+ *
+ * **The test for what belongs here.** A clause earns a law when its violation is
+ * silent. Every entry below is silent by construction: an unlayered bare-element
+ * declaration of the page ground looks like a design decision in a screenshot, a
+ * `var()` that resolves to nothing erases the declaration rather than painting a
+ * wrong colour, a link that goes nowhere renders exactly like a link that works,
+ * and a boundary that resolves the light block on a dark page is pack-correct and
+ * looks right. None of them throws. That is the whole reason they are programs.
+ *
+ * **Why `stops` is here and not in a document.** A gate's failure message is read
+ * at the moment somebody's build is red, which is the only moment a rule about
+ * cross-repository conduct is ever going to be read by the person it is for. The
+ * consequence therefore belongs in the same string as the assertion, or it is
+ * prose again.
+ *
+ * Published at `@nanisoft/prism-ui/gates`. Not imported from `src/`, because a
+ * gate is a build-time program for a consumer's repository and must never enter a
+ * consumer's module graph or its bundle.
+ */
+
+/**
+ * Every law the kit can enforce, keyed by the id a consumer names in its
+ * configuration. Order is the order a reader meets them in, which is the order
+ * they were written in the contract this file replaces.
+ */
+export const LAWS = {
+  'retired-line': {
+    title: 'No trace of the retired component library survives.',
+    message:
+      'No trace of the retired line survives in a consumer: not a dependency, not an import, not a\n' +
+      '  generated stylesheet, not a build step, and not a living instruction. A dependency line is the\n' +
+      '  easy half; the lockfile is read as a graph because deleting a line does not empty a tree while\n' +
+      '  another package still declares the library.',
+    why:
+      'The four repositories shipped the retired line together and each of them discovered it had to\n' +
+      '      remove it separately. The rule survived the removal as prose in four files and nothing failed\n' +
+      '      when one of them brought it back.',
+  },
+
+  'stylesheet-ownership': {
+    title: "A site stylesheet does not own a surface the design system owns.",
+    message:
+      'A site stylesheet must not own a surface the design system already owns. The cascade layer is\n' +
+      '  not the cause of the failures this replaces; it is the reason they were invisible. Prism\'s base\n' +
+      '  is layered and a consumer\'s sheet is not, so an unlayered declaration wins at any specificity\n' +
+      '  whatever the cascade then does with it.',
+    why:
+      'An unlayered bare-element declaration of the page ground, the body ink, a focus outline or a\n' +
+      '      hairline colour was live in all four repositories at once, and every one of them was a box\n' +
+      '      with no edge, a white page in dark mode, or an element with no keyboard indicator, each of\n' +
+      '      which is a plausible design in a screenshot.',
+  },
+
+  'token-read': {
+    title: 'A custom property that nothing declares is not a wrong colour; it is no declaration at all.',
+    message:
+      'Every custom property this sheet reads is declared, and that is what a shorthand with one dead\n' +
+      '  operand does to itself: a declaration that is invalid at computed-value time is not a wrong\n' +
+      '  colour, it is no declaration, so a page ground reverts to transparent and a hairline reverts to\n' +
+      '  border-style: none. A read that cannot fail hides its own failure, which is the whole reason the\n' +
+      '  runtime form of this law was written first.',
+    why:
+      'Roughly two hundred and twenty custom-property reads across the four repositories resolved to\n' +
+      '      nothing on the new line, about half of them shorthands. The page ground, the body ink, the\n' +
+      '      hairline and the focus outline all reverted, and a screenshot of unstyled body text is a\n' +
+      '      plausible design.',
+  },
+
+  links: {
+    title: 'Every internal destination resolves, and every fragment names an element that exists.',
+    message:
+      'A reader followed a link on this site and arrived nowhere. Every address a reader has ever used\n' +
+      '  has to keep working, and a broken internal link renders exactly like a working one, so nothing\n' +
+      '  else in the build can see it.',
+    why:
+      'A migration rewrites the rendering layer and is forbidden from changing a word, so a route that\n' +
+      '      quietly stopped being published is the one defect class the whole programme was at risk of\n' +
+      '      shipping. This is the gate that outlived the parity baseline.',
+  },
+
+  'pack-boundary': {
+    title: 'A pack boundary lands on a mark, and a declared region set is the whole of what may carry a second pack.',
+    message:
+      'A pack boundary is a promise with two axes. It re-points the corner radius as well as the colour,\n' +
+      '  so a boundary on anything but a fully rounded mark changes that shape, and a boundary with no\n' +
+      '  mode class of its own resolves its pack in the wrong mode on half the pages a reader sees. A\n' +
+      '  screenshot in one mode is not evidence for either.',
+    why:
+      'A boundary that carries no descendant form resolves the light block on a dark page, which is\n' +
+      '      pack-correct, mode-inverted and indistinguishable from a design decision. And because radius\n' +
+      '      is the one non-colour member of a pack block, a section ground would put the section index\n' +
+      '      into that section\'s corner radius, which is an encoding nobody chose.',
+  },
+
+  'runtime-token-read': {
+    title: 'No token is read at runtime, and a read with a hard-coded fallback is a read that cannot fail.',
+    message:
+      'A token is resolved once at runtime and the resolved value does not follow the cascade, so a reader with\n' +
+      '  a stored theme and a reader without one are served different colours from the same markup. The design\n' +
+      '      system publishes the replacement, which is a token-driven inline replacement painted in the HTML: it\n' +
+      '      resolves through the cascade, holds every pack, and ships no client code. The fix is deletion, not a\n' +
+      '      better value.',
+    why:
+      'One site shipped a curve of numbers under a label reading as a live market feed, and the gate that should\n' +
+      '      have seen it read prose while the dishonesty was arithmetic. A runtime token read is the same shape:\n' +
+      '      the disagreement is between what is painted and what the cascade says, and only a program that reads\n' +
+      '      the read can see it.',
+  },
+
+  'hidden-state': {
+    title: 'A CSS-authored hidden state is escapable, and its exit is not a clock.',
+    message:
+      'A reader with scripting switched off received opacity: 0 and no way out of it. A hidden state is\n' +
+      '  allowed in exactly two shapes: an escapable condition, or a script-armed ancestor attribute. The\n' +
+      '  arming attribute has one writer, the module that writes it withdraws it on every path including\n' +
+      '      load, and an inlined listener covers the reader whose scripting started and stopped.',
+    why:
+      'A fallback animation\'s clock starts at first style resolution rather than at scroll, so by the\n' +
+      '      time the class lands there is nothing left to cancel. Cancellability was never the\n' +
+      '      load-bearing property; having an exit that does not depend on a clock was.',
+  },
+
+  pin: {
+    title: 'The design system is pinned exactly, and the token package is the component package\'s dependency rather than the site\'s.',
+    message:
+      'The pinned package is the whole cross-repository contract, so the pin is an exact version and the\n' +
+      '  token package is not a dependency of this repository: `@nanisoft/prism-ui` declares it at an\n' +
+      '      exact version, so a consumer cannot be handed a mismatched pair, and a second declaration of\n' +
+      '      that number in a consumer is a second fact to keep in step with a release.',
+    why:
+      'The four repositories each declared the token version beside the component version, in a\n' +
+      '      workspace configuration file as well as a manifest, so there were five places holding the\n' +
+      '      same pair and no gate that could read all five. One site spent a release on the wrong line\n' +
+      '      because nothing failed.',
+  },
+}
+
+/** The ids, in the order they are declared. The order a report prints them in. */
+export const LAW_IDS = Object.keys(LAWS)
+
+/**
+ * One law by id, or a throw naming the ones that exist.
+ *
+ * A `throw` rather than a default, because a caller that misspells an id and
+ * receives an empty law gets a gate that runs and prints nothing, which is the
+ * failure this file exists to remove.
+ */
+export function law(id) {
+  const found = LAWS[id]
+  if (!found) {
+    throw new Error(
+      `prism-gates: unknown law "${id}". The kit enforces: ${LAW_IDS.join(', ')}.`,
+    )
+  }
+  return { id, ...found }
+}