@starci/eslint-canon-fe 8.2.14 → 8.2.16

package/fe-stack.mjs

@@ -0,0 +1,86 @@
+/**
+ * The rule that holds the front-end stack (`knowledge/hfs/fe-stack.yaml`, failure code `FE_STACK_FORBIDDEN`).
+ *
+ * ONE LIBRARY PER CONCERN. Every common front-end concern - GraphQL, REST, data hooks, toast, forms, state, realtime, i18n, UI,
+ * icons, motion, dates, numbers, storage, charts, markdown, code - has one canonical library, the same for the lite and the full
+ * edition (owner ruling 2026-10-13). A second library for a concern is a second set of conventions a reader has to know and a
+ * second dependency a release has to keep current, and it always arrives one import at a time. The catalog names, per concern,
+ * the alternatives a front end never imports; this rule refuses exactly those, read from the catalog, so the list lives once.
+ *
+ * SUPABASE IS AUTH ONLY. With a Supabase connection the front end holds the Supabase Auth client and nothing else of Supabase
+ * (the data path is GraphQL to the back end): `@supabase/*` is imported only by `modules/auth` (slot `fe.modules.auth`).
+ *
+ * WHAT IS LEFT TO SIBLINGS. A canonical library imported in the wrong place (Apollo outside `modules/api`, axios outside its REST
+ * calls, socket.io-client outside `hooks/socketio`) and `fetch` outside the API layer are `fetch-only-in-api-client`'s findings;
+ * a glyph library outside the icon leaf is the icon law's. Each import is judged by one rule.
+ */
+import { forbiddingConcern, packageNameOf } from "./lib/fe-stack.mjs"
+import { globalReferences, inSlot, isProductSource } from "./lib/scope.mjs"
+
+/** The package scope only the identity-provider client may import. */
+const SUPABASE_SCOPE = "@supabase/"
+
+/**
+ * No import (static, re-export, dynamic or `require`) of a package the fe-stack catalog forbids, and no `@supabase/*` outside
+ * `modules/auth`. Type-only imports count: a type import still makes the package a dependency of the front end.
+ */
+export const feStackImport = {
+  meta: {
+    type: "problem",
+    docs: { description: "A front end imports no library the fe-stack catalog forbids, and `@supabase/*` only in `modules/auth`." },
+    schema: [],
+    messages: {
+      forbidden:
+        "`{{name}}` is a forbidden alternative for the {{concern}} concern of the front-end stack. The stack has one library per concern, the same in every app and both editions: use {{canonical}} ({{pattern}}). {{why}}",
+      supabase:
+        "`{{name}}` is imported outside `modules/auth`. Supabase on the front end is the auth client only, held by `modules/auth` (the session, the access token the Apollo link attaches, sign-in and sign-out); data is read and written through the GraphQL operations of `modules/api`, never through Supabase from the browser.",
+    },
+  },
+  create(context) {
+    if (!isProductSource(context)) return {}
+    const authOwner = inSlot(context, "fe.modules.auth")
+    const judge = (node, source) => {
+      const name = packageNameOf(source)
+      if (name === null) return
+      const concern = forbiddingConcern(source)
+      if (concern) {
+        const named = concern.packages?.length > 0 ? concern.packages : concern.home ?? []
+        const canonical = named.map((entry) => `\`${entry}\``).join(", ")
+        context.report({ node, messageId: "forbidden", data: { name, concern: concern.id, canonical, pattern: concern.pattern ?? "", why: concern.why ?? "" } })
+        return
+      }
+      if (name.startsWith(SUPABASE_SCOPE) && !authOwner) context.report({ node, messageId: "supabase", data: { name } })
+    }
+    return {
+      ImportDeclaration(node) {
+        judge(node, node.source.value)
+      },
+      ExportNamedDeclaration(node) {
+        if (node.source) judge(node, node.source.value)
+      },
+      ExportAllDeclaration(node) {
+        judge(node, node.source.value)
+      },
+      ImportExpression(node) {
+        if (node.source.type === "Literal") judge(node, node.source.value)
+      },
+      TSImportEqualsDeclaration(node) {
+        // `import x = require("moment")`
+        if (node.moduleReference?.type === "TSExternalModuleReference" && node.moduleReference.expression?.type === "Literal") judge(node, node.moduleReference.expression.value)
+      },
+      CallExpression(node) {
+        // `require("moment")` where `require` is the CommonJS global.
+        if (node.callee.type !== "Identifier" || node.callee.name !== "require" || node.arguments[0]?.type !== "Literal") return
+        if (globalReferences(context, new Set(["require"])).includes(node.callee)) judge(node, node.arguments[0].value)
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "fe-stack-import": feStackImport,
+}
+
+/** Every rule is an error: a second library for a concern is the defect, not a style. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/formatting.mjs

@@ -10,11 +10,13 @@
  *
  * WHAT IS REFUSED. `toLocaleString`, `toLocaleDateString`, `toLocaleTimeString`; `new Intl.*Format`;
  * `toFixed` when the result is shown (inside JSX or a template); a currency symbol glued to a
- * substitution in a template; and the date libraries (`moment`, `dayjs`, `date-fns`, `luxon`).
- * `modules/i18n/**` is exempt: it is where the formatters are configured.
+ * substitution in a template; and `dayjs` outside `modules/dayjs` (the front-end stack's date-math home; its display
+ * goes through the formatter). The other date libraries (`moment`, `date-fns`, `luxon`) are forbidden alternatives of the
+ * stack and refused by `fe-stack-import`. `modules/i18n/**` is exempt: it is where the formatters are configured.
  */
 
-import { fileOf, inSlot } from "./lib/scope.mjs"
+import { forbiddingConcern } from "./lib/fe-stack.mjs"
+import { classOf, inSlot } from "./lib/scope.mjs"
 
 /** The locale-sensitive `Date` and `Number` methods. */
 const LOCALE_METHODS = new Set(["toLocaleString", "toLocaleDateString", "toLocaleTimeString"])
@@ -23,7 +25,10 @@ const LOCALE_METHODS = new Set(["toLocaleString", "toLocaleDateString", "toLocal
 const INTL_FORMATTERS = new Set(["NumberFormat", "DateTimeFormat", "RelativeTimeFormat", "ListFormat", "PluralRules"])
 
 /** Date libraries that format on their own locale. */
-const DATE_LIBRARIES = /^(?:moment(?:-timezone)?|dayjs|date-fns(?:\/.+)?|luxon)$/
+const DATE_LIBRARIES = /^(?:moment(?:-timezone)?|dayjs(?:\/.+)?|date-fns(?:\/.+)?|luxon)$/
+
+/** The date-math home of the front-end stack (fe-stack `dates`): the capability `dayjs` of slot `fe.modules` (`modules/dayjs/`). */
+const isDayjsHome = (context) => inSlot(context, "fe.modules") && classOf(context).bindings?.capability === "dayjs"
 
 /** A currency mark or code beside a substitution. */
 const CURRENCY = /[₫€£¥]|\b(?:VND|USD|EUR)\b/
@@ -53,7 +58,7 @@ export const useIntlFormatter = {
       currency:
         "A currency mark glued to a substitution in a template writes the symbol on the wrong side for half of the locales and skips grouping. Use `useFormatter().number(value, { style: \"currency\", currency })`.",
       library:
-        "`{{name}}` formats dates on its own locale data, next to `next-intl`'s. One library decides the language of a date: use the `next-intl` formatter (`dateTime`, `relativeTime`).",
+        "`{{name}}` is imported outside `modules/dayjs`. It formats dates on its own locale data, next to `next-intl`'s, and one library decides the language of a date: do date math through `modules/dayjs` and display with the `next-intl` formatter (`dateTime`, `relativeTime`).",
     },
   },
   create(context) {
@@ -61,7 +66,8 @@ export const useIntlFormatter = {
     return {
       ImportDeclaration(node) {
         const source = String(node.source.value)
-        if (DATE_LIBRARIES.test(source)) context.report({ node, messageId: "library", data: { name: source } })
+        // a date library the stack forbids is fe-stack-import's finding; dayjs is legal in its home
+        if (DATE_LIBRARIES.test(source) && !forbiddingConcern(source) && !isDayjsHome(context)) context.report({ node, messageId: "library", data: { name: source } })
       },
       CallExpression(node) {
         const callee = node.callee

package/hooks-folder.mjs

@@ -4,11 +4,21 @@
  * `hooks/` MEANS REACT HOOKS. One app kept its server readers there - fetch, map, no React - and
  * had a single real hook; another had a filename-equals-export rule that gave a helper shared by
  * sixteen hooks nowhere to live, so it was copied sixteen times. Both came from the standard not
- * saying where the non-hook code goes. It now does:
+ * saying where the non-hook code goes. It now does, per family of the front-end stack (each its own slot):
  *
- *   hooks/<domain>/use<Name>.ts      one hook per file
+ *   hooks/swr/api/{graphql,rest}/{queries,mutations}/use{Query,Mutate,Get,Post,Put,Patch,Delete}<X>Swr.ts
+ *                                     one SWR hook per modules/api operation (fe.hooks.swr), plus SwrSideEffects.tsx
+ *   hooks/rhf/use<X>Form.ts           one form (fe.hooks.rhf)
+ *   hooks/zustand/<store>/store.ts    one local store and its use*.ts selectors (fe.hooks.zustand)
+ *   hooks/socketio/                   sockets.ts, SocketIoSideEffects.tsx, enums/, types/, use*.ts (fe.hooks.socketio)
+ *   hooks/effects/use<X>.ts           app-wide side effects (fe.hooks.effects)
+ *   hooks/reuseables/use<X>.ts        generic reusable hooks (fe.hooks.reuseables)
+ *   hooks/<domain>/use<Name>.ts       one hook per file (fe.hooks)
  *   hooks/<domain>/<domain>.shared.ts one file for the domain's non-hook helpers (key builders...)
- *   modules/api/<domain>/read-*.ts    server readers (wrapped in `cache()`)
+ *
+ * A call to the back end is never a hook's own code: it is an operation of `modules/api`, which an SWR hook wraps. The two
+ * `.tsx` files a family names (`SwrSideEffects.tsx`, `SocketIoSideEffects.tsx`, role `effects`) are the components a provider
+ * mounts once; every other file of a family carries the name its slot gives it.
  *
  * The rule holds the shape of one file at a time. Whether a folder holds exactly one `.shared.ts`
  * and whether a helper name repeats across files is a repository fact, and belongs to the
@@ -21,9 +31,21 @@ import { baseName, classOf, fileOf, inSlot } from "./lib/scope.mjs"
 /** Names that mark a hook. */
 const isHookName = (name) => /^use[A-Z0-9]/.test(name)
 
-/** Modules that only run on the server: a reader, not a hook. */
+/**
+ * The SWR key of a hook (`QUERY_<X>_SWR_KEY`, `MUTATE_<X>_SWR_KEY`, fe-stack data): the one constant a hook file exports beside its
+ * hook, so a mutation or a socket message revalidates exactly that cache entry.
+ */
+const isSwrKeyName = (name) => /^[A-Z][A-Z0-9_]*_SWR_KEY$/.test(name)
+
+/** A hook file name: `use<Name>.ts`. */
+const isHookFileName = (name) => /^use[A-Z0-9]\w*\.ts$/.test(name)
+
+/** Modules that only run on the server: server code, not a hook. */
 const SERVER_ONLY = /^(?:server-only|next\/headers)$/
 
+/** The hooks families of the front-end stack: each slot names its files (`allows`) and its non-hook files (roles). */
+const FAMILY_SLOTS = ["fe.hooks.swr", "fe.hooks.rhf", "fe.hooks.zustand", "fe.hooks.socketio", "fe.hooks.effects", "fe.hooks.reuseables"]
+
 /** The exported names a declaration introduces. */
 const exportedNames = (node) => {
   if (node.type === "ExportDefaultDeclaration") {
@@ -39,48 +61,68 @@ const exportedNames = (node) => {
   return []
 }
 
-/** `hooks/` holds React hooks and one shared helper file per domain. */
+/**
+ * What the linted file is inside `hooks/`, or null when no hooks slot owns it: `stray` is a file its slot does not name
+ * (directly in `hooks/`, a non-hook name in a domain, a name outside a family's `allows`); `hookFile` a `use<Name>.ts` hook
+ * file; `sharedFile` a domain's `<domain>.shared.ts`.
+ */
+const hookFileOf = (context) => {
+  const hfs = hfsOf(context)
+  const file = fileOf(context)
+  const found = classOf(context)
+  const name = baseName(file)
+  if (inSlot(context, ...FAMILY_SLOTS)) {
+    const verdict = hfs.allows(file)
+    const stray = Boolean(verdict) && !verdict.allowed
+    const allows = (verdict?.allows ?? hfs.slot(found.slot)?.allows ?? []).join("`, `")
+    // A role the slot names (`entry`, `effects`, `store`) or a non-hook file it allows (sockets.ts, enums/, types/, barrels) is no hook file.
+    return { stray, directlyInHooks: false, hookFile: !stray && !found.role && isHookFileName(name), sharedFile: false, family: found.slot, allows }
+  }
+  if (!inSlot(context, "fe.hooks")) return null
+  // A file directly in `hooks/` is its own root: the slot binds the file name as the `domain`.
+  const directlyInHooks = hfs.relative(file) === found.root
+  // The slot names the domain's entry (`index.ts`, role `entry`) and its shared helper file (`<domain>.shared.ts`, role `shared`).
+  // Both sit directly in the domain folder: a nested `x/index.ts` is a file the slot does not name.
+  const directlyInDomain = hfs.relative(file) === `${found.root}/${name}`
+  const entryFile = directlyInDomain && found.role === "entry"
+  const sharedFile = directlyInDomain && found.role === "shared"
+  const hookFile = isHookFileName(name)
+  return { stray: !hookFile && !sharedFile && !entryFile, directlyInHooks, hookFile, sharedFile, family: null, allows: "" }
+}
+
+/** `hooks/` holds React hooks, each under the name its family or domain gives it, and one shared helper file per domain. */
 export const hooksFolderHoldsHooksOnly = {
   meta: {
     type: "problem",
-    docs: { description: "`hooks/<domain>/` holds `use*.ts` hooks and one `<domain>.shared.ts`; nothing else." },
+    docs: { description: "`hooks/` holds `use*.ts` hooks under the names their family slot gives (`hooks/swr`, `hooks/rhf`, `hooks/zustand`, `hooks/socketio`, `hooks/effects`, `hooks/reuseables`) and, per domain, one `<domain>.shared.ts`; nothing else." },
     schema: [],
     messages: {
       domain:
-        "A file directly in `hooks/`. Hooks live in `hooks/<domain>/use<Name>.ts`; the domain folder is what keeps a shared helper next to the hooks that use it.",
+        "A file directly in `hooks/`. Hooks live in a family folder (`hooks/swr/`, `hooks/rhf/`, `hooks/zustand/<store>/`, `hooks/socketio/`, `hooks/effects/`, `hooks/reuseables/`) or in `hooks/<domain>/use<Name>.ts`; the folder is what keeps a hook findable and a shared helper next to the hooks that use it.",
       notHook:
-        "`{{name}}` is in `hooks/` but is not a React hook. Hooks are `use<Name>.ts`; the domain's non-hook helpers go in `<domain>.shared.ts`; a server reader goes in `modules/api/<domain>/read-*.ts`.",
+        "`{{name}}` is in `hooks/` but is not a React hook. Hooks are `use<Name>.ts`; the domain's non-hook helpers go in `<domain>.shared.ts`; a call to the back end is an operation of `modules/api`, wrapped by an SWR hook in `hooks/swr/`.",
+      family:
+        "`{{name}}` is not a file `{{family}}` names. This family holds `{{allows}}`: an SWR hook is `use{Query,Mutate}<X>Swr.ts` (GraphQL) or `use{Get,Post,Put,Patch,Delete}<X>Swr.ts` (REST) in its `api/<protocol>/<queries|mutations>/` folder, a form is `use<X>Form.ts`. A name outside the list is a hook nobody finds by its family, or code that is not a hook.",
       export:
-        "`{{name}}` is exported from a hook file but is not a hook. A hook file exports the hook (a function named `use...`); a helper belongs in `<domain>.shared.ts`.",
+        "`{{name}}` is exported from a hook file but is not a hook. A hook file exports the hook (a function named `use...`) and at most its SWR key (`QUERY_<X>_SWR_KEY`, `MUTATE_<X>_SWR_KEY`); a helper belongs in `<domain>.shared.ts`.",
       many:
         "This file exports {{count}} hooks. One hook per file keeps a hook findable by its name and keeps a change to one from re-running the tests of the others.",
       sharedHook:
         "`{{name}}` is a hook exported from the shared helper file. That file holds non-hook helpers; a hook there is a hook nobody will find. Give it its own `use<Name>.ts`.",
       server:
-        "`{{source}}` marks server-only code, which is a reader, not a hook. Server readers live in `modules/api/<domain>/read-*.ts`, wrapped in React's `cache()`.",
+        "`{{source}}` marks server-only code, which is not a hook. The front end reads its back end through the operations of `modules/api`, wrapped by the SWR hooks of `hooks/swr/`; request-scoped server APIs stay in server components.",
     },
   },
   create(context) {
-    // Slot `fe.hooks` owns `apps/<app>/src/hooks/<domain>/`; a file no slot puts there is not judged here.
-    if (!inSlot(context, "fe.hooks")) return {}
-    const file = fileOf(context)
-    const found = classOf(context)
-    // A file directly in `hooks/` is its own root: the slot binds the file name as the `domain`.
-    const directlyInHooks = hfsOf(context).relative(file) === found.root
-    const name = baseName(file)
-    const subject = name
-    const domain = found.bindings.domain
-    const isHookFile = /^use[A-Z0-9]\w*\.ts$/.test(subject)
-    // The slot names the domain's entry (`index.ts`, role `entry`) and its shared helper file (`<domain>.shared.ts`, role `shared`).
-    // Both sit directly in the domain folder: a nested `x/index.ts` is a file the slot does not name.
-    const directlyInDomain = hfsOf(context).relative(file) === `${found.root}/${name}`
-    const isEntryFile = directlyInDomain && (found.role === "entry")
-    const isSharedFile = directlyInDomain && (found.role === "shared")
-
+    const judged = hookFileOf(context)
+    if (judged === null) return {}
+    const name = baseName(fileOf(context))
     return {
       Program(program) {
-        if (directlyInHooks) return context.report({ node: program, messageId: "domain" })
-        if (!isHookFile && !isSharedFile && !isEntryFile) context.report({ node: program, messageId: "notHook", data: { name } })
+        if (judged.directlyInHooks) return context.report({ node: program, messageId: "domain" })
+        if (!judged.stray) return
+        if (judged.family) context.report({ node: program, messageId: "family", data: { name, family: judged.family, allows: judged.allows } })
+        else context.report({ node: program, messageId: "notHook", data: { name } })
       },
       ImportDeclaration(node) {
         if (SERVER_ONLY.test(String(node.source.value))) {
@@ -88,11 +130,11 @@ export const hooksFolderHoldsHooksOnly = {
         }
       },
       "Program:exit"(program) {
-        if (directlyInHooks || (!isHookFile && !isSharedFile)) return
+        if (judged.directlyInHooks || judged.stray || (!judged.hookFile && !judged.sharedFile)) return
         const exported = program.body
           .filter((node) => node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration")
           .flatMap((node) => exportedNames(node).map((exportedName) => ({ node, name: exportedName })))
-        if (isSharedFile) {
+        if (judged.sharedFile) {
           for (const item of exported) {
             if (isHookName(item.name)) context.report({ node: item.node, messageId: "sharedHook", data: { name: item.name } })
           }
@@ -100,7 +142,7 @@ export const hooksFolderHoldsHooksOnly = {
         }
         const hooks = exported.filter((item) => isHookName(item.name))
         for (const item of exported) {
-          if (!isHookName(item.name) && item.name !== "default") {
+          if (!isHookName(item.name) && !isSwrKeyName(item.name) && item.name !== "default") {
             context.report({ node: item.node, messageId: "export", data: { name: item.name } })
           }
         }

package/hygiene.mjs

@@ -7,7 +7,7 @@
  *   - a timer, listener, observer, socket or subscription started by an effect that never releases it
  *     keeps running after the component is gone and sets state on nothing;
  *   - a fetch started in an effect has no cache, no dedupe, no error state and no cancel, which is
- *     what SWR and the server readers already give for free (R50: client reads use SWR);
+ *     what the SWR hooks over the `modules/api` operations already give for free (R50: reads use SWR);
  *   - an empty `catch` turns a failure into a blank screen with no trace;
  *   - `console.*` is a log nobody reads, in a place no log pipeline sees.
  *
@@ -413,15 +413,15 @@ const loadStartedBy = (context, effect) => {
   return found
 }
 
-/** No data loading inside `useEffect`; SWR on the client, a reader on the server. */
+/** No data loading inside `useEffect`; data is read through an SWR hook over an operation of `modules/api`. */
 export const noDataFetchInEffect = {
   meta: {
     type: "problem",
-    docs: { description: "An effect body starts no promise: no `await`, `fetch`, `.then`, `void load()`, `mutate()` or `refresh()`; read through SWR or a server reader." },
+    docs: { description: "An effect body starts no promise: no `await`, `fetch`, `.then`, `void load()`, `mutate()` or `refresh()`; read through an SWR hook (`hooks/swr`) over an operation of `modules/api`." },
     schema: [],
     messages: {
       fetch:
-        "This effect starts a load: it awaits, calls `fetch`, chains `.then`, or calls a function that returns a promise (`void load()`, an SWR `mutate()` or `refresh()` too). An effect has no cache, no request dedupe, no error or loading state and no cancel, so two components asking for the same thing fetch twice and a slow first answer overwrites a fast second one. Data freshness comes from the SWR key, not from an effect: call the app client through SWR (`hooks/`) keyed on what changes, run `mutate()` from the event that changed the data (a handler, a socket message), and read what a route needs in a server reader (`modules/api/<domain>/read-*.ts`).",
+        "This effect starts a load: it awaits, calls `fetch`, chains `.then`, or calls a function that returns a promise (`void load()`, an SWR `mutate()` or `refresh()` too). An effect has no cache, no request dedupe, no error or loading state and no cancel, so two components asking for the same thing fetch twice and a slow first answer overwrites a fast second one. Data freshness comes from the SWR key, not from an effect: read through the SWR hook of the operation (`hooks/swr/`, over `modules/api`) keyed on what changes, and run `mutate()` from the event that changed the data (a handler, a socket message).",
     },
   },
   create(context) {

package/icon.mjs

@@ -13,8 +13,9 @@
  */
 
 import { isClassAttribute, staticText } from "./lib/ast.mjs"
+import { canonicalPackages } from "./lib/fe-stack.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
-import { fileOf, isComponentFile, isProductSource, kindOfFile, roleOfFile } from "./lib/scope.mjs"
+import { fileOf, inSlot, isComponentFile, isProductSource, kindOfFile, roleOfFile } from "./lib/scope.mjs"
 
 /** The one module allowed to name a glyph from a library: the entry of the leaf owner named `Icon`. */
 const ICON_LEAF = { kind: "leaves", owner: "Icon" }
@@ -44,13 +45,15 @@ const GLYPH_PACKAGES = [
 /** Package-name signal for a glyph catalogue not yet listed explicitly. */
 const GLYPH_PACKAGE_NAME = /(?:icon|glyph|lucide|feather|tabler|fortawesome)/i
 
-/** Upstream Heroicons plus StarCi's custom-only extension, each on the same two optical families. */
-const HEROICON_PACKAGES = new Set([
-  "@heroicons/react/24/outline",
-  "@heroicons/react/16/solid",
-  "@starci/heroicons/24/outline",
-  "@starci/heroicons/16/solid",
-])
+/** The two optical families of the heroicons family: the 24px outline heading cut and the 16px solid micro cut. */
+const GLYPH_CUTS = ["24/outline", "16/solid"]
+
+/**
+ * The closed glyph surface: each package of the one application icon set (fe-stack `icons`: upstream `@heroicons/react`,
+ * used first, and StarCi's custom-only `@starci/heroicons` for the glyphs it lacks) on each of the two cuts. Read from the
+ * catalog, so the set is named once.
+ */
+const glyphSurface = () => canonicalPackages("icons").flatMap((name) => GLYPH_CUTS.map((cut) => `${name}/${cut}`))
 
 /**
  * True when the file is the entry (slot role `entry`) of the component owner named `owner` in the layer `kind`.
@@ -60,8 +63,11 @@ const isEntryOf = (context, { kind, owner }) =>
   isComponentFile(context) && kindOfFile(context) === kind && roleOfFile(context) === "entry" &&
   hfsOf(context).relative(fileOf(context)).split("/").slice(-2)[0] === owner
 
-/** True when this file is the icon leaf, which owns the meaning-to-glyph map. */
-const isIconLeafFile = (context) => isEntryOf(context, ICON_LEAF)
+/**
+ * True when this file owns glyphs: the icon leaf, which owns the meaning-to-glyph map, or the toast module (`fe.modules.toast`),
+ * whose region draws the status glyph of each toast and sits in the modules tier, below every component it could ask.
+ */
+const isIconLeafFile = (context) => isEntryOf(context, ICON_LEAF) || inSlot(context, "fe.modules.toast")
 
 /** True for the reusable repeated metric cell whose reference contains no decorative glyph. */
 const isLabelledProgressRowFile = (context) => isEntryOf(context, LABELLED_PROGRESS_ROW)
@@ -104,15 +110,19 @@ export const noVendorIconOutsideIconLeaf = {
 
 // -- ICON-7 ----------------------------------------------------------------------------------------
 
-/** The icon leaf owns the map, but that ownership does not license a second glyph vocabulary. */
+/**
+ * The icon leaf owns the map, but that ownership does not license a second glyph vocabulary: every glyph comes from the
+ * heroicons family on its two cuts. Phosphor, Iconify, Lucide and every other glyph catalogue are refused, including the
+ * ones no list can name in advance.
+ */
 export const heroiconsIsTheGlyphVendor = {
   meta: {
     type: "problem",
-    docs: { description: "Only the Heroicons heading and micro families may supply product glyphs." },
+    docs: { description: "Only the Heroicons heading and micro families (`@heroicons/react`, then `@starci/heroicons`) may supply product glyphs." },
     schema: [],
     messages: {
       vendor:
-        "`{{source}}` is outside StarCi's closed glyph surface. Use upstream `@heroicons/react/24/outline` or `16/solid` when the icon exists; use the matching `@starci/heroicons` subpath only for a custom cut missing upstream. The StarCi package never re-exports upstream icons. Iconify, Phosphor and every other glyph catalogue are refused.",
+        "`{{source}}` is outside StarCi's closed glyph surface ({{surface}}). Use upstream `@heroicons/react/24/outline` or `16/solid` when the icon exists; use the matching `@starci/heroicons` subpath only for a custom cut missing upstream, and add a missing glyph there. The StarCi package never re-exports upstream icons. Phosphor, Iconify and every other glyph catalogue are refused: two sets draw the same meaning with two strokes, two grids and two weights.",
     },
   },
   create(context) {
@@ -120,8 +130,9 @@ export const heroiconsIsTheGlyphVendor = {
     return {
       ImportDeclaration(node) {
         const source = node.source && node.source.value
-        if (!isGlyphImport(source) || HEROICON_PACKAGES.has(String(source))) return
-        context.report({ node, messageId: "vendor", data: { source } })
+        const surface = glyphSurface()
+        if (!isGlyphImport(source) || surface.includes(String(source))) return
+        context.report({ node, messageId: "vendor", data: { source, surface: surface.map((name) => `\`${name}\``).join(", ") } })
       },
     }
   },

package/index.mjs

@@ -20,6 +20,7 @@ import { recommended as clientBoundaryRecommended, rules as clientBoundaryRules
 import { recommended as commentsRecommended, rules as commentsRules } from "./comments.mjs"
 import { recommended as classNamesRecommended, rules as classNamesRules } from "./class-names.mjs"
 import { recommended as envOwnerRecommended, rules as envOwnerRules } from "./env-owner.mjs"
+import { recommended as feStackRecommended, rules as feStackRules } from "./fe-stack.mjs"
 import { recommended as fileLayoutRecommended, rules as fileLayoutRules } from "./file-layout.mjs"
 import { recommended as grammarBoundaryRecommended, rules as grammarBoundaryRules } from "./grammar-boundary.mjs"
 import { recommended as formattingRecommended, rules as formattingRules } from "./formatting.mjs"
@@ -63,6 +64,7 @@ const CONTRIBUTIONS = [
     recommended: classNamesRecommended,
   },
   { law: "env-owner", rules: envOwnerRules, recommended: envOwnerRecommended },
+  { law: "fe-stack", rules: feStackRules, recommended: feStackRecommended },
   { law: "file-layout", rules: fileLayoutRules, recommended: fileLayoutRecommended },
   { law: "grammar-boundary", rules: grammarBoundaryRules, recommended: grammarBoundaryRecommended },
   { law: "formatting", rules: formattingRules, recommended: formattingRecommended },

package/lib/fe-stack.mjs

@@ -0,0 +1,73 @@
+/**
+ * The one door between the front-end lint rules and the fe-stack catalog (`knowledge/hfs/fe-stack.yaml`): for each common
+ * front-end concern the ONE canonical library, its HFS home and the alternatives a front end never imports.
+ *
+ * The catalog is read from this package's `runtime/` copy, the same way the slot manifest and the canon pins are (a byte copy
+ * of the runtime's knowledge file, refreshed by `scripts/hfs/sync-runtime.mjs`), so a rule in a product repository judges
+ * against the catalog of the canon version it installed. A rule that needs the catalog and finds none stops the lint run
+ * with an error naming the fix: a rule must not guess which libraries are forbidden.
+ */
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { parseYaml } from "../runtime/engine/yaml.mjs"
+
+const CATALOG = join(dirname(fileURLToPath(import.meta.url)), "..", "runtime", "knowledge", "hfs", "fe-stack.yaml")
+
+/** @type {{ concerns: ReadonlyArray<object>, forbidden: ReadonlyMap<string, object> } | null} */
+let loaded = null
+
+/**
+ * The parsed catalog: its concerns, and every forbidden package mapped to the concern that forbids it.
+ *
+ * @returns {{ concerns: ReadonlyArray<object>, forbidden: ReadonlyMap<string, object> }} The catalog.
+ */
+export const feStack = () => {
+  if (loaded) return loaded
+  let text
+  try {
+    text = readFileSync(CATALOG, "utf8")
+  } catch (error) {
+    throw new Error(`@starci/eslint-canon-fe reads the fe-stack catalog from runtime/knowledge/hfs/fe-stack.yaml and it is missing (${error.code ?? error.message}): regenerate the runtime copy (scripts/hfs/sync-runtime.mjs)`)
+  }
+  const concerns = parseYaml(text)?.concerns
+  if (!Array.isArray(concerns) || concerns.length === 0) throw new Error("runtime/knowledge/hfs/fe-stack.yaml declares no concerns: the fe-stack catalog is malformed")
+  const forbidden = new Map()
+  for (const concern of concerns) for (const name of concern.forbids ?? []) forbidden.set(String(name), concern)
+  loaded = Object.freeze({ concerns: Object.freeze(concerns), forbidden })
+  return loaded
+}
+
+/**
+ * The package a module specifier names (`@scope/name` or `name`, its subpath dropped), or null for a relative, aliased,
+ * node-builtin or empty specifier.
+ *
+ * @param {unknown} specifier - The module specifier.
+ * @returns {string | null} The package name.
+ */
+export const packageNameOf = (specifier) => {
+  const text = typeof specifier === "string" ? specifier : ""
+  if (text === "" || text.startsWith(".") || text.startsWith("/") || text.startsWith("@/") || text.startsWith("~/") || text.startsWith("node:")) return null
+  const parts = text.split("/")
+  if (text.startsWith("@")) return parts.length >= 2 && parts[1] !== "" ? `${parts[0]}/${parts[1]}` : null
+  return parts[0]
+}
+
+/**
+ * The concern whose `forbids` lists the package a specifier names, else null.
+ *
+ * @param {unknown} specifier - The module specifier.
+ * @returns {object | null} The concern (`{ id, packages, home, pattern, forbids, why }`).
+ */
+export const forbiddingConcern = (specifier) => {
+  const name = packageNameOf(specifier)
+  return name === null ? null : feStack().forbidden.get(name) ?? null
+}
+
+/**
+ * The canonical packages of a concern.
+ *
+ * @param {string} id - The concern id (`icons`, `graphql`, ...).
+ * @returns {ReadonlyArray<string>} Its packages; empty for an unknown concern.
+ */
+export const canonicalPackages = (id) => feStack().concerns.find((concern) => concern.id === id)?.packages ?? []

package/lib/scope.mjs

@@ -60,10 +60,31 @@ export const isComponentPath = (context, file) => {
 /** The one place that may read the environment: slot `fe.modules.config`. */
 export const isConfigModule = (context) => inSlot(context, "fe.modules.config")
 
-/** The one place that may call `fetch`: slot `fe.transport.client` (one-app repository) or `fe.package.api.client` (shared package). */
+/**
+ * The transport owner: the folder of the auth and no-auth Apollo clients and their link chain, slot `fe.transport.client`
+ * (`modules/api/graphql/clients/`, one-app repository) or `fe.package.api.client` (`src/graphql/clients/` of the shared api package).
+ */
 export const isApiClient = (context) => inSlot(context, "fe.transport.client", "fe.package.api.client")
 
-/** The file that may declare the one Outcome union: the file of the slot the manifest marks `outcomeHome`. */
+/** The slots of the API layer: the app's `modules/api` (with its clients folder and its GraphQLResponse file) and the shared api package. */
+const API_LAYER_SLOTS = Object.freeze(["fe.modules.api", "fe.transport.client", "fe.transport.outcome", "fe.package.api", "fe.package.api.client", "fe.package.api.outcome"])
+
+/** True when the linted file sits in the API layer: the only place that talks to the back end (Apollo, axios, `fetch`). */
+export const isApiLayer = (context) => inSlot(context, ...API_LAYER_SLOTS)
+
+/**
+ * True when the linted file is a REST call of the API layer: `modules/api/rest/**` of an app (slot `fe.modules.api`) or
+ * `src/rest/**` of the shared api package (slot `fe.package.api`), the one home of axios.
+ */
+export const isApiRest = (context) => {
+  if (!inSlot(context, "fe.modules.api", "fe.package.api")) return false
+  const hfs = hfsOf(context)
+  const file = fileOf(context)
+  const below = hfs.relative(file).slice(hfs.classify(file).root.length + 1).split("/")
+  return (below[0] === "src" ? below[1] : below[0]) === "rest"
+}
+
+/** The file that may declare the one result vocabulary (`GraphQLResponse`): the file of the slot the manifest marks `outcomeHome`. */
 export const isOutcomeModule = (context) => {
   const hfs = hfsOf(context)
   const slot = slotOfFile(context)