@starci/eslint-canon-fe 6.0.0 → 6.0.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 6.0.2 - 2026-09-30
+
+- **Fix: `use-client-only-at-boundary` refused the providers wrapper.** The route tree's `providers.tsx` (root or `[locale]`,
+  role `providers` of `fe.route` in the slot manifest) is the client component a server layout renders around its children to host
+  context providers; the directive is accepted there. A providers wrapper kept elsewhere (a layout feature, a module) is still a
+  finding, and the message names `providers.tsx` as its home.
+
+## 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`

package/client-boundary.mjs

@@ -20,7 +20,8 @@ import { classifyImport, fileOf, isProductSource, isSpecFile, kindOfFile, roleOf
 import { typed } from "./lib/types.mjs"
 
 /** 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"])
+/** Route-tree roles that are client components by construction: the error boundaries, and the providers wrapper a layout renders. */
+const FRAMEWORK_CLIENT_ROLES = new Set(["error", "global-error", "providers"])
 
 /** True when the program opens with the `"use client"` directive. */
 const clientDirective = (program) =>
@@ -58,9 +59,9 @@ export const useClientOnlyAtBoundary = {
     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`.",
+        "`\"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`; context providers go in the route tree's `providers.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.",
+        "`\"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, on `error.tsx`/`global-error.tsx`, or on the route tree's `providers.tsx` (the context providers a layout renders around its children). Below a client block the file is already client; above one it must stay a server component.",
     },
   },
   create(context) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "description": "The StarCi front-end lint canon: every rule its laws publish, gathered as one flat-config plugin and attached by one factory.",
   "type": "module",
   "license": "UNLICENSED",

package/runtime/knowledge/hfs/slots.yaml

@@ -662,7 +662,7 @@ slots:
     presence: optional
     tracked: tracked
     tier: inherit
-    requires: [connection.ts]     # CONNECTION = <CONN>_CONNECTION of an hfs.json connection, and the capability's <c>Entities / <c>Migrations arrays (the owner index re-exports the two arrays by name)
+    requires: [connection.ts]     # the capability's <c>Entities / <c>Migrations arrays (the owner index re-exports the two arrays by name); no CONNECTION alias: the connection is the one the apps register the arrays on
     allows: ["entities/<table>.entity.ts", "migrations/<epochMs13>-<kebab-name>.ts", "<name>.sql.ts", "<name>.rows.ts", connection.ts, "*.spec.ts"]
     forbids: [index.ts, "<name>.repository.ts"]
     tests: unit-beside
@@ -838,7 +838,8 @@ slots:
              not-found.tsx, layout.tsx,    # next-intl: a request outside every locale renders the root not-found inside a root layout
              "health/{live,ready}/route.ts", "api/**/route.ts", "_*/**", providers.tsx, globals.css,
              "{icon,favicon,apple-icon,opengraph-image,twitter-image}.*", robots.ts, sitemap.ts, manifest.ts, "**/*.spec.ts", "**/*.spec.tsx"]
-    roles: {page: page.tsx, layout: layout.tsx, template: template.tsx, loading: loading.tsx, error: error.tsx, not-found: not-found.tsx, default: default.tsx, route: route.ts, global-error: global-error.tsx}
+    # providers.tsx (root or [locale]) is the client wrapper the server layout renders around its children to host context providers.
+    roles: {page: page.tsx, layout: layout.tsx, template: template.tsx, loading: loading.tsx, error: error.tsx, not-found: not-found.tsx, default: default.tsx, route: route.ts, global-error: global-error.tsx, providers: providers.tsx}
     tests: none
     rules: [FE_ROUTE_FILES_THIN, FE_CLIENT_BOUNDARY, FE_OWNER_REACHABLE]
   - id: fe.source-root-pinned

package/size-and-state-budget.mjs

@@ -18,7 +18,9 @@
  * socket), so the loop in a component is always the wrong one.
  */
 
+import { functionOf, isFn } from "./lib/bindings.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
+import { isPromiseValued } from "./lib/types.mjs"
 import { fileOf, isSpecFile, roleOfFile, slotOfFile } from "./lib/scope.mjs"
 
 /**
@@ -167,17 +169,55 @@ const isIntervalCall = (node) => {
   )
 }
 
-/** No hand-written polling loop in a component or hook. */
+/** The function node a timer runs: the inline callback, or the same-file function a name stands for. */
+const timerCallback = (context, node) => functionOf(context, node.arguments[0])
+
+/**
+ * True when running `fn` reads data: a call in its body (outside nested functions) whose value is a promise - `fetch`, the
+ * transport client, a reader, SWR's `mutate()`/revalidation, anything awaited - or an `await`. A tick that only reads the time or
+ * sets state (a shared clock, a countdown, an animation step) is not a refresh mechanism.
+ */
+const readsData = (context, fn, seen = new Set()) => {
+  if (!fn || seen.has(fn)) return false
+  seen.add(fn)
+  let found = false
+  const visit = (current) => {
+    if (found || !current || typeof current.type !== "string") return
+    if (current !== fn && isFn(current)) return
+    if (current.type === "AwaitExpression") { found = true; return }
+    if (current.type === "CallExpression") {
+      if (isPromiseValued(context, current)) { found = true; return }
+      const local = functionOf(context, current.callee)
+      if (local && readsData(context, local, seen)) { found = true; return }
+    }
+    for (const [key, child] of Object.entries(current)) {
+      if (key === "parent") continue
+      if (Array.isArray(child)) child.forEach(visit)
+      else if (child && typeof child.type === "string") visit(child)
+    }
+  }
+  visit(fn.body)
+  return found
+}
+
+/**
+ * No hand-written polling loop in a component or hook.
+ *
+ * A timer is polling when what it runs READS DATA (see `readsData`, decided by the type of each call, not by a name): a
+ * `setInterval`, or a `setTimeout` whose callback schedules the enclosing function again. The FE convention names no shared clock
+ * owner (knowledge/hfs/README.md section 6: "one refresh mechanism per resource, poll or socket"), so a timer that only ticks time
+ * or state - nivo-fe `useNow`, a one-minute clock behind `useSyncExternalStore` - is not a second refresh mechanism.
+ */
 export const noHandRolledPolling = {
   meta: {
     type: "problem",
-    docs: { description: "No `setInterval` and no self-scheduling `setTimeout`: one refresh mechanism per resource." },
+    docs: { description: "No `setInterval` and no self-scheduling `setTimeout` that reads data: one refresh mechanism per resource." },
     schema: [],
     messages: {
       interval:
-        "A `setInterval` loop. This is a second refresh mechanism beside the data hook's own; two mechanisms per resource means double requests and a spinner that never settles. Refresh through the data hook (`refreshInterval`) or a socket, not a timer in the component.",
+        "A `setInterval` loop that reads data. This is a second refresh mechanism beside the data hook's own; two mechanisms per resource means double requests and a spinner that never settles. Refresh through the data hook (`refreshInterval`) or a socket, not a timer in the component.",
       timeout:
-        "A `setTimeout` that schedules its own next run is a polling loop written by hand. Refresh through the data hook (`refreshInterval`) or a socket.",
+        "A `setTimeout` that schedules its own next run and reads data is a polling loop written by hand. Refresh through the data hook (`refreshInterval`) or a socket.",
     },
   },
   create(context) {
@@ -185,19 +225,29 @@ export const noHandRolledPolling = {
     const source = context.sourceCode || context.getSourceCode()
     return {
       CallExpression(node) {
-        if (isIntervalCall(node)) return context.report({ node, messageId: "interval" })
+        if (isIntervalCall(node)) {
+          if (readsData(context, timerCallback(context, node))) context.report({ node, messageId: "interval" })
+          return
+        }
         const callee = node.callee
         if (callee.type !== "Identifier" || callee.name !== "setTimeout") return
         const callback = node.arguments[0]
         if (!callback || (callback.type !== "ArrowFunctionExpression" && callback.type !== "FunctionExpression")) return
-        // The enclosing named function: does the timer's own callback call it again?
-        const owner = source.getAncestors(node).reverse().find((ancestor) =>
-          ["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"].includes(ancestor.type) && functionName(ancestor),
-        )
-        const name = owner ? functionName(owner) : null
-        if (!name) return
-        const calls = new RegExp(`\\b${name}\\s*\\(`).test(source.getText(callback))
-        if (calls) context.report({ node, messageId: "timeout" })
+        // The enclosing function: does the timer's own callback call it again (the same binding, not the same spelling)?
+        const owner = source.getAncestors(node).reverse().find((ancestor) => isFn(ancestor))
+        if (!owner) return
+        let again = false
+        const visit = (current) => {
+          if (again || !current || typeof current.type !== "string") return
+          if (current.type === "CallExpression" && functionOf(context, current.callee) === owner) { again = true; return }
+          for (const [key, child] of Object.entries(current)) {
+            if (key === "parent") continue
+            if (Array.isArray(child)) child.forEach(visit)
+            else if (child && typeof child.type === "string") visit(child)
+          }
+        }
+        visit(callback.body)
+        if (again && (readsData(context, callback) || readsData(context, owner))) context.report({ node, messageId: "timeout" })
       },
     }
   },