@starci/eslint-canon-fe 4.0.0 → 5.1.2

package/lists.mjs

@@ -0,0 +1,197 @@
+/**
+ * The rules that hold `lists.md` (HFS R65 `FE_SIZE_AND_STATE_BUDGET`, sub-check `FE_LIST_KEY`).
+ *
+ * A LIST IS ITEMS WITH IDENTITY. React reconciles a rendered list by `key`: the key is how it knows
+ * that the third row is still the third row after the first was deleted. With no key React falls
+ * back to position, with an index key it says position is identity, and either way a deleted row
+ * hands its state (an open menu, a half-typed input, a focus ring) to its neighbour. Nothing fails a
+ * type check and the bug appears only on the second interaction, on a real list.
+ *
+ * WHAT COUNTS AS A LIST. A `.map` callback that returns JSX. A static array written in place
+ * (`[0, 1, 2].map(...)`) or a callback that ignores its item (`(_, index) => ...`, a skeleton) has no identity to lose, so an index key there is fine.
+ *
+ * THE MEMO TAX. A component prop written as `{{ ... }}` or `[...]` inside a `.map` callback is a new
+ * object per row per render, so `memo` on the row never hits and the whole list re-renders on every
+ * keystroke of its parent. Hoist the constant, or build it once above the map.
+ */
+
+import { attribute, attributeValue, calleeName, isFunction, mentions } from "./lib/ast.mjs"
+import { isSpecFile } from "./lib/scope.mjs"
+
+/** `.map(callback)` where the callback is written inline; the call node, else null. */
+const mapCallback = (call) => {
+  if (call.type !== "CallExpression" || call.callee.type !== "MemberExpression" || call.callee.computed) return null
+  if (call.callee.property.type !== "Identifier" || call.callee.property.name !== "map") return null
+  const receiver = calleeName(call.callee.object)
+  if (receiver !== null && /(?:^|\.)Children$/.test(receiver)) return null
+  const callback = call.arguments[0]
+  return callback && isFunction(callback) ? callback : null
+}
+
+/** The JSX a callback returns: its expression body, or the value of each of its own `return` statements. */
+const returnedJsx = (callback) => {
+  const found = []
+  const take = (node) => {
+    if (!node) return
+    if (node.type === "JSXElement" || node.type === "JSXFragment") found.push(node)
+    else if (node.type === "ConditionalExpression") {
+      take(node.consequent)
+      take(node.alternate)
+    } else if (node.type === "LogicalExpression") take(node.right)
+  }
+  if (callback.body.type !== "BlockStatement") {
+    take(callback.body)
+    return found
+  }
+  const scan = (node) => {
+    if (!node || typeof node.type !== "string") return
+    if (node.type === "ReturnStatement") return take(node.argument)
+    if (node.type === "BlockStatement") node.body.forEach(scan)
+    else if (node.type === "IfStatement") {
+      scan(node.consequent)
+      scan(node.alternate)
+    } else if (node.type === "SwitchStatement") node.cases.forEach((entry) => entry.consequent.forEach(scan))
+    else if (node.type === "TryStatement") {
+      scan(node.block)
+      scan(node.handler?.body)
+    }
+  }
+  scan(callback.body)
+  return found
+}
+
+/**
+ * True when the rows have no identity to lose: the receiver is an array written in place, or the callback
+ * ignores the item (`(_, index) => ...`), which is how a skeleton or a placeholder count is rendered.
+ */
+const isPositional = (call, callback) => {
+  if (call.callee.object.type === "ArrayExpression") return true
+  const item = callback.params[0]
+  return Boolean(item) && item.type === "Identifier" && item.name.startsWith("_")
+}
+
+// -- LISTS-1 ---------------------------------------------------------------------------------------
+
+/** Every element a `.map` callback returns carries a `key`. */
+export const listItemHasKey = {
+  meta: {
+    type: "problem",
+    docs: { description: "An element returned from `.map` carries a `key`." },
+    schema: [],
+    messages: {
+      missing:
+        "This element is returned from `.map` with no `key`. React then identifies rows by position, so deleting or reordering one hands its state (an open menu, typed text, focus) to its neighbour. Give it a stable key from the data: `key={row.id}`.",
+      fragment:
+        "A `<>...</>` returned from `.map` cannot carry a key. Use `<Fragment key={...}>` (import `Fragment` from `react`) so each row has an identity.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      CallExpression(call) {
+        const callback = mapCallback(call)
+        if (!callback) return
+        for (const element of returnedJsx(callback)) {
+          if (element.type === "JSXFragment") context.report({ node: element, messageId: "fragment" })
+          else if (!attribute(element.openingElement, "key")) context.report({ node: element.openingElement, messageId: "missing" })
+        }
+      },
+    }
+  },
+}
+
+// -- LISTS-2 ---------------------------------------------------------------------------------------
+
+/** The key is never the position, and never made up on every render. */
+export const noIndexKey = {
+  meta: {
+    type: "problem",
+    docs: { description: "A list key is stable data identity, never the map index or a random value." },
+    schema: [],
+    messages: {
+      index:
+        "`key` is built from the `.map` index. The index is the row's position, not its identity: after a delete or a reorder the wrong row keeps the state. Use an id the data carries (`key={row.id}`).",
+      random:
+        "`key` is generated during render (`Math.random`, `Date.now`, `crypto.randomUUID`). A new key on every render remounts every row, throwing away its state and its DOM. Use an id the data carries.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    const source = context.sourceCode ?? context.getSourceCode()
+    return {
+      CallExpression(call) {
+        const callback = mapCallback(call)
+        if (!callback) return
+        const indexParam = callback.params[1]
+        const indexName = indexParam && indexParam.type === "Identifier" ? indexParam.name : null
+        for (const element of returnedJsx(callback)) {
+          if (element.type !== "JSXElement") continue
+          const key = attribute(element.openingElement, "key")
+          const value = attributeValue(key)
+          if (!value) continue
+          const text = source.getText(value)
+          if (/\b(?:Math\.random|Date\.now|randomUUID|nanoid|uuid)\b/.test(text)) {
+            context.report({ node: key, messageId: "random" })
+          } else if (indexName && !isPositional(call, callback) && mentions(source, value, indexName)) {
+            context.report({ node: key, messageId: "index" })
+          }
+        }
+      },
+    }
+  },
+}
+
+// -- LISTS-3 ---------------------------------------------------------------------------------------
+
+/** True for `<Component>` and `<a.B>`, false for a DOM tag: only a component can be memoised. */
+const isComponentTag = (opening) => {
+  if (opening.name.type === "JSXMemberExpression") return true
+  return opening.name.type === "JSXIdentifier" && /^[A-Z]/.test(opening.name.name)
+}
+
+/** True when the nearest function around `node` is a `.map` callback. */
+const insideMapCallback = (node) => {
+  for (let current = node.parent; current; current = current.parent) {
+    if (!isFunction(current)) continue
+    return current.parent?.type === "CallExpression" && current.parent.arguments[0] === current && mapCallback(current.parent) === current
+  }
+  return false
+}
+
+/** A component in a mapped list gets no object or array literal for a prop. */
+export const noInlineLiteralPropInList = {
+  meta: {
+    type: "problem",
+    docs: { description: "No object or array literal as a prop of a component rendered inside `.map`." },
+    schema: [],
+    messages: {
+      literal:
+        "`{{prop}}` is an object or array literal written inside `.map`: a new value per row per render, so a memoised row never hits and the whole list re-renders on every parent update. Hoist it to a constant above the component, or build it once before the map.",
+    },
+  },
+  create(context) {
+    if (isSpecFile(context.filename || context.getFilename())) return {}
+    return {
+      JSXAttribute(node) {
+        const opening = node.parent
+        if (!opening || opening.type !== "JSXOpeningElement" || !isComponentTag(opening)) return
+        if (node.name.type !== "JSXIdentifier" || node.name.name === "key") return
+        const value = attributeValue(node)
+        if (!value || (value.type !== "ObjectExpression" && value.type !== "ArrayExpression")) return
+        if (value.type === "ArrayExpression" && value.elements.length === 0) return
+        if (!insideMapCallback(node)) return
+        context.report({ node, messageId: "literal", data: { prop: node.name.name } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "list-item-has-key": listItemHasKey,
+  "no-index-key": noIndexKey,
+  "no-inline-literal-prop-in-list": noInlineLiteralPropInList,
+}
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/loading.mjs

@@ -1,164 +1,163 @@
-/**
- * The rules that hold `loading.md`.
- *
- * Three shapes of the same mistake: a second tree describing the first. A twin component, a
- * ready-made placeholder handed in as a prop, and a ternary picking between two different
- * components at a call site. Each is correct on the day it is written and wrong the first time the
- * real shape changes.
- *
- * WHY THIS NEEDS RULES AT ALL, when so much of this canon is held by types. A resting shape has no
- * assertion to fail: it is not wrong in a way a compiler or a test can see, it is wrong on screen,
- * and only for the second somebody happens to be watching. That is exactly the class of defect a
- * lint rule is for - the one nothing else will ever report.
- */
-
-/** Forward-slash form of a filename, so Windows paths compare like every other path. */
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** The component tree; a placeholder in a test fixture is a fixture, not a second tree. */
-const isComponentFile = (filename) => normalizePath(filename).includes("/src/components/")
-
-/** A twin test may build a resting shape by hand to assert against it. */
-const isTestFile = (filename) => /\.(?:test|spec)\.(?:ts|tsx)$/.test(normalizePath(filename))
-
-/** Product component source these rules govern. */
-const isGoverned = (filename) => isComponentFile(filename) && !isTestFile(filename)
-
-/** A flag that means "waiting", in the spellings this codebase uses. */
-const WAITING_FLAG = /\bis(?:Loading|Skeleton|Pending)\b/
-
-/** The name of a component whose whole job is to mirror another one's shape. */
-const TWIN_NAME = /^[A-Za-z0-9]*Skeleton$/
-
-/** JSX element name, including `Foo.Bar`. */
-const jsxElementName = (opening) => {
-  const name = opening && opening.name
-  if (!name) return null
-  if (name.type === "JSXIdentifier") return name.name
-  if (name.type === "JSXMemberExpression" && name.object && name.property) {
-    return `${name.object.name}.${name.property.name}`
-  }
-  return null
-}
-
-// -- LOADING-1 -------------------------------------------------------------------------------------
-
-/** No component exists whose job is to mirror another component's shape. */
-export const noRestingTwinComponent = {
-  meta: {
-    type: "problem",
-    docs: { description: "No component whose whole job is to mirror another one's shape." },
-    schema: [],
-    messages: {
-      twin:
-        "`{{name}}` is a hand-mirrored twin: a second description of a shape that already has one. It cannot be kept in step - it can only be noticed after it has already drifted, and a resting shape has no assertion to fail, so nothing will report the drift. Give the component it mirrors a resting state and let it rest as ITSELF.",
-    },
-  },
-  create(context) {
-    const file = normalizePath(context.filename || context.getFilename())
-    if (!isGoverned(file)) return {}
-    const hit = file.match(/\/([A-Za-z0-9]*Skeleton)\/index\.tsx?$/) || file.match(/\/([A-Za-z0-9]*Skeleton)\.tsx?$/)
-    if (!hit || !TWIN_NAME.test(hit[1])) return {}
-    return {
-      Program(node) {
-        context.report({ node, messageId: "twin", data: { name: hit[1] } })
-      },
-    }
-  },
-}
-
-// -- LOADING-1, handed in from outside --------------------------------------------------------------
-
-/** A ready-made placeholder is the same second tree, passed as a prop. */
-export const noPlaceholderProp = {
-  meta: {
-    type: "problem",
-    docs: { description: "No prop hands a component a ready-made resting shape to render." },
-    schema: [],
-    messages: {
-      prop:
-        "A resting shape handed in as markup is a second description of a tree that already has one, and it sits further from the shape it copies than a twin does - the component it describes cannot even see it. Pass the waiting flag down instead, and let each part rest as itself.",
-      import:
-        "`{{name}}` is a hand-kept resting tree imported from beside its subject. It drifts the first time the real shape changes, and nothing reports it. Thread the waiting flag down instead.",
-    },
-  },
-  create(context) {
-    if (!isGoverned(context.filename || context.getFilename())) return {}
-    return {
-      JSXAttribute(node) {
-        const name = node.name && node.name.type === "JSXIdentifier" ? node.name.name : null
-        if (name !== "skeleton" && name !== "placeholder" && name !== "fallback") return
-        const value = node.value
-        if (!value || value.type !== "JSXExpressionContainer") return
-        const expression = value.expression
-        if (expression.type === "JSXElement" || expression.type === "JSXFragment") {
-          context.report({ node, messageId: "prop" })
-        }
-      },
-      ImportDeclaration(node) {
-        const source = node.source && node.source.value
-        if (typeof source !== "string" || !/^\.\.?\//.test(source)) return
-        for (const specifier of node.specifiers || []) {
-          const local = specifier.local && specifier.local.name
-          // A bare `Skeleton` is the primitive a component rests WITH, not a twin of one.
-          if (!local || local === "Skeleton" || !TWIN_NAME.test(local)) continue
-          context.report({ node: specifier, messageId: "import", data: { name: local } })
-        }
-      },
-    }
-  },
-}
-
-// -- LOADING-2 -------------------------------------------------------------------------------------
-
-/** A caller never picks between a resting shape and a real one. */
-export const noRestingBranchAtCallSite = {
-  meta: {
-    type: "problem",
-    docs: { description: "A waiting flag must not choose between two different components." },
-    schema: [],
-    messages: {
-      branch:
-        "`{{flag}}` picks between two DIFFERENT elements, which is a resting shape written at the call site - and it drifts from the real one the first time the real one changes. Give the component below a waiting flag and pass it down; let it rest as ITSELF. The same component on both sides is the honest form: one description, two states.",
-    },
-  },
-  create(context) {
-    if (!isGoverned(context.filename || context.getFilename())) return {}
-    const source = context.sourceCode || context.getSourceCode()
-    /** Root element name of one arm, or null when the arm is not an element. */
-    const armName = (expression) => {
-      if (!expression) return null
-      if (expression.type === "JSXElement") return jsxElementName(expression.openingElement)
-      if (expression.type === "JSXFragment") return "<>"
-      return null
-    }
-    return {
-      ConditionalExpression(node) {
-        const test = source.getText(node.test)
-        if (!WAITING_FLAG.test(test)) return
-        const left = armName(node.consequent)
-        const right = armName(node.alternate)
-        // Both arms must be real elements AND differ. `null` on one side is LOADING-5 - a control
-        // that has nowhere to go yet - and that is correct rather than a second tree.
-        if (!left || !right || left === right) return
-        context.report({ node, messageId: "branch", data: { flag: test.trim().slice(0, 40) } })
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "no-resting-twin-component": noRestingTwinComponent,
-  "no-placeholder-prop": noPlaceholderProp,
-  "no-resting-branch-at-call-site": noRestingBranchAtCallSite,
-}
-
-/**
- * The level this law asks for, as the plugin's own opinion.
- *
- * A repository adopting these with history should expect the twin rule to report a folder at a
- * time: hand-kept placeholder trees arrive in families, one per screen, and each is a real shape
- * that has to be folded back into the component it copies rather than deleted.
- */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))
+/**
+ * The rules that hold `loading.md`.
+ *
+ * Three shapes of the same mistake: a second tree describing the first. A twin component, a
+ * ready-made placeholder handed in as a prop, and a ternary picking between two different
+ * components at a call site. Each is correct on the day it is written and wrong the first time the
+ * real shape changes.
+ *
+ * WHY THIS NEEDS RULES AT ALL, when so much of this canon is held by types. A resting shape has no
+ * assertion to fail: it is not wrong in a way a compiler or a test can see, it is wrong on screen,
+ * and only for the second somebody happens to be watching. That is exactly the class of defect a
+ * lint rule is for - the one nothing else will ever report.
+ */
+
+import { normalizePath } from "./lib/path.mjs"
+
+/** The component tree; a placeholder in a test fixture is a fixture, not a second tree. */
+const isComponentFile = (filename) => normalizePath(filename).includes("/src/components/")
+
+/** A twin test may build a resting shape by hand to assert against it. */
+const isTestFile = (filename) => /\.(?:test|spec)\.(?:ts|tsx)$/.test(normalizePath(filename))
+
+/** Product component source these rules govern. */
+const isGoverned = (filename) => isComponentFile(filename) && !isTestFile(filename)
+
+/** A flag that means "waiting", in the spellings this codebase uses. */
+const WAITING_FLAG = /\bis(?:Loading|Skeleton|Pending)\b/
+
+/** The name of a component whose whole job is to mirror another one's shape. */
+const TWIN_NAME = /^[A-Za-z0-9]*Skeleton$/
+
+/** JSX element name, including `Foo.Bar`. */
+const jsxElementName = (opening) => {
+  const name = opening && opening.name
+  if (!name) return null
+  if (name.type === "JSXIdentifier") return name.name
+  if (name.type === "JSXMemberExpression" && name.object && name.property) {
+    return `${name.object.name}.${name.property.name}`
+  }
+  return null
+}
+
+// -- LOADING-1 -------------------------------------------------------------------------------------
+
+/** No component exists whose job is to mirror another component's shape. */
+export const noRestingTwinComponent = {
+  meta: {
+    type: "problem",
+    docs: { description: "No component whose whole job is to mirror another one's shape." },
+    schema: [],
+    messages: {
+      twin:
+        "`{{name}}` is a hand-mirrored twin: a second description of a shape that already has one. It cannot be kept in step - it can only be noticed after it has already drifted, and a resting shape has no assertion to fail, so nothing will report the drift. Give the component it mirrors a resting state and let it rest as ITSELF.",
+    },
+  },
+  create(context) {
+    const file = normalizePath(context.filename || context.getFilename())
+    if (!isGoverned(file)) return {}
+    const hit = file.match(/\/([A-Za-z0-9]*Skeleton)\/index\.tsx?$/) || file.match(/\/([A-Za-z0-9]*Skeleton)\.tsx?$/)
+    if (!hit || !TWIN_NAME.test(hit[1])) return {}
+    return {
+      Program(node) {
+        context.report({ node, messageId: "twin", data: { name: hit[1] } })
+      },
+    }
+  },
+}
+
+// -- LOADING-1, handed in from outside --------------------------------------------------------------
+
+/** A ready-made placeholder is the same second tree, passed as a prop. */
+export const noPlaceholderProp = {
+  meta: {
+    type: "problem",
+    docs: { description: "No prop hands a component a ready-made resting shape to render." },
+    schema: [],
+    messages: {
+      prop:
+        "A resting shape handed in as markup is a second description of a tree that already has one, and it sits further from the shape it copies than a twin does - the component it describes cannot even see it. Pass the waiting flag down instead, and let each part rest as itself.",
+      import:
+        "`{{name}}` is a hand-kept resting tree imported from beside its subject. It drifts the first time the real shape changes, and nothing reports it. Thread the waiting flag down instead.",
+    },
+  },
+  create(context) {
+    if (!isGoverned(context.filename || context.getFilename())) return {}
+    return {
+      JSXAttribute(node) {
+        const name = node.name && node.name.type === "JSXIdentifier" ? node.name.name : null
+        if (name !== "skeleton" && name !== "placeholder" && name !== "fallback") return
+        const value = node.value
+        if (!value || value.type !== "JSXExpressionContainer") return
+        const expression = value.expression
+        if (expression.type === "JSXElement" || expression.type === "JSXFragment") {
+          context.report({ node, messageId: "prop" })
+        }
+      },
+      ImportDeclaration(node) {
+        const source = node.source && node.source.value
+        if (typeof source !== "string" || !/^\.\.?\//.test(source)) return
+        for (const specifier of node.specifiers || []) {
+          const local = specifier.local && specifier.local.name
+          // A bare `Skeleton` is the primitive a component rests WITH, not a twin of one.
+          if (!local || local === "Skeleton" || !TWIN_NAME.test(local)) continue
+          context.report({ node: specifier, messageId: "import", data: { name: local } })
+        }
+      },
+    }
+  },
+}
+
+// -- LOADING-2 -------------------------------------------------------------------------------------
+
+/** A caller never picks between a resting shape and a real one. */
+export const noRestingBranchAtCallSite = {
+  meta: {
+    type: "problem",
+    docs: { description: "A waiting flag must not choose between two different components." },
+    schema: [],
+    messages: {
+      branch:
+        "`{{flag}}` picks between two DIFFERENT elements, which is a resting shape written at the call site - and it drifts from the real one the first time the real one changes. Give the component below a waiting flag and pass it down; let it rest as ITSELF. The same component on both sides is the honest form: one description, two states.",
+    },
+  },
+  create(context) {
+    if (!isGoverned(context.filename || context.getFilename())) return {}
+    const source = context.sourceCode || context.getSourceCode()
+    /** Root element name of one arm, or null when the arm is not an element. */
+    const armName = (expression) => {
+      if (!expression) return null
+      if (expression.type === "JSXElement") return jsxElementName(expression.openingElement)
+      if (expression.type === "JSXFragment") return "<>"
+      return null
+    }
+    return {
+      ConditionalExpression(node) {
+        const test = source.getText(node.test)
+        if (!WAITING_FLAG.test(test)) return
+        const left = armName(node.consequent)
+        const right = armName(node.alternate)
+        // Both arms must be real elements AND differ. `null` on one side is LOADING-5 - a control
+        // that has nowhere to go yet - and that is correct rather than a second tree.
+        if (!left || !right || left === right) return
+        context.report({ node, messageId: "branch", data: { flag: test.trim().slice(0, 40) } })
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "no-resting-twin-component": noRestingTwinComponent,
+  "no-placeholder-prop": noPlaceholderProp,
+  "no-resting-branch-at-call-site": noRestingBranchAtCallSite,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * A repository adopting these with history should expect the twin rule to report a folder at a
+ * time: hand-kept placeholder trees arrive in families, one per screen, and each is a real shape
+ * that has to be folded back into the component it copies rather than deleted.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))