@starci/eslint-canon-fe 4.0.0 → 5.1.2

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 5.1.2 - 2026-09-30
+
+- **Fix: `timer-needs-effect-cleanup` refused a correctly cleaned-up timer outside an effect.** nivo-fe `useNow` starts its `setInterval` inside the `subscribe` given to `useSyncExternalStore` and clears it in the unsubscribe that `subscribe` returns; the rule knew only `useEffect` cleanups and reported it. A timer is now also accepted when a function enclosing it directly returns a function (arrow expression body, or the last top-level `return`) that calls `clearTimeout`/`clearInterval` (bare, `window.` or `globalThis.`) on the same identifier the timer handle was stored in (`const id = ...` or `id = ...`). Detection is structural, not by name. A timer with no stored handle, a returned cleanup that clears another handle, or no returned cleanup at all is still refused.
+
+## 5.1.1 - 2026-09-30
+
+- **Fix: `use-client-only-at-boundary` knew only the app layout.** A workspace package keeps its grammar tiers directly under `src/` (`packages/<pkg>/src/{composites,branches,leaves}`, the `fe.package.ui` slot), but the rule accepted the directive only under `/components/...`, so nivo-fe's `packages/nivo-ui` reported 13 false findings. The tier names come from `PACKAGE_TIERS` in `lib/scope.mjs` (the slot's layers, no repo name); a package branch or leaf is a boundary, a package composite is not, and the app layout is unchanged.
+- **Fix: the `monorepo` layout scanned only `packages/ui`.** `LAYOUT_GLOBS.monorepo` named the shared package literally (`packages/ui/src/**`), so a workspace package with any other name (nivo-fe's `packages/nivo-ui`) was governed by no starci-fe rule and a deliberate bare `<img>` there printed nothing. The source glob is now `packages/*/src/**/*.{ts,tsx}` and the e2e glob adds `packages/*/e2e/**/*.{ts,tsx}`; every package is judged by the same rules.
+
+## 5.1.0 - 2026-09-29
+
+Round 2 of the FE enforcers, measured on nivo-fe, starci-next-fe and miamia-fe. Twenty-two rules, every one an error; no rule of 5.0.0 changed. Each is registered in `knowledge/hfs/rules.yaml` under the catalogue rule it enforces, with a Vietnamese failure code.
+
+- **Type safety (R22, `FE_TYPE_ESCAPE`)**: `no-type-assertion` (`as T`, `<T>x`; `as const` and `as unknown` stay), `no-non-null-assertion`, `no-explicit-any`. `no-double-cast` now has a why entry.
+- **Lists (R65, `FE_LIST_KEY`)**, new law `lists`: `list-item-has-key`, `no-index-key`, `no-inline-literal-prop-in-list`.
+- **Runtime hygiene (R65, R50)**, new law `hygiene`: `timer-needs-effect-cleanup` (`FE_EFFECT_CLEANUP`), `no-data-fetch-in-effect` (`FE_EFFECT_FETCH`), `no-empty-catch` (`FE_SWALLOWED_ERROR`), `no-console` (`FE_CONSOLE_CALL`).
+- **Formatting (R59, `FE_I18N_FORMATTER`)**, new law `formatting`: `use-intl-formatter` (`toLocale*String`, `new Intl.*Format`, displayed `toFixed`, currency glued to a template, date libraries).
+- **Next conventions**: `page-exports-metadata` (R54, `FE_PAGE_METADATA_MISSING`), `no-null-suspense-fallback` (R53, `FE_SUSPENSE_NULL_FALLBACK`), `navigation-from-intl` and `no-native-anchor` (R59, `FE_I18N_NAVIGATION`), `no-hardcoded-route` (R57, `FE_ROUTE_HARDCODED`).
+- **Client boundary (R55)**: `client-no-server-import` (`FE_CLIENT_SERVER_IMPORT`), `web-storage-only-in-modules` (`FE_STORAGE_OUTSIDE_MODULES`), `no-dangerous-html` (`FE_DANGEROUS_HTML`).
+- **Native controls (R62, `FE_NATIVE_IMAGE`)**: `no-native-img`, `image-has-size`.
+- **Transport (R51, `FE_OUTCOME_KIND_UNHANDLED`)**: `outcome-kinds-exhaustive`.
+- `lib/ast.mjs` holds the JSX attribute, call-name and effect-callback readers the new laws share. One doc page per new law; type-safety gained its page.
+
+## 5.0.0 - 2026-09-29
+
+HFS Phase 0 item 0.6. Breaking: the factory signature, the retired rules and the level of every rule.
+
+- **`starciFeConfig({ layout })`** returns two flat-config blocks (source and e2e) and owns the law: every published rule at `error` (the factory throws if one is not), the React Hooks rules (`eslint-plugin-react-hooks` 7, recommended set lifted to `error`, `set-state-in-effect` and `refs` required), and `linterOptions` (`noInlineConfig` plus `reportUnusedDisableDirectives: "error"`). The `plugin`, `recommended` and `linterOptions` inputs are gone. `eslint-plugin-react-hooks >=7` is a new peer dependency.
+- **`vn-ok` is removed entirely.** `no-second-language-in-source` and `no-hardcoded-copy-in-vocabulary` are replaced by `no-hardcoded-copy` (R58): no literal copy at any tier, in any language, no pragma, no endonym or `resources/` exemption. Same notion of literal as nivo-fe's `check-i18n-catalog.mjs` (a word is two or more letters). A `vn-ok:` comment is now itself a finding of `no-inline-lint-config`, which also refuses `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `eslint-env` and inline `eslint rule:` config, and now covers specs and the e2e tree.
+- New laws and rules: `env-owner` (R49: `no-env-outside-config`, `no-hardcoded-endpoint-fallback`), `transport` (R50-R52: `fetch-only-in-api-client`, `client-fetch-has-signal`, `no-shared-transport-state`, `client-maps-auth-to-refused`, `no-http-status-collapse`, `no-hand-typed-wire`), `client-boundary` (R55: `use-client-only-at-boundary`), `hooks-folder` (R56 lint half: `hooks-folder-holds-hooks-only`), `next-conventions` (`no-middleware-file`, `locale-segment-is-locale`, `no-second-i18n-stack`, `html-lang-from-locale`), `brand-values` (R61 TypeScript half: `no-raw-brand-value`), `native-controls` (R62: `no-native-form-control`), `size-and-state-budget` (R65: `component-line-budget`, `unit-hook-budget`, `no-hand-rolled-polling`), `e2e-shape` (R66, seven rules on `e2e/**` and `playwright.config.*`), `spec-quality` (R67 and the real-catalogue half of R60: six rules).
+- `sourceRecommended` and `e2eRecommended` are exported beside `recommended` (their union); the effective-config audit compares a production probe against `sourceRecommended`.
+- `why[rule]` is `{ code, vi, fixVi }`: the catalogue finding code and the Vietnamese why for every rule of the catalogued laws.
+- One doc page per law under `docs/`.

package/README.md

@@ -1,32 +1,47 @@
 # @starci/eslint-canon-fe
 
-The StarCi front-end lint canon for traditional React and TypeScript applications. It keeps
+The StarCi front-end lint canon for Next.js and TypeScript applications. It keeps
 component ownership, accessibility, loading behavior, vendor boundaries, translations, naming,
 and colocated class-name composition consistent without prescribing a custom rendering protocol.
 
 ```bash
-npm i -D @starci/eslint-canon-fe
+npm i -D @starci/eslint-canon-fe eslint-plugin-react-hooks
 ```
 
 ```js
-import starciFe, { recommended, linterOptions, starciFeConfig } from "@starci/eslint-canon-fe"
-
-export default [starciFeConfig({
-  layout: "single-app",
-  plugin: starciFe,
-  recommended,
-  linterOptions,
-})]
+import { starciFeConfig } from "@starci/eslint-canon-fe"
+
+export default [...starciFeConfig({ layout: "single-app" })]
 ```
 
-The `single-app` layout governs `src/**`; `monorepo` governs shared package and app source trees.
-The package publishes the plugin, recommended levels, repository audits, and layout helper from
-the root entry point.
+The factory returns two flat-config blocks and owns everything about the law: which rules are on
+(every one, at `error` - nothing is off and nothing is a warning), the React Hooks rules
+(`eslint-plugin-react-hooks` 7, its recommended set lifted to `error`, including
+`set-state-in-effect` and `refs`), and the inline-directive fence (`noInlineConfig` plus
+`reportUnusedDisableDirectives`). A repository names its layout and nothing else.
+
+- The **source** block governs `src/**` (`single-app`) or `packages/*/src/**` (every workspace package, not one named `ui`) and `apps/*/src/**`
+  (`monorepo`). A package keeps its grammar tiers at `src/{composites,branches,leaves}`; the client-boundary rule reads that layout as well as an app's `src/components/`.
+- The **e2e** block governs `e2e/**` and `playwright.config.*` with the e2e rules and the
+  escape-hatch fence.
+
+`recommended`, `sourceRecommended`, `e2eRecommended`, `why`, `audits` and the plugin itself are also
+exported. `sourceRecommended` is the map to compare against a production probe file with
+`audits["effective-config"]`; `why[rule]` is `{ code, vi, fixVi }`, the finding code and the
+Vietnamese why the harness quotes.
 
 ## Rules
 
-Rules cover comments, file layout, icons and vendor ownership, landmarks, loading states, naming,
-props, served locales, component splits, design tokens, translations, type safety, typography, and
+Each law has a page under [`docs/`](docs) with, for every rule, an invalid and a valid example and
+its Vietnamese why. New in 5.0: [env-owner](docs/env-owner.md), [transport](docs/transport.md),
+[client-boundary](docs/client-boundary.md), [hooks-folder](docs/hooks-folder.md),
+[next-conventions](docs/next-conventions.md), [translation](docs/translation.md) (no literal copy at any
+tier, no `vn-ok`), [brand-values](docs/brand-values.md), [native-controls](docs/native-controls.md),
+[size-and-state-budget](docs/size-and-state-budget.md), [e2e-shape](docs/e2e-shape.md),
+[spec-quality](docs/spec-quality.md) and [lint-escape-hatch](docs/lint-escape-hatch.md). `timer-needs-effect-cleanup` also accepts a timer whose enclosing function returns a cleanup clearing the same handle (5.1.2). New in 5.1: [lists](docs/lists.md), [hygiene](docs/hygiene.md), [formatting](docs/formatting.md) and [type-safety](docs/type-safety.md), plus rules added to next-conventions, client-boundary, native-controls and transport.
+
+Older laws cover comments, file layout, icons and vendor ownership, landmarks, loading states,
+naming, props, served locales, component splits, design tokens, type safety, typography, and
 class-name ownership. Reusable class names belong in a colocated `classNames.ts` module and should
 be composed with HeroUI `cn` using one utility token per argument.
 
@@ -37,9 +52,12 @@ shapes and never a data status (`no-data-status-shape`), and a block renders eac
 loading/forbidden/error/empty through `SlotView` (`slot-status-through-slotview`). Reference tree:
 `.claude/examples/shape-slot`.
 
+The one locale pattern everywhere is `next-intl`, a `[locale]` segment, default `vi`,
+`localePrefix: "as-needed"`, and `proxy.ts` instead of `middleware.ts`.
+
 Grammar is a business-neutral HeroUI-backed component package. Its components accept ordinary
 typed React props and children.
 
 ## Requirements
 
-ESLint 9+ (flat config) and Node.js 20.9+.
+ESLint 9+ (flat config), `eslint-plugin-react-hooks` 7+, and Node.js 20.9+.

package/brand-values.mjs

@@ -0,0 +1,174 @@
+/**
+ * The rule that holds `brand-values.md` (HFS R61 `FE_STYLE_TOKEN_ONLY`, the TypeScript half; the CSS
+ * half belongs to `@starci/stylelint-canon`).
+ *
+ * ONE PLACE FOR A COLOUR. Colour values exist in `modules/brand/brand.css`, set only on the tokens
+ * the grammar declares, with a light and a dark value, and checked against the brand record. A hex
+ * in a component is a colour that has no dark value, cannot be re-branded, and drifts from the
+ * record: one repository carried three different ways to override the brand, and another 4.3k lines
+ * of hand-made CSS with a private token namespace.
+ *
+ * LENGTHS FOLLOW. A pixel length in TypeScript (`"12px"`, `{ width: 12 }` in a `style` prop) is a
+ * spacing decision that skipped the grammar's scale, so it does not move with density, zoom or a
+ * breakpoint. Spacing and sizing come from the grammar's utility tokens.
+ *
+ * WHAT IT DELIBERATELY LEAVES ALONE: a fragment identifier (`href="#top"`, `id`, `htmlFor`), a
+ * `data:` URI, a component's `color="primary"` prop (that is a variant name, not a colour), and
+ * Tailwind arbitrary values (`w-[12px]`), which `no-arbitrary-value` already reports - two rules
+ * for one span would be two findings for one fix.
+ */
+
+import { isSpecFile } from "./lib/scope.mjs"
+import { isContentFile } from "./comments.mjs"
+
+/** A hex colour: 3, 4, 6 or 8 digits, not a longer word and not part of an identifier. */
+const HEX_COLOR = /(?<![\w&])#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![\w-])/
+
+/** A functional colour notation. */
+const COLOR_FUNCTION = /\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color-mix)\(/i
+
+/** A pixel length, not inside an arbitrary-value bracket and not part of a longer number or word. */
+const PIXEL_LENGTH = /(?<![\w.#[-])-?(?:\d+\.?\d*|\.\d+)px\b/
+
+/** Attributes whose value is a fragment or an id, where a `#abc` is not a colour. */
+const NON_COLOR_ATTRS = new Set(["href", "id", "htmlFor", "to", "name", "aria-controls", "aria-labelledby", "aria-describedby"])
+
+/** SVG paint attributes: a named colour here is a raw brand value. */
+const PAINT_ATTRS = new Set(["fill", "stroke", "stopColor", "floodColor", "lightingColor"])
+
+/** Style properties that take a colour. */
+const COLOR_KEYS = new Set([
+  "color",
+  "background",
+  "backgroundColor",
+  "borderColor",
+  "outlineColor",
+  "fill",
+  "stroke",
+  "caretColor",
+  "accentColor",
+  "textDecorationColor",
+])
+
+/** Style properties that take a length. */
+const LENGTH_KEYS = new Set([
+  "width",
+  "height",
+  "minWidth",
+  "maxWidth",
+  "minHeight",
+  "maxHeight",
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "gap",
+  "margin",
+  "marginTop",
+  "marginRight",
+  "marginBottom",
+  "marginLeft",
+  "padding",
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+  "fontSize",
+  "borderRadius",
+  "letterSpacing",
+])
+
+/** Values that carry no raw colour: a token reference or a keyword. */
+const NEUTRAL_COLOR = /^(?:var\(|inherit$|initial$|unset$|revert$|currentcolor$|transparent$|none$)/i
+
+/** Static string of a literal or an expression-free template, else null. */
+const staticString = (node) => {
+  if (!node) return null
+  if (node.type === "Literal" && typeof node.value === "string") return node.value
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0]?.value.cooked ?? ""
+  return null
+}
+
+/** No raw colour, hex or pixel value outside `brand.css`. */
+export const noRawBrandValue = {
+  meta: {
+    type: "problem",
+    docs: { description: "No hex, colour function, named paint colour or px length in TypeScript; tokens only." },
+    schema: [],
+    messages: {
+      color:
+        "A raw colour value (`{{value}}`). Colour values exist only in `modules/brand/brand.css`, on the tokens the grammar declares, with a light and a dark value. Here it has no dark value, cannot be re-branded and drifts from the brand record. Use a grammar token class or variable.",
+      length:
+        "A raw pixel length (`{{value}}`). Spacing and size come from the grammar's scale so they move with density, zoom and breakpoint. Use a grammar utility token.",
+      named:
+        "`{{key}}: {{value}}` puts a named colour in a style. Colour is a token, not a word: use a grammar token (`var(--...)` or a token class).",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isSpecFile(filename) || isContentFile(filename)) return {}
+    const source = context.sourceCode || context.getSourceCode()
+    /** Values already reported through an owner, so a string reports once. */
+    const claimed = new WeakSet()
+
+    /** True when a node sits inside a JSX `style={...}` attribute. */
+    const inStyleAttribute = (node) =>
+      source
+        .getAncestors(node)
+        .some((ancestor) => ancestor.type === "JSXAttribute" && ancestor.name.type === "JSXIdentifier" && ancestor.name.name === "style")
+
+    /** Reports the first raw value in a string, once. */
+    const scan = (node, text) => {
+      if (claimed.has(node) || typeof text !== "string" || text.startsWith("data:")) return
+      const parent = node.parent
+      if (parent && parent.type === "JSXAttribute" && NON_COLOR_ATTRS.has(parent.name.name)) return
+      if (parent && parent.type === "JSXExpressionContainer" && parent.parent.type === "JSXAttribute") {
+        if (NON_COLOR_ATTRS.has(parent.parent.name.name)) return
+      }
+      if (parent && (parent.type === "ImportDeclaration" || parent.type === "ExportAllDeclaration" || parent.type === "ExportNamedDeclaration")) return
+      const color = HEX_COLOR.exec(text) || COLOR_FUNCTION.exec(text)
+      if (color) return context.report({ node, messageId: "color", data: { value: color[0].replace(/\($/, "(...)") } })
+      const length = PIXEL_LENGTH.exec(text)
+      if (length) context.report({ node, messageId: "length", data: { value: length[0] } })
+    }
+
+    return {
+      Literal(node) {
+        scan(node, node.value)
+      },
+      TemplateElement(node) {
+        scan(node, node.value && node.value.cooked)
+      },
+      JSXAttribute(node) {
+        if (node.name.type !== "JSXIdentifier" || !PAINT_ATTRS.has(node.name.name)) return
+        const value = node.value && node.value.type === "JSXExpressionContainer" ? node.value.expression : node.value
+        const text = staticString(value)
+        if (text === null || NEUTRAL_COLOR.test(text) || HEX_COLOR.test(text) || COLOR_FUNCTION.test(text)) return
+        claimed.add(value)
+        context.report({ node, messageId: "named", data: { key: node.name.name, value: text } })
+      },
+      Property(node) {
+        if (node.computed || node.key.type !== "Identifier" || !inStyleAttribute(node)) return
+        const key = node.key.name
+        if (COLOR_KEYS.has(key)) {
+          const text = staticString(node.value)
+          if (text === null || NEUTRAL_COLOR.test(text) || HEX_COLOR.test(text) || COLOR_FUNCTION.test(text)) return
+          claimed.add(node.value)
+          context.report({ node, messageId: "named", data: { key, value: text } })
+        } else if (LENGTH_KEYS.has(key) && node.value.type === "Literal" && typeof node.value.value === "number") {
+          if (node.value.value === 0) return
+          claimed.add(node.value)
+          context.report({ node: node.value, messageId: "length", data: { value: `${key}: ${node.value.value}` } })
+        }
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-raw-brand-value": noRawBrandValue,
+}
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/class-names.mjs

@@ -3,7 +3,7 @@
  * classNames files own the utility-token composition.
  */
 
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+import { normalizePath } from "./lib/path.mjs"
 const isComponentSource = (filename) => normalizePath(filename).includes("/src/components/")
 const isClassNamesFile = (filename) => /\/classNames\.tsx?$/.test(normalizePath(filename))
 const isClassAttribute = (node) => node.type === "JSXAttribute" && ["className", "class"].includes(node.name?.name)

package/client-boundary.mjs

@@ -0,0 +1,199 @@
+/**
+ * The rule that holds `client-boundary.md` (HFS R55, `FE_CLIENT_BOUNDARY`).
+ *
+ * SERVER FIRST. A route file is a server component; `"use client"` is a cost the app pays where a
+ * reader interacts, and it is paid once, at the top of the interactive subtree, not sprinkled
+ * wherever a hook happened to be needed. The measured alternative: 155 client files in one app,
+ * a client layout that shipped a 132 KB message catalog to every page, against 3 client files in a
+ * sibling app that did the same job server-first.
+ *
+ * The directive is allowed in exactly the places the framework or the interaction requires:
+ *   - the `index.tsx` of an interactive block (or overlay), which is the connected half;
+ *   - a leaf, whose interactivity is intrinsic (a menu, a tooltip trigger);
+ *   - `error.tsx` and `global-error.tsx`, which Next requires to be client components.
+ * Everything below a client block is already on the client and needs no directive; everything
+ * above it is a server component and must not have one.
+ */
+
+import { PACKAGE_TIERS, ROUTE_SLOTS, isSpecFile, stem } from "./lib/scope.mjs"
+import { normalizePath } from "./lib/path.mjs"
+
+/** The framework's own client-only files. */
+const FRAMEWORK_CLIENT = new Set(["error", "global-error"])
+
+/** True when the program opens with the `"use client"` directive. */
+const clientDirective = (program) =>
+  program.body.find(
+    (statement) => statement.type === "ExpressionStatement" && statement.directive === "use client",
+  ) ?? null
+
+/**
+ * The component tiers of a workspace package sit directly under `src/` (grammar tier names,
+ * `slots.yaml` `fe.package.ui`: composites, branches, leaves), with no `components/` folder above
+ * them. A package has no data layer, so its interactive tiers, branches and leaves, are where the
+ * directive is legitimate; a composite is presentation and stays a server-safe component.
+ */
+const PACKAGE_CLIENT_TIERS = PACKAGE_TIERS.filter((tier) => tier !== "composites")
+const PACKAGE_TIER = new RegExp(`/packages/[^/]+/src/(?:${PACKAGE_CLIENT_TIERS.join("|")})/`)
+
+/** Where the directive is a legitimate boundary. */
+const isBoundary = (file) =>
+  FRAMEWORK_CLIENT.has(stem(file)) ||
+  (/\/components\/blocks\//.test(file) && stem(file) === "index") ||
+  (/\/features\/overlays\//.test(file) && stem(file) === "index") ||
+  /\/components\/leaves\//.test(file) ||
+  PACKAGE_TIER.test(file)
+
+/** The slot a file fills in the route tree, when it fills one. */
+const slotOf = (file) => {
+  const name = stem(file)
+  if (/\/app\//.test(file) && ROUTE_SLOTS.includes(name)) return name
+  if (/\/features\/pages\//.test(file)) return "page owner"
+  if (/\/features\/layouts\//.test(file)) return "layout owner"
+  return null
+}
+
+/** `"use client"` only at an interaction boundary; pages and layouts stay server components. */
+export const useClientOnlyAtBoundary = {
+  meta: {
+    type: "problem",
+    docs: { description: "`\"use client\"` appears only at a block index, a leaf, or a Next error boundary." },
+    schema: [],
+    messages: {
+      slot:
+        "`\"use client\"` on a {{slot}}. Routes, pages and layouts are server components: making one a client component ships its whole subtree, including the message catalog, to every reader and stops it reading data on the server. Move the interaction into a block below it and put the directive on that block's `index.tsx`.",
+      elsewhere:
+        "`\"use client\"` here is not at an interaction boundary. The directive belongs on the `index.tsx` of the interactive block (or overlay), on a leaf whose interaction is intrinsic, or on `error.tsx`/`global-error.tsx`. Below a client block the file is already client; above one it must stay a server component.",
+    },
+  },
+  create(context) {
+    const filename = normalizePath(context.filename || context.getFilename())
+    if (isSpecFile(filename) || isBoundary(filename)) return {}
+    const slot = slotOf(filename)
+    return {
+      Program(program) {
+        const directive = clientDirective(program)
+        if (!directive) return
+        if (slot) context.report({ node: directive, messageId: "slot", data: { slot } })
+        else context.report({ node: directive, messageId: "elsewhere" })
+      },
+    }
+  },
+}
+
+// -- FE-CLIENT-2 -----------------------------------------------------------------------------------
+
+/** Node built-ins a browser bundle cannot carry. */
+const NODE_BUILTINS = /^(?:node:.+|fs|fs\/promises|path|os|net|tls|http|https|http2|child_process|cluster|crypto|stream|zlib|dns|worker_threads)$/
+
+/** A server-only source: the marker package, the request-scoped Next APIs, a Node built-in, a server reader. */
+const serverOnlyReason = (source) => {
+  if (source === "server-only") return "`server-only`"
+  if (source === "next/headers") return "`next/headers`"
+  if (source === "next/server") return "`next/server`"
+  if (NODE_BUILTINS.test(source)) return `\`${source}\``
+  if (/(?:^|\/)modules\/api\/(?:.+\/)?read-[^/]+$/.test(source)) return `the server reader \`${source}\``
+  return null
+}
+
+/** A client component imports nothing that only exists on the server. */
+export const clientNoServerImport = {
+  meta: {
+    type: "problem",
+    docs: { description: "A `\"use client\"` file does not import `server-only`, `next/headers`, a Node built-in or a server reader." },
+    schema: [],
+    messages: {
+      server:
+        "This client component imports {{what}}, which exists only on the server. The build either fails or, worse, pulls server code and its secrets toward the browser bundle. Read the data in a server component or a server reader and pass the result down as props, or call the app client through SWR.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (isSpecFile(file)) return {}
+    let client = false
+    return {
+      Program(program) {
+        client = clientDirective(program) !== null
+      },
+      ImportDeclaration(node) {
+        if (!client || node.importKind === "type") return
+        const what = serverOnlyReason(String(node.source.value))
+        if (what) context.report({ node, messageId: "server", data: { what } })
+      },
+    }
+  },
+}
+
+// -- FE-CLIENT-3 -----------------------------------------------------------------------------------
+
+/** Web storage exists only in the browser and only under `modules/`, which guards it. */
+const STORAGE = new Set(["localStorage", "sessionStorage"])
+
+/** Web storage is read and written only inside `modules/`. */
+export const webStorageOnlyInModules = {
+  meta: {
+    type: "problem",
+    docs: { description: "`localStorage` and `sessionStorage` are touched only inside `modules/`." },
+    schema: [],
+    messages: {
+      storage:
+        "`{{name}}` here, outside `modules/`. Storage does not exist on the server and throws in private windows and when the quota is full, so a block that reads it during render breaks server rendering and hydrates differently from the HTML it received. Put the read and write behind a hook or a module that guards both (`typeof window`, try/catch) and let the block call that.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (isSpecFile(file) || !file.includes("/src/") || /\/modules\//.test(file)) return {}
+    return {
+      MemberExpression(node) {
+        if (node.computed || node.property.type !== "Identifier" || !STORAGE.has(node.property.name)) return
+        if (node.object.type !== "Identifier" || (node.object.name !== "window" && node.object.name !== "globalThis")) return
+        context.report({ node, messageId: "storage", data: { name: node.property.name } })
+      },
+      Identifier(node) {
+        if (!STORAGE.has(node.name)) return
+        const parent = node.parent
+        if (parent.type === "MemberExpression" && parent.property === node) return
+        if (parent.type === "Property" && parent.key === node && !parent.shorthand) return
+        if (parent.type === "TSPropertySignature" || parent.type === "TSTypeAnnotation") return
+        context.report({ node, messageId: "storage", data: { name: node.name } })
+      },
+    }
+  },
+}
+
+// -- FE-CLIENT-4 -----------------------------------------------------------------------------------
+
+/** Raw HTML is set only on a `<script>`, where the framework has no other way to inline JSON-LD or the theme bootstrap. */
+export const noDangerousHtml = {
+  meta: {
+    type: "problem",
+    docs: { description: "`dangerouslySetInnerHTML` only on `<script>`; never on a visible element." },
+    schema: [],
+    messages: {
+      html:
+        "`dangerouslySetInnerHTML` on `<{{tag}}>` writes a string into the page as markup, so any text from a user, a provider or a message catalogue becomes script. Render the content as elements. The one legitimate use is a `<script>` carrying JSON-LD or the theme bootstrap, from a constant this app wrote.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      JSXAttribute(node) {
+        if (node.name.type !== "JSXIdentifier" || node.name.name !== "dangerouslySetInnerHTML") return
+        const opening = node.parent
+        const tag = opening.name.type === "JSXIdentifier" ? opening.name.name : "element"
+        if (tag !== "script") context.report({ node, messageId: "html", data: { tag } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "use-client-only-at-boundary": useClientOnlyAtBoundary,
+  "client-no-server-import": clientNoServerImport,
+  "web-storage-only-in-modules": webStorageOnlyInModules,
+  "no-dangerous-html": noDangerousHtml,
+}
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))