@nanisoft/prism-ui 0.7.0 → 0.8.0

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 }
+}

package/gates/links.mjs

@@ -0,0 +1,187 @@
+/**
+ * The links law, and the one gate that outlived the migration.
+ *
+ * Four kinds of destination, four different failures, and only two of them are
+ * things this gate can decide:
+ *
+ *   1. An `href` beginning with `/` must equal an emitted route. This is the one
+ *      that breaks quietly, because a broken internal link renders exactly like a
+ *      working one and a crawler finds it a month later.
+ *   2. An `href` beginning with `#` must name an `id` the same document emits, so
+ *      a rebuilt section cannot orphan a deep link.
+ *   3. An `href` beginning with `mailto:` or `tel:` is a destination the reader's
+ *      own client handles, and is listed rather than resolved.
+ *   4. An absolute `href` to another origin is a destination off this site, and is
+ *      listed rather than resolved. This gate cannot know that a sibling site
+ *      exists, and a check that guessed would be a check that reported a network
+ *      failure as a content failure.
+ *
+ * Extraction goes through a document parser rather than a regular expression.
+ * Two titles on one of these sites serialise an ampersand, and a regex would
+ * store the escaped form and then report it as a permanent difference against
+ * itself.
+ *
+ * **An exemption list is a finding when it matches nothing.** A consumer that
+ * declares a destination it knows is broken has to say why, and the declaration
+ * is site data rather than a law: it is one site's content defect. What is a law
+ * is that the declaration must match a real destination on this build, because an
+ * exemption list that outlives its cause is a lie and a gate that accepts a new
+ * link because the list is long enough to seem plausible is not a gate.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import { law } from './laws.mjs'
+import { CoverageError, finding, floor } from './run.mjs'
+
+/**
+ * The document parser, resolved from the consumer's own dependency.
+ *
+ * The consumer owns its parser because the consumer's tests already do; a gate
+ * that carried its own would add a copy of jsdom to four repositories so that
+ * four gates could read four documents.
+ */
+function loadParser(root) {
+  try {
+    return createRequire(path.join(root, 'package.json'))('jsdom').JSDOM
+  } catch (cause) {
+    throw new CoverageError(
+      `jsdom does not resolve from this repository (${cause.message}), so no document can be parsed\n` +
+        '  and every destination in this run would be unanswerable.',
+    )
+  }
+}
+
+/** Every emitted HTML file under `outDir`, as `[absolute path, route]` pairs, sorted. */
+export function emittedRoutes(root, outDir) {
+  const out = path.join(root, outDir)
+  if (!existsSync(out)) {
+    throw new CoverageError(
+      `${outDir} does not resolve, so there is no export to read and a reader's destinations cannot be\n` +
+        '  checked at all. Run the build first.',
+    )
+  }
+  const files = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) walk(full)
+      else if (entry.name.endsWith('.html')) {
+        const relative = path.relative(out, full).split(path.sep).join('/')
+        files.push([full, relative === 'index.html' ? '/' : `/${relative.replace(/\.html$/, '')}`])
+      }
+    }
+  }
+  walk(out)
+  return files
+}
+
+export function run({ root, config }) {
+  const l = law('links')
+  const outDir = config.outDir ?? 'out'
+  const minRoutes = config.minRoutes ?? 6
+  const minAnchors = config.minAnchors ?? 0
+  const knownBroken = config.knownBroken ?? {}
+
+  const JSDOM = loadParser(root)
+  const files = emittedRoutes(root, outDir)
+  floor('route(s) read', files.length, minRoutes)
+
+  const emitted = new Set(files.map(([, route]) => route))
+  const resolves = (target) => {
+    const wanted = target.replace(/\/$/, '') || '/'
+    return emitted.has(wanted) || emitted.has(`${wanted}/`)
+  }
+
+  const findings = []
+  const internal = new Set()
+  const fragments = new Set()
+  const external = new Set()
+  const schemes = new Set()
+  const discharged = new Set()
+  let anchors = 0
+
+  for (const [file, route] of files) {
+    const document = new JSDOM(readFileSync(file, 'utf8')).window.document
+    const ids = new Set([...document.querySelectorAll('[id]')].map((element) => element.id))
+    for (const anchor of document.querySelectorAll('a[href]')) {
+      anchors += 1
+      const href = anchor.getAttribute('href') ?? ''
+      if (href === '') {
+        findings.push(
+          finding(route, 'empty-destination', 'an anchor with no href is a shape a reader has to guess at.'),
+        )
+      } else if (href.startsWith('/')) {
+        internal.add(href)
+        const target = href.split('#')[0] || route
+        const known = knownBroken[target]
+        if (known) {
+          discharged.add(target)
+        } else if (!resolves(target)) {
+          findings.push(
+            finding(
+              route,
+              'internal-destination',
+              `"${href}" is not an emitted route. Every address a reader has ever used has to keep\n` +
+                '      working, and a link that renders is a link nobody notices is broken.',
+            ),
+          )
+        }
+        if (href.includes('#')) fragments.add(`${target}${href.slice(href.indexOf('#'))}`)
+      } else if (href.startsWith('#')) {
+        fragments.add(`${route}${href}`)
+        if (!ids.has(href.slice(1))) {
+          findings.push(
+            finding(route, 'fragment', `"${href}" names an id this document does not emit.`),
+          )
+        }
+      } else if (/^(mailto:|tel):/.test(href)) {
+        schemes.add(`${href.split(':')[0]}:`)
+      } else if (/^https?:\/\//.test(href)) {
+        external.add(new URL(href).host)
+      } else {
+        findings.push(
+          finding(route, 'unclassified-destination', `"${href}" is neither internal, a fragment nor absolute.`),
+        )
+      }
+    }
+  }
+
+  floor('anchor(s) read', anchors, minAnchors)
+
+  for (const [destination] of Object.entries(knownBroken)) {
+    if (discharged.has(destination)) continue
+    findings.push(
+      finding(
+        destination,
+        'stale-exemption',
+        `this destination is declared as known-broken and this build emits no link to it. An exemption\n` +
+          '      that fires on nothing is indistinguishable from a rule that found nothing, so close it and\n' +
+          '      delete the entry in the same commit.',
+      ),
+    )
+  }
+
+  const notes = [
+    `${l.id}: ${findings.length} finding(s) across ${files.length} route(s) and ${anchors} anchor(s) read;` +
+      ` floors ${minRoutes} route(s), ${minAnchors} anchor(s)`,
+    `${l.id}: ${emitted.size} emitted route(s): ${[...emitted].sort().join(', ')}`,
+    `${l.id}: destinations resolved on this site: ${[...internal].sort().join(', ') || 'none'}`,
+    `${l.id}: fragments resolved: ${[...fragments].sort().join(', ') || 'none'}`,
+    `${l.id}: destinations off this site, listed and not resolved: ${[...external].sort().join(', ') || 'none'}`,
+  ]
+  if (schemes.size > 0) {
+    notes.push(`${l.id}: reader-handled schemes, listed and not resolved: ${[...schemes].sort().join(', ')}`)
+  }
+  notes.push(
+    `${l.id}: an off-site host is listed, not resolved. This gate cannot know that another origin exists, and a\n` +
+      '      network failure reported as a content failure is a check that teaches people to ignore it.',
+  )
+  for (const [destination] of Object.entries(knownBroken)) {
+    const state = discharged.has(destination) ? 'and still linked' : 'AND NO LONGER LINKED'
+    notes.push(`${l.id}:   declared broken, ${state}: ${destination}`)
+  }
+
+  return { law: l, findings, notes }
+}