@erclx/canon 5.59.0 → 5.61.0

package/src/design/audit.ts

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { measureDesignProse } from '@/design/budget'
+import { parseDesignDoc } from '@/design/parse'
+import { DESIGN_DOCUMENT } from '@/design/regen'
+import {
+  checkThemes,
+  readThemes,
+  scanDeclarations,
+  type ThemeResult,
+} from '@/design/themes'
+
+/** The custom property a table row names, such as `--color-accent`. */
+const PROPERTY = /--[A-Za-z0-9_-]+/g
+
+/** A custom property declaration, which a stylesheet and a Tailwind `@theme` block share. */
+const DECLARATION = /(--[A-Za-z0-9_-]+)\s*:/g
+
+/** A backticked path to a stylesheet. */
+const STYLESHEET = /`([^`\s]+\.css)`/
+
+export type TokenCheck =
+  | {
+      readonly status: 'checked'
+      readonly stylesheet: string
+      readonly properties: number
+      readonly missing: readonly string[]
+      /** One entry per theme the record declares, absent where it declares none. */
+      readonly themes?: readonly ThemeResult[]
+    }
+  | { readonly status: 'unchecked'; readonly reason: string }
+  | { readonly status: 'not-applicable'; readonly reason: string }
+
+export interface DesignAudit {
+  readonly ok: true
+  /** The record read, or null where the project holds none. */
+  readonly record: string | null
+  readonly prose: readonly string[]
+  readonly tokens: TokenCheck | null
+  /** True only when the prose is within budget and the token check ran clean. */
+  readonly clean: boolean
+}
+
+/**
+ * Reads a project's design record against the prose budget and checks each
+ * custom property its tables name against the stylesheet its lead names. It
+ * writes nothing.
+ *
+ * A token check that cannot run says why under `unchecked` and leaves `clean`
+ * false, since a check that did not look is no pass.
+ */
+export function auditDesign(root: string): DesignAudit {
+  const path = join(root, DESIGN_DOCUMENT)
+  if (!existsSync(path)) {
+    return { ok: true, record: null, prose: [], tokens: null, clean: true }
+  }
+
+  const source = readFileSync(path, 'utf8')
+  const prose = measureDesignProse(source)
+  const tokens = checkTokens(root, path, source)
+  const clean =
+    prose.length === 0 &&
+    tokens.status !== 'unchecked' &&
+    (tokens.status !== 'checked' ||
+      (tokens.missing.length === 0 &&
+        (tokens.themes ?? []).every(
+          (theme) => theme.matched && theme.missing.length === 0,
+        )))
+
+  return { ok: true, record: DESIGN_DOCUMENT, prose, tokens, clean }
+}
+
+function checkTokens(root: string, path: string, source: string): TokenCheck {
+  const doc = parseDesignDoc(path)
+  const rows = [...doc.color, ...doc.borders]
+
+  // A values record renders from a token module and carries `Value` where an
+  // intent record carries `Property`, so it has no property to compare.
+  if (!rows.some((row) => 'Property' in row)) {
+    return {
+      status: 'not-applicable',
+      reason:
+        'The record has no Property column, so it holds no property to compare.',
+    }
+  }
+
+  const lead = source.split(/^##\s/m)[0]
+  const named = lead.match(STYLESHEET)?.[1]
+  if (named === undefined) {
+    return {
+      status: 'unchecked',
+      reason: 'The lead names no stylesheet, so no property could be checked.',
+    }
+  }
+
+  const stylesheet = resolve(root, named)
+  if (!stylesheet.startsWith(resolve(root)) || !existsSync(stylesheet)) {
+    return {
+      status: 'unchecked',
+      reason: `The lead names ${named}, which does not resolve in the project.`,
+    }
+  }
+
+  const css = readFileSync(stylesheet, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+  const declared = new Set([...css.matchAll(DECLARATION)].map((m) => m[1]))
+
+  const properties = [
+    ...new Set(
+      rows.flatMap((row) =>
+        [...(row['Property']?.value.matchAll(PROPERTY) ?? [])].map((m) => m[0]),
+      ),
+    ),
+  ]
+
+  const themes = readThemes(source)
+  const colors = [
+    ...new Set(
+      doc.color.flatMap((row) =>
+        [...(row['Property']?.value.matchAll(PROPERTY) ?? [])].map((m) => m[0]),
+      ),
+    ),
+  ]
+
+  return {
+    status: 'checked',
+    stylesheet: named,
+    properties: properties.length,
+    missing: properties.filter((property) => !declared.has(property)),
+    ...(themes.length > 0 && {
+      themes: checkThemes(themes, scanDeclarations(css), colors),
+    }),
+  }
+}

package/src/design/budget.ts

@@ -1,4 +1,5 @@
 import { canonicalHeading } from '@/design/parse'
+import { stripFrontmatter } from '@/markdown/frontmatter'
 
 /**
  * The prose budget `claude/skills/design-record/references/design.md` sets for a design record, and the
@@ -91,7 +92,7 @@ function splitSections(source: string): Section[] {
   const sections: { heading: string | undefined; lines: string[] }[] = [
     { heading: undefined, lines: [] },
   ]
-  for (const line of source.split('\n')) {
+  for (const line of stripFrontmatter(source).split('\n')) {
     const match = line.match(/^##\s+(.+?)\s*$/)
     if (match) {
       sections.push({ heading: match[1], lines: [] })

package/src/design/css.ts

@@ -154,8 +154,6 @@ export function fontFaceBlock(
 }
 
 export interface CssOptions {
-  /** Prepended as a comment, naming what wrote the file and from where. */
-  readonly banner?: string
   /**
    * Component rules ride along by default; a token-only consumer opts out
    * with `false`. Pass an explicit list to emit those instead of the generic default.
@@ -173,8 +171,6 @@ export function buildDesignCss(
   tokens: DesignTokens = TOKENS,
   options: CssOptions = {},
 ): string {
-  const banner =
-    options.banner === undefined ? '' : `/* ${options.banner} */\n\n`
   const root = [':root {', ...tokenProperties(tokens), '}'].join('\n')
   const faces =
     options.embedFonts === true
@@ -193,5 +189,5 @@ export function buildDesignCss(
         : COMPONENTS
   if (components) parts.push(componentBlock(components))
 
-  return `${banner}${parts.join('\n\n')}\n`
+  return `${parts.join('\n\n')}\n`
 }

package/src/design/document.ts

@@ -5,7 +5,7 @@ import type {
   SpaceToken,
   TypeToken,
 } from '@/design/tokens'
-import { TOKENS } from '@/design/tokens'
+import { REVIEWED, TOKENS } from '@/design/tokens'
 
 /**
  * Renders `canon/DESIGN.md` from the token source.
@@ -110,6 +110,10 @@ function section(heading: string, ...blocks: string[]): string {
 
 export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
   const body = [
+    '---',
+    `reviewed: ${REVIEWED}`,
+    '---',
+    '',
     '# Design',
     '',
     LEAD,

package/src/design/themes.ts

@@ -0,0 +1,176 @@
+const RAW_FRONTMATTER = /^---\n([\s\S]*?)\n---/
+const THEMES_BLOCK = /^themes:[ \t]*\n((?:[ \t]+-[^\n]*\n?|[ \t]*\n)+)/m
+const LIST_ITEM = /^[ \t]*-[ \t]+(.*?)[ \t]*$/
+const FLOW_LIST = /^themes:[ \t]*\[(.*)\][ \t]*$/m
+const ENTRY = /\s*(?:'([^']*)'|"([^"]*)"|([^,#]*?))\s*(?:,|(?:#.*)?$)/y
+const DECLARATION = /^\s*(--[A-Za-z0-9_-]+)\s*:/
+
+/**
+ * One custom property declaration and the preludes enclosing it, outermost
+ * first. Each level holds the alternatives of its selector list, normalized so
+ * a record and a stylesheet compare equal.
+ */
+export interface ScannedDeclaration {
+  readonly property: string
+  readonly chain: readonly (readonly string[])[]
+}
+
+/**
+ * Reads the `themes:` list off the raw frontmatter block, for the reason
+ * `readReviewed` in `@/records/stale-canonical` gives. Each entry is the
+ * stylesheet prelude that opens the theme, such as `:root` or
+ * `@media (prefers-color-scheme: dark)`. A record declaring none reads as an
+ * empty list.
+ */
+export function readThemes(source: string): string[] {
+  const block = RAW_FRONTMATTER.exec(source.replaceAll('\r\n', '\n'))?.[1]
+  if (!block) return []
+
+  const flow = FLOW_LIST.exec(block)?.[1]
+  const list = THEMES_BLOCK.exec(`${block}\n`)?.[1]
+  const entries =
+    flow !== undefined
+      ? splitEntries(flow)
+      : (list ?? '')
+          .split('\n')
+          .map((line) => LIST_ITEM.exec(line)?.[1])
+          .filter((item): item is string => item !== undefined)
+          .flatMap((item) => splitEntries(item).slice(0, 1))
+
+  return entries.filter((entry) => entry !== '')
+}
+
+/**
+ * Splits a flow list or one block item into entries, honoring quotes and
+ * dropping a trailing ` #` comment, since a selector may carry a comma or a
+ * hash inside quotes.
+ */
+function splitEntries(text: string): string[] {
+  const out: string[] = []
+  ENTRY.lastIndex = 0
+  while (ENTRY.lastIndex < text.length) {
+    const match = ENTRY.exec(text)
+    if (match === null || match[0] === '') break
+    out.push((match[1] ?? match[2] ?? match[3] ?? '').trim())
+  }
+  return out
+}
+
+/**
+ * Collapses the differences a hand-written prelude carries: runs of
+ * whitespace, the quote style around an attribute value, and spacing inside
+ * an at-rule condition.
+ */
+export function normalizePrelude(prelude: string): string {
+  const flat = prelude.replace(/\s+/g, ' ').trim()
+  if (flat.startsWith('@')) return flat.replace(/\s*:\s*/g, ': ')
+  return flat
+    .replace(
+      /\[\s*([^\]=\s]+)\s*=\s*["']?([^"'\]]*?)["']?\s*\]/g,
+      (_, name: string, value: string) => `[${name}=${value}]`,
+    )
+    .replace(/\s*([>+~])\s*/g, ' $1 ')
+    .replace(/\s+/g, ' ')
+}
+
+/** Splits a selector list at its top-level commas, and leaves an at-rule whole. */
+function members(prelude: string): string[] {
+  if (prelude.trimStart().startsWith('@')) return [normalizePrelude(prelude)]
+
+  const out: string[] = []
+  let depth = 0
+  let start = 0
+  for (let index = 0; index < prelude.length; index += 1) {
+    const char = prelude[index]
+    if (char === '(' || char === '[') depth += 1
+    else if (char === ')' || char === ']') depth -= 1
+    else if (char === ',' && depth === 0) {
+      out.push(prelude.slice(start, index))
+      start = index + 1
+    }
+  }
+  out.push(prelude.slice(start))
+  return out.map(normalizePrelude).filter((member) => member !== '')
+}
+
+/**
+ * Walks a stylesheet and returns every custom property declaration with the
+ * block chain around it.
+ */
+export function scanDeclarations(css: string): ScannedDeclaration[] {
+  const source = css.replace(/\/\*[\s\S]*?\*\//g, '')
+  const found: ScannedDeclaration[] = []
+  const stack: (readonly string[])[] = []
+  let buffer = ''
+
+  const flush = (): void => {
+    const property = DECLARATION.exec(buffer)?.[1]
+    if (property !== undefined) found.push({ property, chain: [...stack] })
+    buffer = ''
+  }
+
+  for (const char of source) {
+    if (char === '{') {
+      stack.push(members(buffer))
+      buffer = ''
+    } else if (char === '}') {
+      flush()
+      stack.pop()
+    } else if (char === ';') {
+      flush()
+    } else {
+      buffer += char
+    }
+  }
+  flush()
+
+  return found
+}
+
+export interface ThemeResult {
+  readonly selector: string
+  /** False when no block in the stylesheet opens this theme. */
+  readonly matched: boolean
+  /** Properties the record names that the theme's blocks do not declare. */
+  readonly missing: readonly string[]
+}
+
+/**
+ * Checks each declared theme for the properties given. A declaration counts
+ * for the outermost enclosing prelude that is a declared theme, so a `:root`
+ * inside a declared media query belongs to the query and never to the light
+ * `:root` as well, and `:root` never matches `:root[data-theme='dark']` by
+ * containment.
+ */
+export function checkThemes(
+  themes: readonly string[],
+  declarations: readonly ScannedDeclaration[],
+  properties: readonly string[],
+): ThemeResult[] {
+  const declared = new Set(themes.map(normalizePrelude))
+  const owned = new Map<string, Set<string>>()
+
+  for (const { property, chain } of declarations) {
+    const level = chain.find((alternatives) =>
+      alternatives.some((prelude) => declared.has(prelude)),
+    )
+    for (const prelude of level ?? []) {
+      if (!declared.has(prelude)) continue
+      const set = owned.get(prelude) ?? new Set<string>()
+      set.add(property)
+      owned.set(prelude, set)
+    }
+  }
+
+  return themes.map((selector) => {
+    const theme = owned.get(normalizePrelude(selector))
+    return {
+      selector,
+      matched: theme !== undefined,
+      missing:
+        theme === undefined
+          ? []
+          : properties.filter((property) => !theme.has(property)),
+    }
+  })
+}

package/src/design/tokens.ts

@@ -95,6 +95,9 @@ const SANS = 'Geist Variable, DejaVu Sans, sans-serif'
 const DARK_GROUNDS = ['background', 'surface'] as const
 const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
 
+/** The day the record was last read whole, rendered into its frontmatter so `canon design regen` and the review point agree. */
+export const REVIEWED = '2026-10-24'
+
 export const TOKENS: DesignTokens = {
   personality:
     'Warm neutrals under one rust accent, set in Geist. The page reads as prose, and monospace appears only where a surface shows what a shell printed. One accent carries every count, link, and primary action.',

package/src/driver/drive.ts

@@ -1,6 +1,7 @@
 import { chromium } from 'playwright-core'
 import type { Browser, Page } from 'playwright-core'
 import { isBrowserMissing, isServerUnreachable } from '@/browser/engine'
+import { AxeEngineMissing, probeAxe } from '@/driver/probes/axe'
 import { probeDetails } from '@/driver/probes/details'
 import {
   probeDiagramGeometry,
@@ -43,6 +44,19 @@ const PROBES: Record<ProbeName, (page: Page) => Promise<Finding[]>> = {
   details: probeDetails,
   'diagram-geometry': probeDiagramGeometry,
   'diagram-strokes': probeDiagramStrokes,
+  axe: probeAxe,
+}
+
+/**
+ * Runs `axe` after every other probe a step names, whatever order the run
+ * wrote, so every probe sharing its step reads the page before the engine's
+ * script has ever loaded into it.
+ */
+function inRunOrder(names: readonly ProbeName[]): ProbeName[] {
+  return [
+    ...names.filter((name) => name !== 'axe'),
+    ...names.filter((name) => name === 'axe'),
+  ]
 }
 
 export interface DriveOptions {
@@ -60,6 +74,7 @@ export interface PassReading {
 
 export type DriverRefusal =
   | 'browser-missing'
+  | 'axe-missing'
   | 'server-unreachable'
   | 'drive-failed'
 
@@ -107,6 +122,7 @@ export async function drive(options: DriveOptions): Promise<DriverResult> {
       passes.push(...pass.passes)
     }
   } catch (error) {
+    if (error instanceof AxeEngineMissing) return failed('axe-missing', error)
     return failed(
       isServerUnreachable(error) ? 'server-unreachable' : 'drive-failed',
       error,
@@ -159,7 +175,7 @@ async function driveViewport(
 
       const names = stepProbes(options.plan, step)
       let count = 0
-      for (const name of names) {
+      for (const name of inRunOrder(names)) {
         const probe = PROBES[name]
         for (const finding of await probe(page)) {
           findings.push({ ...finding, step: step.name, viewport: where })

package/src/driver/probes/axe.ts

@@ -0,0 +1,195 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import type { Page } from 'playwright-core'
+import type { Finding } from '@/driver/steps'
+
+/**
+ * Runs axe-core on the WCAG A and AA tags and reports what it found, marking
+ * the findings a UI review holds open on.
+ *
+ * The engine is canon's own dependency and is read from canon's install at run
+ * time, so nothing reaches a target's manifest or production build.
+ *
+ * The bundle assigns `window.axe`, `doT`, and `_encodeHTML` as it loads, and
+ * registers with any AMD loader the page carries. It is evaluated with
+ * `define`, `module`, and `exports` shadowed, and every global it added or
+ * replaced as it loaded is put back once the run settles, so a page owning a
+ * global named `axe` keeps it, a global the page sets during the run survives,
+ * and a probe running after this one reads the page it found.
+ */
+
+/** The tags the groundwork measured on, which together are WCAG 2.2 A and AA. */
+const TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa']
+
+/**
+ * The rules a violation of which keeps a UI review open. Each raised no false
+ * finding across frameboard's real screens, and a rule moves to report-only on
+ * its first false finding on a real pull request.
+ *
+ * `label-content-name-mismatch` stays off it as a text heuristic, and every
+ * incomplete result stays off it as axe saying it could not decide.
+ */
+export const AXE_GATE_RULES: readonly string[] = [
+  'color-contrast',
+  'target-size',
+  'button-name',
+  'link-name',
+  'input-button-name',
+  'select-name',
+  'label',
+  'image-alt',
+  'document-title',
+  'html-has-lang',
+  'html-lang-valid',
+  'aria-valid-attr',
+  'aria-required-attr',
+  'aria-roles',
+  'nested-interactive',
+]
+
+const ENGINE = 'axe-core/axe.min.js'
+
+/**
+ * The engine was not where canon's install should hold it. Thrown rather than
+ * returned as an empty list, since no findings and no engine read the same to
+ * a caller counting findings.
+ */
+export class AxeEngineMissing extends Error {
+  override readonly name = 'AxeEngineMissing'
+}
+
+/** Reads the engine bundle out of canon's own install. */
+export function readAxeEngine(specifier: string = ENGINE): string {
+  try {
+    const path = createRequire(import.meta.url).resolve(specifier)
+    return readFileSync(path, 'utf8')
+  } catch (error) {
+    throw new AxeEngineMissing(
+      `axe-core did not resolve from canon's install as ${specifier}. ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    )
+  }
+}
+
+let cached: string | undefined
+
+/** Read once per process, since a drive calls the probe after every step. */
+function cachedEngine(): string {
+  cached ??= readAxeEngine()
+  return cached
+}
+
+interface Row {
+  readonly rule: string
+  readonly outcome: 'violation' | 'incomplete'
+  readonly help: string
+  readonly criteria: string
+  readonly selector: string
+  readonly summary: string
+}
+
+const OUTCOME_ORDER = { violation: 0, incomplete: 1 } as const
+
+export async function probeAxe(
+  page: Page,
+  engine: () => string = cachedEngine,
+): Promise<Finding[]> {
+  const source = engine()
+  const rows = (await page.evaluate(runner(source))) as Row[]
+  const gating = new Set(AXE_GATE_RULES)
+
+  return [...rows]
+    .sort(
+      (a, b) =>
+        OUTCOME_ORDER[a.outcome] - OUTCOME_ORDER[b.outcome] ||
+        a.rule.localeCompare(b.rule) ||
+        a.selector.localeCompare(b.selector),
+    )
+    .map((row) => ({
+      probe: 'axe' as const,
+      selector: row.selector,
+      detail:
+        row.outcome === 'violation'
+          ? row.help
+          : `${row.help}, which axe could not decide and a person reads`,
+      measured: [row.criteria, row.summary].filter(Boolean).join(': '),
+      rule: row.rule,
+      outcome: row.outcome,
+      gate: row.outcome === 'violation' && gating.has(row.rule),
+    }))
+}
+
+/**
+ * Builds the expression the page evaluates. A string rather than a function,
+ * so the bundle is evaluated by the debugging protocol, which a page's content
+ * security policy does not govern, where a `new Function` inside the page would
+ * be refused by any policy without `unsafe-eval`.
+ */
+function runner(source: string): string {
+  const options = JSON.stringify({
+    runOnly: { type: 'tag', values: TAGS },
+    resultTypes: ['violations', 'incomplete'],
+    iframes: false,
+  })
+
+  return `(async () => {
+    const scope = window
+    const before = new Map()
+    for (const key of Object.getOwnPropertyNames(scope)) {
+      before.set(key, Object.getOwnPropertyDescriptor(scope, key))
+    }
+    const prior = before.get('axe')
+
+    // The keys the bundle's load added or replaced, read once it has loaded and
+    // before the run awaits, so a global the page sets mid-run stays the page's.
+    const loaded = () =>
+      Object.getOwnPropertyNames(scope).filter((key) => {
+        const was = before.get(key)
+        if (!was) return true
+        const now = Object.getOwnPropertyDescriptor(scope, key)
+        return Boolean(now && 'value' in was && now.value !== was.value)
+      })
+    let touched
+
+    try {
+      ;(function (define, module, exports) {
+${source}
+      }).call(scope)
+      touched = loaded()
+
+      const engine = scope.axe
+      if (!engine || engine === prior?.value || typeof engine.run !== 'function') {
+        throw new Error('the page holds window.axe in a property the engine could not replace')
+      }
+
+      const result = await engine.run(document, ${options})
+      const rows = []
+      const read = (outcome, rules) => {
+        for (const rule of rules) {
+          const criteria = rule.tags.filter((tag) => /^wcag\\d{3,}$/.test(tag)).join(' ')
+          for (const node of rule.nodes) {
+            rows.push({
+              rule: rule.id,
+              outcome,
+              help: rule.help,
+              criteria,
+              selector: node.target.map((part) => [].concat(part).join(' >>> ')).join(' '),
+              summary: (node.failureSummary || '').replace(/\\s+/g, ' ').trim(),
+            })
+          }
+        }
+      }
+      read('violation', result.violations)
+      read('incomplete', result.incomplete)
+      return rows
+    } finally {
+      // A load that threw partway set nothing the page could have raced, so
+      // the keys that differ now are all the bundle's.
+      for (const key of touched ?? loaded()) {
+        const was = before.get(key)
+        if (was) Object.defineProperty(scope, key, was)
+        else delete scope[key]
+      }
+    }
+  })()`
+}

package/src/driver/steps.ts

@@ -28,10 +28,20 @@ export const PROBE_NAMES = [
   'details',
   'diagram-geometry',
   'diagram-strokes',
+  'axe',
 ] as const
 
 export type ProbeName = (typeof PROBE_NAMES)[number]
 
+/**
+ * What a run that names no list measures. `axe` is left out because it loads a
+ * third-party script into the page under test, which a run opts into by name
+ * rather than inheriting.
+ */
+export const DEFAULT_PROBES: readonly ProbeName[] = PROBE_NAMES.filter(
+  (name) => name !== 'axe',
+)
+
 /**
  * One thing a probe measured and judged wrong. The step and the viewport are
  * filled in by the orchestrator rather than by the probe, since a probe runs
@@ -44,6 +54,15 @@ export interface Finding {
   readonly selector: string
   readonly detail: string
   readonly measured: string
+  /** The engine rule that raised it, set by a probe that delegates to one. */
+  readonly rule?: string
+  /** Whether the engine judged the element or declined to decide. */
+  readonly outcome?: 'violation' | 'incomplete'
+  /**
+   * True when the finding is one a review holds open on. The probe sets it and
+   * still never gates, since a gate belongs to the reader, not to this command.
+   */
+  readonly gate?: boolean
 }
 
 /** A finding once the run has said where it happened. */
@@ -169,7 +188,7 @@ export function readDriverPlan(source: string): PlanRead {
 
 /** Returns the parsed list, or the message naming what failed. */
 function readProbeList(value: unknown): ProbeName[] | string {
-  if (value === undefined) return [...PROBE_NAMES]
+  if (value === undefined) return [...DEFAULT_PROBES]
   if (!Array.isArray(value)) return 'probes is not a list'
 
   const names: ProbeName[] = []