@estiva-app/ui 0.35.2 → 0.37.0

package/src/gates/gates.test.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { ESLint, type Linter } from 'eslint'
 import { afterAll, describe, expect, it } from 'vitest'
+import { countCommitted, hookRuns, skippedFolders, skipsListed } from './ci'
 import { writeGateCount } from './count'
 import { gateConfig, gateLint } from './gate-config'
 import { runHook } from './hook'
@@ -78,6 +79,18 @@ describe('tokenLint and tokenValues', () => {
     expect(await lintWith([tokenLint()], "import { cn } from '@estiva-app/ui'\nexport const merged = cn('p-2', 'p-3')\n", 'src/lib/probe.ts')).toEqual([])
   })
 
+  it('refuse a colour in a style with its key in quotes, or kept in a const (R9)', async () => {
+    const quoted = await lintWith([tokenLint(), tokenValues()], component(`<div style={{ 'background': 'red' }}>x</div>`), 'src/Probe.tsx')
+    expect(quoted.filter((m) => m.severity === 2).map((m) => m.ruleId)).toEqual(['no-restricted-syntax'])
+    const kept = `const look = { background: 'red', width: 20 } as const\n${component('<div style={look}>x</div>')}`
+    const constant = await lintWith([tokenLint(), tokenValues()], kept, 'src/Probe.tsx')
+    expect(constant.filter((m) => m.severity === 2)).toEqual([expect.objectContaining({ ruleId: 'token-style/no-token-style', line: 1 })])
+    // A size in a const, and a style worked out while it runs, pass.
+    expect((await lintWith([tokenLint(), tokenValues()], `const at = { width: 20 }\n${component('<div style={at}><div style={props.style} /></div>')}`, 'src/Probe.tsx')).filter((m) => m.severity === 2)).toEqual([])
+    // Its escape works in the gate too: the gate knows the rule's name.
+    expect(await lintWith(gateConfig(), `// eslint-disable-next-line token-style/no-token-style -- @estiva-escape: a colour the probe keeps\n${kept}`, 'src/Probe.tsx')).toEqual([])
+  })
+
   it('leave a test file to its test', async () => {
     const messages = await lintWith([tokenLint(), tokenValues()], component('<div style={{ color: "red" }}>x</div>'), 'src/Probe.test.tsx')
     expect(messages.filter((m) => m.severity === 2)).toEqual([])
@@ -147,7 +160,7 @@ describe('tokenConfig', () => {
 describe('writeGateCount', () => {
   it('writes the count once, leaves it alone when nothing changed, and fails on a rule switched off', async () => {
     const dir = app('count', {
-      'src/Kept.tsx': component('(\n    // @estiva-escape: a probe that keeps its element on purpose\n    <form />\n  )'),
+      'src/Kept.tsx': component('(\n    // @estiva-escape(no-raw-element): a probe that keeps its element on purpose\n    <form />\n  )'),
     })
     const first = await writeGateCount({ root: dir, repo: 'probe' })
     expect(first.changed).toBe(true)
@@ -164,6 +177,47 @@ describe('writeGateCount', () => {
   })
 })
 
+describe('estiva-gates ci: the steps no lint runs (B2, B13)', () => {
+  const git = (dir: string, ...args: string[]) => execFileSync('git', ['-c', 'user.name=probe', '-c', 'user.email=probe@example.com', ...args], { cwd: dir, stdio: 'ignore' })
+
+  it('fails when the count the gate writes is not the committed one', async () => {
+    const dir = app('ci-count', { 'src/Plain.tsx': component('<div>x</div>') })
+    git(dir, 'init', '-q')
+    await writeGateCount({ root: dir, repo: 'probe' })
+    git(dir, 'add', '.')
+    git(dir, 'commit', '-q', '-m', 'count')
+    expect(countCommitted(dir)).toEqual([])
+    writeFileSync(join(dir, 'src', 'Kept.tsx'), component('(\n    // @estiva-escape(no-raw-element): a probe that keeps its element on purpose\n    <form />\n  )'))
+    await writeGateCount({ root: dir, repo: 'probe' })
+    const moved = countCommitted(dir)
+    expect(moved[0]).toContain('commit `.gates-count.json`')
+    expect(moved.join('\n')).toContain('"escapes": 1')
+  })
+
+  it('fails when no hook runs before both Write and Edit, or the hook lets a raw button through', () => {
+    const cli = join(root, 'dist', 'gates', 'cli.js').split('\\').join('/')
+    const settings = (matcher: string, command: string) => JSON.stringify({ hooks: { PreToolUse: [{ matcher, hooks: [{ type: 'command', command }] }] } })
+    const dir = app('ci-hook', { '.claude/settings.json': settings('Edit|Write', `node "${cli}" hook`) })
+    expect(hookRuns(dir)).toEqual([])
+    writeFileSync(join(dir, '.claude', 'settings.json'), settings('Write', `node "${cli}" hook`))
+    expect(hookRuns(dir)[0]).toContain('before both Write and Edit')
+    writeFileSync(join(dir, '.claude', 'settings.json'), settings('Edit|Write', 'node -e "process.exit(0)"'))
+    expect(hookRuns(dir)[0]).toContain('let a raw button through')
+    rmSync(join(dir, '.claude'), { recursive: true })
+    expect(hookRuns(dir)[0]).toContain('missing')
+  })
+
+  it('fails when the gate skips a folder the debt page does not name', async () => {
+    const dir = app('ci-skips', { 'docs/GATES-DEBT.md': '# Debt\n\nNothing skipped.\n' })
+    expect(await skipsListed(dir, 'app')).toEqual([])
+    writeFileSync(join(dir, 'eslint.gates.config.js'), `import { gateConfig } from '${built}'\nexport default gateConfig({ ignores: ['demo-scenarios/**'] })\n`)
+    expect(await skippedFolders(dir)).toEqual(['demo-scenarios/**'])
+    expect((await skipsListed(dir, 'app')).join('\n')).toContain('demo-scenarios/**')
+    writeFileSync(join(dir, 'docs', 'GATES-DEBT.md'), '# Debt\n\n`demo-scenarios` is not checked: fixtures for the demo, never shipped.\n')
+    expect(await skipsListed(dir, 'app')).toEqual([])
+  })
+})
+
 describe('runHook', () => {
   const dir = app('hook', { 'src/Page.tsx': 'export function Page() {\n  return <div>x</div>\n}\n' })
   const write = (file_path: string, content: string) => ({ tool_name: 'Write', tool_input: { file_path, content } })
@@ -182,6 +236,29 @@ describe('runHook', () => {
     expect((await runHook({ root: dir, input: fine })).code).toBe(0)
   })
 
+  // B4 (Katerina, 25 September): the token contract is refused before the write, not only in CI.
+  it('refuses a hand-written size and a raw colour before the write, naming the token', async () => {
+    const result = await runHook({ root: dir, input: write('src/Probe.tsx', component('<div className="text-[13px] bg-[#ff0000]">x</div>')) })
+    expect(result.code).toBe(2)
+    expect(result.message).toContain('token-values/no-restricted-classes')
+  })
+
+  // R10: a copied look only warns, so the write goes through, with a note Claude sees.
+  it('lets a copied look through with a note, and no note when nothing is copied', async () => {
+    const own = app('hook-copied', {
+      // An app's Tailwind config, on the package preset: the token lint knows its classes from it.
+      'tailwind.config.js': `import estiva from '${pathToFileURL(join(root, 'tailwind-preset.js')).href}'\nexport default { presets: [estiva], content: ['./src/**/*.tsx'] }\n`,
+      'src/Badge.tsx': '/** A badge. */\nexport function Badge() {\n  return <span className="inline-flex items-center rounded-md border border-border-default bg-bg-elevated px-2 text-caption text-text-secondary">x</span>\n}\n',
+      // Already there, so the write is an edit of a part, not a new one the search stops.
+      'src/Probe.tsx': component('<span>y</span>'),
+    })
+    const copied = await runHook({ root: own, input: write('src/Probe.tsx', component('<span className="inline-flex items-center rounded-md border border-border-default bg-bg-elevated px-2 text-caption text-text-secondary">y</span>')) })
+    expect(copied.code).toBe(0)
+    expect(copied.note).toContain('Badge')
+    const plain = await runHook({ root: own, input: write('src/Probe.tsx', component('<span className="mt-2">y</span>')) })
+    expect(plain).toEqual({ code: 0, message: '' })
+  })
+
   // The re-review after the audit before UIG-26: only .ts and .tsx were read, so these passed.
   it('reads every script type under src: a raw button in a .jsx, a page listener in a .mts', async () => {
     expect((await runHook({ root: dir, input: write('src/Probe.jsx', component('<button type="button">x</button>')) })).code).toBe(2)
@@ -242,6 +319,14 @@ describe('gates:status', () => {
     expect(h.ciJob('gate', 'lint:rules').result).toBe('pass')
     expect(h.ciJob('check', 'lint:rules').result).toBe('fail')
     expect(h.script('package.json', 'gates:status').result).toBe('pass')
+    // A job that runs `estiva-gates ci` runs the gate's scripts (R13), and nothing else.
+    writeFileSync(join(dir, '.github', 'workflows', 'deploy.yml'), 'jobs:\n  gate:\n    steps:\n      - run: npx estiva-gates ci\n')
+    expect(h.ciJob('gate', 'lint:rules').result).toBe('pass')
+    expect(h.ciJob('gate', 'registry:check').result).toBe('pass')
+    expect(h.ci('lint:tokens').result).toBe('pass')
+    expect(h.ciJob('gate', 'test').result).toBe('fail')
+    writeFileSync(join(dir, '.github', 'workflows', 'deploy.yml'), 'jobs:\n  gate:\n    steps:\n      # - run: npx estiva-gates ci\n      - run: npm test\n')
+    expect(h.ciJob('gate', 'lint:rules').result).toBe('fail')
   })
 
   // Audit A2: a hook is judged by running it, the way Claude Code does, on a raw

package/src/gates/hook.ts

@@ -13,7 +13,9 @@
  * UIG-4 findings).
  *
  * It runs the gate's own config and reimplements nothing: a hook and a lint
- * that could disagree would be worse than neither. Tests are not checked
+ * that could disagree would be worse than neither. Since 0.36.0 it runs the
+ * token contract too, keeping only that contract's errors (B4), and a copied
+ * look, which only warns, reaches Claude as a note on a write let through (R10). Tests are not checked
  * (Katerina, 13 September); stories are. This package's inward gate reads `.tsx`
  * only, as its lint does.
  *
@@ -37,8 +39,9 @@ import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import type { ESLint as ESLintClass } from 'eslint'
+import type { ESLint as ESLintClass, Linter } from 'eslint'
 import { countGates } from '../eslint/index'
+import { tokenConfig } from './token-lint'
 import { repositoryOf } from '../registry/skill'
 
 export interface HookOptions {
@@ -59,6 +62,27 @@ export interface HookResult {
   code: 0 | 2
   /** What goes to stderr when refused. */
   message: string
+  /** A note for Claude on a write let through: a copied look, which only warns. */
+  note?: string
+}
+
+/** The token contract's own rules: what the hook keeps from its lint, and nothing else. */
+const TOKEN_RULE_IDS = new Set(tokenConfig().flatMap((c) => Object.keys(c.rules ?? {})))
+
+/**
+ * The token contract's errors for the text about to be written. The app's own
+ * token config when it has one (`eslint.tokens.config.js`, which knows the app's
+ * other plugins' names); otherwise the package's `tokenConfig`. Only the token
+ * rules' errors count, so an app's wider lint (TypeScript's, React's) never
+ * blocks a write that is still being made.
+ */
+async function tokenErrors(ESLint: typeof ESLintClass, appDir: string, file: string, text: string, audience: 'app' | 'package'): Promise<Linter.LintMessage[]> {
+  const own = join(appDir, 'eslint.tokens.config.js')
+  const eslint = existsSync(own)
+    ? new ESLint({ cwd: appDir, overrideConfigFile: own })
+    : new ESLint({ cwd: appDir, overrideConfigFile: true, overrideConfig: tokenConfig({ audience }) })
+  const results = await eslint.lintText(text, { filePath: file })
+  return results.flatMap((r) => r.messages.filter((m) => m.severity === 2 && m.ruleId && TOKEN_RULE_IDS.has(m.ruleId)))
 }
 
 interface ToolCall {
@@ -103,14 +127,24 @@ export async function runHook({ root, app = '.', audience = 'app', input, seen }
   // A rule's errors only. Code that does not parse yet (one edit of several) is
   // the typecheck's to judge; the gate looks again at the edit that completes it.
   const errors = results.flatMap((r) => r.messages.filter((m) => m.severity === 2 && m.ruleId))
+  // The token contract too (Katerina's ruling B4, 25 September): a colour or a size
+  // is refused before the write, as CI's gate refuses it, not only at the PR.
+  errors.push(...(await tokenErrors(ESLint, appDir, file, text, audience)))
   const { disabled } = countGates(results)
-  if (errors.length === 0 && disabled.length === 0) return searchFirst(call, file, text, appDir, top, seen) ?? PASS
+  if (errors.length === 0 && disabled.length === 0) {
+    const stopped = searchFirst(call, file, text, appDir, top, seen)
+    if (stopped) return stopped
+    // A copied look is a warning (C2): it never blocks, and Claude hears of it now,
+    // not only in CI (R10, 25 September).
+    const copies = results.flatMap((r) => r.messages.filter((m) => m.severity === 1 && m.ruleId === 'estiva/no-copied-look'))
+    return copies.length ? { code: 0, message: '', note: copies.map((m) => `${relative(top, file).split(sep).join('/')}:${m.line}  ${m.message}`).join('\n') } : PASS
+  }
 
   const shown = (p: string) => relative(top, p).split(sep).join('/')
   const lines = [`${shown(file)} was not written: the UI Guardrails refuse it (${shown(config)}).`]
   for (const m of errors) lines.push(`  ${m.line}:${m.column}  ${m.message}${m.ruleId ? `  (${m.ruleId})` : ''}`)
   const keep = audience === 'package' ? 'Keep it only' : 'Keep the element only'
-  for (const d of disabled) lines.push(`  ${d.line}  an eslint-disable switches ${d.ruleId} off. ${keep} with its reason on the line above: // @estiva-escape: <reason>`)
+  for (const d of disabled) lines.push(`  ${d.line}  an eslint-disable switches ${d.ruleId} off. ${keep} with its reason on the line above: // @estiva-escape(${d.ruleId.slice(d.ruleId.lastIndexOf('/') + 1)}): <reason>`)
   return { code: 2, message: `${lines.join('\n')}\n` }
 }
 

package/src/gates/index.ts

@@ -11,21 +11,25 @@
  * - `tokenConfig` — the token lint on its own, as `lint:tokens` runs it (UIG-37).
  * - `gateLint`, `gateConfig` — where the rules apply, and the gate that runs them alone.
  * - `writeGateCount` — `.gates-count.json` (seam S3).
+ * - `runCi` — CI's job `gate`, every step of it (R13).
  * - `runHook` — the editor gate a `PreToolUse` hook runs.
  * - `runStatus`, `helpers` — gates:status and the helpers a checks file is written with.
  *
  * - `appChecks` — the gate checks every app runs, for its `scripts/gates-checks.mjs`.
  * - `appFiles`, `createApp`, `themes` — a new app with every gate on (`create-estiva-app`).
  *
- * `estiva-gates` (`cli.ts`) runs the count, the hook and the status as one command.
+ * `estiva-gates` (`cli.ts`) runs the gate's CI, the count, the hook and the status as one command.
  *
  * Built by build.mjs into `dist/gates/`, for Node. Nothing here reaches the
  * components' browser bundle.
  */
 export { TOKEN_LINT_IGNORES, tokenConfig, tokenLint, tokenValues, type TokenAudience, type TokenConfigOptions, type TokenLintOptions } from './token-lint'
 export { gateConfig, gateLint, type GateConfigOptions } from './gate-config'
+export { countCommitted, hookRuns, runCi, skippedFolders, skipsListed, type CiOptions } from './ci'
 export { writeGateCount, type CountOptions, type CountResult } from './count'
 export { runHook, type HookOptions, type HookResult } from './hook'
+export { nameEscapes, type NameEscapesOptions, type NameEscapesResult } from './name-escapes'
+export { escapeLines, listEscapes, REVIEW_AFTER_DAYS, type Escape } from './escapes'
 export { ENGINE, helpers, runStatus, type CheckResult, type GateCheck, type GateHelpers, type GateSpec, type GateTicket, type LintProbe, type StatusOptions, type TicketListEntry } from './status'
 export { APP_TICKET_TITLES, appChecks, type AppCheckOptions } from './app-checks'
 export { appFiles, askNpm, createApp, themes, type CreateAppOptions } from './create-app'

package/src/gates/name-escapes.ts

@@ -0,0 +1,77 @@
+/// <reference types="node" />
+/**
+ * `estiva-gates name-escapes`: write into every escape marker the rules it keeps
+ * off, once (Katerina's ruling B3, 25 September).
+ *
+ * A marker used to keep off every rule on its element; now it keeps off only the
+ * rules it names, `// @estiva-escape(no-raw-element): <reason>`. So that nothing
+ * that was escaped breaks, this asks the gate itself which rules each unnamed
+ * marker stands for: linted with the new reader, an unnamed marker is reported
+ * once per rule that finds its element ("Name the rule … `@estiva-escape(<rule>)`"),
+ * and those names are written into the marker. Nothing is guessed, and a marker
+ * no rule reaches is left as it is and listed.
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { ESLint as ESLintClass } from 'eslint'
+
+export interface NameEscapesOptions {
+  /** The folder the gate lints from. */
+  root?: string
+  /** The gate's config file, relative to `root`. */
+  config?: string
+}
+
+export interface NameEscapesResult {
+  /** One line per marker rewritten: `file:line  rule, rule`. */
+  named: string[]
+  /** Markers no rule reached, left unnamed. */
+  unreached: string[]
+}
+
+const UNNAMED = /@estiva-escape(?!\s*\()/
+const NAMED_IN_MESSAGE = /@estiva-escape\(([^)]+)\)/
+
+export async function nameEscapes({ root = process.cwd(), config = 'eslint.gates.config.js' }: NameEscapesOptions = {}): Promise<NameEscapesResult> {
+  const resolved = createRequire(join(root, 'package.json')).resolve('eslint')
+  const { ESLint } = (await import(pathToFileURL(resolved).href)) as { ESLint: typeof ESLintClass }
+  const eslint = new ESLint({ cwd: root, overrideConfigFile: join(root, config) })
+  const results = await eslint.lintFiles(['.'])
+
+  const named: string[] = []
+  const unreached: string[] = []
+  for (const result of results) {
+    // The rules each unnamed marker stands for, by the line its comment starts on.
+    const byLine = new Map<number, Set<string>>()
+    for (const m of result.messages) {
+      if (m.messageId !== 'escapeWithoutRule') continue
+      const rule = NAMED_IN_MESSAGE.exec(m.message)?.[1]
+      if (!rule) continue
+      byLine.set(m.line, (byLine.get(m.line) ?? new Set()).add(rule))
+    }
+    const source = result.source ?? readFileSync(result.filePath, 'utf8')
+    const eol = source.includes('\r\n') ? '\r\n' : '\n'
+    const lines = source.split(/\r?\n/)
+    let changed = false
+    const file = relative(root, result.filePath).split('\\').join('/')
+    for (const [line, rules] of byLine) {
+      // The marker is on the comment's first line, or within the next few (a block comment).
+      for (let i = line - 1; i < Math.min(lines.length, line + 3); i++) {
+        if (!UNNAMED.test(lines[i])) continue
+        const names = [...rules].sort().join(', ')
+        lines[i] = lines[i].replace(UNNAMED, `@estiva-escape(${names})`)
+        named.push(`${file}:${i + 1}  ${names}`)
+        changed = true
+        break
+      }
+    }
+    if (changed) writeFileSync(result.filePath, lines.join(eol), 'utf8')
+    // Unnamed markers the gate did not report: nothing of the gate's reaches that element.
+    lines.forEach((text, i) => {
+      if (UNNAMED.test(text) && !/eslint-disable/.test(text) && /\/\/|\/\*/.test(text)) unreached.push(`${file}:${i + 1}`)
+    })
+  }
+  return { named, unreached }
+}

package/src/gates/status.ts

@@ -31,6 +31,7 @@ import { createRequire } from 'node:module'
 import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { ESLint as ESLintClass } from 'eslint'
+import { escapeLines, listEscapes } from './escapes'
 
 export type CheckResult = { result: 'pass' | 'fail' | 'part' | 'unknown'; detail: string }
 type Maybe<T> = T | Promise<T>
@@ -141,6 +142,16 @@ const said = (e: unknown) => {
   return { text: `${err.stdout ?? ''}${err.stderr ?? ''}`, message: String(err.message ?? e), code: err.code }
 }
 
+/** The scripts `estiva-gates ci` runs (R13): a job that runs it runs these. */
+const GATE_CI_SCRIPTS = new Set(['lint:rules', 'lint:tokens', 'lint', 'registry:check'])
+
+/** `estiva-gates ci`, as a workflow runs it, when it runs `script`; null otherwise. A comment line does not count. */
+function runsGateCi(text: string, script: string | RegExp): string | null {
+  if (typeof script !== 'string' || !GATE_CI_SCRIPTS.has(script)) return null
+  const m = /^(?!\s*#).*?((?:npx )?estiva-gates ci\b|npm run gates:ci\b|cli\.js"? ci\b)/m.exec(text)
+  return m ? m[1] : null
+}
+
 /** The helpers, bound to one repository. */
 export function helpers(ROOT: string): GateHelpers {
   const abs = (rel: string) => resolve(ROOT, rel)
@@ -263,6 +274,8 @@ export function helpers(ROOT: string): GateHelpers {
       for (const f of files) {
         const m = read(f).match(step)
         if (m) return PASS(`${f} runs npm run ${m[1]}`)
+        const all = runsGateCi(read(f), script)
+        if (all) return PASS(`${f} runs ${all}, which runs npm run ${script}`)
       }
       return FAIL(`no workflow runs npm run ${script}`)
     },
@@ -285,7 +298,9 @@ export function helpers(ROOT: string): GateHelpers {
         if (start === -1) continue
         const end = lines.findIndex((l, i) => i > start && /^ {0,2}\S/.test(l))
         const body = lines.slice(start + 1, end === -1 ? undefined : end).join('\n')
-        return step.test(body) ? PASS(`${f}: the job ${job} runs npm run ${script}`) : FAIL(`${f}: the job ${job} does not run npm run ${script}`)
+        if (step.test(body)) return PASS(`${f}: the job ${job} runs npm run ${script}`)
+        const all = runsGateCi(body, script)
+        return all ? PASS(`${f}: the job ${job} runs ${all}, which runs npm run ${script}`) : FAIL(`${f}: the job ${job} does not run npm run ${script}`)
       }
       return FAIL(`no workflow has a job ${job}`)
     },
@@ -560,10 +575,35 @@ export interface StatusOptions {
   app?: string
   json?: boolean
   detail?: boolean
+  /** List every escape, not only those due for review (B1). */
+  escapes?: boolean
+}
+
+/**
+ * What an app's catalogue leaves for Katerina: the parts nothing uses, by name
+ * (her UIG-13 ruling: an unused part is listed for her, never deleted by the
+ * catalogue; R20), and the parts with no link into Storybook (R22). A reusable
+ * part with none fails `estiva-ui check`; a one-off needs none (B10), so its
+ * number is shown and nothing more.
+ */
+async function catalogueLines(appDir: string): Promise<string[]> {
+  try {
+    const { buildAppRegistry } = await import('../registry/index')
+    const entries = buildAppRegistry({ root: appDir }).entries
+    const unused = entries.filter((e) => e.app?.class === 'unused')
+    const oneOffs = entries.filter((e) => e.app?.class === 'one-off')
+    const unlinked = oneOffs.filter((e) => !e.storyId && !e.docsId)
+    return [
+      `Unused parts: ${unused.length}${unused.length ? ` · Katerina rules on each: ${unused.map((e) => `${e.name} (${e.sourceFile})`).join(', ')}` : ''}`,
+      `Storybook links: every reusable part has one (estiva-ui check holds it) · one-offs with none: ${unlinked.length} of ${oneOffs.length}, which need none`,
+    ]
+  } catch (error) {
+    return [`Catalogue: could not be built here: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`]
+  }
 }
 
 /** Print where the project stands. Returns what was printed, or the JSON report. */
-export async function runStatus({ root = process.cwd(), app = '.', json = false, detail = false }: StatusOptions = {}): Promise<string> {
+export async function runStatus({ root = process.cwd(), app = '.', json = false, detail = false, escapes = false }: StatusOptions = {}): Promise<string> {
   const ROOT = resolve(root)
   const h = helpers(ROOT)
   const shown = (dir: string) => (relative(ROOT, dir) || dir).replace(/\\/g, '/')
@@ -574,8 +614,11 @@ export async function runStatus({ root = process.cwd(), app = '.', json = false,
   const out: string[] = []
   out.push('UI Guardrails · gates:status', 'Read from the code. Nothing here is a hand-ticked list.', '')
   out.push(`${pad(spec.repo, 10)} ${report.branch} @ ${report.commit}${behindMain(ROOT)}`)
+  // Every escape, listed and aged (Katerina's rulings B1, 25 September): the ones due for review always.
+  out.push('', ...escapeLines(listEscapes(join(ROOT, app)), { all: escapes }))
 
   if (!spec.all) {
+    out.push('', ...(await catalogueLines(join(ROOT, app))))
     // A sibling repo on its own: its own rows, then its parts of rows owned elsewhere.
     const own = report.rows.filter((r) => r.owner).map((r) => ({ ...r, ownerRepo: spec.repo, status: statusOf(r.checks) }))
     const parts = report.rows.filter((r) => !r.owner).map((r) => ({ ...r, ownerRepo: '', status: statusOf(r.checks) }))

package/src/gates/token-lint.ts

@@ -39,6 +39,7 @@ import type { ESLint, Linter } from 'eslint'
 import betterTailwindcss from 'eslint-plugin-better-tailwindcss'
 import { getDefaultSelectors } from 'eslint-plugin-better-tailwindcss/defaults'
 import { parser as typescriptParser, plugin as typescriptPlugin } from 'typescript-eslint'
+import { INLINE_STYLE_MESSAGE, INLINE_STYLE_TOKEN_KEYS, tokenStylePlugin } from './token-style'
 
 /** Who reads the messages. */
 export type TokenAudience = 'app' | 'package'
@@ -162,8 +163,7 @@ const HAND_WRITTEN = {
   width: `${V}(?:border(?:-[xytrblse])?|divide-[xy]|outline|ring|ring-offset)-\\[(?:length:)?-?[0-9.]+(?:px|rem|em)?\\]$`,
 }
 
-const INLINE_STYLE_TOKEN_PROPERTIES =
-  '/^(color|background|backgroundColor|backgroundImage|fill|stroke|fontSize|border|borderTop|borderRight|borderBottom|borderLeft|borderBlock|borderInline|borderStyle|boxShadow|textShadow)$|Color$/'
+const INLINE_STYLE_TOKEN_PROPERTIES = String(INLINE_STYLE_TOKEN_KEYS)
 
 interface Preset {
   theme: { extend: { fontSize: Record<string, string | [string, unknown]>; borderRadius: Record<string, string> } }
@@ -204,8 +204,10 @@ export function tokenValues({ audience = 'app' }: Pick<TokenLintOptions, 'audien
   return {
     files: ['**/*.{ts,tsx}'],
     ignores: ['**/*.test.ts', '**/*.test.tsx'],
-    plugins: { 'token-values': betterTailwindcss, 'token-spacing': betterTailwindcss },
+    plugins: { 'token-values': betterTailwindcss, 'token-spacing': betterTailwindcss, 'token-style': tokenStylePlugin },
     rules: {
+      // A style kept in a const and passed by name (R9): the selector below cannot follow it.
+      'token-style/no-token-style': 'error',
       'token-values/no-restricted-classes': [
         'error',
         {
@@ -252,7 +254,12 @@ export function tokenValues({ audience = 'app' }: Pick<TokenLintOptions, 'audien
         'error',
         {
           selector: `JSXAttribute[name.name="style"] > JSXExpressionContainer > ObjectExpression > Property[key.name=${INLINE_STYLE_TOKEN_PROPERTIES}]`,
-          message: 'An inline style that sets a colour, a font size, a border or a shadow is outside the token contract: use a token class. If the value is computed (a palette, a size from a prop), say why in an eslint-disable comment. Width, height and transforms are fine.',
+          message: INLINE_STYLE_MESSAGE,
+        },
+        // The same key in quotes, `style={{ 'background': 'red' }}` (R9).
+        {
+          selector: `JSXAttribute[name.name="style"] > JSXExpressionContainer > ObjectExpression > Property[key.value=${INLINE_STYLE_TOKEN_PROPERTIES}]`,
+          message: INLINE_STYLE_MESSAGE,
         },
       ],
     },

package/src/gates/token-style.ts

@@ -0,0 +1,79 @@
+/// <reference types="node" />
+/**
+ * The token contract's inline-style check, where a selector cannot reach
+ * (the second review's R9, 25 September). `no-restricted-syntax` reads a
+ * `style={{ … }}` written in place; a style kept in a `const` and passed by name
+ * got through every lint in all three repos:
+ *
+ *   const look = { background: 'red' }
+ *   <div style={look} />
+ *
+ * This follows the name to its `const` in the same file and reads the keys
+ * there, quoted or not. It reports on the key, where the value is written, so
+ * an escape sits beside it. A style the code works out while it runs passes:
+ * nothing can read it.
+ */
+import type { ESLint, Rule, Scope } from 'eslint'
+
+/** The style keys outside the token contract: colours, a font size, borders and shadows. */
+export const INLINE_STYLE_TOKEN_KEYS = /^(color|background|backgroundColor|backgroundImage|fill|stroke|fontSize|border|borderTop|borderRight|borderBottom|borderLeft|borderBlock|borderInline|borderStyle|boxShadow|textShadow)$|Color$/
+
+export const INLINE_STYLE_MESSAGE =
+  'An inline style that sets a colour, a font size, a border or a shadow is outside the token contract: use a token class. If the value is computed (a palette, a size from a prop), say why in an eslint-disable comment. Width, height and transforms are fine.'
+
+interface Node {
+  type: string
+  [key: string]: unknown
+}
+
+const keyOf = (property: Node): string | undefined => {
+  if (property.computed) return undefined
+  const key = property.key as Node
+  return key.type === 'Identifier' ? (key.name as string) : key.type === 'Literal' && typeof key.value === 'string' ? key.value : undefined
+}
+
+/** The object a `const` of this name holds, in this scope or one around it. */
+function constObject(name: string, scope: Scope.Scope | null): Node | undefined {
+  for (let current = scope; current; current = current.upper) {
+    const variable = current.set.get(name)
+    if (!variable) continue
+    const definition = variable.defs[0] as unknown as { type: string; node: Node; parent?: Node } | undefined
+    if (variable.defs.length !== 1 || definition?.type !== 'Variable' || definition.parent?.kind !== 'const') return undefined
+    let init = definition.node.init as Node | undefined
+    while (init && (init.type === 'TSAsExpression' || init.type === 'TSSatisfiesExpression')) init = init.expression as Node
+    return init?.type === 'ObjectExpression' ? init : undefined
+  }
+  return undefined
+}
+
+const noTokenStyle: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'No colour, font size, border or shadow in a style kept in a const' },
+    schema: [],
+    messages: { token: INLINE_STYLE_MESSAGE },
+  },
+  create(context) {
+    const reported = new Set<unknown>()
+    return {
+      JSXAttribute(ruleNode: Rule.Node) {
+        const attribute = ruleNode as unknown as Node
+        if ((attribute.name as Node).name !== 'style') return
+        const value = attribute.value as Node | null
+        const expression = value?.type === 'JSXExpressionContainer' ? (value.expression as Node) : undefined
+        if (expression?.type !== 'Identifier') return
+        const object = constObject(expression.name as string, context.sourceCode.getScope(ruleNode))
+        for (const property of (object?.properties as Node[] | undefined) ?? []) {
+          if (property.type !== 'Property' || reported.has(property)) continue
+          const key = keyOf(property)
+          if (!key || !INLINE_STYLE_TOKEN_KEYS.test(key)) continue
+          reported.add(property)
+          context.report({ node: property as unknown as Rule.Node, messageId: 'token' })
+        }
+      },
+    }
+  },
+}
+
+/** The plugin, as the token lint registers it: `token-style/no-token-style`. */
+export const tokenStylePlugin: ESLint.Plugin = { rules: { 'no-token-style': noTokenStyle } }