@nanisoft/prism-ui 0.7.0 → 0.9.0

package/gates/run.mjs

@@ -0,0 +1,320 @@
+/**
+ * The kit's shared machinery, and the one place a consumer's design system is
+ * resolved.
+ *
+ * Three things live here because all six gates need them and a consumer must
+ * only write them once:
+ *
+ *   1. **Resolution of the design system.** A gate reads the token contract and
+ *      the emitted base rules, and it reads them *through the component
+ *      package's own dependency*, not through the consumer's. That is the whole
+ *      reason a consumer no longer declares `@nanisoft/prism-tokens`: the file
+ *      belongs to the package that owns it, and the package that owns it is the
+ *      one the consumer pinned exactly. A second declaration of the token
+ *      version in a consumer is a second fact to keep in step with a release.
+ *   2. **The CSS scanner**, shared by the ownership, token-read, hidden-state
+ *      and pack-boundary gates, so four gates cannot disagree about what a
+ *      declaration is. Comments are blanked rather than removed, so a finding
+ *      names the line a reader has to edit.
+ *   3. **The report shape**, so every gate says what it read, names every
+ *      exclusion, and fails when it read less than its floor.
+ *
+ * A gate that can read nothing must fail. `floor()` is that: it is called by
+ * every gate on the number it is about to be judged on, and it throws rather
+ * than warning, because a run that scanned an empty export directory and
+ * reported zero findings is indistinguishable from a clean repository.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+/** The component package's name. The one package a consumer of the kit pins. */
+export const PACKAGE = '@nanisoft/prism-ui'
+
+/** The token package's name, and the fact that it is the component package's dependency. */
+export const TOKEN_PACKAGE = '@nanisoft/prism-tokens'
+
+/**
+ * A gate read less than it needed to read.
+ *
+ * Its own class rather than a generic `Error`, so the report can name it as a
+ * coverage failure instead of a crash: the difference matters, because a crash
+ * reads as "the gate is broken" and a coverage failure reads as "the gate saw
+ * nothing", and only the second is true.
+ */
+export class CoverageError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'CoverageError'
+  }
+}
+
+/**
+ * Fail the run when `actual` is below `floor`.
+ *
+ * `what` is the unit, because "read 0" is meaningless and "read 0 routes" is a
+ * diagnosis. The message says what a reader has to do, which is the whole
+ * reason this is a function and not a number in each gate.
+ */
+export function floor(what, actual, minimum) {
+  if (actual >= minimum) return actual
+  throw new CoverageError(
+    `${what} ${actual} and this gate needs at least ${minimum}. A gate that read nothing reports\n` +
+      `  zero findings, and a zero-finding report is indistinguishable from a clean repository.`,
+  )
+}
+
+/* ------------------------------------------------------------------ reading */
+
+/** Directories no gate ever reads. Printed on every run, because an exclusion is arguable. */
+export const SKIP_DIRECTORIES = [
+  '.git',
+  '.next',
+  '.source',
+  '.wrangler',
+  'coverage',
+  'node_modules',
+  'out',
+]
+
+/**
+ * Every file under `root`, as forward-slashed relative paths, depth first and
+ * sorted, with `skip` pruned rather than filtered afterwards.
+ *
+ * Sorted because a gate's output order is a reader's reading order and a
+ * filesystem's order is not one.
+ */
+export function walk(root, { skip = SKIP_DIRECTORIES, extensions = null } = {}) {
+  const pruned = new Set(skip)
+  const found = []
+  const visit = (dir) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (pruned.has(entry.name)) continue
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) visit(full)
+      else if (extensions === null || extensions.some((pattern) => pattern.test(entry.name))) {
+        found.push(path.relative(root, full).split(path.sep).join('/'))
+      }
+    }
+  }
+  visit(root)
+  return found
+}
+
+/** Read a file under `root`, or return null when it is absent. */
+export function read(root, relative) {
+  try {
+    return readFileSync(path.join(root, relative), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/** Read a JSON file under `root`, or return null when it is absent or malformed. */
+export function readJson(root, relative) {
+  const text = read(root, relative)
+  if (text === null) return null
+  try {
+    return JSON.parse(text)
+  } catch (cause) {
+    throw new Error(`${relative} is not valid JSON: ${cause.message}`)
+  }
+}
+
+/** Fail the run when a declared root does not resolve, naming the file. */
+export function requireRoot(root, relative) {
+  const full = path.join(root, relative)
+  if (!existsSync(full) || !statSync(full).isFile()) {
+    throw new CoverageError(
+      `${relative} does not resolve, so this gate cannot read what it was pointed at. ` +
+        `A renamed file empties a run and an emptied run reports a clean repository.`,
+    )
+  }
+  return full
+}
+
+/* ------------------------------------------------- the design system, resolved */
+
+/**
+ * The consumer's installed design system, reached through its own export map.
+ *
+ * Everything a gate knows about tokens comes from here, so a gate never has to
+ * be told where the token package is and a consumer never has to declare it.
+ * `createRequire` is seeded with the *component* package's `package.json`, which
+ * is itself a published export, so the token package is resolved as a dependency
+ * of the thing that owns it rather than as a top-level lookup in the consumer.
+ */
+export function designSystem(root) {
+  const fromConsumer = createRequire(path.join(root, 'package.json'))
+  let manifestPath
+  try {
+    manifestPath = fromConsumer.resolve(`${PACKAGE}/package.json`)
+  } catch (cause) {
+    throw new CoverageError(
+      `the pinned design system does not resolve from ${PACKAGE}/package.json (${cause.message}).\n` +
+        `  Every judgement about tokens and base rules is a guess without it. Run pnpm install first.`,
+    )
+  }
+  const packageRoot = path.dirname(manifestPath)
+  const require = createRequire(manifestPath)
+  const version = JSON.parse(readFileSync(manifestPath, 'utf8')).version
+
+  return {
+    version,
+    packageRoot,
+    /** The one emitted stylesheet, which carries the token blocks and the base layer. */
+    styles() {
+      try {
+        return readFileSync(require.resolve(`${PACKAGE}/styles.css`), 'utf8')
+      } catch (cause) {
+        throw new CoverageError(
+          `${PACKAGE}/styles.css does not resolve (${cause.message}), so the token contract and the\n` +
+            '  base rules cannot be read and every judgement about them would be a guess.',
+        )
+      }
+    },
+    /**
+     * The published per-pack block for one pack and mode, as the token package
+     * emits it. Resolved through the component package's dependency, which is
+     * why a consumer does not declare the token package itself.
+     */
+    tokenTheme(pack, mode) {
+      try {
+        const file = require.resolve(`${TOKEN_PACKAGE}/dist/themes/${pack}/${mode}.css`)
+        return properties(readFileSync(file, 'utf8'))
+      } catch (cause) {
+        throw new CoverageError(
+          `the token package's ${pack} ${mode} block does not resolve through ${PACKAGE} ` +
+            `(${cause.message}).\n  A boundary resolves this file's values in both modes, so without it the\n` +
+            '  both-modes check cannot run at all.',
+        )
+      }
+    },
+  }
+}
+
+/* ------------------------------------------------------------------- the css */
+
+/**
+ * Blank comments rather than removing them, so every line number a finding
+ * prints is still the line a reader has to edit.
+ */
+export function blankComments(source) {
+  const out = source.split('')
+  for (let i = 0; i < out.length; i += 1) {
+    if (out[i] === '/' && out[i + 1] === '*') {
+      const close = source.indexOf('*/', i + 2)
+      const end = close === -1 ? out.length : close + 2
+      for (let k = i; k < end; k += 1) if (out[k] !== '\n') out[k] = ' '
+      i = end - 1
+    } else if (out[i] === '/' && out[i + 1] === '/') {
+      let end = source.indexOf('\n', i)
+      if (end === -1) end = source.length
+      for (let k = i; k < end; k += 1) out[k] = ' '
+      i = end - 1
+    }
+  }
+  return out.join('')
+}
+
+/**
+ * Split a stylesheet into `selector { declarations }`, keeping the line each
+ * block starts on. A declaration parser rather than a cascade resolution, and
+ * the difference is printed on every run: this cannot see a class-scoped rule
+ * that competes, an inline style prop, or a sheet it was not pointed at.
+ */
+export function cssBlocks(source) {
+  const blanked = blankComments(source)
+  const blocks = []
+  for (const match of blanked.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    blocks.push({
+      selectors: splitSelectors(match[1]),
+      body: match[2],
+      line: blanked.slice(0, match.index).split('\n').length,
+    })
+  }
+  return blocks
+}
+
+/**
+ * A selector list, split on the commas that separate selectors.
+ *
+ * Not `split(',')`, because a comma inside `:where(a, b)` or `:is()` separates
+ * arguments rather than selectors, and splitting there makes the tail look like a
+ * bare-element selector: `.site :where(a, b)` would report `b)` as an unclassed
+ * element rule that declares a property the design system owns. A gate that
+ * reports a false positive on ordinary modern CSS is a gate that gets switched
+ * off, so the parentheses are tracked and the split only happens at depth zero.
+ */
+export function splitSelectors(text) {
+  const parts = []
+  let depth = 0
+  let current = ''
+  for (const character of text) {
+    if (character === '(') depth += 1
+    else if (character === ')') depth = Math.max(0, depth - 1)
+    if (character === ',' && depth === 0) {
+      parts.push(current)
+      current = ''
+      continue
+    }
+    current += character
+  }
+  parts.push(current)
+  return parts.map((part) => part.trim()).filter(Boolean)
+}
+
+/** The custom properties a declaration list declares, `--name` included. */
+export function properties(body) {
+  return new Map([...body.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)].map((m) => [m[1], m[2].trim()]))
+}
+
+/** Every custom property name a stylesheet declares. */
+export function declaredProperties(css) {
+  return new Set([...css.matchAll(/(--[a-z0-9-]+)\s*:/g)].map((m) => m[1]))
+}
+
+/**
+ * Two colours are the same colour however they are written.
+ *
+ * A minifier shortens `#ffffff` to `#fff`, and a value read from an emitted
+ * sheet compared byte for byte against the contract reports a difference that is
+ * not one. Normalising is what lets a gate compare values rather than spellings.
+ */
+export function sameColour(left, right) {
+  const expand = (value) => {
+    const hex = /^#([0-9a-f]{3,8})$/i.exec(String(value).trim())
+    if (!hex) return String(value).trim().toLowerCase()
+    const digits = hex[1]
+    return digits.length === 3 || digits.length === 4
+      ? `#${[...digits].map((digit) => digit + digit).join('')}`.toLowerCase()
+      : `#${digits}`.toLowerCase()
+  }
+  return expand(left) === expand(right)
+}
+
+/* ---------------------------------------------------------------- reporting */
+
+/**
+ * One finding, formatted the way every gate formats one, so a reader who has
+ * seen one finding has seen every finding.
+ *
+ * `where` is the file and line a reader has to edit, `tag` is the class of the
+ * defect, and `body` is what it is. The law is not repeated per finding: it is
+ * printed once at the end, because a message repeated per finding is a message
+ * a reader learns to skip.
+ */
+export function finding(where, tag, body) {
+  return `error ${where}  [${tag}]  ${body}`
+}
+
+/** A note the run prints, so coverage and exclusions are on every run. */
+export function note(text) {
+  return text
+}

package/gates/runtime-token-read.mjs

@@ -0,0 +1,129 @@
+/**
+ * The token-read law's runtime form: no token is read at runtime.
+ *
+ * The clause was written about canvas, because a canvas reads a computed style
+ * from one element and paints it into pixels. The pack is a runtime attribute on
+ * an ancestor, so a scoped boundary hands that read the pack's light values on a
+ * dark page, and a painted pixel does not move when the pack beneath it changes.
+ * A reader with dark mode stored and a reader without it are served different
+ * colours from the same markup, and nothing in the rendered page says so.
+ *
+ * It generalises from canvas to any runtime token read, and it holds its shape
+ * from the original clause: **a read with a hard-coded fallback is a read that
+ * cannot fail, and a read that cannot fail hides its own failure.** The token
+ * build publishes the replacement, which is a token-driven inline replacement
+ * painted in the HTML: it resolves through the cascade, holds every pack, and
+ * ships no client code. So the fix is deletion rather than repair, and this gate
+ * asserts the deletion.
+ *
+ * What this gate does not do is forbid client code. Three of the four consumer
+ * repositories ship none and one ships exactly one component for a reason its own
+ * gate explains; whether a given repository has a client boundary is that
+ * repository's business, and a gate that forbade one would be a law about one
+ * site's structure pretending to be a law about all of them. What is universal is
+ * the read, because a read resolves once and paints a value that never follows the
+ * cascade.
+ *
+ * Coverage is asserted: the declared roots must hold at least as many source files
+ * as the consumer declares as its floor, so a renamed directory cannot empty this
+ * run and report a repository that reads nothing.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+import { law } from './laws.mjs'
+import { CoverageError, finding, floor } from './run.mjs'
+
+/** Every way a program resolves a custom property from a live element. */
+const RUNTIME_READ = /getPropertyValue|getComputedStyle|documentElement\.style\.|style\.setProperty/
+
+/** The retired line's runtime read helpers, which a half-finished removal leaves behind. */
+const RETIRED_READS = /prismCssVarKey|prismBrandPacks|PrismThemeModeProvider/
+
+/** How a canvas or an inline replacement is painted, for the message that names the fix. */
+const PAINTS = /getContext\(|<canvas|document\.createElement\(['"]canvas['"]\)/
+
+export function run({ root, config }) {
+  const l = law('runtime-token-read')
+  const findings = []
+  const notes = []
+  const sourceRoots = config.sourceRoots ?? ['app', 'components', 'lib']
+  const minFiles = config.minFiles ?? 5
+
+  const missing = sourceRoots.filter((declared) => !existsSync(path.join(root, declared)))
+  if (missing.length > 0) {
+    throw new CoverageError(
+      `${missing.length} of ${sourceRoots.length} declared source roots do not resolve: ${missing.join(', ')}.\n` +
+        '  A gate that read nothing reports a repository that reads nothing, which is the cleanest possible\n' +
+        '  reading of this law and the one this gate must never give by accident.',
+    )
+  }
+
+  const skip = new Set(['node_modules', '.next', 'out', '.git', '.wrangler', '.source'])
+  const files = []
+  const visit = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      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|jsx?)$/.test(entry.name)) files.push(full)
+    }
+  }
+  for (const declared of sourceRoots) visit(path.join(root, declared))
+  floor('source file(s)', files.length, minFiles)
+
+  const relative = (file) => path.relative(root, file).split(path.sep).join('/')
+  let clientModules = 0
+
+  for (const file of files) {
+    const source = readFileSync(file, 'utf8')
+    const where = relative(file)
+    if (/^\s*['"]use client['"]/m.test(source)) clientModules += 1
+
+    source.split('\n').forEach((line, index) => {
+      const read = line.match(RUNTIME_READ)
+      if (read) {
+        const paints = PAINTS.test(source)
+        findings.push(
+          finding(
+            `${where}:${index + 1}`,
+            'runtime-token-read',
+            `"${read[0]}" resolves a token from a live element. ${paints ? 'A canvas reads it once and paints\n' +
+              '      pixels, so a scoped boundary hands it the light values on a dark page and a painted pixel does not\n' +
+              '      move when the pack beneath it does. ' : ''}A read with a hard-coded fallback is a read that cannot\n` +
+              '      fail, and a read that cannot fail hides its own failure.',
+          ),
+        )
+      }
+      const retired = line.match(RETIRED_READS)
+      if (retired) {
+        findings.push(
+          finding(
+            `${where}:${index + 1}`,
+            'retired-runtime-read',
+            `"${retired[0]}" is the retired line's runtime read helper. The theme is two attributes on the document\n` +
+              '      element and a blocking script the design system ships.',
+          ),
+        )
+      }
+    })
+  }
+
+  notes.push(
+    `${l.id}: ${findings.length} finding(s) across ${files.length} source file(s) read, floor ${minFiles}; roots: ${sourceRoots.join(', ')}`,
+  )
+  notes.push(
+    `${l.id}: ${clientModules} module(s) carry a client directive. Whether this repository has a client boundary at\n` +
+      '      all is its own business; what is universal is the read, because a read resolves once and a resolved\n' +
+      '      value does not follow the cascade.',
+  )
+  notes.push(
+    `${l.id}: every directory this run did not read, printed so an exclusion is arguable: ${[...skip].sort().join(', ')}`,
+  )
+  notes.push(
+    `${l.id}: the honest limit: this is a lexical scan. It cannot see a computed \`import()\` or a \`require\` assembled at\n` +
+      '      runtime, and it does not attempt to decide whether a read it found is load-bearing.',
+  )
+
+  return { law: l, findings, notes }
+}

package/gates/stylesheet-ownership.mjs

@@ -0,0 +1,207 @@
+/**
+ * Two laws about one sheet: what it may not own, and what it may not read.
+ *
+ * **Ownership.** Prism's base rules sit in `@layer base` and a consumer's sheet
+ * is unlayered, so an unlayered declaration outranks a layered one at any
+ * specificity regardless of import order, and a consumer that imported its sheet
+ * first would have exactly the same outcome. The layer is not the cause of these
+ * failures; it is the reason they were invisible, because nobody can tell from a
+ * screenshot that the site won.
+ *
+ * A site declaration **competes** when it can match the same element, for a
+ * property the design system's base declares, with shorthands expanded. Two looser
+ * definitions were tried and rejected: "any declaration of a property the base
+ * declares anywhere" is 1,478 rows across this family and says that every
+ * declaration in CSS touches something a reset already sets; "any declaration of a
+ * property the base declares" is 98 rows of which 55 match no element on the
+ * current line. The list below is the narrow one, and it needs no cascade to
+ * decide: an unlayered bare-element declaration for a property the base declares
+ * **is** the defect, whatever the cascade then does with it.
+ *
+ * A focus rule is a finding whatever it declares. The design system draws its
+ * ring on the component as a `box-shadow`, so a site `outline` does not compete
+ * with it; it draws a second band over the real one, and on anything that is not
+ * a Prism Component it is the only thing standing between a keyboard reader and
+ * no indicator at all.
+ *
+ * **The token read.** A custom property that resolves to nothing does not paint a
+ * wrong colour. The declaration it appears in is invalid at computed-value time,
+ * so a shorthand erases itself and a longhand reverts to its initial value: a page
+ * ground reverts to transparent, an inherited ink reverts to the browser default,
+ * and a hairline reverts to `border-style: none`, which is a box with no edge
+ * rather than a box with a wrong-coloured one. Ninety-eight of the 219 dead reads
+ * in the four repositories were shorthands. The reference is the design system's
+ * emitted stylesheet, read through its own export map, so a renamed token is a
+ * finding rather than a silent erasure.
+ *
+ * **The runtime form is the same law.** A read in JavaScript with a hard-coded
+ * fallback is a read that cannot fail, which is why the original clause was
+ * written about canvas: the pack is a runtime attribute on an ancestor, a canvas
+ * reads a computed style from one element, and a scoped boundary hands it the
+ * pack's light values on a dark page. The shipped form of that law is the gate
+ * that forbids the client read, and a repository that has no client code has
+ * nothing left to check.
+ *
+ * Coverage: the declared sheets must resolve and must hold at least as many
+ * declarations as the site declares as its floor. A floor on *findings* would fail
+ * a correct sheet, and a floor on nothing would pass an unread one, so the floor
+ * is on declarations read.
+ */
+import { law } from './laws.mjs'
+import {
+  CoverageError,
+  blankComments,
+  cssBlocks,
+  declaredProperties,
+  designSystem,
+  finding,
+  floor,
+  read,
+} from './run.mjs'
+
+/** The properties the design system's own base layer declares, so a bare-element rule competes. */
+const COMPETING_PROPERTIES = [
+  'background',
+  'background-color',
+  'color',
+  'font-family',
+  'outline',
+  'outline-style',
+  'border-color',
+]
+
+/** Any focus selector. The design system owns the indicator; a consumer drawing one is a second one. */
+const FOCUS_SELECTOR = /:focus(-visible)?\b/
+
+/** A `color-mix()` that takes a custom property as an operand erases itself rather than repainting. */
+const DEAD_OPERAND = /color-mix\([^)]*var\(/g
+
+export function run({ root, config }) {
+  const l = law('stylesheet-ownership')
+  const readLaw = law('token-read')
+  const findings = []
+  const notes = []
+  const sheets = config.sheets ?? ['app/globals.css']
+  const supplied = config.supplied ?? {}
+  const minDeclarations = config.minDeclarations ?? 20
+
+  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 system = designSystem(root)
+  const emitted = system.styles()
+  const emittedProperties = declaredProperties(emitted)
+
+  let rules = 0
+  let declarations = 0
+  let competing = 0
+  let deadReads = 0
+
+  for (const sheet of sheets) {
+    const source = blankComments(read(root, sheet))
+    for (const block of cssBlocks(source)) {
+      rules += 1
+      for (const declaration of block.body.split(';')) {
+        if (/^[a-z-]+\s*:/.test(declaration.trim())) declarations += 1
+      }
+      for (const selector of block.selectors) {
+        if (FOCUS_SELECTOR.test(selector)) {
+          competing += 1
+          findings.push(
+            finding(
+              `${sheet}:${block.line}`,
+              'focus-indicator',
+              `${selector} draws a focus indicator in this repository's own sheet. The design system draws its\n` +
+                '      ring on the component, and a plain anchor keeps the browser\'s own. A site rule is a second\n' +
+                "      band over the first or the suppression of the second, and a shorthand whose colour token\n" +
+                '      stops resolving suppresses it rather than failing to draw one.',
+            ),
+          )
+          continue
+        }
+        // A bare-element selector: `body`, `a`, `*`, `html`. A class in the selector makes
+        // the rule this repository's own surface, which is a different question.
+        const hasClass = selector.includes('.') || selector.includes('[') || selector.includes(':')
+        if (hasClass) continue
+        for (const property of COMPETING_PROPERTIES) {
+          if (!new RegExp(`(?:^|[;{\\s])${property}\\s*:`, 'm').test(block.body)) continue
+          competing += 1
+          findings.push(
+            finding(
+              `${sheet}:${block.line}`,
+              'competes-with-base',
+              `${selector} declares ${property}, which the design system's own base layer declares. The base is\n` +
+                "      layered and this sheet is not, so this rule wins the cascade at any specificity and silently\n" +
+                "      replaces the design system's.",
+            ),
+          )
+        }
+      }
+      const dead = [...block.body.matchAll(DEAD_OPERAND)]
+      competing += dead.length
+      if (dead.length > 0) {
+        findings.push(
+          finding(
+            `${sheet}:${block.line}`,
+            'dead-operand',
+            'color-mix() takes a var() as an operand. A custom property that resolves to nothing does not paint a\n' +
+              '      wrong colour: a shorthand with one dead operand erases the whole declaration, so the rule stops\n' +
+              '      existing.',
+          ),
+        )
+      }
+    }
+  }
+
+  floor('declarations read', declarations, minDeclarations)
+
+  for (const sheet of sheets) {
+    const source = blankComments(read(root, sheet))
+    const own = declaredProperties(source)
+    for (const match of source.matchAll(/var\((--[a-z0-9-]+)/g)) {
+      const property = match[1]
+      if (own.has(property) || emittedProperties.has(property) || property in supplied) continue
+      deadReads += 1
+      const line = source.slice(0, match.index).split('\n').length
+      findings.push(
+        finding(
+          `${sheet}:${line}`,
+          'dead-read',
+          `var(${property}) names a custom property nothing declares. The declaration is invalid at\n` +
+            '      computed-value time, so a shorthand erases itself and a longhand reverts to its initial value.\n' +
+            '      This is not a wrong colour; it is no declaration at all.',
+        ),
+      )
+    }
+  }
+
+  notes.push(
+    `${l.id}: ${sheets.length} sheet(s), ${rules} rule(s) and ${declarations} declaration(s) read, floor ${minDeclarations}`,
+  )
+  notes.push(`${l.id}: sheets read: ${sheets.join(', ')}`)
+  notes.push(
+    `${l.id}: ${competing} competing declaration(s); properties the design system's base declares: ${COMPETING_PROPERTIES.join(', ')}`,
+  )
+  notes.push(
+    `${readLaw.id}: ${deadReads} dead read(s). Every var() in this repository's own sheet names a property the\n` +
+      `      emitted stylesheet declares (${emittedProperties.size} properties), the sheet itself declares, or one of\n` +
+      `      ${Object.keys(supplied).length} the build supplies.`,
+  )
+  for (const [property, why] of Object.entries(supplied)) notes.push(`${readLaw.id}:   supplied: ${property} is ${why}`)
+  notes.push(
+    `${l.id}: the reference is ${'`@nanisoft/prism-ui/styles.css`'}, resolved through the installed package's own export map,\n` +
+      '      so a renamed subpath is an error here rather than a run that reports every property as undeclared.',
+  )
+  notes.push(
+    `${l.id}: the honest limit, printed on every run: this is a text scan over selectors and declarations, not a\n` +
+      '      cascade resolution. It cannot see a class-scoped rule that competes, an inline style prop, a sheet it\n' +
+      "      was not pointed at, or a change to the design system's base layer.",
+  )
+
+  return { law: l, findings, notes, also: [readLaw] }
+}