division-ds 0.0.0-stage → 0.1.0

package/scripts/lib/props-validator.mjs

@@ -0,0 +1,320 @@
+// The props validator: every JSX element that is a Division DS component, checked against the
+// component manifest (public/manifest/components.json). Run in a consumer project through
+// `division-ds check` (scripts/division-ds.mjs); this file is the pure function it wraps, the
+// same split the other gates use, so the rules are unit-testable without a filesystem.
+//
+// Why it exists. Inside this repository `tsc` catches a wrong prop. An agent writing a screen in
+// another project often has no type-check in its loop (a JS project, a sandbox, a file it never
+// compiles), and the two mistakes it makes are the ones a type would catch: a prop the component
+// does not take (`<Badge variant=...>`, where Badge's prop is `tone`), and an enum value that is
+// not in the union (`<Button variant="danger">`, where the value is `hostile`). Both render
+// something, so neither is visible until a person looks.
+//
+// Parsing is the TypeScript compiler's own (`ts.createSourceFile`, syntax only: no program, no
+// type-check, no tsconfig), so generics, arrow functions in attributes and fragments are read
+// exactly as the compiler reads them. A regex tag scanner like button-spacing.mjs's is enough
+// for a parent/child count; it is not enough to know which import a tag name refers to.
+//
+// What the manifest can and cannot say, and so what is checked:
+// - A props table lists the props declared in this repository, plus a `...rest` row when the
+//   component spreads native or Radix props. It never lists every inherited native attribute.
+// - Enum values: checked on every component and part, wherever a row's type is a union of string
+//   literals and the value is a literal.
+// - Unknown props: checked only on a component that is the one component its manifest entry
+//   exports. A compound entry (Dialog, Tabs, DropdownMenu, Card, ...) lists each part's own props
+//   and nothing of the Radix part underneath, so judging `<TabsTrigger asChild>` against the table
+//   would be a false positive. A false positive teaches an agent to stop reading the gate.
+// - With a `...rest` row of native attributes, an event handler or a standard HTML attribute is
+//   accepted; one the rest type names in its Omit<> is not. With a `...rest` row of a Radix
+//   component's props, any other prop is accepted (the Radix surface is not in the manifest).
+import ts from 'typescript'
+import { parseRowName, resolvePart } from './component-props.mjs'
+
+/** Always accepted on any component: React's own props, and attributes every DOM wrapper takes. */
+const ALWAYS = new Set(['key', 'ref', 'className', 'children', 'id', 'style'])
+const isAlwaysAllowed = name => ALWAYS.has(name) || /^(aria|data)-/.test(name)
+const isEventHandler = name => /^on[A-Z]/.test(name)
+
+/** The HTML and React DOM attributes a native `...rest` accepts, beyond aria-*, data-* and on*.
+ *  Generous on purpose: a missing name here is a false positive, an extra one only a miss. */
+const HTML_ATTRIBUTES = new Set(
+  (
+    'about accessKey autoCapitalize autoCorrect autoFocus autoSave contentEditable contextMenu dir draggable ' +
+    'enterKeyHint hidden inert inputMode is itemID itemProp itemRef itemScope itemType lang nonce part popover ' +
+    'popoverTarget popoverTargetAction prefix property radioGroup resource rel rev role security slot spellCheck ' +
+    'suppressContentEditableWarning suppressHydrationWarning tabIndex title translate typeof unselectable vocab ' +
+    'dangerouslySetInnerHTML defaultChecked defaultValue color results ' +
+    // forms, buttons, inputs, textareas
+    'accept alt autoComplete capture checked cols dirName disabled form formAction formEncType formMethod ' +
+    'formNoValidate formTarget height list max maxLength min minLength multiple name pattern placeholder ' +
+    'readOnly required rows size src step type value width wrap ' +
+    // anchors
+    'download href hrefLang media ping referrerPolicy target'
+  ).split(/\s+/)
+)
+
+/** Words that mean the same thing to an agent. A value in a group that is not in the union gets
+ *  the first member of its group that is: Button's `variant="hostile"` becomes "danger", and
+ *  Badge's `tone="danger"` becomes "hostile" (the system uses both words, on different props). */
+const SYNONYMS = [
+  ['hostile', 'danger', 'destructive', 'error', 'negative', 'critical', 'red'],
+  ['ok', 'success', 'positive', 'green'],
+  ['warning', 'warn', 'caution', 'amber', 'yellow'],
+  ['info', 'information', 'blue'],
+  ['secondary', 'outline', 'outlined'],
+  ['ghost', 'text', 'plain', 'link'],
+  ['quiet', 'muted', 'subtle'],
+  ['sm', 'small', 'xs'],
+  ['md', 'medium', 'default'],
+  ['lg', 'large', 'xl'],
+]
+
+/** The union member an agent most likely meant by `value`, or undefined. */
+export function synonymIn(value, literals) {
+  const group = SYNONYMS.find(words => words.includes(value.toLowerCase()))
+  return group?.find(word => literals.includes(word))
+}
+
+/** The string literals of a type cell, or null when the type is not purely a union of them
+ *  (`'sm' | 'md'` -> ['sm', 'md']; `string`, `number | 'auto'`, `ReactNode` -> null).
+ *  `undefined` members are ignored: an optional union is still the same union. */
+export function literalUnion(type) {
+  if (!type) return null
+  const members = type.split('|').map(member => member.trim()).filter(member => member && member !== 'undefined')
+  if (members.length === 0) return null
+  const values = []
+  for (const member of members) {
+    const match = member.match(/^'([^']*)'$/) || member.match(/^"([^"]*)"$/)
+    if (!match) return null
+    values.push(match[1])
+  }
+  return values
+}
+
+/** What a `...rest` row's type says: `{ open, excluded }`. `open` is 'native' for HTML attributes
+ *  (`HTMLAttributes<...>`, `ButtonHTMLAttributes<...>`), 'any' for anything else (a Radix part's
+ *  props: the manifest cannot list them). `excluded` is the Omit<> list, plus every aria-* key
+ *  when the type says it removes them (Select). */
+export function parseRest(type = '') {
+  const excluded = new Set()
+  const omit = type.match(/Omit<[\s\S]*?,\s*((?:'[^']*'\s*\|?\s*)+)>/)
+  if (omit) for (const match of omit[1].matchAll(/'([^']*)'/g)) excluded.add(match[1])
+  // `children` is left out even when omitted: a component that renders children declares its own
+  // `children` prop and Omits the native one, and the tables do not list `children` rows reliably
+  // (meta.test.ts exempts it from coverage), so the manifest cannot tell the two cases apart.
+  excluded.delete('children')
+  if (/\bminus\b[^.]*\bdata-testid\b/.test(type)) excluded.add('data-testid')
+  const minusAria = /\bminus every aria-\* key/.test(type)
+  const native = /\b\w*HTMLAttributes</.test(type) || /^HTMLAttributes/.test(type)
+  return { open: native ? 'native' : 'any', excluded, minusAria }
+}
+
+const isComponentExport = name => /^[A-Z][a-z]/.test(name) && !/Variants$/.test(name)
+
+/**
+ * The manifest, indexed by export name: `Map<exportName, spec>` where a spec is
+ * `{ entry, docs, props: Map<prop, { type, literals }>, rest, checkUnknown }`.
+ * Rows are attributed to parts the way `checkPropsTable` attributes them (component-props.mjs):
+ * a `(Part)` qualifier names one export; an unqualified row belongs to every component the
+ * entry exports.
+ */
+export function buildIndex(manifest) {
+  const index = new Map()
+  for (const entry of manifest.components ?? []) {
+    const exportNames = (entry.imports ?? []).flatMap(item => item.names).filter(isComponentExport)
+    if (exportNames.length === 0) continue
+    const components = Object.fromEntries(exportNames.map(name => [name, true]))
+    const specs = Object.fromEntries(
+      exportNames.map(name => [name, { entry: entry.name, docs: entry.docs, props: new Map(), rest: null }])
+    )
+    let unresolved = false
+    for (const row of entry.props ?? []) {
+      const parsed = parseRowName(row.name)
+      if (parsed.call) continue
+      let holders = exportNames
+      // A rest row names its part in the type cell: `(Radio) Omit<RadioGroup.Item props, ...>`.
+      const part = parsed.rest ? row.type.match(/^\(([^)]+)\)\s/)?.[1] : parsed.part
+      if (part) {
+        const target = resolvePart(part, entry.name, { components, types: {} })
+        if (!target) {
+          unresolved = true
+          continue
+        }
+        holders = [target.name]
+      }
+      if (parsed.rest) {
+        const rest = parseRest(row.type.replace(/^\([^)]+\)\s*/, ''))
+        for (const name of holders) specs[name].rest = rest
+        continue
+      }
+      if (row.type === '—') continue
+      for (const name of holders) {
+        for (const prop of parsed.props) specs[name].props.set(prop, { type: row.type, literals: literalUnion(row.type) })
+      }
+    }
+    const single = exportNames.length === 1
+    for (const name of exportNames) {
+      const spec = specs[name]
+      spec.checkUnknown = single && !unresolved && spec.rest?.open !== 'any'
+      index.set(name, spec)
+    }
+  }
+  return index
+}
+
+/** True when an import specifier is Division DS: a component path (`components/atoms|molecules|
+ *  organisms`, any prefix) or the package name. Anything else is the consumer's own code. */
+export function isDivisionSource(specifier) {
+  return /(^|\/)components\/(atoms|molecules|organisms)(\/|$)/.test(specifier) || /^division-ds(\/|$)/.test(specifier)
+}
+
+export function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0]
+    row[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const current = row[j]
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1))
+      previous = current
+    }
+  }
+  return row[b.length]
+}
+
+/** The nearest candidate to `word`, or undefined when nothing is close enough to be a typo. */
+export function closest(word, candidates) {
+  let best
+  let bestScore = Infinity
+  for (const candidate of candidates) {
+    const score = distance(word, candidate)
+    if (score < bestScore) {
+      best = candidate
+      bestScore = score
+    }
+  }
+  return bestScore <= Math.max(2, Math.floor(word.length / 3)) ? best : undefined
+}
+
+const list = values => values.map(value => `"${value}"`).join(', ')
+
+/** The literal string values an attribute's initializer can take, or null when it is not a
+ *  literal (a variable, a call, a template with substitutions). A conditional of two literals
+ *  yields both. */
+function literalValues(initializer) {
+  if (!initializer) return null
+  if (ts.isStringLiteral(initializer)) return [initializer]
+  if (!ts.isJsxExpression(initializer) || !initializer.expression) return null
+  const collect = node => {
+    while (ts.isParenthesizedExpression(node)) node = node.expression
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return [node]
+    if (ts.isConditionalExpression(node)) {
+      const whenTrue = collect(node.whenTrue)
+      const whenFalse = collect(node.whenFalse)
+      return whenTrue && whenFalse ? [...whenTrue, ...whenFalse] : null
+    }
+    return null
+  }
+  return collect(initializer.expression)
+}
+
+function scriptKind(path) {
+  if (/\.tsx$/.test(path)) return ts.ScriptKind.TSX
+  if (/\.jsx$/.test(path)) return ts.ScriptKind.JSX
+  if (/\.[cm]?js$/.test(path)) return ts.ScriptKind.JSX
+  return ts.ScriptKind.TS
+}
+
+/**
+ * Every props violation in one file: `{ path, line, column, rule, component, prop, found, fix }`.
+ * `rule` is 'unknown-prop' or 'invalid-value'. `index` comes from `buildIndex`.
+ */
+export function findPropViolations(text, path, index) {
+  const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind(path))
+  // local name -> export name, for named imports from Division DS; namespace imports by local name.
+  const named = new Map()
+  const namespaces = new Set()
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue
+    if (!isDivisionSource(statement.moduleSpecifier.text)) continue
+    const bindings = statement.importClause?.namedBindings
+    if (!bindings) continue
+    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text)
+    else for (const element of bindings.elements) named.set(element.name.text, (element.propertyName ?? element.name).text)
+  }
+  if (named.size === 0 && namespaces.size === 0) return []
+
+  const violations = []
+  const resolve = tagName => {
+    if (ts.isIdentifier(tagName)) return named.get(tagName.text)
+    if (ts.isPropertyAccessExpression(tagName) && ts.isIdentifier(tagName.expression) && namespaces.has(tagName.expression.text)) {
+      return tagName.name.text
+    }
+    return undefined
+  }
+
+  const check = element => {
+    const exportName = resolve(element.tagName)
+    const spec = exportName && index.get(exportName)
+    if (!spec) return
+    const tag = element.tagName.getText(source)
+    const known = [...spec.props.keys()]
+    for (const attribute of element.attributes.properties) {
+      if (!ts.isJsxAttribute(attribute)) continue
+      const prop = attribute.name.getText(source)
+      const at = source.getLineAndCharacterOfPosition(attribute.getStart(source))
+      const add = (rule, found, fix) =>
+        violations.push({ path, line: at.line + 1, column: at.character + 1, rule, component: tag, prop, found, fix })
+      const row = spec.props.get(prop)
+
+      if (!row) {
+        const rest = spec.rest
+        const excluded = rest && (rest.excluded.has(prop) || (rest.minusAria && /^aria-/.test(prop)))
+        if (excluded) {
+          add('unknown-prop', `<${tag} ${prop}>`, `${spec.entry} types "${prop}" away on purpose. ${known.length ? `Its props: ${known.join(', ')}.` : ''} See ${spec.docs}.`.replace(/\s+/g, ' ').trim())
+          continue
+        }
+        if (!spec.checkUnknown || isAlwaysAllowed(prop)) continue
+        if (rest && (isEventHandler(prop) || HTML_ATTRIBUTES.has(prop))) continue
+        const near = closest(prop, known)
+        const hint = near
+          ? `Did you mean "${near}"?`
+          : known.length
+            ? `${tag} takes: ${known.join(', ')}${rest ? ', and native attributes' : ''}.`
+            : `${tag} takes no props of its own.`
+        add('unknown-prop', `<${tag} ${prop}>`, `${tag} has no prop "${prop}". ${hint} See ${spec.docs}.`)
+        continue
+      }
+
+      if (!row.literals) continue
+      const values = literalValues(attribute.initializer)
+      if (!values) continue
+      for (const value of values) {
+        if (row.literals.includes(value.text)) continue
+        const near = synonymIn(value.text, row.literals) ?? closest(value.text, row.literals)
+        const valueAt = source.getLineAndCharacterOfPosition(value.getStart(source))
+        violations.push({
+          path,
+          line: valueAt.line + 1,
+          column: valueAt.character + 1,
+          rule: 'invalid-value',
+          component: tag,
+          prop,
+          found: `${prop}="${value.text}"`,
+          fix: `${tag}'s ${prop} is one of ${list(row.literals)}.${near ? ` Write ${prop}="${near}".` : ''}`,
+        })
+      }
+    }
+  }
+
+  const visit = node => {
+    if (ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) check(node)
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return violations.sort((a, b) => a.line - b.line || a.column - b.column)
+}
+
+export function formatPropViolation({ path, line, column, rule, found, fix }) {
+  return `${path}:${line}:${column}  [${rule}] ${found}\n      ${fix}`
+}

package/scripts/lib/rules-installer.mjs

@@ -0,0 +1,132 @@
+// The rules installer: writes the Rules section of this repository's AGENTS.md into a consumer
+// project, for the three agents that read a file by convention. Run through
+// `division-ds rules` (scripts/division-ds.mjs); this file plans every change as data, so the
+// runner's dry run and its real run are the same code, and the tests need only a temp dir.
+//
+// Why markers and not a copy. The rules change when an agent gets something new wrong; a copy
+// pasted into another project goes stale the day it is pasted. Between namespaced markers the
+// block is replaced on every run (idempotent: a second run with the same rules changes nothing)
+// and the consumer's own text around it is never touched. `--remove` takes the block back out.
+//
+// Targets:
+//   agents  AGENTS.md                       Codex, Claude Code (via AGENTS.md), Copilot, Jules, ...
+//   cursor  .cursor/rules/division-ds.mdc   Cursor project rules; the whole file is ours
+//   gemini  GEMINI.md                       Gemini CLI
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export const START = '<!-- division-ds:start -->'
+export const END = '<!-- division-ds:end -->'
+export const TARGETS = ['agents', 'cursor', 'gemini']
+
+const FILES = {
+  agents: 'AGENTS.md',
+  cursor: '.cursor/rules/division-ds.mdc',
+  gemini: 'GEMINI.md',
+}
+
+const NOTE =
+  '> Installed by `division-ds rules`. Re-run it to update; anything between the division-ds markers is ' +
+  'overwritten. Before finishing a screen, run `npx division-ds check <files>` (Node 22 or newer): it flags a raw colour, an ' +
+  'invented token, touching buttons, an unknown prop and a wrong enum value, and says what to write instead.'
+
+/** The rules as they read in someone else's file: titled with the system's name, since "## Rules"
+ *  alone means nothing in a project with rules of its own. */
+export function rulesBody(rules) {
+  return [rules.replace(/^## Rules\b/, '## Division DS rules'), '', NOTE].join('\n')
+}
+
+/** The marked block, start and end markers included. */
+export const markedBlock = rules => `${START}\n${rulesBody(rules)}\n${END}`
+
+/** The Cursor rule file: frontmatter that attaches it to JSX/TSX files, then the rules. */
+export function cursorRule(rules) {
+  return [
+    '---',
+    'description: Division DS rules. Which component and token to use, and the composition rules prop types cannot express. Apply when writing or changing UI built with Division DS components.',
+    'globs: **/*.tsx, **/*.jsx',
+    'alwaysApply: false',
+    '---',
+    '',
+    rulesBody(rules),
+    '',
+  ].join('\n')
+}
+
+const BLOCK = new RegExp(`${escapeRegExp(START)}[\\s\\S]*?${escapeRegExp(END)}`)
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** `existing` with the block inserted (appended after a blank line) or replaced in place. */
+export function upsertBlock(existing, rules) {
+  const block = markedBlock(rules)
+  if (existing === null || existing.trim() === '') return block + '\n'
+  if (BLOCK.test(existing)) return existing.replace(BLOCK, () => block)
+  return existing.replace(/\s*$/, '') + '\n\n' + block + '\n'
+}
+
+/** `existing` with the block and the blank lines that framed it taken out. */
+export function removeBlock(existing) {
+  if (!BLOCK.test(existing)) return existing
+  const without = existing.replace(new RegExp(`\\n*${escapeRegExp(START)}[\\s\\S]*?${escapeRegExp(END)}\\n*`), '\n\n')
+  return without.replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '') + (without.trim() ? '\n' : '')
+}
+
+const read = path => (existsSync(path) ? readFileSync(path, 'utf8') : null)
+
+/**
+ * Every file change for one run, without writing anything:
+ * `[{ target, path, action, before, after }]`, where `action` is 'create', 'update', 'unchanged',
+ * 'delete' or 'absent' and `after` is null for a deletion. A file in CRLF stays in CRLF.
+ */
+export function planRules({ targetDir, rules, only = TARGETS, remove = false }) {
+  return only.map(target => {
+    const path = join(targetDir, FILES[target])
+    const raw = read(path)
+    const crlf = raw !== null && raw.includes('\r\n')
+    const before = raw === null ? null : raw.replace(/\r\n/g, '\n')
+    let after
+    if (target === 'cursor') after = remove ? null : cursorRule(rules)
+    else if (remove) after = before === null ? null : removeBlock(before)
+    else after = upsertBlock(before, rules)
+    // A file holding nothing but the block is ours: removing the block removes the file.
+    if (remove && after !== null && after.trim() === '') after = null
+
+    let action
+    if (before === null) action = after === null ? 'absent' : 'create'
+    else if (after === null) action = 'delete'
+    else action = after === before ? 'unchanged' : 'update'
+    const restore = text => (text !== null && crlf ? text.replace(/\n/g, '\r\n') : text)
+    return { target, path, action, before: raw, after: restore(after) }
+  })
+}
+
+/** Writes a plan to disk. */
+export function applyPlan(plan) {
+  for (const change of plan) {
+    if (change.action === 'create' || change.action === 'update') {
+      mkdirSync(dirname(change.path), { recursive: true })
+      writeFileSync(change.path, change.after)
+    } else if (change.action === 'delete') {
+      rmSync(change.path)
+    }
+  }
+}
+
+/** A line diff between two texts: the common head and tail are skipped, the middle is shown as
+ *  `-` and `+` lines. Enough to review a block being replaced, which is the only change made. */
+export function diff(before, after) {
+  const a = before === null ? [] : before.replace(/\r\n/g, '\n').split('\n')
+  const b = after === null ? [] : after.replace(/\r\n/g, '\n').split('\n')
+  let head = 0
+  while (head < a.length && head < b.length && a[head] === b[head]) head++
+  let tail = 0
+  while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) tail++
+  const lines = []
+  if (head > 0) lines.push(`@@ ${head} unchanged line(s) @@`)
+  for (const line of a.slice(head, a.length - tail)) lines.push(`- ${line}`)
+  for (const line of b.slice(head, b.length - tail)) lines.push(`+ ${line}`)
+  if (tail > 0) lines.push(`@@ ${tail} unchanged line(s) @@`)
+  return lines.join('\n')
+}

package/scripts/lib/token-discipline.mjs

@@ -0,0 +1,125 @@
+// The token-discipline gate's rules, as pure functions over text. The runner is
+// scripts/check-token-discipline.mjs.
+//
+// Colour comes from a token or it does not ship. Until this gate existed the components were
+// clean by convention only, and a convention is exactly what an agent new to the system cannot
+// see: a hardcoded hex renders fine, and an invented token name (`var(--color-brand)`) fails
+// silently, because an undefined custom property is not an error anywhere.
+//
+// Colour only, on purpose. Spacing is not gated: enforcing it before the scale is complete makes
+// an author (or an agent) invent a token name to satisfy the rule, which is the worse failure.
+
+export const SCANNED_ROOTS = ['src']
+export const SCANNED_EXTENSIONS = /\.(tsx?|css)$/
+
+/** Files where a literal colour is the point, each with its reason. Everything else is scanned.
+ *  A new entry needs a reason as good as these; "it was easier" is the case the gate exists for. */
+export const EXEMPT = [
+  { pattern: /^src\/styles\/tokens\.css$/, why: 'generated from tokens/: this is where the literals are meant to be' },
+  { pattern: /\.test\.tsx?$/, why: 'tests assert on literal values and on deliberately wrong input' },
+  { pattern: /^src\/demo\/(scene|blob|terrain)\//, why: 'WebGL materials: three.js takes colours as numbers, not CSS variables' },
+  { pattern: /^src\/components\/atoms\/loading-animation\/(palette|scene|kit|variants)\.ts$/, why: 'WebGL materials, read from the tokens at runtime where they can be' },
+  { pattern: /^src\/pages\/guidelines\//, why: 'the pages that display the palette, the ramps and the measured values themselves' },
+]
+
+const TOKEN_NAMESPACE = /var\(\s*(--(?:color|component|spacing|duration|ease)-[a-z0-9-]*)/g
+const PRIMITIVE_RAMP = /^--color-(signal|hostile|ok|info|warning|neutral)-\d+$/
+const HEX = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/g
+const COLOR_FUNCTION = /\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\(/g
+const PALETTE_CLASS = new RegExp(
+  '(?<![\\w-])(?:bg|text|border|ring|outline|fill|stroke|from|via|to|decoration|divide|placeholder|caret|accent|shadow)-' +
+    '(?:(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-(?:50|[1-9]00|950)' +
+    '|white|black)(?![\\w-])',
+  'g'
+)
+
+/** Blanks comments, keeping every newline so line numbers hold. A value quoted in a comment is
+ *  documentation ("raised from #6f7a88"), not a colour on the page. */
+export function stripComments(text) {
+  const blank = match => match.replace(/[^\n]/g, ' ')
+  return text.replace(/\/\*[\s\S]*?\*\//g, blank).replace(/(^|[^:'"`\\])\/\/[^\n]*/g, (match, lead) => lead + blank(match.slice(lead.length)))
+}
+
+/** Up to three real tokens closest to a name that is not one, nearest first. */
+export function suggest(name, tokenNames) {
+  const parts = name.split('-').filter(Boolean)
+  return tokenNames
+    .map(candidate => {
+      const other = candidate.split('-').filter(Boolean)
+      const shared = parts.filter(part => other.includes(part)).length
+      return { candidate, score: shared * 2 - Math.abs(other.length - parts.length) }
+    })
+    .filter(entry => entry.score > 2)
+    .sort((a, b) => b.score - a.score || a.candidate.localeCompare(b.candidate))
+    .slice(0, 3)
+    .map(entry => entry.candidate)
+}
+
+const ALLOW = /token-discipline: allow\b[\s,:-]*(.*?)\s*(?:\*\/\}?)?\s*$/
+
+/** The line numbers a `token-discipline: allow <reason>` comment covers: its own line and the
+ *  next one. The reason is required, at least a few words; a bare marker covers nothing, so the
+ *  gate reports the line as if the comment were not there. */
+export function allowedLines(text) {
+  const covered = new Set()
+  text.split('\n').forEach((line, index) => {
+    const match = line.match(ALLOW)
+    if (match && match[1].trim().split(/\s+/).length >= 3) {
+      covered.add(index + 1)
+      covered.add(index + 2)
+    }
+  })
+  return covered
+}
+
+/** How many allow comments a file carries, for the runner's summary line. */
+export const countAllows = text => text.split('\n').filter(line => ALLOW.test(line)).length
+
+const isExempt = path => EXEMPT.some(entry => entry.pattern.test(path))
+const inComponents = path => /^src\/components\/(atoms|molecules|organisms)\//.test(path)
+
+/**
+ * Every violation in one file: `{ path, line, rule, found, fix }`.
+ * `tokenNames` is every CSS variable the token build emits (public/manifest/tokens.json).
+ */
+export function findViolations(text, path, tokenNames) {
+  if (isExempt(path)) return []
+  const known = new Set(tokenNames)
+  const violations = []
+  const allowed = allowedLines(text)
+  const lines = stripComments(text).split('\n')
+  lines.forEach((line, index) => {
+    if (allowed.has(index + 1)) return
+    const add = (rule, found, fix) => violations.push({ path, line: index + 1, rule, found, fix })
+
+    for (const match of line.matchAll(TOKEN_NAMESPACE)) {
+      const name = match[1]
+      // A name ending in a hyphen is the fixed part of a computed one: var(--color-accent-${tone}-fill).
+      if (name.endsWith('-')) continue
+      if (!known.has(name)) {
+        const near = suggest(name, tokenNames)
+        add('unknown-token', `var(${name})`, near.length ? `No such token. Did you mean ${near.join(', ')}?` : 'No such token. The full list is public/manifest/tokens.json.')
+      } else if (PRIMITIVE_RAMP.test(name) && inComponents(path)) {
+        add('primitive-in-component', `var(${name})`, 'A component reads semantic tokens, not a ramp step. Pick one by intent from public/manifest/tokens.json (accent.<state>.text, .fill or .ink).')
+      }
+    }
+
+    // What is left once every var(...) and every `--name: value` on a token is out of the way is
+    // where a literal colour would be.
+    const rest = line.replace(/var\([^)]*\)/g, '')
+    for (const match of rest.matchAll(HEX)) {
+      add('raw-colour', match[0], 'Use a semantic token: text-[var(--color-text-primary)], bg-[var(--color-surface-base)]. Tokens and what each is for: public/manifest/tokens.json.')
+    }
+    for (const match of rest.matchAll(COLOR_FUNCTION)) {
+      add('raw-colour', match[0] + '…)', 'Use a semantic token. If no token fits, the colour is a change to the system: add it under tokens/ with a contrast pair.')
+    }
+    for (const match of rest.matchAll(PALETTE_CLASS)) {
+      add('palette-class', match[0], 'Tailwind\'s palette is not this system\'s. Use an arbitrary value on a token: bg-[var(--color-surface-raised)], text-[var(--color-accent-hostile-text)].')
+    }
+  })
+  return violations
+}
+
+export function formatViolation({ path, line, rule, found, fix }) {
+  return `${path}:${line}  [${rule}] ${found}\n      ${fix}`
+}