@starci/eslint-canon-fe 3.0.2 → 5.1.2

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"]))

package/spec-quality.mjs

@@ -0,0 +1,239 @@
+/**
+ * The rules that hold `spec-quality.md` (HFS R67 `FE_SPEC_QUALITY`, and the "specs use the real
+ * catalogue" half of R60).
+ *
+ * A SPEC IS A CLAIM ABOUT ONE UNIT'S BEHAVIOUR. The defects these rules refuse are the ones that made
+ * specs pass while the product was wrong, or fail while it was right:
+ *
+ *   - pinning a class string: the spec fails when a designer changes a token, and passes when the
+ *     element that carries it is gone;
+ *   - testing something other than the neighbour: a spec that imports a different unit is that
+ *     unit's spec in the wrong folder, and its owner will not find it;
+ *   - a spec for a barrel: there is no behaviour in `export * from`, so the spec asserts that the
+ *     language works;
+ *   - a double cast (`as unknown as T`) to build a value the types forbid: the spec then proves the
+ *     unit against a shape it can never receive;
+ *   - a connected screen with no accessibility assertion: the state a reader with a screen reader
+ *     meets is the one nobody looked at;
+ *   - a mocked `next-intl`: the spec then passes on the KEY, so a missing or misspelled catalogue
+ *     entry is invisible until a reader sees `course.titel`.
+ */
+
+import { baseName, isSpecFile } from "./lib/scope.mjs"
+import { normalizePath } from "./lib/path.mjs"
+
+/** The subject a spec sits beside: `Feed.test.tsx` -> `Feed`. */
+const subjectOf = (file) => baseName(file).replace(/\.(?:test|spec)\.[cm]?tsx?$/, "")
+
+/** The name a call is made through: `toHaveClass` in `expect(x).toHaveClass(...)`, or `axe` in `axe(x)`. */
+const calleeName = (callee) => {
+  if (callee.type === "Identifier") return callee.name
+  if (callee.type === "MemberExpression" && !callee.computed) return callee.property.name
+  return null
+}
+
+/** Static string of a literal or an expression-free template, else null. */
+const staticString = (node) => {
+  if (!node) return null
+  if (node.type === "Literal" && typeof node.value === "string") return node.value
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0]?.value.cooked ?? ""
+  return null
+}
+
+// -- SPEC-1 ----------------------------------------------------------------------------------------
+
+/** A spec does not pin class strings. */
+export const noClassStringInSpec = {
+  meta: {
+    type: "problem",
+    docs: { description: "A component spec asserts behaviour, never a class string." },
+    schema: [],
+    messages: {
+      pinned:
+        "This spec pins a class string. It fails when a designer changes a token and passes when the element that carried it is gone - it tests the stylesheet, not the unit. Assert what the reader gets: a role, a name, a state, or the text.",
+    },
+  },
+  create(context) {
+    if (!isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      CallExpression(node) {
+        const name = calleeName(node.callee)
+        if (name === "toHaveClass") return context.report({ node, messageId: "pinned" })
+        if ((name === "toHaveAttribute" || name === "getAttribute") && staticString(node.arguments[0]) === "class") {
+          return context.report({ node, messageId: "pinned" })
+        }
+        if (name === "querySelector" || name === "querySelectorAll") {
+          const selector = staticString(node.arguments[0])
+          if (selector !== null && /(?:^|[\s>+~,])\.[\w-]|\[class/.test(selector)) context.report({ node, messageId: "pinned" })
+        }
+      },
+      MemberExpression(node) {
+        if (node.computed || !["className", "classList"].includes(node.property.name)) return
+        context.report({ node, messageId: "pinned" })
+      },
+    }
+  },
+}
+
+// -- SPEC-2 ----------------------------------------------------------------------------------------
+
+/** A spec imports the unit beside it. */
+export const specTestsItsNeighbour = {
+  meta: {
+    type: "problem",
+    docs: { description: "A spec imports its sibling subject: `X.test.tsx` imports `./X`." },
+    schema: [],
+    messages: {
+      subject:
+        "This spec does not import its neighbour `./{{subject}}`. A spec exercises the unit beside it; one that imports something else is that unit's spec in the wrong folder, and its owner will not find it. Move it beside its subject, or test the neighbour.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isSpecFile(file)) return {}
+    const subject = subjectOf(file)
+    const accepted = new Set([`./${subject}`, `./${subject}.tsx`, `./${subject}.ts`, `./${subject}.js`, `./${subject}.jsx`])
+    if (subject === "index") ["./", ".", "./index"].forEach((entry) => accepted.add(entry))
+    let imported = false
+    return {
+      ImportDeclaration(node) {
+        if (accepted.has(String(node.source.value))) imported = true
+      },
+      CallExpression(node) {
+        // `await import("./X")` and `require("./X")` are also an import of the subject.
+        const isImport = node.callee.type === "Import" || (node.callee.type === "Identifier" && node.callee.name === "require")
+        if (isImport && accepted.has(staticString(node.arguments[0]))) imported = true
+      },
+      ImportExpression(node) {
+        if (accepted.has(staticString(node.source))) imported = true
+      },
+      "Program:exit"(program) {
+        if (!imported) context.report({ node: program, messageId: "subject", data: { subject } })
+      },
+    }
+  },
+}
+
+// -- SPEC-3 ----------------------------------------------------------------------------------------
+
+/** No spec for a barrel. */
+export const noBarrelSpec = {
+  meta: {
+    type: "problem",
+    docs: { description: "No `index.test.ts` beside an `index.ts` barrel." },
+    schema: [],
+    messages: {
+      barrel:
+        "A spec for a barrel. `index.ts` holds re-exports, which have no behaviour; a spec beside one asserts that the language works. Test the units the barrel re-exports, beside each of them.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!/(?:^|\/)index\.(?:test|spec)\.[cm]?ts$/.test(file)) return {}
+    return { Program: (node) => context.report({ node, messageId: "barrel" }) }
+  },
+}
+
+// -- SPEC-4 ----------------------------------------------------------------------------------------
+
+/** No `as unknown as T` in a spec. */
+export const noDoubleCastInSpec = {
+  meta: {
+    type: "problem",
+    docs: { description: "A spec builds its values with the type's own shape, not `as unknown as`." },
+    schema: [],
+    messages: {
+      double:
+        "A double cast in a spec. It builds a value the types forbid, so the spec proves the unit against a shape it can never receive. Build the value with a typed factory (`mock<T>()` or a fixture builder), or narrow from `unknown` with a check.",
+    },
+  },
+  create(context) {
+    if (!isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      TSAsExpression(node) {
+        const inner = node.expression
+        if (inner && inner.type === "TSAsExpression" && inner.typeAnnotation.type === "TSUnknownKeyword") {
+          context.report({ node, messageId: "double" })
+        }
+      },
+    }
+  },
+}
+
+// -- SPEC-5 ----------------------------------------------------------------------------------------
+
+/** The specs of connected screens: a block's `index` and a feature's `index`. */
+const isConnectedSpec = (file) =>
+  /(?:^|\/)index\.(?:test|spec)\.[cm]?tsx$/.test(file) &&
+  (/\/components\/blocks\//.test(file) || /\/features\/(?:pages|layouts|overlays)\//.test(file))
+
+/** Names that run an accessibility check. */
+const AXE_CALLS = new Set(["axe", "runAxe", "expectNoAxeViolations", "expectNoA11yViolations", "toHaveNoViolations"])
+
+/** A connected screen's spec asserts accessibility. */
+export const connectedSpecHasAxe = {
+  meta: {
+    type: "problem",
+    docs: { description: "The spec of a connected block or feature runs an axe assertion." },
+    schema: [],
+    messages: {
+      axe:
+        "This spec covers a connected screen but runs no accessibility assertion. The state a reader with a screen reader meets is the one nobody looked at; add `expect(await axe(container)).toHaveNoViolations()`.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isConnectedSpec(file)) return {}
+    let ran = false
+    return {
+      CallExpression(node) {
+        const name = calleeName(node.callee)
+        if (name && AXE_CALLS.has(name)) ran = true
+      },
+      "Program:exit"(program) {
+        if (!ran) context.report({ node: program, messageId: "axe" })
+      },
+    }
+  },
+}
+
+// -- SPEC-6 ----------------------------------------------------------------------------------------
+
+/** No mock of the translation runtime. */
+export const noMockedTranslations = {
+  meta: {
+    type: "problem",
+    docs: { description: "A spec renders with the real catalogue; it never mocks `next-intl`." },
+    schema: [],
+    messages: {
+      mocked:
+        "A mocked `next-intl`. The spec then passes on the KEY, so a missing or misspelled catalogue entry is invisible until a reader sees `course.titel`. Render inside `NextIntlClientProvider` with the real `messages/<locale>.json`.",
+    },
+  },
+  create(context) {
+    if (!isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "MemberExpression" || callee.computed) return
+        if (!["mock", "doMock", "unstable_mockModule"].includes(callee.property.name)) return
+        if (!["vi", "jest"].includes(callee.object.name)) return
+        const target = staticString(node.arguments[0])
+        if (target !== null && /^next-intl(?:\/|$)/.test(target)) context.report({ node, messageId: "mocked" })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-class-string-in-spec": noClassStringInSpec,
+  "spec-tests-its-neighbour": specTestsItsNeighbour,
+  "no-barrel-spec": noBarrelSpec,
+  "no-double-cast-in-spec": noDoubleCastInSpec,
+  "connected-spec-has-axe": connectedSpecHasAxe,
+  "no-mocked-translations": noMockedTranslations,
+}
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))