@starci/eslint-canon-fe 4.0.0 → 5.1.2

package/served-locale.mjs

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

package/shape-slot.mjs

@@ -19,8 +19,7 @@
  * never wrong, beyond it.
  */
 
-/** Forward-slash form of a filename, so Windows paths compare like every other path. */
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+import { normalizePath } from "./lib/path.mjs"
 
 /** The pure half of a split tier, and which tier it is. */
 const pureHalf = (filename) => {

package/size-and-state-budget.mjs

@@ -0,0 +1,196 @@
+/**
+ * The rules that hold `size-and-state-budget.md` (HFS R65, `FE_SIZE_AND_STATE_BUDGET`).
+ *
+ * A BUDGET IS A SMELL DETECTOR, NOT A STYLE. A component past 300 lines, or one that holds more than
+ * six pieces of state or reads six data hooks, is doing the work of several units: one repository's
+ * status-flow component held 20 `useState`s and three data sources in one 900-line file, and no
+ * reviewer could say what it did. The numbers are the same for every app so that "too big" is a
+ * measurement, not an opinion.
+ *
+ * WHAT THE LINT HOLDS, AND WHAT IT LEAVES. Absolute limits per file and per component are file-local
+ * facts and are held here. "Size may not GROW against the parent commit" (`HFS_SIZE_GROWTH`) is a
+ * repository fact needing the previous revision, so it belongs to the architecture machine; the two
+ * are complementary, not duplicates - this catches the new giant, that catches the old one growing.
+ *
+ * POLLING. A hand-rolled `setInterval` or self-scheduling `setTimeout` is a second refresh mechanism
+ * beside the data hook's own, and two mechanisms per resource means double requests and a spinner
+ * that never settles. Each resource refreshes by exactly one mechanism (a SWR `refreshInterval`, or a
+ * socket), so the loop in a component is always the wrong one.
+ */
+
+import { isSpecFile } from "./lib/scope.mjs"
+import { normalizePath } from "./lib/path.mjs"
+
+/** The largest a component file may be. */
+export const MAX_COMPONENT_LINES = 300
+
+/** The most `useState` calls one connected unit may hold. */
+export const MAX_STATE_HOOKS = 6
+
+/** The most data hooks one connected unit may read. */
+export const MAX_DATA_HOOKS = 6
+
+/** A hook that reads remote data. */
+const DATA_HOOK = /^use\w*(?:Swr|SWR|Query|Mutation|Fetch|Infinite|Subscription)\w*$/
+
+/** A state hook. */
+const STATE_HOOK = /^(?:useState|useReducer)$/
+
+/** The name a call is made through: `useState` or `React.useState`. */
+const calleeName = (callee) => {
+  if (callee.type === "Identifier") return callee.name
+  if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.object.name === "React") {
+    return callee.property.name
+  }
+  return null
+}
+
+/** The name a function is bound to, when it has one. */
+const functionName = (node) => {
+  if (node.id) return node.id.name
+  const parent = node.parent
+  if (parent && parent.type === "VariableDeclarator" && parent.id.type === "Identifier") return parent.id.name
+  return null
+}
+
+/** A component or hook, by the naming convention React itself relies on. */
+const isUnitName = (name) => Boolean(name) && (/^[A-Z]/.test(name) || /^use[A-Z0-9]/.test(name))
+
+// -- BUDGET-1 --------------------------------------------------------------------------------------
+
+/** A component file is at most 300 lines. */
+export const componentLineBudget = {
+  meta: {
+    type: "suggestion",
+    docs: { description: `A component file has at most ${MAX_COMPONENT_LINES} lines.` },
+    schema: [],
+    messages: {
+      lines:
+        "This component file has {{count}} lines; the budget is {{max}}. A file this size is several units in one: split the drawing from the data, and the sections from each other, so each part can be named, tested and reviewed on its own.",
+    },
+  },
+  create(context) {
+    const filename = normalizePath(context.filename || context.getFilename())
+    if (!filename.endsWith(".tsx") || isSpecFile(filename) || !filename.includes("/src/")) return {}
+    const source = context.sourceCode || context.getSourceCode()
+    return {
+      Program(node) {
+        // A trailing newline is not a line of code.
+        const count = source.lines.length - (source.lines[source.lines.length - 1] === "" ? 1 : 0)
+        if (count > MAX_COMPONENT_LINES) context.report({ node, messageId: "lines", data: { count, max: MAX_COMPONENT_LINES } })
+      },
+    }
+  },
+}
+
+// -- BUDGET-2 --------------------------------------------------------------------------------------
+
+/** A connected unit holds at most six state hooks and reads at most six data hooks. */
+export const unitHookBudget = {
+  meta: {
+    type: "suggestion",
+    docs: { description: `A unit has at most ${MAX_STATE_HOOKS} state hooks and ${MAX_DATA_HOOKS} data hooks.` },
+    schema: [],
+    messages: {
+      state:
+        "`{{name}}` holds {{count}} state hooks; the budget is {{max}}. That much local state is several concerns tangled together: group what changes together into a reducer or a hook of its own, and derive the rest instead of storing it.",
+      data:
+        "`{{name}}` reads {{count}} data hooks; the budget is {{max}}. A unit that gathers this many resources is a page pretending to be a block: give each slot its own connected block.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    /** One frame per function being walked; only a component or hook frame accumulates. */
+    const frames = []
+    const enter = (node) => frames.push({ node, name: functionName(node), state: 0, data: 0 })
+    const exit = () => {
+      const frame = frames.pop()
+      if (!frame || !isUnitName(frame.name)) return
+      const at = frame.node.id || frame.node
+      if (frame.state > MAX_STATE_HOOKS) {
+        context.report({ node: at, messageId: "state", data: { name: frame.name, count: frame.state, max: MAX_STATE_HOOKS } })
+      }
+      if (frame.data > MAX_DATA_HOOKS) {
+        context.report({ node: at, messageId: "data", data: { name: frame.name, count: frame.data, max: MAX_DATA_HOOKS } })
+      }
+    }
+    return {
+      FunctionDeclaration: enter,
+      FunctionExpression: enter,
+      ArrowFunctionExpression: enter,
+      "FunctionDeclaration:exit": exit,
+      "FunctionExpression:exit": exit,
+      "ArrowFunctionExpression:exit": exit,
+      CallExpression(node) {
+        const name = calleeName(node.callee)
+        if (!name) return
+        // Attribute the call to the nearest enclosing component or hook.
+        const owner = [...frames].reverse().find((frame) => isUnitName(frame.name))
+        if (!owner) return
+        if (STATE_HOOK.test(name)) owner.state += 1
+        else if (DATA_HOOK.test(name)) owner.data += 1
+      },
+    }
+  },
+}
+
+// -- BUDGET-3 --------------------------------------------------------------------------------------
+
+/** `setInterval`, or `window.setInterval`. */
+const isIntervalCall = (node) => {
+  const callee = node.callee
+  if (callee.type === "Identifier") return callee.name === "setInterval"
+  return (
+    callee.type === "MemberExpression" &&
+    !callee.computed &&
+    callee.property.name === "setInterval" &&
+    callee.object.type === "Identifier" &&
+    ["window", "globalThis", "self"].includes(callee.object.name)
+  )
+}
+
+/** No hand-written polling loop in a component or hook. */
+export const noHandRolledPolling = {
+  meta: {
+    type: "problem",
+    docs: { description: "No `setInterval` and no self-scheduling `setTimeout`: 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.",
+      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.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    const source = context.sourceCode || context.getSourceCode()
+    return {
+      CallExpression(node) {
+        if (isIntervalCall(node)) return context.report({ node, messageId: "interval" })
+        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 rules this law contributes to the plugin. */
+export const rules = {
+  "component-line-budget": componentLineBudget,
+  "unit-hook-budget": unitHookBudget,
+  "no-hand-rolled-polling": noHandRolledPolling,
+}
+
+/** Every rule is an error: the budget is the same for every app, and there is no baseline. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))