@estiva-app/ui 0.35.1 → 0.36.0

package/src/eslint/no-raw-element.ts

@@ -111,7 +111,43 @@ function isOn(element: JSXOpeningElement, name: string): boolean {
   return attr !== undefined && literal(attr) !== false
 }
 
-type Found = { report: 'raw'; element: string; part: RawElementPart } | { report: 'noPart'; element: string } | null
+type Found = { report: 'raw'; element: string; part: RawElementPart } | { report: 'noPart'; element: string } | { report: 'clickable'; element: string } | null
+
+/** The pointer's press, as a handler on a plain element makes it a control (R5). */
+const CLICK_HANDLERS = ['onClick', 'onMouseDown', 'onMouseUp', 'onPointerDown', 'onPointerUp', 'onDoubleClick']
+
+interface Expression {
+  type: string
+  [key: string]: unknown
+}
+
+/** `e.stopPropagation()` or `e.preventDefault()`: a handler that only keeps the click from what is behind. */
+function onlyStops(handler: Expression | undefined): boolean {
+  if (!handler || (handler.type !== 'ArrowFunctionExpression' && handler.type !== 'FunctionExpression')) return false
+  const body = handler.body as Expression
+  const calls = body.type === 'BlockStatement' ? (body.body as Expression[]).map((s) => (s.type === 'ExpressionStatement' ? (s.expression as Expression) : s)) : [body]
+  return (
+    calls.length > 0 &&
+    calls.every((call) => {
+      if (call.type !== 'CallExpression') return false
+      const callee = call.callee as Expression
+      const property = callee.type === 'MemberExpression' ? (callee.property as Expression) : undefined
+      return property?.type === 'Identifier' && (property.name === 'stopPropagation' || property.name === 'preventDefault')
+    })
+  )
+}
+
+/** A plain element made clickable by hand: the first press handler that does more than stop the click. */
+function clickHandler(element: JSXOpeningElement): string | undefined {
+  for (const name of CLICK_HANDLERS) {
+    const attr = attribute(element, name)
+    if (!attr) continue
+    const value = attr.value
+    const handler = value?.type === 'JSXExpressionContainer' ? (value.expression as Expression | undefined) : undefined
+    if (!onlyStops(handler)) return name
+  }
+  return undefined
+}
 
 /** What this element is to the rule: a raw element with a part, one with none yet, or none of its business. */
 export function classify(element: JSXOpeningElement): Found {
@@ -131,7 +167,14 @@ export function classify(element: JSXOpeningElement): Found {
     return part ? { report: 'raw', element: shown, part } : { report: 'noPart', element: shown }
   }
 
-  if (!Object.hasOwn(RAW_ELEMENT_PARTS, name)) return null
+  if (!Object.hasOwn(RAW_ELEMENT_PARTS, name)) {
+    // A plain element with a press handler is a button drawn by hand (Katerina's ruling R5,
+    // 25 September): no focus, no keys, no look anybody keeps in step. `<option>` and
+    // `<summary>` live inside a control the rule already reads.
+    if (!/^[a-z][a-z0-9]*$/.test(name) || name === 'option' || name === 'summary') return null
+    const handler = clickHandler(element)
+    return handler ? { report: 'clickable', element: `<${name} ${handler}>` } : null
+  }
   if ((name === 'audio' || name === 'video') && !isOn(element, 'controls')) return null
   if (name === 'img' && !attribute(element, 'usemap') && !attribute(element, 'useMap')) return null
 
@@ -150,6 +193,10 @@ export function classify(element: JSXOpeningElement): Found {
  * that says so: the part is made in the package, not by hand in an app
  * (Katerina, 16 September).
  *
+ * A plain element with a press handler (`<div onClick>`) is a control too, and
+ * is refused naming `Button` (R5, 25 September); a handler that only stops the
+ * click reaching what is behind passes.
+ *
  * Only a JSX element written with a lowercase name. `<Button>`,
  * `<Foo.button>` and `createElement('button')` are not this rule's business.
  */
@@ -160,6 +207,8 @@ export const noRawElement: Rule.RuleModule = {
     schema: [],
     messages: {
       raw: 'Use `{{use}}` from @estiva-app/ui instead of a raw {{element}}.{{more}}',
+      clickable:
+        'A clickable {{element}} is a button made by hand: it takes no focus and answers no key. Use `Button` from @estiva-app/ui; for a whole card that opens something, `Card` with `href`. A handler that only stops the click (`e.stopPropagation()`) is fine.',
       noPart: '@estiva-app/ui has no part for a raw {{element}} yet. Do not build one here: ask Katerina, and it gets made in @estiva-app/ui.',
       ...ESCAPE_MESSAGES,
     },
@@ -172,7 +221,8 @@ export const noRawElement: Rule.RuleModule = {
         const found = classify(element)
         if (!found) return
         if (isEscaped(context, element)) return
-        if (found.report === 'noPart') context.report({ loc: element.loc, messageId: 'noPart', data: { element: found.element } })
+        if (found.report === 'clickable') context.report({ loc: element.loc, messageId: 'clickable', data: { element: found.element } })
+        else if (found.report === 'noPart') context.report({ loc: element.loc, messageId: 'noPart', data: { element: found.element } })
         else context.report({ loc: element.loc, messageId: 'raw', data: { element: found.element, use: found.part.use, more: found.part.more ?? '' } })
       },
     }

package/src/eslint/no-rebuilt-behaviour.test.ts

@@ -65,27 +65,27 @@ tester.run('no-rebuilt-behaviour', noRebuiltBehaviour, {
     // escapes
     {
       name: 'an escape above the statement keeps a page listener',
-      code: effect("  // @estiva-escape: an inline panel, not a floating one, closes on a press outside\n  document.addEventListener('mousedown', close)"),
+      code: effect("  // @estiva-escape(no-rebuilt-behaviour): an inline panel, not a floating one, closes on a press outside\n  document.addEventListener('mousedown', close)"),
     },
     {
       name: 'an escape above the element keeps a hand-written role',
-      code: component('    // @estiva-escape: a list the editor drives from its caret\n    <MenuItem role="option" aria-selected label="Item" />'),
+      code: component('    // @estiva-escape(no-rebuilt-behaviour): a list the editor drives from its caret\n    <MenuItem role="option" aria-selected label="Item" />'),
     },
     {
       name: 'an escape above the object property keeps its arrow keys',
-      code: "useImperativeHandle(ref, () => ({\n  // @estiva-escape: a list the editor drives from its caret\n  onKeyDown: ({ event }) => {\n    if (event.key === 'ArrowDown') next()\n    if (event.key === 'ArrowUp') previous()\n    return false\n  },\n}))",
+      code: "useImperativeHandle(ref, () => ({\n  // @estiva-escape(no-rebuilt-behaviour): a list the editor drives from its caret\n  onKeyDown: ({ event }) => {\n    if (event.key === 'ArrowDown') next()\n    if (event.key === 'ArrowUp') previous()\n    return false\n  },\n}))",
     },
     {
       name: 'an escape above the call keeps a portal',
-      code: "import { createPortal } from 'react-dom'\nfunction Viewer() {\n  // @estiva-escape: becomes the package Lightbox at stage 7\n  return createPortal(<div />, document.body)\n}",
+      code: "import { createPortal } from 'react-dom'\nfunction Viewer() {\n  // @estiva-escape(no-rebuilt-behaviour): becomes the package Lightbox at stage 7\n  return createPortal(<div />, document.body)\n}",
     },
     {
       name: 'an escape above an array item keeps its class',
-      code: "const CLASSES = [\n  'flex',\n  // @estiva-escape: a code block the editor draws, which nothing can wrap\n  '[&_pre]:overflow-x-auto',\n]",
+      code: "const CLASSES = [\n  'flex',\n  // @estiva-escape(no-rebuilt-behaviour): a code block the editor draws, which nothing can wrap\n  '[&_pre]:overflow-x-auto',\n]",
     },
     {
       name: 'one escape above an element covers everything found on it',
-      code: component('    // @estiva-escape: a surface that holds headings, which a button cannot\n    <div role="button" tabIndex={0} className="overflow-auto" />'),
+      code: component('    // @estiva-escape(no-rebuilt-behaviour): a surface that holds headings, which a button cannot\n    <div role="button" tabIndex={0} className="overflow-auto" />'),
     },
   ],
   invalid: [
@@ -175,17 +175,17 @@ tester.run('no-rebuilt-behaviour', noRebuiltBehaviour, {
     // escapes
     {
       name: 'an escape with no reason hides nothing',
-      code: effect("  // @estiva-escape:\n  document.addEventListener('mousedown', close)"),
+      code: effect("  // @estiva-escape(no-rebuilt-behaviour):\n  document.addEventListener('mousedown', close)"),
       errors: [{ messageId: 'escapeWithoutReason', line: 2 }, { messageId: 'press', line: 3 }],
     },
     {
       name: 'an escape above one statement does not reach the next',
-      code: effect("  // @estiva-escape: an inline panel, not a floating one, closes on a press outside\n  document.addEventListener('mousedown', close)\n  document.addEventListener('keydown', onKey)"),
+      code: effect("  // @estiva-escape(no-rebuilt-behaviour): an inline panel, not a floating one, closes on a press outside\n  document.addEventListener('mousedown', close)\n  document.addEventListener('keydown', onKey)"),
       errors: [{ messageId: 'key', line: 4 }],
     },
     {
       name: 'with reportEscapes on, one escape over two findings is counted once',
-      code: component('    // @estiva-escape: a surface that holds headings, which a button cannot\n    <div role="button" tabIndex={0} />'),
+      code: component('    // @estiva-escape(no-rebuilt-behaviour): a surface that holds headings, which a button cannot\n    <div role="button" tabIndex={0} />'),
       settings: { estiva: { reportEscapes: true } },
       errors: [{ messageId: 'escaped', line: 3 }],
     },

package/src/eslint/no-restyled-part.test.ts

@@ -51,6 +51,8 @@ const local = (imports: string, from: string, body: string) => `import { ${impor
 const USE_VARIANT_OR_SIZE = ' Use its `variant` or `size`.'
 const restyled = (classes: string, where: string, use: string) =>
   `${classes} on ${where} changes how it looks. A part of @estiva-app/ui is placed from outside, never restyled: only space, size, flex and grid, and position pass in.${use} A look for what is around it goes on your own element around it.`
+const restyledStyle = (keys: string, where: string, use: string) =>
+  `${keys} in the \`style\` of ${where} changes how it looks. A part of @estiva-app/ui is placed from outside, never restyled, by class or by style: only space, size, flex and grid, and position pass in.${use} A look for what is around it goes on your own element around it.`
 const noProp = (part: string) => ` \`${part}\` has no prop for this yet: ask Katerina, and it gets made in @estiva-app/ui.`
 
 tester.run('no-restyled-part', noRestyledPart, {
@@ -66,14 +68,31 @@ tester.run('no-restyled-part', noRestyledPart, {
     { name: 'a raw element is not a part', filename: app, code: ui('Button', '    <div className="bg-bg-surface text-h2 rounded-lg" />') },
     { name: 'an app component of the same name is not a part', filename: app, code: local('Button', './components/Button', '    <Button className="text-h2" />') },
     { name: 'a style prop is not a class prop', filename: app, code: ui('Button', '    <Button style={{ width: 20 }} data-class="text-h2">x</Button>') },
+    // style on a part: placement keys pass (B6)
+    { name: 'style: space, size, position and a move', filename: app, code: ui('Card', "    <Card style={{ marginTop: 4, 'paddingInline': 8, width: '50%', maxHeight: 240, flexGrow: 1, gridColumn: '1 / 3', position: 'absolute', top: 0, zIndex: 2, transform: `translateY(${y}px)` }} />") },
+    { name: 'style: a const of placement, and a custom property', filename: app, code: "import { Card } from '@estiva-app/ui'\nconst at = { top: 0, left: 0 }\nexport function Probe() {\n  return <Card style={at}><Card style={{ '--row': 2 }} /></Card>\n}\n" },
+    { name: 'style the code works out while it runs passes', filename: app, code: ui('Card', '    <Card style={props.style} />') },
+    { name: 'style on a component that hands on only its className is not read', filename: app, code: local('ConversationCard', './components/ConversationCard', '    <ConversationCard title="x" style={{ opacity: 0.5 }} />') },
     { name: 'EmptyState placed', filename: app, code: ui('EmptyState', '    <EmptyState className="mt-2 flex-1" message="Nothing yet" />') },
     // escapes
-    { name: 'escaped, with its reason', filename: app, code: ui('Link', '    // @estiva-escape: the whole row is the link, and no part does that yet\n    <Link href="/x" className="after:absolute after:inset-0">x</Link>') },
+    { name: 'escaped, with its reason', filename: app, code: ui('Link', '    // @estiva-escape(no-restyled-part): the whole row is the link, and no part does that yet\n    <Link href="/x" className="after:absolute after:inset-0">x</Link>') },
     // the package itself
     { name: 'inside the package: a name index.ts does not export', filename: pkg, code: local('Base', './Base', '    <Base className="text-h2" />') },
     { name: 'inside the package: a raw element in a part', filename: pkg, code: 'export function Card() {\n  return <div className="rounded-lg border" />\n}\n' },
   ],
   invalid: [
+    {
+      name: 'style: a corner, an opacity, a weight and a line height (B6)',
+      filename: app,
+      code: ui('Button', '    <Button style={{ borderRadius: 999, opacity: 0.4, fontWeight: 700, lineHeight: 2, marginTop: 4 }}>x</Button>'),
+      errors: [{ message: restyledStyle('`borderRadius` `opacity` `fontWeight` `lineHeight`', '`Button`', USE_VARIANT_OR_SIZE) }],
+    },
+    {
+      name: 'style: quoted keys, a const, and a re-export',
+      filename: app,
+      code: "import { Button } from './components/ui'\nconst look = { 'background': 'red' } as const\nexport function Probe() {\n  return <Button style={look}>x</Button>\n}\n",
+      errors: [{ message: restyledStyle('`background`', '`Button`', USE_VARIANT_OR_SIZE) }],
+    },
     {
       name: 'a colour and a text size, naming the props that carry a look',
       filename: app,
@@ -176,7 +195,7 @@ tester.run('no-restyled-part', noRestyledPart, {
     {
       name: 'an escape with no reason is reported, and so is the class',
       filename: app,
-      code: ui('Link', '    // @estiva-escape:\n    <Link href="/x" className="text-h2">x</Link>'),
+      code: ui('Link', '    // @estiva-escape(no-restyled-part):\n    <Link href="/x" className="text-h2">x</Link>'),
       errors: [{ messageId: 'escapeWithoutReason' }, { message: restyled('`text-h2`', '`Link`', ' Use its `variant` or `truncate`.') }],
     },
     {

package/src/eslint/no-restyled-part.ts

@@ -53,6 +53,16 @@ export const PLACEMENT: { what: string; pattern: RegExp }[] = [
   { what: 'a name for hover', pattern: /^(?:group|peer)(?:\/[\w-]+)?$/ },
 ]
 
+/**
+ * The same, as `style` keys (Katerina's ruling B6, 25 September): `style` on a
+ * part is read like its `className`, so a radius, a weight or an opacity cannot
+ * go in by the other door. CSS's own names for space, size, flex and grid, and
+ * position; `transform` and `translate` move a part without changing its look.
+ * A custom property (`--name`) passes: the part decides what it means.
+ */
+export const PLACEMENT_STYLE =
+  /^(?:margin|padding|inset|scrollMargin)(?:Top|Right|Bottom|Left|Block|Inline|BlockStart|BlockEnd|InlineStart|InlineEnd)?$|^(?:width|height|minWidth|minHeight|maxWidth|maxHeight|inlineSize|blockSize|minInlineSize|minBlockSize|maxInlineSize|maxBlockSize)$|^(?:display|flex|flexGrow|flexShrink|flexBasis|order|gap|rowGap|columnGap|alignSelf|justifySelf|placeSelf|gridArea|gridColumn|gridColumnStart|gridColumnEnd|gridRow|gridRowStart|gridRowEnd)$|^(?:position|top|right|bottom|left|zIndex|transform|translate)$/
+
 /**
  * A variant that draws another box or reaches inside the part: `before:`,
  * `after:`, `[&>*]:`, `*:`… A placement class behind one of these is not the
@@ -592,6 +602,8 @@ export const noRestyledPart: Rule.RuleModule = {
     messages: {
       restyled:
         '{{classes}} on {{where}} changes how it looks. A part of @estiva-app/ui is placed from outside, never restyled: only space, size, flex and grid, and position pass in.{{use}} A look for what is around it goes on your own element around it.',
+      restyledStyle:
+        '{{keys}} in the `style` of {{where}} changes how it looks. A part of @estiva-app/ui is placed from outside, never restyled, by class or by style: only space, size, flex and grid, and position pass in.{{use}} A look for what is around it goes on your own element around it.',
       emptyStatePadding:
         '{{classes}} pads {{where}}. EmptyState takes no padding (Katerina, 14 September): its room comes from the box its rows live in, so put the padding on that box.',
       ...ESCAPE_MESSAGES,
@@ -628,6 +640,23 @@ export const noRestyledPart: Rule.RuleModule = {
       if (padding.length) context.report({ loc: at.loc as NonNullable<Rule.Node['loc']>, messageId: 'emptyStatePadding', data: { classes: code(padding), where } })
     }
 
+    /** `style` on a part: every key it can read must be placement (B6). */
+    const checkStyle = (element: Node, binding: PartBinding, value: Node | null | undefined, at: Node) => {
+      if (binding.props !== 'all' || value?.type !== 'JSXExpressionContainer') return
+      let object = child(value, 'expression')
+      if (object?.type === 'Identifier') object = constantOf(object, scopeOf(object))
+      while (object?.type === 'TSAsExpression' || object?.type === 'TSSatisfiesExpression') object = child(object, 'expression')
+      if (object?.type !== 'ObjectExpression') return
+      const keys = children(object, 'properties')
+        .map((property) => (property?.type === 'Property' && !property.computed ? nameOf(child(property, 'key')) : undefined))
+        .filter((key): key is string => !!key && !key.startsWith('--') && !PLACEMENT_STYLE.test(key))
+      if (!keys.length || escaped(element)) return
+      const props = PART_LOOK_PROPS[binding.part]
+      const use = props ? ` Use its ${or(props)}.` : ` \`${binding.part}\` has no prop for this yet: ask Katerina, and it gets made in @estiva-app/ui.`
+      const where = binding.via && binding.via !== binding.part ? `\`${binding.via}\` (it hands its props to \`${binding.part}\`)` : `\`${binding.part}\``
+      context.report({ loc: at.loc as NonNullable<Rule.Node['loc']>, messageId: 'restyledStyle', data: { keys: code([...new Set(keys)]), where, use } })
+    }
+
     return {
       Program(program) {
         locals = moduleParts(file, program as unknown as Node, parser, new Set([file])).locals
@@ -641,6 +670,7 @@ export const noRestyledPart: Rule.RuleModule = {
           if (attribute.type === 'JSXAttribute') {
             const prop = nameOf(child(attribute, 'name'))
             if (prop && CLASS_PROP.test(prop)) check(element, binding, prop, child(attribute, 'value'), attribute)
+            else if (prop === 'style') checkStyle(element, binding, child(attribute, 'value'), attribute)
             continue
           }
           // `{...{ className }}`, or a `const` object spread onto the part.

package/src/eslint/raw-element-outside-a-wrapper.test.ts

@@ -35,7 +35,7 @@ tester.run('raw-element-outside-a-wrapper', rawElementOutsideAWrapper, {
     { name: 'layout inside a component', code: component('    <div>\n      <span>Issues</span>\n    </div>') },
     {
       name: 'a nested element with its reason on the line above',
-      code: component('    <div>\n      {/* @estiva-escape: the trail is one line of text and an anchor keeps it */}\n      <a href="/x">Issues</a>\n    </div>'),
+      code: component('    <div>\n      {/* @estiva-escape(raw-element-outside-a-wrapper): the trail is one line of text and an anchor keeps it */}\n      <a href="/x">Issues</a>\n    </div>'),
     },
   ],
   invalid: [
@@ -66,14 +66,14 @@ tester.run('raw-element-outside-a-wrapper', rawElementOutsideAWrapper, {
     },
     {
       name: 'a reason too short to be a reason',
-      code: component('    <div>\n      {/* @estiva-escape: short */}\n      <a href="/x">Issues</a>\n    </div>'),
+      code: component('    <div>\n      {/* @estiva-escape(raw-element-outside-a-wrapper): short */}\n      <a href="/x">Issues</a>\n    </div>'),
       errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'nested', data: { name: 'a' } }],
     },
     {
       name: 'an eslint-disable instead of a reason',
       // The tester runs the rule under its bare name; in a real lint the plugin
       // prefixes it, and `isEscaped` compares against whichever the rule has.
-      code: component('    <div>\n      {/* eslint-disable-next-line rule-to-test/raw-element-outside-a-wrapper -- @estiva-escape: the trail keeps its anchor */}\n      <a href="/x">Issues</a>\n    </div>'),
+      code: component('    <div>\n      {/* eslint-disable-next-line rule-to-test/raw-element-outside-a-wrapper -- @estiva-escape(raw-element-outside-a-wrapper): the trail keeps its anchor */}\n      <a href="/x">Issues</a>\n    </div>'),
       // The directive silences the rule's own report, which is exactly why it is
       // refused: `countGates` sees the silenced report and the gate fails on it.
       errors: [{ messageId: 'escapeInDirective' }],

package/src/gates/app-checks.ts

@@ -114,6 +114,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
     ]),
     ticket('UIG-7', [
       { what: 'a raw <input> is an error naming TextInput', run: probe(component('<input />'), 'error', 'TextInput') },
+      { what: 'a clickable <div> is an error naming Button (R5)', run: probe(component('<div onClick={() => history.back()}>Back</div>'), 'error', '`Button`') },
       { what: 'a raw <a> is an error naming Link', run: all(h, [probe(component('<a href="/topics">Topics</a>'), 'error', 'Link'), probe(component('<a href="/issues">Issues</a>'), 'error', 'Link')], 'a raw <a> is an error naming Link') },
       { what: 'a raw <form> is an error naming Form, and a file input one naming FilePicker', run: async () => {
         const form = await probe(component('<form />'), 'error', '`Form`')()
@@ -131,7 +132,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'an escaped element is not an error, while the same element is', run: async () => {
         const raw = await probe(component('<form />'), 'error')()
         if (raw.result !== 'pass') return h.FAIL(`a raw <form> is not caught yet, so this proves nothing: ${raw.detail}`)
-        return probe('export function Probe() {\n  return (\n    // @estiva-escape: a probe that keeps its element on purpose\n    <form />\n  )\n}\n', 'none')()
+        return probe('export function Probe() {\n  return (\n    // @estiva-escape(no-raw-element): a probe that keeps its element on purpose\n    <form />\n  )\n}\n', 'none')()
       } },
       { what: 'a real page, full of elements that are not controls, gets no error', run: realPage },
     ]),
@@ -154,7 +155,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'an escaped listener is not an error, while the same listener is', run: async () => {
         const raw = await probe("export function listen() {\n  document.addEventListener('mousedown', () => {})\n}\n", 'error', undefined, 'src/lib/__gates_probe__.ts')()
         if (raw.result !== 'pass') return h.FAIL(`a page listener is not caught yet, so this proves nothing: ${raw.detail}`)
-        return probe("export function listen() {\n  // @estiva-escape: a probe that keeps its listener on purpose\n  document.addEventListener('mousedown', () => {})\n}\n", 'none', undefined, 'src/lib/__gates_probe__.ts')()
+        return probe("export function listen() {\n  // @estiva-escape(no-rebuilt-behaviour): a probe that keeps its listener on purpose\n  document.addEventListener('mousedown', () => {})\n}\n", 'none', undefined, 'src/lib/__gates_probe__.ts')()
       } },
       { what: 'a real page gets no error', run: realPage },
     ]),
@@ -164,7 +165,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'an escaped look is not an error, while the same look is', run: async () => {
         const raw = await probe(`import { Link } from '@estiva-app/ui'\n${component('<Link href="/x" className="after:absolute after:inset-0">x</Link>')}`, 'error', '`Link`')()
         if (raw.result !== 'pass') return h.FAIL(`a restyled part is not caught yet, so this proves nothing: ${raw.detail}`)
-        return probe(`import { Link } from '@estiva-app/ui'\nexport function Probe() {\n  return (\n    // @estiva-escape: a probe that keeps its row link on purpose\n    <Link href="/x" className="after:absolute after:inset-0">x</Link>\n  )\n}\n`, 'none')()
+        return probe(`import { Link } from '@estiva-app/ui'\nexport function Probe() {\n  return (\n    // @estiva-escape(no-restyled-part): a probe that keeps its row link on purpose\n    <Link href="/x" className="after:absolute after:inset-0">x</Link>\n  )\n}\n`, 'none')()
       } },
       { what: 'a real page gets no error', run: realPage },
     ]),

package/src/gates/ci.ts

@@ -0,0 +1,152 @@
+/// <reference types="node" />
+/**
+ * `estiva-gates ci` — CI's job `gate`, as one command (Katerina's ruling R13,
+ * 25 September). Until 0.36.0 each repo listed the gate's steps in its own
+ * workflow, and the lists had drifted: Peek ran `lint:tokens`, Ship the whole
+ * `lint`, and no repo checked the two things below. Now the steps live here,
+ * and a repo's `gate` job runs this and nothing else of the gate's.
+ *
+ * 1. The gate lint (`npm run lint:rules`), which writes `.gates-count.json`.
+ * 2. The count is committed (B2): a pull request that changes what the gate
+ *    finds and leaves the old count behind fails, so the file is the truth.
+ * 3. The token contract (`npm run lint:tokens`, or `npm run lint` where a repo
+ *    has no token lint of its own).
+ * 4. The catalogue (`npm run registry:check`).
+ * 5. The wall's own settings (B13): the committed `.claude/settings.json` runs
+ *    the editor hook before every Write and Edit, and that hook refuses a raw
+ *    button; every folder the gate skips is named on the debt page, with why.
+ *
+ * Every step runs, so one red step does not hide the others.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { TOKEN_LINT_IGNORES } from './token-lint'
+
+export interface CiOptions {
+  /** The repository's top folder, where the gate lints from. */
+  root?: string
+  /** `package` is this package's own gate: its skipped folders are named in docs/GATES.md. */
+  audience?: 'app' | 'package'
+  /** Print as the steps run. Defaults to stdout. */
+  print?: (line: string) => void
+}
+
+/** The part a CI run writes to the probe: a raw button, which every gate refuses. */
+const PROBE = '/** A probe CI writes to check the editor hook; never on disk. */\nexport function GateProbe() {\n  return <button type="button">x</button>\n}\n'
+
+const npm = (root: string, script: string) => spawnSync('npm', ['run', script], { cwd: root, stdio: 'inherit', shell: true }).status === 0
+
+/** `.gates-count.json` as the gate lint left it matches the committed file; the lines that say otherwise. */
+export function countCommitted(root: string): string[] {
+  const run = spawnSync('git', ['status', '--porcelain', '--', '.gates-count.json'], { cwd: root, encoding: 'utf8' })
+  if (run.status !== 0) return [`git could not read .gates-count.json's state: ${run.stderr.trim()}`]
+  if (!run.stdout.trim()) return []
+  const diff = spawnSync('git', ['diff', '--', '.gates-count.json'], { cwd: root, encoding: 'utf8' }).stdout.trim()
+  return [
+    'The gate found something other than the committed count: run `npm run lint:rules` and commit `.gates-count.json` with the change that moved it.',
+    ...(diff ? diff.split('\n').filter((l) => /^[+-]\s/.test(l)).map((l) => `  ${l}`) : ['  .gates-count.json is not committed at all']),
+  ]
+}
+
+interface HookEntry {
+  matcher?: string
+  hooks?: { type?: string; command?: string }[]
+}
+
+/** The committed hook runs before every Write and Edit and refuses a raw button; the lines that say otherwise. */
+export function hookRuns(root: string): string[] {
+  const file = join(root, '.claude', 'settings.json')
+  if (!existsSync(file)) return ['.claude/settings.json is missing: the editor hook is not switched on (docs/GATES.md §23).']
+  let entries: HookEntry[]
+  try {
+    entries = ((JSON.parse(readFileSync(file, 'utf8')) as { hooks?: { PreToolUse?: HookEntry[] } }).hooks?.PreToolUse ?? [])
+  } catch (error) {
+    return [`.claude/settings.json does not read as JSON: ${error instanceof Error ? error.message : String(error)}`]
+  }
+  const covers = (matcher: string | undefined, tool: string) => {
+    if (!matcher || matcher === '*') return true
+    try {
+      return new RegExp(`^(?:${matcher})$`).test(tool)
+    } catch {
+      return false
+    }
+  }
+  const input = JSON.stringify({ tool_name: 'Write', session_id: 'estiva-gates-ci', cwd: root, tool_input: { file_path: join(root, 'src', 'GateProbe.tsx'), content: PROBE } })
+  const tried: string[] = []
+  for (const entry of entries) {
+    if (!covers(entry.matcher, 'Write') || !covers(entry.matcher, 'Edit')) continue
+    for (const hook of entry.hooks ?? []) {
+      if (hook.type !== 'command' || !hook.command) continue
+      // The project folder, written in: a Windows shell does not expand `$VAR`.
+      const command = hook.command.replace(/\$\{?CLAUDE_PROJECT_DIR\}?/g, root.split('\\').join('/'))
+      const run = spawnSync(command, { cwd: root, input, encoding: 'utf8', shell: true, env: { ...process.env, CLAUDE_PROJECT_DIR: root }, timeout: 120_000 })
+      if (run.status === 2 && /UI Guardrails/.test(run.stderr)) return []
+      tried.push(`  ${hook.command}  → exit ${run.status ?? 'none'}${run.stderr.trim() ? `: ${run.stderr.trim().split('\n')[0]}` : ''}`)
+    }
+  }
+  return [
+    tried.length
+      ? 'The editor hook let a raw button through: no PreToolUse hook in .claude/settings.json refused it.'
+      : 'No PreToolUse hook in .claude/settings.json runs before both Write and Edit: the editor gate is off.',
+    ...tried,
+  ]
+}
+
+/** A glob as the words a page would name it by: `demo-scenarios/**` → `demo-scenarios`. */
+const plain = (glob: string) => glob.replace(/\/\*\*.*$|\/$/, '')
+
+/** The folders a gate config skips beyond the package's own three, from the config itself. */
+export async function skippedFolders(root: string): Promise<string[]> {
+  const found = new Set<string>()
+  for (const name of ['eslint.gates.config.js', 'eslint.tokens.config.js']) {
+    const file = join(root, name)
+    if (!existsSync(file)) continue
+    // The file as it is now: Node keeps a module it has imported once, by its URL.
+    const loaded = (await import(`${pathToFileURL(file).href}?at=${statSync(file).mtimeMs}`)) as { default?: unknown }
+    const configs = [loaded.default].flat(Infinity) as { ignores?: string[]; [key: string]: unknown }[]
+    for (const c of configs) {
+      // Only a config with nothing but `ignores` skips a folder for every rule.
+      if (!c || typeof c !== 'object' || !Array.isArray(c.ignores) || Object.keys(c).some((k) => k !== 'ignores' && k !== 'name')) continue
+      for (const glob of c.ignores) if (!TOKEN_LINT_IGNORES.includes(glob)) found.add(glob)
+    }
+  }
+  return [...found]
+}
+
+/** Every skipped folder is named on the debt page; the lines that say otherwise. */
+export async function skipsListed(root: string, audience: 'app' | 'package'): Promise<string[]> {
+  const page = audience === 'package' ? 'docs/GATES.md' : 'docs/GATES-DEBT.md'
+  const skipped = await skippedFolders(root)
+  if (!skipped.length) return []
+  const text = existsSync(join(root, page)) ? readFileSync(join(root, page), 'utf8') : ''
+  const missing = skipped.filter((glob) => !text.includes(plain(glob)))
+  if (!missing.length) return []
+  return [`The gate skips folders ${page} does not name. Name each there, with why it is not checked (B11):`, ...missing.map((g) => `  ${g}`)]
+}
+
+export async function runCi({ root = process.cwd(), audience = 'app', print = (line) => process.stdout.write(`${line}\n`) }: CiOptions = {}): Promise<number> {
+  const scripts = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {}
+  const tokens = scripts['lint:tokens'] ? 'lint:tokens' : 'lint'
+  const failed: string[] = []
+  const step = async (title: string, run: () => boolean | string[] | Promise<string[]>) => {
+    print(`\n▸ ${title}`)
+    const result = await run()
+    const problems = result === true ? [] : result === false ? [`${title}: failed (above)`] : result
+    if (problems.length) {
+      failed.push(title)
+      for (const line of problems) print(process.env.GITHUB_ACTIONS && !line.startsWith(' ') ? `::error::${line}` : line)
+    } else print('  ✓')
+  }
+
+  await step('The gate lint (npm run lint:rules)', () => npm(root, 'lint:rules'))
+  await step('The count is committed (.gates-count.json)', () => countCommitted(root))
+  await step(`The token contract (npm run ${tokens})`, () => npm(root, tokens))
+  await step('The catalogue (npm run registry:check)', () => npm(root, 'registry:check'))
+  await step('The editor hook refuses a raw button (.claude/settings.json)', () => hookRuns(root))
+  await step('Every folder the gate skips is named on the debt page', () => skipsListed(root, audience))
+
+  print(failed.length ? `\nThe gate failed: ${failed.join('; ')}.` : '\nThe gate passed.')
+  return failed.length ? 1 : 0
+}

package/src/gates/cli.ts

@@ -2,9 +2,11 @@
 /**
  * `estiva-gates` — the gate pieces as one command (docs/GATES.md §23).
  *
+ *   estiva-gates ci [--package]                    CI's job `gate`: every step of the gate (R13)
  *   estiva-gates count --repo <name> [--package]   write .gates-count.json (postlint:rules)
  *   estiva-gates hook [--app <dir>] [--package]    the editor gate, run by a PreToolUse hook
- *   estiva-gates status [--app <dir>] [--json] [--detail]   gates:status
+ *   estiva-gates name-escapes [--config <file>]    once: name the rule in every escape marker (B3)
+ *   estiva-gates status [--app <dir>] [--json] [--detail] [--escapes]   gates:status
  *
  * An app's `package.json` runs the first and the last through npm, which finds
  * the command in `node_modules/.bin`. The hook is run by path, from the
@@ -19,8 +21,10 @@
  *   node "$CLAUDE_PROJECT_DIR/web/node_modules/@estiva-app/ui/dist/gates/cli.js" hook --app web
  *   node web/node_modules/@estiva-app/ui/dist/gates/cli.js status --app web
  */
+import { runCi } from './ci'
 import { writeGateCount } from './count'
 import { runHook } from './hook'
+import { nameEscapes } from './name-escapes'
 import { runStatus } from './status'
 
 const [command, ...rest] = process.argv.slice(2)
@@ -33,6 +37,8 @@ const audience = flag('package') ? 'package' : 'app'
 
 async function main(): Promise<number> {
   switch (command) {
+    case 'ci':
+      return runCi({ audience })
     case 'count': {
       const repo = value('repo')
       if (!repo) {
@@ -44,6 +50,13 @@ async function main(): Promise<number> {
       if (result.failures.length) process.stderr.write(`${result.failures.join('\n')}\n`)
       return result.failures.length ? 1 : 0
     }
+    case 'name-escapes': {
+      // Once, after taking 0.36.0: every unnamed marker gets the rules it keeps off (B3).
+      const result = await nameEscapes({ config: value('config') })
+      process.stdout.write(`${result.named.length} markers named:\n  ${result.named.join('\n  ')}\n`)
+      if (result.unreached.length) process.stdout.write(`${result.unreached.length} unnamed markers no rule reaches, left as they are:\n  ${result.unreached.join('\n  ')}\n`)
+      return 0
+    }
     case 'hook': {
       // A hook that fails open guards nothing: Claude Code lets a write through
       // on any exit but 2, and a crash exits 1 (audit A2). So a gate that cannot
@@ -52,6 +65,9 @@ async function main(): Promise<number> {
       try {
         const result = await runHook({ app: value('app'), audience })
         if (result.code === 2) process.stderr.write(result.message)
+        // A note on a write let through reaches Claude as additional context: plain
+        // stdout on exit 0 does not, for a PreToolUse hook (code.claude.com/docs/en/hooks-guide).
+        else if (result.note) process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: `A copied look, let through (it only warns):\n${result.note}` } })}\n`)
         return result.code
       } catch (error) {
         const why = error instanceof Error ? error.message.split('\n')[0] : String(error)
@@ -60,11 +76,11 @@ async function main(): Promise<number> {
       }
     }
     case 'status': {
-      process.stdout.write(`${await runStatus({ app: value('app'), json: flag('json'), detail: flag('detail') })}${flag('json') ? '' : '\n'}`)
+      process.stdout.write(`${await runStatus({ app: value('app'), json: flag('json'), detail: flag('detail'), escapes: flag('escapes') })}${flag('json') ? '' : '\n'}`)
       return 0
     }
     default:
-      process.stderr.write('estiva-gates <count | hook | status>\n')
+      process.stderr.write('estiva-gates <ci | count | hook | status | name-escapes>\n')
       return 1
   }
 }

package/src/gates/count.ts

@@ -69,7 +69,7 @@ export async function writeGateCount({ root = process.cwd(), repo, audience = 'a
 
   const failures: string[] = []
   if (disabled.length > 0) {
-    failures.push('', 'An eslint-disable switched a gate rule off. Write the reason above the element instead: // @estiva-escape: <reason>')
+    failures.push('', 'An eslint-disable switched a gate rule off. Write the reason above the element instead, naming the rule: // @estiva-escape(<rule>): <reason>')
     for (const d of disabled) failures.push(`  ${relative(root, d.filePath)}:${d.line}  ${d.ruleId}`)
   }
   return { rules, disabled, changed, lines, failures }

package/src/gates/create-app.test.ts

@@ -71,7 +71,7 @@ describe('create-estiva-app', () => {
   it('starts the count at zero and keeps the CI job named gate', () => {
     const count = JSON.parse(files['.gates-count.json'])
     expect(Object.values(count.rules)).toEqual([{ errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }])
-    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*npm run lint:rules/)
+    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*run: npx estiva-gates ci/)
     expect(files['docs/GATES-DEBT.md']).toContain('Nothing.')
   })
 
@@ -131,7 +131,7 @@ describe('create-estiva-app', () => {
     expect(registry.filesWithoutParts.map((file) => file.file)).toEqual(['src/main.tsx'])
     const scripts = JSON.parse(files['package.json']).scripts
     expect(scripts).toMatchObject({ 'ui:find': 'estiva-ui find', registry: 'estiva-ui build', 'registry:check': 'estiva-ui check' })
-    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*npm run registry:check/)
+    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*run: npx estiva-gates ci/)
     expect(files['.gitignore'].split('\n')).toContain('registry.json')
   })