@starci/eslint-canon-fe 5.1.2 → 6.0.1

package/CHANGELOG.md

@@ -1,8 +1,92 @@
 # Changelog
 
+## 6.0.1 - 2026-09-30
+
+- **Fix: `no-hand-rolled-polling` refused a shared clock.** A timer is polling only when what it runs reads data - a call whose
+  value is a promise (`fetch`, the transport client, a reader, SWR's `mutate()`), an `await`, or a same-file function that does -
+  decided by type, not by name. nivo-fe `useNow` (a one-minute tick behind `useSyncExternalStore`) and a state countdown pass; a
+  timer that fetches or revalidates is still refused. The self-scheduling `setTimeout` check follows the enclosing function's
+  binding, not its spelling. The FE convention names no shared clock owner, so no clock rule is added.
+
+## 6.0.0 - 2026-09-30
+
+- **Census fixes (starci-next-fe main, lane F0):** `one-outcome-union` treats a `kind` union as a result union only with an `ok`
+  arm beside a failure kind (a mapper's view union - `LessonViewerView`, `StudyStepView` - is a screen state);
+  `client-maps-auth-to-refused` accepts the Outcome constructor named by its kind (`failed("refused", ...)`) and a status branch
+  inside a helper whose parameter every call fills with the response status;
+  `i18n-stack-in-one-module` lets the proxy of a one-app repository build the locale middleware; `server-module-marks-server-only`
+  requires the marker of server modules and of every server reader (role `reader`), not of components (reachability is
+  FE_CLIENT_REACHES_SERVER's); `route-tree-holds-routes-only` admits next-intl's root `not-found.tsx` and its root `layout.tsx`.
+
+- **Every law scopes by slot, never by folder regex (lane F0-H).** The path predicates of `class-names`, `props-and-slots`,
+  `vendor-boundary`, `loading`, `type-safety`, `typography`, `brand-values`, `formatting`, `comments`, `hygiene`, `translation`,
+  `lint-escape-hatch`, `client-boundary`, `file-layout`, `shape-slot`, `the-split`, `landmark`, `icon`, `served-locale`, `e2e-shape`,
+  `hooks-folder`, `naming`, `next-conventions`, `tokens`, `size-and-state-budget`, `spec-quality` and `transport` ask the slot view
+  (`kind`, `role`, tier, owner, `hfs.allows(file)`, `classifyImport`) instead of testing a path. Shared-package layers (`fe.package.ui`)
+  are governed like app components; a file no slot owns is judged by `hfs check` (`HFS_SLOT_UNDECLARED`), not by a folder-name rule.
+  Line and hook budgets (`component.tsx`, `index.tsx`, `file`, `useState`, `dataHooks`) are read from the slot manifest.
+  `navigation-from-intl` exempts only the `proxy` and `global-error` roles; `no-middleware-file` reads slot `fe.source-root-retired`;
+  `route-tree-holds-routes-only` reads the `allows` of `fe.route`; `no-unresolved-token-class` reads the app's route and brand stylesheets.
+
+- New law `status-colors` (R61 `FE_STYLE_TOKEN_ONLY`): `status-text-uses-soft-foreground` refuses a class that paints text, an icon or a
+  text decoration with a solid status tone (`text-success`, `fill-danger`, `stroke-warning`, `decoration-info`, with any variant, opacity or
+  `!`), read from `className`/`class`, `cn()`/`clsx()` arguments, conditionals, arrays, constants and `classes` entries. The soft pair
+  (`text-<tone>-soft-foreground`, `bg-<tone>-soft`), a solid fill with its own ink (`bg-<tone> text-<tone>-foreground`) and solid borders,
+  rings and outlines pass. The tones come from `lib/status-tones.generated.mjs`, generated from the grammar by
+  `packages/stylelint` (`npm run vocabulary`), never listed in the rule.
+
+- **Breaking: `starciFeConfig({ hfs: loadHfs(import.meta.url) })` replaces `starciFeConfig({ layout })`.** The factory reads the
+  repository's `hfs.json` and the shipped slot manifest (`runtime/`, refreshed by `packages/hfs/scripts/sync-runtime.mjs`), lints
+  every app's and every workspace package's `src/` with typed linting (`parserOptions.projectService`) and the e2e tree
+  syntax-only, ignores build output, `__generated__/` and `.starci/`, and puts the slot view in `settings.starci.hfs`
+  (`lib/hfs.mjs` `hfsOf(context)`); `lib/types.mjs` holds the type-aware helpers. `LAYOUTS`/`LAYOUT_GLOBS` are deleted.
+- **Breaking: the `lint-adoption` law and its `effective-config` audit are deleted**, with `audits`/`auditOwners`: the
+  managed `eslint.config.mjs` one-liner that `hfs check` compares with its render (R17) is the one proof that no rule is off.
+- `linterOptions` lives in `lib/config.mjs` only (the copy in `lint-escape-hatch.mjs` is gone).
+- New peer dependency `typescript >=5.9`; `@typescript-eslint/parser` is a dependency. Tests build typed cases with
+  `fixtures/typed/tester.mjs` (`typedTester`, `slotTester`, `at`).
+
+- **Breaking: `no-direct-heroicon-import` is deleted.** It was a second name for a second copy of
+  `no-vendor-icon-outside-icon-leaf` (icon law); one obligation has one rule (redundancy RED20). The copy in
+  `vendor-boundary.mjs` is gone; `no-vendor-icon-outside-icon-leaf` is unchanged.
+- New law `size-growth` (R20 `HFS_SIZE_GROWTH`): `file-size-growth` refuses a new source file over the line budget and an existing file over it that is longer than at the parent commit. The budget is `ruleParams.fe.fileLines` of the slot manifest, read through the slot view (`hfsOf(context).ruleParams`, the package's own `runtime/` copy) (`packages/hfs/scripts/sync-runtime.mjs` keeps it equal to the runtime's); the rule takes no option.
+- **Breaking: `no-internal-starci-href` is deleted.** It was a second, weaker copy of `no-hardcoded-route` (which already refuses a
+  route literal in any JSX `href` and any navigation call, specs excluded); one obligation has one rule. `no-hardcoded-route` gained a
+  passing case for `mailto:` on `<a>` and a violating case for `<a href="/tasks">`. R93 no longer lists it.
+- **Fix: `no-direct-const-alias` fired on `export const generateMetadata = x` in a Next route segment file.** The names Next reserves
+  (`generateMetadata`, `metadata`, `viewport`, `dynamic`, ... in `lib/next.mjs`, the list of the architecture machine's
+  `NEXT_RESERVED_EXPORTS`) are exempt when the file is a route segment file (slot `fe.route`, stem `page`/`layout`/`template`/...);
+  a non-reserved alias in a route file and a reserved name elsewhere still fire. The rule now needs the slot view (`hfsOf`).
+- **Fix: `no-barrel-spec` fired on every `index.spec.ts`.** It now reads and parses the sibling `index.ts(x)` and fires only when the
+  sibling holds nothing but import and export declarations (a barrel); an `index.ts` with a function, class or value (starci-next-fe
+  `modules/browser-storage`) may have its spec, and a missing sibling is no finding. It also covers `.tsx`.
+- **Fix: `no-mocked-translations` refused a `next-intl/server` mock that serves the real catalogue.** A server helper has no provider to
+  render inside; the mock is allowed when its factory (or a `vi.hoisted` block it reads) uses an import that resolves into the app's
+  `modules/i18n/messages/`. Client `next-intl` mocks, literal/key-echoing server mocks and automocks still fire, now with a
+  server-specific message (`mockedServer`) naming `createTranslator` over the real messages. The rule needs the slot view (`hfsOf`).
+- **Fix: `no-hand-typed-wire` fired on `(await response.json()) as unknown`, the narrowing entry `no-type-assertion` allows.** It now
+  fires only when a value read from `.json()` (directly or through a `const`) is asserted or annotated to a type that is not `unknown`
+  and not imported from a `__generated__/` module (decided from the file's import declarations). **Breaking:** the `declared` branch
+  (a name suffix `Wire|Dto|DTO|Response|Payload` on an interface or alias in `modules/api`) and the `graphqlType` branch (a name
+  pattern `GraphQl*`) are deleted; detection by name is not a detection.
+- Every rule is catalogued under an HFS rule id (R91 FE_SOURCE_FORM, R92 FE_COMPONENT_API, R93 FE_VENDOR_BOUNDARY added).
+- **One client, one Outcome, one i18n stack, grammar components (lane F0-D).**
+  - `lib/scope.mjs`: `isConfigModule`, `isApiClient` and the new `isOutcomeModule` are slot questions (`fe.modules.config`, `fe.transport.client` / `fe.package.api.client`, `fe.transport.outcome` / `fe.package.api.outcome`) taking the rule `context`, not path regexes; `PACKAGE_TIERS` is deleted (`use-client-only-at-boundary` asks slot `fe.package.ui` and reads the tier below the package root); `slotOfFile`, `inSlot` and `globalReferences` (scope-resolved globals) are new. Their rule tests run under `slotTester()`/`typedTester()` with `at("apps/web/src/...")` filenames.
+  - `fetch-only-in-api-client` resolves the global `fetch` (and `globalThis.fetch`, `window.fetch`, `self.fetch`, aliases, destructuring), `new Request`, `new EventSource`, `navigator.sendBeacon` by scope, and fetch libraries (axios, ky, got, undici, ofetch, graphql-request, urql, `@apollo/*`, `@urql/*`) by module specifier; the one file allowed is slot `fe.transport.client` or `fe.package.api.client`. `client-fetch-has-signal` and `no-shared-transport-state` ask the same slots (the shared api package is covered).
+  - `client-maps-auth-to-refused` judges a real branch: the fetch response's status (typed `Response`) compared with 401 and 403 whose consequent builds `kind: "refused"`; three literals anywhere no longer pass.
+  - New `one-outcome-union` (R51): a union alias of object types sharing a literal `ok` or `kind` discriminant is declared only in the outcome slot.
+  - New `i18n-stack-in-one-module` (R59): `defineRouting`, `createNavigation`, `getRequestConfig`, `createMiddleware` (by import specifier) are called only in slot `fe.package.i18n`, or `fe.modules.i18n` of a one-app repository. `no-second-i18n-stack` stays: it refuses another i18n library, a different obligation.
+  - New `no-raw-structural-element` (`grammar-boundary`, R62): raw `h1-h6 p span hr label form fieldset dl dt dd table..th ul ol li header footer nav section main figure figcaption` in app slots and non-`ui` packages; `div br aside article` have no grammar component and stay allowed.
+
+- **Breaking: the timer rule is now `effect-subscription-needs-cleanup`** (`FE_EFFECT_CLEANUP`, no alias). Inside a React `useEffect` / `useLayoutEffect` callback (resolved through the import) and inside a `useSyncExternalStore` subscribe (also when passed by name), every `setTimeout` / `setInterval` handle, `requestAnimationFrame` id, `addEventListener` (target, type, listener), `.observe`d `ResizeObserver` / `IntersectionObserver` / `MutationObserver`, `WebSocket` / `EventSource` / `BroadcastChannel` and subscription object (`unsubscribe` / `off` / `close` in its type) must be released by the returned cleanup against the SAME handle (scope binding or member path), not by any `clearTimeout` in it. The `/modules/` exemption is gone: outside an effect a timer or frame is accepted only when the function that starts it releases it (the 5.1.2 returned-closure acceptance and the API client's `finally` both hold structurally). Typed linting is required.
+- **`no-data-fetch-in-effect` sees indirect loads.** A call executed synchronously in the effect body whose value is a promise (`void load()` with `load` async anywhere, an SWR `mutate()` / `refresh()`), is `.then`-ed, or is `void`-ed and untyped is a finding; a promise started inside a listener or timer callback the effect registers is not. The effect is React's export, resolved through the import.
+- **New rule `server-module-marks-server-only`** (R55, new code `FE_SERVER_ONLY_MARK`): a module that imports `next/headers`, `next/server`, `next-intl/server`, a Node built-in, or a module that resolves to a file starting with `import "server-only"` must itself start with `import "server-only"`. Route files (slots `fe.route`, `fe.source-root-pinned`) are exempt. `client-no-server-import` also refuses `next-intl/server` and `next/server`.
+- **`no-hardcoded-copy` (R58)** reads template literals with substitutions whose static parts hold a word (`${count} installed`) in JSX children and copy attributes, and any object property whose value is a whole sentence under any key (`{ ready: "Your course is ready" }`); class names, URLs, ids, keys, units and format tokens still pass.
+- **`no-inline-lint-config` (R18)** also refuses `NOSONAR`, `@sonar-ignore`, `istanbul ignore`, `c8 ignore`, `v8 ignore`, `prettier-ignore` and `stylelint-disable` comments.
+- New `lib/bindings.mjs` (scope bindings, imports, stable keys), `lib/platform.mjs` (platform symbols) and `lib/react.mjs` (React exports by import).
+
 ## 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
 
@@ -15,7 +99,7 @@ Round 2 of the FE enforcers, measured on nivo-fe, starci-next-fe and miamia-fe.
 
 - **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`).
+- **Runtime hygiene (R65, R50)**, new law `hygiene`: `effect-subscription-needs-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`).

package/README.md

@@ -5,30 +5,29 @@ component ownership, accessibility, loading behavior, vendor boundaries, transla
 and colocated class-name composition consistent without prescribing a custom rendering protocol.
 
 ```bash
-npm i -D @starci/eslint-canon-fe eslint-plugin-react-hooks
+npm i -D @starci/eslint-canon-fe eslint-plugin-react-hooks typescript
 ```
 
-```js
-import { starciFeConfig } from "@starci/eslint-canon-fe"
+A repository's `eslint.config.mjs` is the managed one-liner `hfs sync` renders (and `hfs check` compares, R05/R17):
 
-export default [...starciFeConfig({ layout: "single-app" })]
+```js
+import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
+export default starciFeConfig({ hfs: loadHfs(import.meta.url) })
 ```
 
-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.
+`loadHfs` reads the repository's `hfs.json` and the slot manifest shipped in `runtime/`. The factory returns three
+flat-config blocks and owns everything about the law: which files are linted (from the HFS profile), 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`), typed linting, and the inline-directive fence (`noInlineConfig` plus
+`reportUnusedDisableDirectives`). The repository states nothing.
 
-- 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.
+- The **ignore** block: `node_modules`, `.next`, `dist`, `coverage`, `__generated__` and `.starci/`.
+- The **source** block governs `apps/*/src/**` and `packages/*/src/**` with types (`parserOptions.projectService`) and
+  `settings.starci.hfs`, the slot view path-scoped rules ask (`lib/hfs.mjs` `hfsOf`), never a path pattern.
+- The **e2e** block governs `e2e/**` and `playwright.config.ts` 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.
+`recommended`, `sourceRecommended`, `e2eRecommended`, `why`, `loadHfs`, `linterOptions` and the plugin itself are also
+exported; `why[rule]` is `{ code, vi, fixVi }`, the finding code and the Vietnamese why the harness quotes.
 
 ## Rules
 
@@ -38,7 +37,7 @@ its Vietnamese why. New in 5.0: [env-owner](docs/env-owner.md), [transport](docs
 [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.
+[spec-quality](docs/spec-quality.md) and [lint-escape-hatch](docs/lint-escape-hatch.md). 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. New in 6.0: `effect-subscription-needs-cleanup` (timers, frames, listeners, observers, sockets and subscriptions are released against the same handle), `server-module-marks-server-only` ([client-boundary](docs/client-boundary.md)), `no-data-fetch-in-effect` sees indirect loads, `no-hardcoded-copy` reads templates and sentence values, `no-inline-lint-config` refuses `NOSONAR` and the coverage/formatter switches. Also new in 6.0: [grammar-boundary](docs/grammar-boundary.md) (`no-raw-structural-element`), `one-outcome-union` ([transport](docs/transport.md)), `i18n-stack-in-one-module` ([next-conventions](docs/next-conventions.md)), [size-growth](docs/size-growth.md) (`file-size-growth`: a file over the manifest's line budget is not born large and does not grow; the budget is `ruleParams.fe.fileLines`, read from the manifest copy in `runtime/`).
 
 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

package/brand-values.mjs

@@ -18,7 +18,6 @@
  * 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. */
@@ -105,8 +104,7 @@ export const noRawBrandValue = {
     },
   },
   create(context) {
-    const filename = context.filename || context.getFilename()
-    if (isSpecFile(filename) || isContentFile(filename)) return {}
+    if (isContentFile(context)) return {}
     const source = context.sourceCode || context.getSourceCode()
     /** Values already reported through an owner, so a string reports once. */
     const claimed = new WeakSet()

package/class-names.mjs

@@ -3,9 +3,10 @@
  * classNames files own the utility-token composition.
  */
 
-import { normalizePath } from "./lib/path.mjs"
-const isComponentSource = (filename) => normalizePath(filename).includes("/src/components/")
-const isClassNamesFile = (filename) => /\/classNames\.tsx?$/.test(normalizePath(filename))
+import { isComponentFile, roleOfFile } from "./lib/scope.mjs"
+
+/** The styling declarations of a component owner: the file its slot gives the role `styles`. */
+const isClassNamesFile = (context) => isComponentFile(context) && roleOfFile(context) === "styles"
 const isClassAttribute = (node) => node.type === "JSXAttribute" && ["className", "class"].includes(node.name?.name)
 const isCn = (node) => node?.type === "Identifier" && node.name === "cn"
 
@@ -81,7 +82,7 @@ export const noInlineClassName = {
     messages: { inline: "Move this className value to an imported colocated classNames.ts export." },
   },
   create(context) {
-    if (!isComponentSource(context.filename || context.getFilename())) return {}
+    if (!isComponentFile(context)) return {}
     const imported = importedClassNames(context)
     return {
       JSXAttribute(node) {
@@ -102,11 +103,11 @@ export const classNamesInColocatedFile = {
     messages: { misplaced: "Put reusable className declarations in a colocated classNames.ts file." },
   },
   create(context) {
-    const filename = context.filename || context.getFilename()
-    if (!isComponentSource(filename)) return {}
+    if (!isComponentFile(context)) return {}
+    const styles = isClassNamesFile(context)
     return {
       CallExpression(node) {
-        if (!isCn(node.callee) || isClassNamesFile(filename)) return
+        if (!isCn(node.callee) || styles) return
         context.report({ node, messageId: "misplaced" })
       },
     }
@@ -126,8 +127,7 @@ export const cnArgumentsAreSingleTokens = {
     },
   },
   create(context) {
-    const filename = context.filename || context.getFilename()
-    if (!isClassNamesFile(filename)) return {}
+    if (!isClassNamesFile(context)) return {}
     return {
       CallExpression(node) {
         if (!isCn(node.callee)) return

package/client-boundary.mjs

@@ -15,11 +15,12 @@
  * 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"
+import ts from "typescript"
+import { classifyImport, fileOf, isProductSource, isSpecFile, kindOfFile, roleOfFile, slotOfFile, tierOfFile } from "./lib/scope.mjs"
+import { typed } from "./lib/types.mjs"
 
-/** The framework's own client-only files. */
-const FRAMEWORK_CLIENT = new Set(["error", "global-error"])
+/** The route roles that are client-only by the framework's own rule: `error` and `global-error`. */
+const FRAMEWORK_CLIENT_ROLES = new Set(["error", "global-error"])
 
 /** True when the program opens with the `"use client"` directive. */
 const clientDirective = (program) =>
@@ -27,29 +28,25 @@ const clientDirective = (program) =>
     (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("|")})/`)
+/** The layers whose files are legitimately client: a block's entry, a leaf (its interaction is intrinsic) and, in a shared package, the interactive layers (branches and leaves; a composite is presentation). */
+const isInteractionBoundary = (context) => {
+  const slot = slotOfFile(context)
+  const kind = kindOfFile(context)
+  const role = roleOfFile(context)
+  if (slot === "fe.components") return kind === "leaves" || (kind === "blocks" && role === "entry")
+  if (slot === "fe.feature") return kind === "overlays" && role === "entry"
+  if (slot === "fe.package.ui") return kind === "branches" || kind === "leaves"
+  return false
+}
 
 /** 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"
+const isBoundary = (context) => (slotOfFile(context) === "fe.route" && FRAMEWORK_CLIENT_ROLES.has(roleOfFile(context))) || isInteractionBoundary(context)
+
+/** The slot a file fills in the route tree (its role in `fe.route`, or the page or layout owner of a feature), when it fills one. */
+const routeFill = (context) => {
+  if (slotOfFile(context) === "fe.route" && roleOfFile(context) !== null) return roleOfFile(context)
+  if (slotOfFile(context) === "fe.feature" && kindOfFile(context) === "pages") return "page owner"
+  if (slotOfFile(context) === "fe.feature" && kindOfFile(context) === "layouts") return "layout owner"
   return null
 }
 
@@ -67,9 +64,8 @@ export const useClientOnlyAtBoundary = {
     },
   },
   create(context) {
-    const filename = normalizePath(context.filename || context.getFilename())
-    if (isSpecFile(filename) || isBoundary(filename)) return {}
-    const slot = slotOf(filename)
+    if (isSpecFile(fileOf(context)) || isBoundary(context)) return {}
+    const slot = routeFill(context)
     return {
       Program(program) {
         const directive = clientDirective(program)
@@ -86,13 +82,22 @@ export const useClientOnlyAtBoundary = {
 /** 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`"
+/** A server API: the request-scoped Next APIs, the server half of next-intl, a Node built-in; null for anything else. */
+const serverApiReason = (source) => {
   if (source === "next/headers") return "`next/headers`"
   if (source === "next/server") return "`next/server`"
+  if (source === "next-intl/server") return "`next-intl/server`"
   if (NODE_BUILTINS.test(source)) return `\`${source}\``
-  if (/(?:^|\/)modules\/api\/(?:.+\/)?read-[^/]+$/.test(source)) return `the server reader \`${source}\``
+  return null
+}
+
+/** A server-only source: the marker package, a server API, a server reader (role `reader` of slot `fe.modules.api`). */
+const serverOnlyReason = (context, source) => {
+  if (source === "server-only") return "`server-only`"
+  const api = serverApiReason(source)
+  if (api) return api
+  const target = classifyImport(context, source)
+  if (target?.slot === "fe.modules.api" && target.role === "reader") return `the server reader \`${source}\``
   return null
 }
 
@@ -108,8 +113,7 @@ export const clientNoServerImport = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (isSpecFile(file)) return {}
+    if (isSpecFile(fileOf(context))) return {}
     let client = false
     return {
       Program(program) {
@@ -117,13 +121,96 @@ export const clientNoServerImport = {
       },
       ImportDeclaration(node) {
         if (!client || node.importKind === "type") return
-        const what = serverOnlyReason(String(node.source.value))
+        const what = serverOnlyReason(context, String(node.source.value))
         if (what) context.report({ node, messageId: "server", data: { what } })
       },
     }
   },
 }
 
+// -- FE-CLIENT-2b ----------------------------------------------------------------------------------
+
+/** The slots whose files are Next route files: server components by construction, so the framework decides, not a marker. */
+const ROUTE_FILE_SLOTS = new Set(["fe.route", "fe.source-root-pinned"])
+
+/** True when a statement is `import "server-only"`: an import with no bindings from the marker package. */
+const isMarkerStatement = (statement) =>
+  statement?.type === "ImportDeclaration" && statement.specifiers.length === 0 && statement.source.value === "server-only"
+
+/** True when a TypeScript source file opens with `import "server-only"`. */
+const tsFileIsMarked = (file) => {
+  const first = file.statements[0]
+  return Boolean(first) && ts.isImportDeclaration(first) && !first.importClause && ts.isStringLiteral(first.moduleSpecifier) && first.moduleSpecifier.text === "server-only"
+}
+
+/**
+ * The source file an import specifier resolves to: the checker's module symbol, so path aliases, extensions and index
+ * files resolve as the compiler resolves them. Null for a declaration file, a package or an unresolved specifier.
+ */
+const resolvedSourceFile = (context, specifier) => {
+  const { checker, toTs } = typed(context)
+  const tsNode = toTs(specifier)
+  if (!tsNode) return null
+  const symbol = checker.getSymbolAtLocation(tsNode)
+  const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0]
+  return declaration && ts.isSourceFile(declaration) && !declaration.isDeclarationFile ? declaration : null
+}
+
+/** A module that uses a server-only API, or imports a module that is itself server-only, opens with `import "server-only"`. */
+/** Component tiers: a component is judged by where client code reaches it, not by a marker. */
+const COMPONENT_TIERS = new Set(["components", "feature"])
+
+export const serverModuleMarksServerOnly = {
+  meta: {
+    type: "problem",
+    docs: { description: "A module importing `next/headers`, `next/server`, `next-intl/server`, a Node built-in or a server-only module starts with `import \"server-only\"`." },
+    schema: [],
+    messages: {
+      mark:
+        "This module imports {{what}}, which exists only on the server, but it does not start with `import \"server-only\"`. Without the marker nothing stops a client component from importing this module (directly or through a hook): the build then fails far from the cause, or ships server code toward the browser. Make `import \"server-only\"` the first statement of the file. Route files (`page`, `layout`, `route`, `proxy`) are server components by construction and need no marker.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(fileOf(context))) return {}
+    const slot = slotOfFile(context)
+    if (!slot || ROUTE_FILE_SLOTS.has(slot)) return {}
+    // A block or a page is a server or client COMPONENT, not a server module: whether client code reaches the server through it is
+    // the machine's multi-hop question (FE_CLIENT_REACHES_SERVER). The marker belongs to the modules that hold server work.
+    if (COMPONENT_TIERS.has(tierOfFile(context))) return {}
+    const reader = roleOfFile(context) === "reader"
+    let client = false
+    let marked = false
+    const uses = []
+    return {
+      Program(program) {
+        client = clientDirective(program) !== null
+        marked = isMarkerStatement(program.body[0])
+      },
+      "ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration"(node) {
+        if (!node.source || node.importKind === "type" || node.exportKind === "type") return
+        const onlyTypes = node.specifiers?.length > 0 && node.specifiers.every((specifier) => specifier.importKind === "type" || specifier.exportKind === "type")
+        if (onlyTypes) return
+        const specifier = String(node.source.value)
+        if (specifier === "server-only") return
+        const api = serverApiReason(specifier)
+        if (api) {
+          uses.push({ node, what: api })
+          return
+        }
+        const target = resolvedSourceFile(context, node.source)
+        if (target && tsFileIsMarked(target)) uses.push({ node, what: `\`${specifier}\` (a module that is itself server-only)` })
+      },
+      "Program:exit"() {
+        // a "use client" file that imports the server is client-no-server-import's finding, not a missing marker
+        if (client || marked) return
+        // A server reader (`read-*.ts`, role `reader` of the api slot) is server-only by its role, whatever it imports.
+        if (reader && uses.length === 0) context.report({ node: context.sourceCode.ast, messageId: "mark", data: { what: "the request (it is a server reader)" } })
+        for (const use of uses) context.report({ node: use.node, messageId: "mark", data: { what: use.what } })
+      },
+    }
+  },
+}
+
 // -- FE-CLIENT-3 -----------------------------------------------------------------------------------
 
 /** Web storage exists only in the browser and only under `modules/`, which guards it. */
@@ -141,8 +228,8 @@ export const webStorageOnlyInModules = {
     },
   },
   create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (isSpecFile(file) || !file.includes("/src/") || /\/modules\//.test(file)) return {}
+    // Product source outside the module tiers (foundation modules, the other modules, the api transport), which are where storage is guarded.
+    if (!isProductSource(context) || ["foundation", "modules", "transport"].includes(tierOfFile(context))) return {}
     return {
       MemberExpression(node) {
         if (node.computed || node.property.type !== "Identifier" || !STORAGE.has(node.property.name)) return
@@ -191,6 +278,7 @@ export const noDangerousHtml = {
 export const rules = {
   "use-client-only-at-boundary": useClientOnlyAtBoundary,
   "client-no-server-import": clientNoServerImport,
+  "server-module-marks-server-only": serverModuleMarksServerOnly,
   "web-storage-only-in-modules": webStorageOnlyInModules,
   "no-dangerous-html": noDangerousHtml,
 }

package/comments.mjs

@@ -11,12 +11,12 @@
  * pragma: user-facing text comes from a `next-intl` catalogue, and the catalogue is the only place
  * a second language is content.
  *
- * The exceptions that remain are paths, not judgements, and that is on purpose: a locale dictionary
+ * The exceptions that remain are placements, not judgements, and that is on purpose: a locale dictionary
  * IS the other language, and a fixture reproducing a real string has to reproduce it exactly. A
  * judgement-based exception would be argued per file forever.
  */
 
-import { normalizePath } from "./lib/path.mjs"
+import { fileOf, inSlot, isSpecFile } from "./lib/scope.mjs"
 
 /** The letters that mark the second language a source string must not carry outside a catalogue. */
 export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìíò-õùúýĂăĐđĨĩŨũƠơƯưẠ-ỿ]/
@@ -33,26 +33,19 @@ export const hasEmoji = (text) =>
   (/\p{Extended_Pictographic}/u.test(text) || /[\u{1F1E6}-\u{1F1FF}]{2}/u.test(text))
 
 /**
- * Paths whose second-language text or emoji is CONTENT rather than authoring.
+ * Files whose second-language text or emoji is CONTENT rather than authoring, decided by what the file IS.
  *
- * Two kinds only: the locale dictionaries (`messages/<locale>.json`), which are the product's other
- * language, and fixtures and specs, which reproduce real strings and would be testing something else
- * if they translated them. There is no "copy module" path: a `resources/` folder of strings is
- * copy that skipped the catalogue.
+ * Three kinds only: the locale dictionaries (a `.json` file of an i18n slot, `fe.modules.i18n` or `fe.package.i18n`),
+ * which are the product's other language; the e2e support tree (slot `fe.e2e-support`: fixtures and support),
+ * and specs, which reproduce real strings and would be testing something else if they translated them. There is no
+ * "copy module": a `resources/` folder of strings is copy that skipped the catalogue.
+ *
+ * @param {object} context - The ESLint rule context.
+ * @returns {boolean} True when the linted file holds content rather than authoring.
  */
-export const CONTENT_PATHS = [
-  /\/messages\/[a-z-]+\.json$/i,
-  /\/__fixtures?__\//,
-  /\/fixtures?\//,
-  /\.fixture\.(ts|tsx|js|mjs|cjs)$/i,
-  /\.test\.(ts|tsx|js|mjs|cjs)$/i,
-  /\.spec\.(ts|tsx|js|mjs|cjs)$/i,
-]
-
-/** True when a file holds content rather than authoring. */
-export const isContentFile = (filename) => {
-  const file = normalizePath(filename)
-  return CONTENT_PATHS.some((pattern) => pattern.test(file))
+export const isContentFile = (context) => {
+  const file = fileOf(context)
+  return isSpecFile(file) || inSlot(context, "fe.e2e-support") || (inSlot(context, "fe.modules.i18n", "fe.package.i18n") && file.endsWith(".json"))
 }
 
 /** Walk every place prose can hide, and hand each to one check. */
@@ -121,7 +114,7 @@ export const noEmojiInSource = {
     },
   },
   create(context) {
-    if (isContentFile(context.filename || context.getFilename())) return {}
+    if (isContentFile(context)) return {}
     return proseVisitors(context, (node, text) => {
       if (hasEmoji(text)) context.report({ node, messageId: "emoji" })
     })

package/docs/client-boundary.md

@@ -32,7 +32,7 @@ export const Feed = () => null
 
 ## `starci-fe/client-no-server-import`
 
-A `"use client"` file does not import `server-only`, `next/headers`, a Node built-in or a server reader (sub-check `FE_CLIENT_SERVER_IMPORT`).
+A `"use client"` file does not import `server-only`, `next/headers`, `next/server`, `next-intl/server`, a Node built-in or a server reader (sub-check `FE_CLIENT_SERVER_IMPORT`).
 
 **Invalid** (`src/components/blocks/Feed/index.tsx`)
 
@@ -54,6 +54,31 @@ import useSWR from "swr"
 
 **Cách sửa:** Đọc dữ liệu ở server component hoặc server reader rồi truyền xuống bằng props; hoặc dùng SWR gọi client của app.
 
+## `starci-fe/server-module-marks-server-only`
+
+A module that imports `next/headers`, `next/server` (a value import), `next-intl/server`, a Node built-in, or a module that is itself server-only starts with `import "server-only"` (sub-check `FE_SERVER_ONLY_MARK`). A module is server-only when the TypeScript module resolution of the import specifier reaches a source file whose first statement is `import "server-only"`; `import type` and `import { type X }` carry no runtime and are not judged. Route files are server components by construction and need no marker: they are recognized by their slot (`fe.route`, `fe.source-root-pinned`), not by their name. A `"use client"` file that imports the server is `client-no-server-import`'s finding. The multi-hop client reachability (a client block reaching a marked module through a hook) is the architecture machine's.
+
+**Invalid** (`src/modules/api/courses/read-courses.ts`)
+
+```ts
+import { headers } from "next/headers"
+export const readCourses = async () => (await headers()).get("x-locale")
+```
+
+**Valid** (`src/modules/api/courses/read-courses.ts`)
+
+```ts
+import "server-only"
+import { headers } from "next/headers"
+export const readCourses = async () => (await headers()).get("x-locale")
+```
+
+**Finding code:** `FE_SERVER_ONLY_MARK`
+
+**Vì sao (why):** Module `<file>` nhập API chỉ có ở server (`next/headers`, `next/server`, `next-intl/server`, module Node hoặc module đã là server-only) nhưng không mở đầu bằng `import "server-only"`.
+
+**Cách sửa:** Đặt `import "server-only"` làm câu lệnh đầu tiên của tệp; tệp route (`page`, `layout`, `route`, `proxy`) là server component sẵn nên không cần.
+
 ## `starci-fe/web-storage-only-in-modules`
 
 `localStorage` and `sessionStorage` are touched only inside `modules/` (sub-check `FE_STORAGE_OUTSIDE_MODULES`).

package/docs/grammar-boundary.md

@@ -0,0 +1,33 @@
+# Grammar boundary
+
+Law module: `grammar-boundary.mjs`. Catalogue: R62 FE_NATIVE_FORM_CONTROL (the grammar owns the element).
+
+Page structure and text are composed from `@starci/grammar` (or the repository's `<family>-ui` package), not drawn as raw HTML.
+
+Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
+
+## `starci-fe/no-raw-structural-element`
+
+Page structure and text are grammar components, not raw `div`-family HTML; only `fe.package.ui` renderers draw raw tags.
+
+Applies to app source that composes the grammar (slots `fe.feature`, `fe.components`, `fe.route`, `fe.hooks`) and to every workspace package except the `<family>-ui` package (`fe.package.ui`), whose components are the renderers. Spec files render raw HTML as a harness and are not judged; a file no slot owns is not judged.
+
+The refused tags are exactly those `@starci/grammar` has a component for (the twin test reads the package source): `h1-h6` (`Heading`), `p` and `span` (`Text`), `hr` (`Divider`), `label` (`Label`), `form` (`Form`), `fieldset` (`Fieldset`), `dl` `dt` `dd` (`DescriptionList`), `table` `thead` `tbody` `tr` `td` `th` (`DataTable`), `ul` `ol` `li` (`SurfaceListCard`, `StaticStateRow`), `header` (`SectionHeader`, `TopBar`), `footer` (`Footer`), `nav` (`Subnav`, `Breadcrumbs`, `NavigationFeatureNav`), `section` (`SurfaceCard`), `main` (`WorkspaceShell`), `figure` and `figcaption` (`MediaFrame`). `div`, `br`, `aside` and `article` are not refused: the grammar has no component for them.
+
+**Invalid** (`src/features/pages/home/component.tsx`)
+
+```ts
+export const Home = () => <section><p>{t("intro")}</p></section>
+```
+
+**Valid** (`src/features/pages/home/component.tsx`)
+
+```ts
+export const Home = () => <SurfaceCard><Text>{t("intro")}</Text></SurfaceCard>
+```
+
+**Finding code:** `FE_NATIVE_FORM_CONTROL`
+
+**Vì sao (why):** `<tag>` thô ở `<file>`. Cấu trúc trang và chữ được ghép từ component của grammar, không viết HTML thô.
+
+**Cách sửa:** Thay bằng component grammar tương ứng (`Heading`, `Text`, `SurfaceCard`, ...); nếu grammar chưa có, thêm vào grammar hoặc gói ui thay vì vẽ tại chỗ.