@starci/eslint-canon-fe 1.0.0

package/props-and-slots.mjs

@@ -0,0 +1,188 @@
+/**
+ * The rules that hold `props-and-slots.md`.
+ *
+ * ALMOST ALL OF THIS LAW IS HELD BY A TYPE, not by a rule. The slot aliases in `props.ts` are the
+ * fence: a fifth slot does not fail review, it fails to compile, and there is nothing left for a
+ * rule to patrol once the shape itself refuses. That is the stronger arrangement and it is why this
+ * module is small.
+ *
+ * What a type cannot see is a shape with no NAME. An inline object type at the parameter satisfies
+ * every constraint the alias imposes and is still wrong, because the wrongness is not about which
+ * fields exist - it is that nothing else can refer to them. A compiler has no opinion about whether
+ * a shape is findable.
+ */
+
+import { COMPONENT_ROOTS, isContractTableFile, isInComponentTier } from "./contract.mjs"
+
+/** True when a parameter type contains an anonymous object shape, including inside intersections. */
+const isInlineObjectType = (node) => {
+  if (!node) return false
+  if (node.type === "TSTypeLiteral") return true
+  if (node.type === "TSParenthesizedType") return isInlineObjectType(node.typeAnnotation)
+  if (node.type === "TSIntersectionType" || node.type === "TSUnionType") {
+    return (node.types || []).some(isInlineObjectType)
+  }
+  return false
+}
+
+// -- SLOTS-3 ---------------------------------------------------------------------------------------
+
+/** A parameter's complete shape is named in the module, never assembled at the parameter. */
+export const noInlineParameterType = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "A parameter takes one named props type, not an inline or intersected object shape." },
+    schema: [],
+    messages: {
+      inline:
+        "This parameter's shape is written inline, so it has no name and nothing can refer to it - not an import, not the twin that tests this file, not somebody looking for what this component accepts. Declare it in the module and name it here. The cost is one line; the difference is between a contract and a signature.",
+    },
+  },
+  create(context) {
+    const checkParams = (node) => {
+      for (const param of node.params || []) {
+        if (!param) continue
+        const declared = param.typeAnnotation?.typeAnnotation
+        if (!isInlineObjectType(declared)) continue
+        context.report({ node: param.typeAnnotation || param, messageId: "inline" })
+      }
+    }
+    return {
+      ArrowFunctionExpression: checkParams,
+      FunctionExpression: checkParams,
+      FunctionDeclaration: checkParams,
+      TSEmptyBodyFunctionExpression: checkParams,
+    }
+  },
+}
+
+// -- 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.
+ *
+ * TWO EXEMPTIONS AND ONE LAYOUT FIX, all of which this predicate got wrong at once.
+ *
+ * It read `/src/components/` as a literal, so in a monorepo - where the same tier sits at
+ * `packages/ui/src/*` - the rule applied to NOTHING. That repository reported no violations, which
+ * looked like compliance and was silence: the fence was not holding anywhere in it.
+ *
+ * The registry table is exempt because `ContractSpec.children` is not a children hole; it is the
+ * 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
+   * matches every file under `src/`, which pulls routed pages into a rule about component slots and
+   * reports a page for taking children - the one thing a page legitimately does.
+   */
+  return COMPONENT_ROOTS.filter((root) => root !== "src").some((root) => path.includes(`/${root}/`))
+}
+
+/**
+ * A container takes `contract` and `render`, never `children`.
+ *
+ * THE TYPE CANNOT CATCH THIS ONE, which is why it is here. `props.ts` refuses a fourth slot on the
+ * 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.
+ */
+export const noChildrenSlot = {
+  meta: {
+    type: "problem",
+    docs: { description: "A container takes contract and render; only the three closed shells may take 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.",
+    },
+  },
+  create(context) {
+    if (!isGoverned(context.filename || context.getFilename())) return {}
+    return {
+      TSPropertySignature(node) {
+        if (node.key && node.key.type === "Identifier" && node.key.name === "children") {
+          context.report({ node: node.key, messageId: "slot" })
+        }
+      },
+      Property(node) {
+        // a destructured `children` in a parameter, which is the same slot arriving by another door
+        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" })
+        }
+      },
+    }
+  },
+}
+
+// -- SLOTS-7 ---------------------------------------------------------------------------------------
+
+/** A joined-list surface receives domain collections through named props, never a generic items lane. */
+export const noSurfaceListItemsSlot = {
+  meta: {
+    type: "problem",
+    docs: { description: "SurfaceListCard receives collection data through named props, never items." },
+    schema: [],
+    messages: {
+      items:
+        "`items` creates a second runtime-data lane beside `props` and makes SurfaceListCard know every domain collection. Put the collection in the render component's named props type (for example `tasks`) and pass it through `props`.",
+    },
+  },
+  create(context) {
+    const filename = String(context.filename || context.getFilename()).replace(/\\/g, "/")
+    if (!filename.includes("/src/")) return {}
+    const bindings = new Set()
+    return {
+      ImportDeclaration(node) {
+        const source = String(node.source?.value || "").replace(/\\/g, "/")
+        if (!/(?:^|\/)components\/branches\/SurfaceListCard$/.test(source)) return
+        for (const specifier of node.specifiers || []) {
+          const imported = specifier.imported?.name
+          if (imported === "SurfaceListCard" && specifier.local?.name) bindings.add(specifier.local.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
+          if (attribute.name?.type === "JSXIdentifier" && attribute.name.name === "items") {
+            context.report({ node: attribute, messageId: "items" })
+          }
+        }
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-inline-parameter-type": noInlineParameterType,
+  "no-children-slot": noChildrenSlot,
+  "no-surface-list-items-slot": noSurfaceListItemsSlot,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Exact and mechanical: it fires on a syntactic shape rather than on a judgement, so there is no
+ * false-positive risk that would justify adopting it at `warn`.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/props.ts

@@ -0,0 +1,145 @@
+/**
+ * TEMPLATE - `src/components/contracts/props.ts`.
+ *
+ * Copy this file to that path unchanged. Unlike the contract table beside it, there is nothing here
+ * for a repository to grow: these are the slot shapes themselves, and a repository that edits them
+ * has changed the rules rather than filled them in.
+ *
+ * THE SLOT SHAPES, AS TYPES RATHER THAN AS A CONVENTION.
+ *
+ * Every component below a block takes a FIXED set of named slots and no others. Written as a type
+ * alias per tier, a fourth slot is not discouraged - it does not compile, because the alias is the
+ * whole shape and there is nowhere to put one.
+ *
+ * This is the difference between a rule and a fence. `interface XProps { props: XData; isLoading?: boolean }`
+ * is a rule: correct today, and one `extends` away from carrying a `className` next month.
+ * `type XProps = LeafProps<XData>` is a fence.
+ */
+import type { ContractComponent, ContractKey } from "./index"
+
+export type { InnerProps } from "./index"
+
+/**
+ * What DATA is: anything a JSON document could hold.
+ *
+ * A function does not satisfy it, and that is the only thing stopping a component being smuggled
+ * through `props` - which is why handlers travel in their own slot rather than beside the data.
+ *
+ * NOTE FOR AUTHORS: a component's data must be declared with `type`, not `interface`. TypeScript
+ * gives an implicit index signature to a type alias and not to an interface, so an interface
+ * silently fails this constraint. That is not a quirk to work around - it is the constraint doing
+ * its job.
+ */
+export type DataValue =
+    | string
+    | number
+    | boolean
+    | null
+    | undefined
+    | ReadonlyArray<DataValue>
+    | { readonly [key: string]: DataValue }
+
+/** The shape any component's data must have: data all the way down. */
+export type ComponentData = { readonly [key: string]: DataValue }
+
+/** The shape any component's handlers must have: functions, kept apart from the data. */
+export type ComponentActions = { readonly [key: string]: ((...args: Array<never>) => void) | undefined }
+
+/**
+ * A LEAF's props. Three slots, no fourth.
+ *
+ * `props` - what it draws. `on` - what it does. `isLoading` - handed down, never decided here.
+ * No `render`: only a branch assembles. No `className`: a caller who can restyle a node has
+ * become its second owner, and the component now has two authors who never speak.
+ */
+export type LeafProps<D extends ComponentData, A extends ComponentActions = ComponentActions> = {
+    readonly props: D
+    readonly on?: A
+    readonly isLoading?: boolean
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * kind of thing. What separates them is what the file may DO, not what it may accept.
+ */
+export type CompositeProps<D extends ComponentData, A extends ComponentActions = ComponentActions> = {
+    readonly props: D
+    readonly on?: A
+    readonly isLoading?: boolean
+}
+
+/**
+ * A BRANCH's props. The same three a leaf has, plus the key it draws and the components that fill
+ * the slots that key declares.
+ *
+ * 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.
+ *
+ * `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.
+ *
+ * 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
+ * placeholders draw while loading, because live length is dynamic and is not the skeleton count.
+ */
+export type BranchProps<
+    D extends ComponentData,
+    K extends ContractKey,
+    A extends ComponentActions = ComponentActions,
+> = {
+    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
+}
+
+/**
+ * A BLOCK's presentational half. Two slots.
+ *
+ * `state` is the business situation and it picks a tree; `props` is what that tree says. There is
+ * no `isLoading` here - a block WRITES the flag when it hands a tree down, and never receives one.
+ * The type is a union per state at the call site, so the data of a situation a surface is NOT in
+ * cannot be passed, and the data of the one it IS in cannot be omitted.
+ */
+export type BlockProps<S extends string, D extends ComponentData> = {
+    readonly state: S
+    readonly props: D
+}

package/served-locale.mjs

@@ -0,0 +1,161 @@
+/**
+ * Rules for the SERVED LOCALE law - `fe/canon/patterns/served-locale.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
+ * an English course on a `/vi/` URL. The chrome came from the dictionary and the content came from an
+ * API that was never told which language to serve, so the failure looked like a translation gap and
+ * was looked for in the dictionary, where there was nothing wrong. The header was missing, and no
+ * gate had anything to say about a header nobody wrote.
+ *
+ * WHAT THEY HOLD. That the transport chain declares a locale, and that exactly one place writes it.
+ * Both are file-at-a-time facts: the chain is assembled in one file, and a header is written where it
+ * is written.
+ *
+ * WHAT THEY CANNOT HOLD, stated rather than implied. Neither rule can tell whether the value the link
+ * computes is CORRECT - whether it reads the address, the cookie or a constant - because that is
+ * inside a function these rules only see the name of. A link that attaches `x-locale: "en"`
+ * unconditionally satisfies both and is wrong. That case is a review question and LOCALE-2 is where
+ * it is argued; pretending otherwise would be the rule claiming a guarantee it does not have.
+ *
+ * WHY THE FIRST RULE KEYS ON THE TERMINAL LINK RATHER THAN ON THE FILE PATH. A repository may name
+ * its client folder anything, and a path pattern that guessed wrong would either miss the real chain
+ * or fire on every helper beside it. The chain is identifiable by what it does: it builds the link
+ * that talks to the network.
+ *
+ * WITH ONE EXEMPTION THAT WAS FOUND BY RUNNING IT, NOT BY THINKING ABOUT IT. "Constructs the
+ * terminal link" is also true of the file that DEFINES that link, so the first version reported
+ * `links/http.ts` and its spec on a repository that had done everything right. There was no correct
+ * way to satisfy it there - a locale link inside the http link is a chain hiding in a link - and a
+ * rule with no correct way to satisfy it is a finding about the rule. A file under `links/` is one
+ * link; a chain is assembled elsewhere, which is where the locale belongs.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalize = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/**
+ * The link file that owns the locale header.
+ *
+ * This is the ONE file allowed to write it, and it is recognised by path rather than by content:
+ * the point of the second rule is that the header appears in one place, so that place has to be
+ * named somewhere, and a name is what the law and the rule can both refer to.
+ */
+export const isLocaleLinkFile = (filename) => /\/links\/locale\.[cm]?tsx?$/.test(normalize(filename))
+
+/**
+ * One link's own implementation, rather than a chain of them.
+ *
+ * WHY THIS EXEMPTION EXISTS, AND IT WAS MEASURED. The first version of the chain rule keyed only on
+ * "constructs the terminal link", which is true of the file that DEFINES that link - `links/http.ts`
+ * builds `new HttpLink(...)`, because that is its whole job. Run against real source it reported
+ * that file and its spec, and there was no correct way to satisfy it there: attaching a locale link
+ * inside the http link would be a chain hiding in a link.
+ *
+ * A file under `links/` is one link. A chain is assembled somewhere else, which is exactly where the
+ * locale belongs.
+ */
+export const isLinkImplementationFile = (filename) => /\/links\/[^/]+$/.test(normalize(filename))
+
+/** A spec or test file - it asserts about production shapes rather than being one. */
+export const isTestFile = (filename) => /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(normalize(filename))
+
+/** The header a request declares its language in. */
+export const LOCALE_HEADER = "x-locale"
+
+/** Callee names that construct the terminal link - the one that actually reaches the network. */
+const TERMINAL_LINK_CALLEES = new Set(["createHttpLink", "HttpLink", "createUploadLink", "BatchHttpLink"])
+
+/** Callee names that attach the reader's locale to an operation. */
+const LOCALE_LINK_CALLEES = new Set(["createAttachLocaleLink", "createLocaleLink"])
+
+/** The callee name of a call or `new` expression, when it has a plain one. */
+const calleeName = (node) => {
+  const callee = node && node.callee
+  if (!callee) return null
+  if (callee.type === "Identifier") return callee.name
+  if (callee.type === "MemberExpression" && callee.property && callee.property.type === "Identifier") {
+    return callee.property.name
+  }
+  return null
+}
+
+/** Every string-ish key a property can carry, so `"x-locale"` and `["x-locale"]` read the same. */
+const propertyKeyOf = (property) => {
+  if (!property || property.type !== "Property") return null
+  const key = property.key
+  if (!key) return null
+  if (key.type === "Identifier" && !property.computed) return key.name
+  if (key.type === "Literal" && typeof key.value === "string") return key.value
+  return null
+}
+
+export const rules = {
+  "api-client-attaches-the-locale": {
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "A transport chain that builds the terminal HTTP link must also attach the reader's locale, so every call declares the language it wants served.",
+      },
+      schema: [],
+      messages: {
+        missing:
+          "This assembles the API transport but never attaches the reader's locale, so every call it makes is served the server's default language. Add the locale link to the chain, beside the auth link and unconditionally - a guest reads in a language too. A surface that is bilingual in its chrome and monolingual in its content reads as a translation gap, which is why it gets looked for in the dictionary rather than here.",
+      },
+    },
+    create(context) {
+      const filename = context.filename || context.getFilename()
+      // A single link's implementation is not a chain - `links/http.ts` constructs the terminal link
+      // because defining it IS its job, and there is no correct way to attach a locale there. A
+      // spec asserts about a chain rather than being one.
+      if (isLinkImplementationFile(filename) || isTestFile(filename)) return {}
+      let terminalNode = null
+      let attachesLocale = false
+      const note = (node) => {
+        const name = calleeName(node)
+        if (name === null) return
+        if (TERMINAL_LINK_CALLEES.has(name)) terminalNode = terminalNode || node
+        if (LOCALE_LINK_CALLEES.has(name)) attachesLocale = true
+      }
+      return {
+        CallExpression: note,
+        NewExpression: note,
+        "Program:exit"() {
+          if (terminalNode && !attachesLocale) {
+            context.report({ node: terminalNode, messageId: "missing" })
+          }
+        },
+      }
+    },
+  },
+
+  "locale-header-belongs-to-the-link": {
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "The locale header is written by the locale link and nowhere else, so one place answers which language a request is in.",
+      },
+      schema: [],
+      messages: {
+        elsewhere:
+          "Only the locale link may write `x-locale`. Setting it here is a second answer to which language this request is in, and the two diverge the first time one of them is updated - usually leaving a single hook correct and the rest of the surface on the server's default. Let the transport attach it.",
+      },
+    },
+    create(context) {
+      const filename = context.filename || context.getFilename()
+      if (isLocaleLinkFile(filename)) return {}
+      return {
+        Property(node) {
+          if (propertyKeyOf(node) === LOCALE_HEADER) {
+            context.report({ node, messageId: "elsewhere" })
+          }
+        },
+      }
+    },
+  },
+}
+
+/** Every FE canon rule is an error; see `sources/fe/index.mjs` for why there is no warn tier. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/the-split.mjs

@@ -0,0 +1,146 @@
+/**
+ * The rule that holds `the-split.md`.
+ *
+ * ONE RULE, AND IT WATCHES ONE HALF. The drawing half's purity is checkable: a file that fetches,
+ * reads a store or resolves a word is visible in what it calls. The connected half's discipline is
+ * not - a file that draws badly, or settles the wrong situation, looks exactly like one that does
+ * neither. So this rule guards the boundary from the side where a machine can see it, and the other
+ * side stays a matter for review.
+ *
+ * The scope is the filename. `component.tsx` is the drawing half by convention across every tier
+ * that splits, so the convention does the scoping and the rule needs no configuration.
+ */
+
+/** Forward-slash form of a filename, so Windows paths compare like every other path. */
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The drawing half, named by the convention every split surface follows. */
+const isDrawingHalf = (filename) => /(?:^|\/)component\.tsx$/.test(normalizePath(filename))
+
+/** A connected block entrypoint and the public name its folder fixes. */
+const connectedBlock = (filename) => {
+  const match = normalizePath(filename).match(
+    /\/src\/components\/blocks\/(?:[^/]+\/)*([A-Z][A-Za-z0-9]*)\/index\.tsx$/,
+  )
+  return match ? match[1] : null
+}
+
+/**
+ * Calls that reach for the world instead of receiving it.
+ *
+ * Four families: a request, a store, the translation runtime, and a direct query. Each is a
+ * dependency the drawing half cannot be rendered from a fixture without.
+ */
+const REACHES_FOR_THE_WORLD =
+  /^(?:useSWR|useSWRMutation|use[A-Za-z0-9]*Swr|useAppSelector|useDispatch|use[A-Za-z0-9]*Store|useTranslations|useLocale|useFormatter|query[A-Z][A-Za-z0-9]*|mutation[A-Z][A-Za-z0-9]*)$/
+
+// -- SPLIT-1 ---------------------------------------------------------------------------------------
+
+/** The drawing half receives everything and asks for nothing. */
+export const presentationalPurity = {
+  meta: {
+    type: "problem",
+    docs: { description: "The drawing half takes resolved props: no request, no store, no translation." },
+    schema: [],
+    messages: {
+      reaches:
+        "`{{name}}(...)` reaches for the world from the drawing half. This file must be renderable from a fixture - that is what makes it testable without standing the world up first, and it is the whole reason the split exists. Move the call to `index.tsx` and pass the result down as a settled situation.",
+    },
+  },
+  create(context) {
+    if (!isDrawingHalf(context.filename || context.getFilename())) return {}
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (!callee || callee.type !== "Identifier") return
+        if (!REACHES_FOR_THE_WORLD.test(callee.name)) return
+        context.report({ node, messageId: "reaches", data: { name: callee.name } })
+      },
+    }
+  },
+}
+
+// -- SPLIT-5 ---------------------------------------------------------------------------------------
+
+/** A connected block delegates every render path to its exact pure twin. */
+export const connectedBlockHasPresentationalTwin = {
+  meta: {
+    type: "problem",
+    docs: { description: "A connected block index renders only its exact `_X` twin from component.tsx." },
+    schema: [],
+    messages: {
+      missing:
+        "`{{block}}` reads the world, so it must import exact `{{twin}}` from `./component`. A single leaf, one tree, or no local state is not an exception.",
+      bypass:
+        "Connected `{{block}}` renders `<{{rendered}}>` directly. Resolve the world here, then render only `<{{twin}}>`; component.tsx owns the complete presentation.",
+      unused:
+        "Connected `{{block}}` imports `{{twin}}` but never renders it. Every connected render path must cross the pure twin.",
+    },
+  },
+  create(context) {
+    const block = connectedBlock(context.filename || context.getFilename())
+    if (!block) return {}
+
+    const twin = `_${block}`
+    const worldBindings = new Set()
+    const rendered = []
+    let importsTwin = false
+    let readsWorld = false
+    let rendersTwin = false
+
+    return {
+      ImportDeclaration(node) {
+        const source = typeof node.source?.value === "string" ? node.source.value : ""
+        for (const specifier of node.specifiers || []) {
+          const imported = specifier.imported?.name
+          const local = specifier.local?.name
+          if (source === "./component" && imported === twin && local === twin) importsTwin = true
+          if (imported && local && REACHES_FOR_THE_WORLD.test(imported)) worldBindings.add(local)
+        }
+      },
+      CallExpression(node) {
+        if (node.callee?.type !== "Identifier") return
+        if (worldBindings.has(node.callee.name) || REACHES_FOR_THE_WORLD.test(node.callee.name)) {
+          readsWorld = true
+        }
+      },
+      JSXOpeningElement(node) {
+        if (node.name?.type !== "JSXIdentifier") return
+        rendered.push({ name: node.name.name, node })
+        if (node.name.name === twin) rendersTwin = true
+      },
+      "Program:exit"(node) {
+        if (!readsWorld) return
+        if (!importsTwin) {
+          context.report({ node, messageId: "missing", data: { block, twin } })
+          return
+        }
+        for (const entry of rendered) {
+          if (entry.name !== twin) {
+            context.report({
+              node: entry.node,
+              messageId: "bypass",
+              data: { block, rendered: entry.name, twin },
+            })
+          }
+        }
+        if (!rendersTwin) context.report({ node, messageId: "unused", data: { block, twin } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "presentational-purity": presentationalPurity,
+  "connected-block-has-presentational-twin": connectedBlockHasPresentationalTwin,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Exact: it fires on a call by name, in one file by name. A repository adopting it with history
+ * should expect each report to be a real move rather than a deletion - the call has to go
+ * somewhere, and where it goes is the other half.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))