@starci/eslint-canon-fe 4.0.0 → 5.1.2

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

package/the-split.mjs

@@ -1,153 +1,152 @@
-/**
- * The rule that holds `the-split.md`.
- *
- * ONE RULE, AND IT WATCHES ONE HALF. The drawing half's purity is checkable: a file that fetches,
- * reads a store or resolves a word is visible in what it calls. The connected half's discipline is
- * not - a file that draws badly, or settles the wrong situation, looks exactly like one that does
- * neither. So this rule guards the boundary from the side where a machine can see it, and the other
- * side stays a matter for review.
- *
- * The scope is the filename. `component.tsx` is the drawing half by convention across every tier
- * that splits, so the convention does the scoping and the rule needs no configuration.
- */
-
-/** Forward-slash form of a filename, so Windows paths compare like every other path. */
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** The drawing half, named by the convention every split surface follows. */
-const isDrawingHalf = (filename) => /(?:^|\/)component\.tsx$/.test(normalizePath(filename))
-
-/** A connected block entrypoint and the public name its folder fixes. */
-const connectedBlock = (filename) => {
-  const match = normalizePath(filename).match(
-    /\/src\/components\/blocks\/(?:[^/]+\/)*([A-Z][A-Za-z0-9]*)\/index\.tsx$/,
-  )
-  return match ? match[1] : null
-}
-
-/**
- * Calls that reach for the world instead of receiving it.
- *
- * Four families: a request, a store, the translation runtime, and a direct query. Each is a
- * dependency the drawing half cannot be rendered from a fixture without.
- */
-const REACHES_FOR_THE_WORLD =
-  /^(?:useSWR|useSWRMutation|use[A-Za-z0-9]*Swr|useAppSelector|useDispatch|use[A-Za-z0-9]*Store|useTranslations|useLocale|useFormatter|query[A-Z][A-Za-z0-9]*|mutation[A-Z][A-Za-z0-9]*)$/
-
-// -- SPLIT-1 ---------------------------------------------------------------------------------------
-
-/** The drawing half receives everything and asks for nothing. */
-export const presentationalPurity = {
-  meta: {
-    type: "problem",
-    docs: { description: "The drawing half takes resolved props: no request, no store, no translation." },
-    schema: [],
-    messages: {
-      reaches:
-        "`{{name}}(...)` reaches for the world from the drawing half. This file must be renderable from a fixture - that is what makes it testable without standing the world up first, and it is the whole reason the split exists. Move the call to `index.tsx` and pass the result down as a settled situation.",
-    },
-  },
-  create(context) {
-    if (!isDrawingHalf(context.filename || context.getFilename())) return {}
-    return {
-      CallExpression(node) {
-        const callee = node.callee
-        if (!callee || callee.type !== "Identifier") return
-        if (!REACHES_FOR_THE_WORLD.test(callee.name)) return
-        context.report({ node, messageId: "reaches", data: { name: callee.name } })
-      },
-    }
-  },
-}
-
-// -- SPLIT-5 ---------------------------------------------------------------------------------------
-
-/** A connected block delegates every render path to its exact pure twin. */
-export const connectedBlockHasPresentationalTwin = {
-  meta: {
-    type: "problem",
+/**
+ * The rule that holds `the-split.md`.
+ *
+ * ONE RULE, AND IT WATCHES ONE HALF. The drawing half's purity is checkable: a file that fetches,
+ * reads a store or resolves a word is visible in what it calls. The connected half's discipline is
+ * not - a file that draws badly, or settles the wrong situation, looks exactly like one that does
+ * neither. So this rule guards the boundary from the side where a machine can see it, and the other
+ * side stays a matter for review.
+ *
+ * The scope is the filename. `component.tsx` is the drawing half by convention across every tier
+ * that splits, so the convention does the scoping and the rule needs no configuration.
+ */
+
+import { normalizePath } from "./lib/path.mjs"
+
+/** The drawing half, named by the convention every split surface follows. */
+const isDrawingHalf = (filename) => /(?:^|\/)component\.tsx$/.test(normalizePath(filename))
+
+/** A connected block entrypoint and the public name its folder fixes. */
+const connectedBlock = (filename) => {
+  const match = normalizePath(filename).match(
+    /\/src\/components\/blocks\/(?:[^/]+\/)*([A-Z][A-Za-z0-9]*)\/index\.tsx$/,
+  )
+  return match ? match[1] : null
+}
+
+/**
+ * Calls that reach for the world instead of receiving it.
+ *
+ * Four families: a request, a store, the translation runtime, and a direct query. Each is a
+ * dependency the drawing half cannot be rendered from a fixture without.
+ */
+const REACHES_FOR_THE_WORLD =
+  /^(?:useSWR|useSWRMutation|use[A-Za-z0-9]*Swr|useAppSelector|useDispatch|use[A-Za-z0-9]*Store|useTranslations|useLocale|useFormatter|query[A-Z][A-Za-z0-9]*|mutation[A-Z][A-Za-z0-9]*)$/
+
+// -- SPLIT-1 ---------------------------------------------------------------------------------------
+
+/** The drawing half receives everything and asks for nothing. */
+export const presentationalPurity = {
+  meta: {
+    type: "problem",
+    docs: { description: "The drawing half takes resolved props: no request, no store, no translation." },
+    schema: [],
+    messages: {
+      reaches:
+        "`{{name}}(...)` reaches for the world from the drawing half. This file must be renderable from a fixture - that is what makes it testable without standing the world up first, and it is the whole reason the split exists. Move the call to `index.tsx` and pass the result down as a settled situation.",
+    },
+  },
+  create(context) {
+    if (!isDrawingHalf(context.filename || context.getFilename())) return {}
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (!callee || callee.type !== "Identifier") return
+        if (!REACHES_FOR_THE_WORLD.test(callee.name)) return
+        context.report({ node, messageId: "reaches", data: { name: callee.name } })
+      },
+    }
+  },
+}
+
+// -- SPLIT-5 ---------------------------------------------------------------------------------------
+
+/** A connected block delegates every render path to its exact pure twin. */
+export const connectedBlockHasPresentationalTwin = {
+  meta: {
+    type: "problem",
     docs: { description: "A connected block index renders only its exact `XBase` twin from component.tsx." },
-    schema: [],
-    messages: {
-      missing:
-        "`{{block}}` reads the world, so it must import exact `{{twin}}` from `./component`. A single leaf, one tree, or no local state is not an exception.",
-      bypass:
-        "Connected `{{block}}` renders `<{{rendered}}>` directly. Resolve the world here, then render only `<{{twin}}>`; component.tsx owns the complete presentation.",
+    schema: [],
+    messages: {
+      missing:
+        "`{{block}}` reads the world, so it must import exact `{{twin}}` from `./component`. A single leaf, one tree, or no local state is not an exception.",
+      bypass:
+        "Connected `{{block}}` renders `<{{rendered}}>` directly. Resolve the world here, then render only `<{{twin}}>`; component.tsx owns the complete presentation.",
       unused:
         "Connected `{{block}}` imports `{{twin}}` but never renders it. Every connected render path must cross the pure twin.",
       called:
         "Connected `{{block}}` calls `{{twin}}(...)` as an ordinary function. Render `<{{twin}} />` so React owns the twin's hook lifecycle and every render keeps one stable component boundary.",
-    },
-  },
-  create(context) {
-    const block = connectedBlock(context.filename || context.getFilename())
-    if (!block) return {}
-
+    },
+  },
+  create(context) {
+    const block = connectedBlock(context.filename || context.getFilename())
+    if (!block) return {}
+
     const twin = `${block}Base`
     const worldBindings = new Set()
     const rendered = []
     const calledTwin = []
-    let importsTwin = false
-    let readsWorld = false
-    let rendersTwin = false
-
-    return {
-      ImportDeclaration(node) {
-        const source = typeof node.source?.value === "string" ? node.source.value : ""
-        for (const specifier of node.specifiers || []) {
-          const imported = specifier.imported?.name
-          const local = specifier.local?.name
-          if (source === "./component" && imported === twin && local === twin) importsTwin = true
-          if (imported && local && REACHES_FOR_THE_WORLD.test(imported)) worldBindings.add(local)
-        }
-      },
+    let importsTwin = false
+    let readsWorld = false
+    let rendersTwin = false
+
+    return {
+      ImportDeclaration(node) {
+        const source = typeof node.source?.value === "string" ? node.source.value : ""
+        for (const specifier of node.specifiers || []) {
+          const imported = specifier.imported?.name
+          const local = specifier.local?.name
+          if (source === "./component" && imported === twin && local === twin) importsTwin = true
+          if (imported && local && REACHES_FOR_THE_WORLD.test(imported)) worldBindings.add(local)
+        }
+      },
       CallExpression(node) {
         if (node.callee?.type !== "Identifier") return
         if (node.callee.name === twin) calledTwin.push(node)
         if (worldBindings.has(node.callee.name) || REACHES_FOR_THE_WORLD.test(node.callee.name)) {
-          readsWorld = true
-        }
-      },
-      JSXOpeningElement(node) {
-        if (node.name?.type !== "JSXIdentifier") return
-        rendered.push({ name: node.name.name, node })
-        if (node.name.name === twin) rendersTwin = true
-      },
-      "Program:exit"(node) {
-        if (!readsWorld) return
-        if (!importsTwin) {
-          context.report({ node, messageId: "missing", data: { block, twin } })
-          return
-        }
+          readsWorld = true
+        }
+      },
+      JSXOpeningElement(node) {
+        if (node.name?.type !== "JSXIdentifier") return
+        rendered.push({ name: node.name.name, node })
+        if (node.name.name === twin) rendersTwin = true
+      },
+      "Program:exit"(node) {
+        if (!readsWorld) return
+        if (!importsTwin) {
+          context.report({ node, messageId: "missing", data: { block, twin } })
+          return
+        }
         for (const entry of rendered) {
-          if (entry.name !== twin) {
-            context.report({
-              node: entry.node,
-              messageId: "bypass",
-              data: { block, rendered: entry.name, twin },
-            })
-          }
+          if (entry.name !== twin) {
+            context.report({
+              node: entry.node,
+              messageId: "bypass",
+              data: { block, rendered: entry.name, twin },
+            })
+          }
         }
         for (const call of calledTwin) {
           context.report({ node: call, messageId: "called", data: { block, twin } })
         }
         if (!rendersTwin) context.report({ node, messageId: "unused", data: { block, twin } })
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "presentational-purity": presentationalPurity,
-  "connected-block-has-presentational-twin": connectedBlockHasPresentationalTwin,
-}
-
-/**
- * The level this law asks for, as the plugin's own opinion.
- *
- * Exact: it fires on a call by name, in one file by name. A repository adopting it with history
- * should expect each report to be a real move rather than a deletion - the call has to go
- * somewhere, and where it goes is the other half.
- */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "presentational-purity": presentationalPurity,
+  "connected-block-has-presentational-twin": connectedBlockHasPresentationalTwin,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Exact: it fires on a call by name, in one file by name. A repository adopting it with history
+ * should expect each report to be a real move rather than a deletion - the call has to go
+ * somewhere, and where it goes is the other half.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))