@starci/eslint-canon-fe 1.4.1 → 1.4.2

package/props-and-slots.mjs

@@ -12,7 +12,7 @@
  * a shape is findable.
  */
 
-import { COMPONENT_ROOTS, isContractTableFile, isInComponentTier } from "./contract.mjs"
+import { COMPONENT_ROOTS, isContractTableFile, isInComponentTier, isTestFile } from "./contract.mjs"
 
 /** True when a parameter type contains an anonymous object shape, including inside intersections. */
 const isInlineObjectType = (node) => {
@@ -58,9 +58,6 @@ export const noInlineParameterType = {
 
 // -- SLOTS-4 ---------------------------------------------------------------------------------------
 
-/** The only three components where a React `children` hole is lawful. */
-const CHILDREN_SHELLS = ["ModalShell", "DrawerShell", "DropdownShell", "RouteShell"]
-
 /**
  * True for a component file the slot fence governs.
  *
@@ -74,15 +71,11 @@ const CHILDREN_SHELLS = ["ModalShell", "DrawerShell", "DropdownShell", "RouteShe
  * NAMED CHILD GRAMMAR that replaces one. Reporting it asks the file that abolished the anonymous
  * slot to stop describing what it admits instead.
  *
- * The three shells stay exempt for the reason canon already gives them: they pass real children
- * through and arrange nothing.
- *
  * @param filename - the file being linted.
  */
 const isGoverned = (filename) => {
   const path = String(filename || "").replace(/\\/g, "/")
   if (isContractTableFile(path)) return false
-  if (CHILDREN_SHELLS.some((shell) => isInComponentTier(path, `shells/${shell}`))) return false
   /*
    * The bare `src` root is dropped here, and only here. `COMPONENT_ROOTS` carries it as a
    * catch-all so a reader that walks up from any file still finds the table; used as a FENCE it
@@ -92,6 +85,69 @@ const isGoverned = (filename) => {
   return COMPONENT_ROOTS.filter((root) => root !== "src").some((root) => path.includes(`/${root}/`))
 }
 
+/**
+ * True when a function's whole body does nothing but turn `children` into a component
+ * reference and hand that reference to exactly one other component under a named prop.
+ *
+ * THIS IS SLOTS-4'S OWN EXCEPTION, READ FROM SHAPE, NOT FROM A NAME. The rule's message
+ * already promises it: a framework route layout may receive `ReactNode` outside the
+ * component tier, but must close it into a named projection before a component sees it.
+ * A shell that crosses `children` over a client/server boundary - wrapping it in
+ * `useCallback` so it survives as a function reference rather than an unserialisable
+ * inline component - IS that closing act; there is no contract key to name because the
+ * shell is deliberately generic across callers. What makes the exception SAFE to keep
+ * narrow is that the shape disqualifies itself the moment the body does one more thing:
+ * a second return, a conditional, a data read, an element of its own, or a forwarded
+ * value that never passes through the closure all fall through to the ordinary report.
+ *
+ * - Every statement but the last is a `const x = ...` naming either a plain member/param
+ *   read (`const Frame = input.frame`) or a `useCallback(...)` call - nothing else.
+ * - The last statement is the only `return`, and it returns exactly one JSX element.
+ * - That element's attributes only spread or forward existing bindings, and at least one
+ *   of them carries the `useCallback` result - the children-derived reference - by name.
+ */
+const isChildrenBoundaryConverter = (fn) => {
+  if (!fn || fn.body?.type !== "BlockStatement") return false
+  const statements = fn.body.body
+  let closureVar = null
+  let returnNode = null
+
+  for (const statement of statements) {
+    if (statement.type === "ReturnStatement") {
+      if (returnNode) return false // a second return means this does more than one thing
+      returnNode = statement.argument
+      continue
+    }
+    if (statement.type !== "VariableDeclaration" || statement.declarations.length !== 1) return false
+    const [declarator] = statement.declarations
+    const init = declarator.init
+    if (declarator.id.type !== "Identifier" || !init) return false
+    if (init.type === "MemberExpression" || init.type === "Identifier") continue // a plain prop read
+    if (init.type === "CallExpression" && init.callee?.type === "Identifier" && init.callee.name === "useCallback") {
+      const callback = init.arguments[0]
+      if (!callback || (callback.type !== "ArrowFunctionExpression" && callback.type !== "FunctionExpression")) {
+        return false
+      }
+      closureVar = declarator.id.name
+      continue
+    }
+    return false // any other statement is the component doing something of its own
+  }
+
+  if (!closureVar || !returnNode || returnNode.type !== "JSXElement") return false
+
+  let carriesClosure = false
+  for (const attribute of returnNode.openingElement.attributes || []) {
+    if (attribute.type === "JSXSpreadAttribute") continue
+    if (attribute.type !== "JSXAttribute" || !attribute.value) return false
+    const raw = attribute.value.type === "JSXExpressionContainer" ? attribute.value.expression : attribute.value
+    const value = raw?.type === "TSAsExpression" ? raw.expression : raw
+    if (value?.type !== "Identifier") return false
+    if (value.name === closureVar) carriesClosure = true
+  }
+  return carriesClosure
+}
+
 /**
  * A container takes `contract` and `render`, never `children`.
  *
@@ -99,25 +155,65 @@ const isGoverned = (filename) => {
  * aliases it defines, but nothing stops a file declaring its own props shape by hand and putting
  * `children` in it. What the alias makes unrepresentable, a hand-written interface makes ordinary.
  *
- * ModalShell, DrawerShell and DropdownShell are exempt because they ignore the interior shape and
- * pass it directly to the vendor body. No folder-wide exemption exists.
+ * Vendor mechanics branches still take a named contract/render projection. Framework route
+ * layouts sit outside the component tier and close their ReactNode into that projection before it
+ * reaches a component.
+ *
+ * ONE CLOSED EXCEPTION LIVES INSIDE THE COMPONENT TIER: a boundary-converter shell whose
+ * whole body matches {@link isChildrenBoundaryConverter}. It is closed by shape, checked
+ * against the actual function the props type belongs to, never by filename or export name
+ * - so nothing can opt in by being called `RouteShell`, and nothing loses the exemption by
+ * being renamed.
  */
 export const noChildrenSlot = {
   meta: {
     type: "problem",
-    docs: { description: "A container takes contract and render; only the three closed shells may take children." },
+    docs: { description: "Every component container takes contract and render, never children." },
     schema: [],
     messages: {
       slot:
-        "`children` accepts markup that has already been built, so its shape cannot be checked. Take contract + render instead. Only ModalShell, DrawerShell, DropdownShell and RouteShell may take one - the first three pass an interior straight to vendor mechanics, and RouteShell converts the children a framework layout is handed.",
+        "`children` accepts markup that has already been built, so its shape cannot be checked. Take contract + render instead. A framework route layout may receive ReactNode outside the component tier, but it must close that value into a named contract projection before handing it to a component.",
     },
   },
   create(context) {
     if (!isGoverned(context.filename || context.getFilename())) return {}
+
+    // Deferred to Program:exit so the boundary-converter exemption - which has to look at
+    // the whole file to find the function a props type belongs to - can clear a candidate
+    // before it is ever reported.
+    const candidates = []
+    const componentsByPropsType = new Map()
+
+    const enclosingFunction = (node) => {
+      for (let current = node.parent; current; current = current.parent) {
+        if (["ArrowFunctionExpression", "FunctionExpression", "FunctionDeclaration"].includes(current.type)) {
+          return current
+        }
+      }
+      return null
+    }
+
+    const enclosingTypeName = (node) => {
+      for (let current = node.parent; current; current = current.parent) {
+        if (current.type === "TSInterfaceDeclaration" || current.type === "TSTypeAliasDeclaration") {
+          return current.id?.name || null
+        }
+      }
+      return null
+    }
+
+    /** The name of the type a function's single parameter is annotated with, if any. */
+    const parameterTypeName = (fn) => {
+      const annotation = fn.params?.[0]?.typeAnnotation?.typeAnnotation
+      return annotation?.type === "TSTypeReference" && annotation.typeName?.type === "Identifier"
+        ? annotation.typeName.name
+        : null
+    }
+
     return {
       TSPropertySignature(node) {
         if (node.key && node.key.type === "Identifier" && node.key.name === "children") {
-          context.report({ node: node.key, messageId: "slot" })
+          candidates.push({ node: node.key, typeName: enclosingTypeName(node) })
         }
       },
       Property(node) {
@@ -125,9 +221,173 @@ export const noChildrenSlot = {
         if (node.parent && node.parent.type !== "ObjectPattern") return
         if (node.parent.parent && node.parent.parent.type === "VariableDeclarator") return
         if (node.key && node.key.type === "Identifier" && node.key.name === "children") {
-          context.report({ node: node.key, messageId: "slot" })
+          candidates.push({ node: node.key, fn: enclosingFunction(node) })
+        }
+      },
+      ":function"(fn) {
+        const typeName = parameterTypeName(fn)
+        if (typeName) componentsByPropsType.set(typeName, fn)
+      },
+      "Program:exit"() {
+        for (const candidate of candidates) {
+          const fn = candidate.fn || (candidate.typeName && componentsByPropsType.get(candidate.typeName))
+          if (fn && isChildrenBoundaryConverter(fn)) continue
+          context.report({ node: candidate.node, messageId: "slot" })
+        }
+      },
+    }
+  },
+}
+
+/** Name of a plain TypeScript property key. */
+const propertyName = (node) => {
+  const key = node?.key ?? node?.property
+  if (!key) return null
+  if (key.type === "Identifier") return key.name
+  if (key.type === "Literal" && typeof key.value === "string") return key.value
+  return null
+}
+
+/** Product source inside a supported component root. */
+const isComponentSource = (filename) => {
+  const path = String(filename || "").replace(/\\/g, "/")
+  return COMPONENT_ROOTS.filter((root) => root !== "src").some((root) => path.includes(`/${root}/`))
+}
+
+// -- SLOTS-5 · SLOTS-6 ---------------------------------------------------------------------------
+
+/** A caller cannot reach into one named internal part and style it. */
+export const noPerPartClassNameProp = {
+  meta: {
+    type: "problem",
+    docs: { description: "No <part>ClassName prop exposes a component's internal nodes." },
+    schema: [],
+    messages: {
+      perPart:
+        "`{{prop}}` lets a caller restyle a node it does not own. Replace the CSS door with a named semantic prop, and keep the appearance decision inside the component or its contract.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestFile(filename) || !isComponentSource(filename)) return {}
+    return {
+      TSPropertySignature(node) {
+        const name = propertyName(node)
+        if (!name || name === "className" || !/^[a-z][A-Za-z0-9]*ClassName$/.test(name)) return
+        context.report({ node, messageId: "perPart", data: { prop: name } })
+      },
+    }
+  },
+}
+
+/** Public house components never expose className/classNames placement doors. */
+export const noPublicClassNameProp = {
+  meta: {
+    type: "problem",
+    docs: { description: "House components own appearance and expose no public className/classNames prop." },
+    schema: [],
+    messages: {
+      declaration:
+        "Public component prop `{{prop}}` is a CSS placement door. Expose a semantic variant or a named contract instead.",
+      usage:
+        "Do not pass `{{prop}}` to house component `{{component}}`; its owner or parent contract decides appearance.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestFile(filename)) return {}
+    const inComponent = isComponentSource(filename)
+    const bindings = new Set()
+    return {
+      ImportDeclaration(node) {
+        const source = String(node.source?.value || "").replace(/\\/g, "/")
+        if (!/(?:^|\/)components\//.test(source)) return
+        for (const specifier of node.specifiers || []) {
+          if (specifier.local?.name) bindings.add(specifier.local.name)
         }
       },
+      TSPropertySignature(node) {
+        if (!inComponent) return
+        const name = propertyName(node)
+        if (name === "className" || name === "classNames") {
+          context.report({ node, messageId: "declaration", data: { prop: name } })
+        }
+      },
+      JSXOpeningElement(node) {
+        const component = node.name?.type === "JSXIdentifier" ? node.name.name : null
+        if (!component || !bindings.has(component)) return
+        for (const attribute of node.attributes || []) {
+          if (attribute.type !== "JSXAttribute") continue
+          const prop = attribute.name?.type === "JSXIdentifier" ? attribute.name.name : null
+          if (prop === "className" || prop === "classNames") {
+            context.report({ node: attribute, messageId: "usage", data: { prop, component } })
+          }
+        }
+      },
+    }
+  },
+}
+
+/** CSS-shaped layout props are not public API above the atomic leaf tier. */
+const FRAME_CSS_PROPS = new Set(["gap", "padding", "align", "justify", "className", "classNames", "style", "inline", "nested"])
+
+export const noPublicFrameCssProps = {
+  meta: {
+    type: "problem",
+    docs: { description: "Non-leaf component contracts expose semantic decisions, not CSS-shaped frame props." },
+    schema: [],
+    messages: {
+      css:
+        "`{{prop}}` is a public CSS/frame decision above the leaf tier. Move the arrangement into a named contract or expose the semantic state that selects one.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestFile(filename) || !isComponentSource(filename) || isInComponentTier(filename, "leaves")) return {}
+    return {
+      TSPropertySignature(node) {
+        const name = propertyName(node)
+        if (name && FRAME_CSS_PROPS.has(name)) context.report({ node, messageId: "css", data: { prop: name } })
+      },
+    }
+  },
+}
+
+/** String literal keys named by Omit/Pick/Exclude. */
+const typeKeys = (node, out = []) => {
+  if (!node) return out
+  if (node.type === "TSUnionType") {
+    for (const member of node.types || []) typeKeys(member, out)
+    return out
+  }
+  if (node.type === "TSLiteralType" && node.literal?.type === "Literal" && typeof node.literal.value === "string") {
+    out.push(node.literal.value)
+  }
+  return out
+}
+
+/** Hiding a CSS door with a utility type is not closing the owner that exposed it. */
+export const noCssDoorTypeLaundering = {
+  meta: {
+    type: "problem",
+    docs: { description: "Omit/Pick/Exclude cannot hide className/classNames/style doors." },
+    schema: [],
+    messages: {
+      utility:
+        "`{{utility}}` of `{{prop}}` launders a CSS door instead of closing it. Remove the prop from the owning public contract and every consumer.",
+    },
+  },
+  create(context) {
+    const file = String(context.filename || context.getFilename()).replace(/\\/g, "/")
+    if (isTestFile(file) || !file.includes("/src/")) return {}
+    return {
+      TSTypeReference(node) {
+        const utility = node.typeName?.type === "Identifier" ? node.typeName.name : null
+        if (!utility || !["Omit", "Pick", "Exclude"].includes(utility)) return
+        const params = node.typeArguments?.params || node.typeParameters?.params || []
+        const prop = typeKeys(params[1]).find((key) => key === "className" || key === "classNames" || key === "style")
+        if (prop) context.report({ node, messageId: "utility", data: { utility, prop } })
+      },
     }
   },
 }
@@ -176,6 +436,10 @@ export const noSurfaceListItemsSlot = {
 export const rules = {
   "no-inline-parameter-type": noInlineParameterType,
   "no-children-slot": noChildrenSlot,
+  "no-per-part-classname-prop": noPerPartClassNameProp,
+  "no-public-classname-prop": noPublicClassNameProp,
+  "no-public-frame-css-props": noPublicFrameCssProps,
+  "no-css-door-type-laundering": noCssDoorTypeLaundering,
   "no-surface-list-items-slot": noSurfaceListItemsSlot,
 }
 

package/props.ts

@@ -61,13 +61,13 @@ export type LeafProps<D extends ComponentData, A extends ComponentActions = Comp
 /**
  * A COMPOSITE's props. The same three slots a leaf has, and the absence of a fourth is the point.
  *
- * A composite is a CLOSED shape: it assembles leaves into an arrangement a caller can use but
- * cannot rearrange. That boundary with `branch` is held by this type rather than by a convention -
- * there is no `render` here, so an author who wanted a slot cannot express one and has to decide
- * which tier they are actually writing. A boundary the compiler holds does not drift.
- * CLOSED DOES NOT MEAN FREEHAND. A composite still assembles through a typed `Tree` contract;
- * raw structural markup would create an unnamed layout outside the registry. If a caller may
- * supply the content or recipe, the component is a branch rather than a composite.
+ * A composite is a CLOSED shape: it assembles leaves into an arrangement a caller can use but
+ * cannot rearrange. That boundary with `branch` is held by this type rather than by a convention -
+ * there is no `render` here, so an author who wanted a slot cannot express one and has to decide
+ * which tier they are actually writing. A boundary the compiler holds does not drift.
+ * CLOSED DOES NOT MEAN FREEHAND. A composite still assembles through a typed `Tree` contract;
+ * raw structural markup would create an unnamed layout outside the registry. If a caller may
+ * supply the content or recipe, the component is a branch rather than a composite.
  *
  * It is structurally identical to {@link LeafProps} and deliberately NOT an alias of it: the two
  * tiers answer different questions, and a shared name would let a reader conclude they are the same
@@ -85,18 +85,18 @@ export type CompositeProps<D extends ComponentData, A extends ComponentActions =
  *
  * THIS IS THE SLOT THAT USED TO BE `children`, AND THE CHANGE IS NOT COSMETIC. `children` is markup
  * that has already been built: it can be a `.map`, a ternary, a fragment, or a subtree nobody named,
- * so nothing above it can say what is inside a node and no rule can check. `render` is a contract
- * value in one of two lanes. This alias is the bound lane: Tree and ordinary branches receive
- * named slots or an explicit projection. A data-driven surface uses {@link ContractRenderBranchProps}
- * to receive a stable component type and pass changing runtime `props` into it.
+ * so nothing above it can say what is inside a node and no rule can check. `render` is a contract
+ * value in one of two lanes. This alias is the bound lane: Tree and ordinary branches receive
+ * named slots or an explicit projection. A data-driven surface uses {@link ContractRenderBranchProps}
+ * to receive a stable component type and pass changing runtime `props` into it.
  *
  * `contract` and `render` are one decision written twice, and `ContractComponent<K>` ties them together:
  * the key fixes which slots exist and what may fill each, so a card cannot say one thing and hold
  * another. A wrong leaf, wrong leaf props, a node where a leaf was asked for, a missing slot and a
  * slot nobody declared are five compile errors rather than five things a reviewer has to spot.
  *
- * A bare callback or JSX value may not arrive: neither carries the exact key metadata that makes
- * `contract` and `render` one checked decision.
+ * A bare callback or JSX value may not arrive: neither carries the exact key metadata that makes
+ * `contract` and `render` one checked decision.
  *
  * THERE IS NO LIST VARIANT, and there does not need to be. A slot that holds many says so in the
  * table with `repeats: true`; that slot becomes an array. `restingCount` separately fixes how many
@@ -110,26 +110,26 @@ export type BranchProps<
     readonly props: D
     readonly on?: A
     readonly contract: K
-    readonly render: ContractComponent<NoInfer<K>>
-    readonly isLoading?: boolean
-}
-
-/**
- * A data-driven contract host's props. Runtime data stays in `props`; `render` is a stable real
- * component type branded for the exact key. `SurfaceListCard` uses this lane because a repeated
- * domain collection must not be closed into a new callback descriptor at every host call site.
- */
-export type ContractRenderBranchProps<
-    D extends ComponentData,
-    K extends ContractKey,
-    A extends ComponentActions = ComponentActions,
-> = {
-    readonly props: D
-    readonly on?: A
-    readonly contract: K
-    readonly render: ContractComponent<NoInfer<K>, LeafProps<D, A>>
-    readonly isLoading?: boolean
-}
+    readonly render: ContractComponent<NoInfer<K>>
+    readonly isLoading?: boolean
+}
+
+/**
+ * A data-driven contract host's props. Runtime data stays in `props`; `render` is a stable real
+ * component type branded for the exact key. `SurfaceListCard` uses this lane because a repeated
+ * domain collection must not be closed into a new callback descriptor at every host call site.
+ */
+export type ContractRenderBranchProps<
+    D extends ComponentData,
+    K extends ContractKey,
+    A extends ComponentActions = ComponentActions,
+> = {
+    readonly props: D
+    readonly on?: A
+    readonly contract: K
+    readonly render: ContractComponent<NoInfer<K>, LeafProps<D, A>>
+    readonly isLoading?: boolean
+}
 
 /**
  * A BLOCK's presentational half. Two slots.

package/served-locale.mjs

@@ -1,5 +1,5 @@
 /**
- * Rules for the SERVED LOCALE law - `fe/canon/patterns/served-locale.md`.
+ * Rules for the SERVED LOCALE law - `patterns/fe/served-locale/INDEX.md`.
  *
  * WHY THESE EXIST. An application obeyed the translation law completely - every label resolved in a
  * connected half, no literal below a block, both catalogues in step - and served a Vietnamese reader

package/the-split.mjs

@@ -66,7 +66,7 @@ export const presentationalPurity = {
 export const connectedBlockHasPresentationalTwin = {
   meta: {
     type: "problem",
-    docs: { description: "A connected block index renders only its exact `_X` twin from component.tsx." },
+    docs: { description: "A connected block index renders only its exact `XBase` twin from component.tsx." },
     schema: [],
     messages: {
       missing:
@@ -81,7 +81,7 @@ export const connectedBlockHasPresentationalTwin = {
     const block = connectedBlock(context.filename || context.getFilename())
     if (!block) return {}
 
-    const twin = `_${block}`
+    const twin = `${block}Base`
     const worldBindings = new Set()
     const rendered = []
     let importsTwin = false

package/typography.mjs

@@ -1,83 +1,83 @@
-/**
- * The rule that holds `typography.md`.
- *
- * MOST OF THIS LAW IS A UNION, and what is left is one shape a type cannot see: a heading TAG
- * written by hand. The level union stops a fifth step being asked for; nothing in the type system
- * notices an `<h2>` in a file that never mentions the heading component at all.
- *
- * The rule's own twin lives in `tokens.mjs`: that one catches a heading assembled out of a large
- * size and a heavy weight on some other element. Between them they cover both ways a heading gets
- * hand-rolled - with the right tag and the wrong look, or the right look and no tag.
- */
-
-/** Forward-slash form of a filename, so Windows paths compare like every other path. */
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** Product source lives under `src/`; tooling and config are out of scope. */
-const isSourceFile = (filename) => normalizePath(filename).includes("/src/")
-
-/** A twin test may build heading markup by hand to assert against it. */
-const isTestFile = (filename) => /\.(?:test|spec)\.(?:ts|tsx)$/.test(normalizePath(filename))
-
-/** The one component that owns the tag and the size together, and therefore may write the tag. */
-const isHeadingComponent = (filename) => normalizePath(filename).includes("/src/components/leaves/Heading/")
-
-/** The tags a document outline is built from. */
-const HEADING_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"])
-
-/** The deepest level the component draws; below this a page has nested too far. */
-const DEEPEST_LEVEL = 4
-
-/** Intrinsic (lowercase) tag name, or null for a component. */
-const tagName = (opening) => {
-  const name = opening && opening.name
-  if (!name || name.type !== "JSXIdentifier") return null
-  return name.name === name.name.toLowerCase() ? name.name : null
-}
-
-// -- TYPESET-1 · TYPESET-2 -------------------------------------------------------------------------------
-
-/** A heading comes from the component that owns its tag and its size as one decision. */
-export const noHeadingTagOutsideHeadingComponent = {
-  meta: {
-    type: "problem",
-    docs: { description: "Heading tags are written by the heading component, from a level." },
-    schema: [],
-    messages: {
-      tag:
-        "`<{{tag}}>` written here throws away the two facts the heading component exists to keep together: the tag a screen reader builds the document outline from, and the size a reader sees. Set separately they drift, and a screen's third-largest text becomes its first heading. Render the heading component with a level of {{level}}; one prop decides both, so they cannot disagree.",
-      tooDeep:
-        "`<{{tag}}>` is deeper than the scale goes: levels stop at {{deepest}}, because a fifth means the page has nested further than a reader can hold. That is a structure problem wearing a styling problem's clothes - flatten the section, then render the title with a level the scale has.",
-    },
-  },
-  create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (!isSourceFile(file) || isTestFile(file) || isHeadingComponent(file)) return {}
-    return {
-      JSXOpeningElement(node) {
-        const tag = tagName(node)
-        if (!tag || !HEADING_TAGS.has(tag)) return
-        const level = Number(tag.slice(1))
-        if (level > DEEPEST_LEVEL) {
-          context.report({ node, messageId: "tooDeep", data: { tag, deepest: DEEPEST_LEVEL } })
-          return
-        }
-        context.report({ node, messageId: "tag", data: { tag, level } })
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "no-heading-tag-outside-heading-component": noHeadingTagOutsideHeadingComponent,
-}
-
-/**
- * The level this law asks for, as the plugin's own opinion.
- *
- * Exact: a tag name in a file that is not the component that owns it. A repository adopting this
- * with history should expect the deeper levels to report a structure problem rather than a styling
- * one, and those take longer to fix than the message suggests.
- */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))
+/**
+ * The rule that holds `typography.md`.
+ *
+ * MOST OF THIS LAW IS A UNION, and what is left is one shape a type cannot see: a heading TAG
+ * written by hand. The level union stops a fifth step being asked for; nothing in the type system
+ * notices an `<h2>` in a file that never mentions the heading component at all.
+ *
+ * The rule's own twin lives in `tokens.mjs`: that one catches a heading assembled out of a large
+ * size and a heavy weight on some other element. Between them they cover both ways a heading gets
+ * hand-rolled - with the right tag and the wrong look, or the right look and no tag.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** Product source lives under `src/`; tooling and config are out of scope. */
+const isSourceFile = (filename) => normalizePath(filename).includes("/src/")
+
+/** A twin test may build heading markup by hand to assert against it. */
+const isTestFile = (filename) => /\.(?:test|spec)\.(?:ts|tsx)$/.test(normalizePath(filename))
+
+/** The one component that owns the tag and the size together, and therefore may write the tag. */
+const isHeadingComponent = (filename) => normalizePath(filename).includes("/src/components/leaves/Heading/")
+
+/** The tags a document outline is built from. */
+const HEADING_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"])
+
+/** The deepest level the component draws; below this a page has nested too far. */
+const DEEPEST_LEVEL = 4
+
+/** Intrinsic (lowercase) tag name, or null for a component. */
+const tagName = (opening) => {
+  const name = opening && opening.name
+  if (!name || name.type !== "JSXIdentifier") return null
+  return name.name === name.name.toLowerCase() ? name.name : null
+}
+
+// -- TYPESET-1 · TYPESET-2 -------------------------------------------------------------------------------
+
+/** A heading comes from the component that owns its tag and its size as one decision. */
+export const noHeadingTagOutsideHeadingComponent = {
+  meta: {
+    type: "problem",
+    docs: { description: "Heading tags are written by the heading component, from a level." },
+    schema: [],
+    messages: {
+      tag:
+        "`<{{tag}}>` written here throws away the two facts the heading component exists to keep together: the tag a screen reader builds the document outline from, and the size a reader sees. Set separately they drift, and a screen's third-largest text becomes its first heading. Render the heading component with a level of {{level}}; one prop decides both, so they cannot disagree.",
+      tooDeep:
+        "`<{{tag}}>` is deeper than the scale goes: levels stop at {{deepest}}, because a fifth means the page has nested further than a reader can hold. That is a structure problem wearing a styling problem's clothes - flatten the section, then render the title with a level the scale has.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isSourceFile(file) || isTestFile(file) || isHeadingComponent(file)) return {}
+    return {
+      JSXOpeningElement(node) {
+        const tag = tagName(node)
+        if (!tag || !HEADING_TAGS.has(tag)) return
+        const level = Number(tag.slice(1))
+        if (level > DEEPEST_LEVEL) {
+          context.report({ node, messageId: "tooDeep", data: { tag, deepest: DEEPEST_LEVEL } })
+          return
+        }
+        context.report({ node, messageId: "tag", data: { tag, level } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-heading-tag-outside-heading-component": noHeadingTagOutsideHeadingComponent,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Exact: a tag name in a file that is not the component that owns it. A repository adopting this
+ * with history should expect the deeper levels to report a structure problem rather than a styling
+ * one, and those take longer to fix than the message suggests.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))