@nanisoft/prism-ui 0.7.0 → 0.8.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanisoft/prism-ui",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Prism's React component, block and page library.",
   "license": "MIT",
@@ -57,10 +57,21 @@
       "default": "./dist/catalog.js"
     },
     "./styles.css": "./dist/styles.css",
+    "./gates": {
+      "default": "./gates/index.mjs"
+    },
+    "./gates/*": {
+      "default": "./gates/*.mjs"
+    },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "prism-gates": "./gates/cli.mjs"
+  },
   "files": [
     "dist",
+    "gates",
+    "!gates/__tests__",
     "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
@@ -101,7 +112,8 @@
     "sync": "node scripts/sync-registry.mjs",
     "validate": "node scripts/validate-registry.mjs",
     "build": "node scripts/build.mjs && pnpm sync && pnpm validate && node scripts/check-catalogue.mjs && shadcn build && node scripts/check-surface.mjs && node scripts/check-focus-indicators.mjs && node scripts/check-item-docs.mjs && node scripts/check-block-copy.mjs && node scripts/check-item-category.mjs && node scripts/check-block-imports.mjs",
-    "check": "node scripts/validate-registry.mjs && node scripts/check-catalogue.mjs && node scripts/check-surface.mjs && node scripts/check-focus-indicators.mjs && node scripts/check-pack-boundary.mjs && node scripts/check-vector-ink.mjs && node scripts/check-client-budget.mjs && node scripts/check-theme-resolution.mjs && node scripts/check-boot-budget.mjs && node scripts/check-item-docs.mjs && node scripts/check-block-copy.mjs && node scripts/check-item-category.mjs && node scripts/check-block-imports.mjs",
+    "check": "node scripts/validate-registry.mjs && node scripts/check-catalogue.mjs && node scripts/check-surface.mjs && node scripts/check-focus-indicators.mjs && node scripts/check-pack-boundary.mjs && node scripts/check-vector-ink.mjs && node scripts/check-client-budget.mjs && node scripts/check-theme-resolution.mjs && node scripts/check-boot-budget.mjs && node scripts/check-item-docs.mjs && node scripts/check-block-copy.mjs && node scripts/check-item-category.mjs && node scripts/check-block-imports.mjs && node scripts/check-gate-kit.mjs",
+    "check:gate-kit": "node scripts/check-gate-kit.mjs",
     "check:vector-ink": "node scripts/check-vector-ink.mjs",
     "check:client-budget": "node scripts/check-client-budget.mjs",
     "check:pack-boundary": "node scripts/check-pack-boundary.mjs",