@codelaw/rules-react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Arpit Arya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+SPDX-License-Identifier: MIT

package/NOTICE

@@ -0,0 +1,10 @@
+@codelaw/rules-react / codelaw-rules-react
+
+data/react/dom-property-aliases.json was written for this pack: HTML attribute
+names and the React DOM prop names that replace them (`class` -> `className`),
+as React documents them. No React code is included.
+
+The rules are reimplementations written for codelaw. Their `ported_from:`
+fields name the eslint-plugin-react and eslint-plugin-react-hooks rules (MIT
+License) whose documented behaviour they reproduce; no code or documentation
+text from either is included.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @codelaw/rules-react · codelaw-rules-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+codelaw's React rules — one of codelaw's first-party rule packs
+([SR-RULE-PACKS](../../records/0101_rule-packs.md)). The
+same files ship on npm as `@codelaw/rules-react` and on PyPI as `codelaw-rules-react`.
+
+```toml
+# codelaw.toml
+extends = ["codelaw:js/recommended", "codelaw:react/recommended"]
+preview = true   # every rule is `preview` until a corpus run promotes it
+```
+
+## Presets
+
+| preset | rules | ported from |
+|---|---|---|
+| `react/recommended` | 19 | eslint-plugin-react 7.37.5 `recommended` + `jsx-runtime` (17 of its 20 active rules), and eslint-plugin-react-hooks 7.1.1's `rules-of-hooks` and `exhaustive-deps` |
+| `react/conventions` | 2 | codelaw's starter catalogue: `react/hook-prefix`, `react/props-type-name` — opt in |
+
+Every rule is **reimplemented**, not vendored: the matchers, messages and docs
+are written fresh, and each rule's `ported_from:` names the source rule.
+
+## How the ports differ
+
+Every rule matches its source's documented behaviour on the source's own
+examples. Where codelaw differs, the rule's `## Differences from the source`
+section says so. The larger ones:
+
+| rule | difference |
+|---|---|
+| `react/jsx-key` | elements returned from a `.map()` callback's block body are not checked yet |
+| `react/no-unknown-property` | renames HTML spellings (`class`, `onclick`, `tabindex`); in `.js`/`.jsx` the JavaScript grammar can't parse `class=` and `for=` |
+| `react/exhaustive-deps` | dependencies compared by root name; setters, dispatchers and refs are stable |
+| `react/rules-of-hooks` | an early `return` anywhere before a hook counts as making it conditional |
+
+## Not ported, and why
+
+| rule | why |
+|---|---|
+| `react/prop-types` | needs the component's declared prop types matched to its uses; TypeScript types do this job |
+| `react/jsx-uses-vars` | marks JSX names as used for `no-unused-vars`; codelaw's semantic model already counts them |
+| `react/react-in-jsx-scope`, `react/jsx-uses-react` | turned off by `jsx-runtime` |
+| eslint-plugin-react-hooks' 14 React Compiler rules | need the React Compiler's analysis |
+
+## Data
+
+`data/react/dom-property-aliases.json` — HTML attribute names and the React prop names that replace them, written for this pack.

package/codelaw-pack.toml

@@ -0,0 +1,6 @@
+name = "@codelaw/rules-react"
+version = "0.1.0"
+min_codelaw = "0.1.0"
+languages = ["javascript", "jsx", "typescript", "tsx"]
+presets = ["react/recommended", "react/conventions"]
+description = "codelaw's React rules, from eslint-plugin-react and eslint-plugin-react-hooks (SR-RULE-PACKS)"

package/data/react/dom-property-aliases.json

@@ -0,0 +1,131 @@
+{
+"accept-charset": "acceptCharset",
+"accesskey": "accessKey",
+"autocapitalize": "autoCapitalize",
+"autocomplete": "autoComplete",
+"autofocus": "autoFocus",
+"autoplay": "autoPlay",
+"cellpadding": "cellPadding",
+"cellspacing": "cellSpacing",
+"charset": "charSet",
+"class": "className",
+"colspan": "colSpan",
+"contenteditable": "contentEditable",
+"crossorigin": "crossOrigin",
+"datetime": "dateTime",
+"enctype": "encType",
+"enterkeyhint": "enterKeyHint",
+"fetchpriority": "fetchPriority",
+"for": "htmlFor",
+"formaction": "formAction",
+"formenctype": "formEncType",
+"formmethod": "formMethod",
+"formnovalidate": "formNoValidate",
+"formtarget": "formTarget",
+"frameborder": "frameBorder",
+"hreflang": "hrefLang",
+"http-equiv": "httpEquiv",
+"inputmode": "inputMode",
+"itemprop": "itemProp",
+"itemscope": "itemScope",
+"itemtype": "itemType",
+"marginheight": "marginHeight",
+"marginwidth": "marginWidth",
+"maxlength": "maxLength",
+"minlength": "minLength",
+"nomodule": "noModule",
+"novalidate": "noValidate",
+"onabort": "onAbort",
+"onanimationend": "onAnimationEnd",
+"onanimationiteration": "onAnimationIteration",
+"onanimationstart": "onAnimationStart",
+"onauxclick": "onAuxClick",
+"onbeforeinput": "onBeforeInput",
+"onblur": "onBlur",
+"oncancel": "onCancel",
+"oncanplay": "onCanPlay",
+"oncanplaythrough": "onCanPlayThrough",
+"onchange": "onChange",
+"onclick": "onClick",
+"onclose": "onClose",
+"oncompositionend": "onCompositionEnd",
+"oncompositionstart": "onCompositionStart",
+"oncompositionupdate": "onCompositionUpdate",
+"oncontextmenu": "onContextMenu",
+"oncopy": "onCopy",
+"oncut": "onCut",
+"ondblclick": "onDoubleClick",
+"ondrag": "onDrag",
+"ondragend": "onDragEnd",
+"ondragenter": "onDragEnter",
+"ondragleave": "onDragLeave",
+"ondragover": "onDragOver",
+"ondragstart": "onDragStart",
+"ondrop": "onDrop",
+"ondurationchange": "onDurationChange",
+"onemptied": "onEmptied",
+"onended": "onEnded",
+"onerror": "onError",
+"onfocus": "onFocus",
+"ongotpointercapture": "onGotPointerCapture",
+"oninput": "onInput",
+"oninvalid": "onInvalid",
+"onkeydown": "onKeyDown",
+"onkeypress": "onKeyPress",
+"onkeyup": "onKeyUp",
+"onload": "onLoad",
+"onloadeddata": "onLoadedData",
+"onloadedmetadata": "onLoadedMetadata",
+"onloadstart": "onLoadStart",
+"onlostpointercapture": "onLostPointerCapture",
+"onmousedown": "onMouseDown",
+"onmouseenter": "onMouseEnter",
+"onmouseleave": "onMouseLeave",
+"onmousemove": "onMouseMove",
+"onmouseout": "onMouseOut",
+"onmouseover": "onMouseOver",
+"onmouseup": "onMouseUp",
+"onpaste": "onPaste",
+"onpause": "onPause",
+"onplay": "onPlay",
+"onplaying": "onPlaying",
+"onpointercancel": "onPointerCancel",
+"onpointerdown": "onPointerDown",
+"onpointerenter": "onPointerEnter",
+"onpointerleave": "onPointerLeave",
+"onpointermove": "onPointerMove",
+"onpointerout": "onPointerOut",
+"onpointerover": "onPointerOver",
+"onpointerup": "onPointerUp",
+"onprogress": "onProgress",
+"onratechange": "onRateChange",
+"onreset": "onReset",
+"onresize": "onResize",
+"onscroll": "onScroll",
+"onseeked": "onSeeked",
+"onseeking": "onSeeking",
+"onselect": "onSelect",
+"onstalled": "onStalled",
+"onsubmit": "onSubmit",
+"onsuspend": "onSuspend",
+"ontimeupdate": "onTimeUpdate",
+"ontoggle": "onToggle",
+"ontouchcancel": "onTouchCancel",
+"ontouchend": "onTouchEnd",
+"ontouchmove": "onTouchMove",
+"ontouchstart": "onTouchStart",
+"ontransitionend": "onTransitionEnd",
+"onvolumechange": "onVolumeChange",
+"onwaiting": "onWaiting",
+"onwheel": "onWheel",
+"playsinline": "playsInline",
+"readonly": "readOnly",
+"referrerpolicy": "referrerPolicy",
+"rowspan": "rowSpan",
+"spellcheck": "spellCheck",
+"srcdoc": "srcDoc",
+"srclang": "srcLang",
+"srcset": "srcSet",
+"tabindex": "tabIndex",
+"usemap": "useMap"
+}

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@codelaw/rules-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "codelaw's React rules, from eslint-plugin-react and eslint-plugin-react-hooks (SR-RULE-PACKS)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arpitarya/codelaw.git"
+  },
+  "homepage": "https://github.com/arpitarya/codelaw",
+  "keywords": [
+    "codelaw",
+    "codelaw-pack",
+    "lint-rules"
+  ]
+}

package/presets/react/conventions.toml

@@ -0,0 +1,5 @@
+description = "House conventions from codelaw's starter catalogue; opt in"
+
+[rules]
+"react/hook-prefix" = "error"
+"react/props-type-name" = "error"

package/presets/react/recommended.toml

@@ -0,0 +1,22 @@
+description = "eslint-plugin-react 7.37.5 recommended with jsx-runtime, and eslint-plugin-react-hooks 7.1.1 rules-of-hooks and exhaustive-deps, reimplemented"
+
+[rules]
+"react/display-name" = "error"
+"react/exhaustive-deps" = "error"
+"react/jsx-key" = "error"
+"react/jsx-no-comment-textnodes" = "error"
+"react/jsx-no-duplicate-props" = "error"
+"react/jsx-no-target-blank" = "error"
+"react/jsx-no-undef" = "error"
+"react/no-children-prop" = "error"
+"react/no-danger-with-children" = "error"
+"react/no-deprecated" = "error"
+"react/no-direct-mutation-state" = "error"
+"react/no-find-dom-node" = "error"
+"react/no-is-mounted" = "error"
+"react/no-render-return-value" = "error"
+"react/no-string-refs" = "error"
+"react/no-unescaped-entities" = "error"
+"react/no-unknown-property" = "error"
+"react/require-render-return" = "error"
+"react/rules-of-hooks" = "error"

package/rules/react/display-name.md

@@ -0,0 +1,91 @@
+---
+id: react/display-name
+title: "A component passed to memo or forwardRef has a name"
+languages: [javascript, jsx, tsx]
+fix: manual
+fix_reason: "the name is the author's choice"
+stability: preview
+ported_from: [eslint-plugin-react/display-name]
+since: 0.1.0
+---
+
+A component wrapped in `memo` or `forwardRef` is a named function, so it has a display name.
+
+**Why:** An anonymous component shows up as `Anonymous` in React DevTools and in error messages,
+which makes both harder to read.
+
+```codelaw
+match:
+  any:
+    - pattern: memo($F)
+    - pattern: React.memo($F)
+    - pattern: forwardRef($F)
+    - pattern: React.forwardRef($F)
+constraints:
+  F:
+    any:
+      - kind: arrow_function
+      - kind: function_expression
+        not: { has: { field: name, pattern: $NAME } }
+message: "This component has no name, so React DevTools and error messages show it as `Anonymous`"
+```
+
+## How to fix
+
+1. Pass a named function: `memo(function Card(props) { … })`.
+2. Or set `Card.displayName = "Card"`.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+export const Card = memo((props) => <div>{props.title}</div>);
+```
+
+#### Do
+
+```js
+export const Card = memo(function Card(props) {
+  return <div>{props.title}</div>;
+});
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+export const Card = memo((props) => <div>{props.title}</div>);
+```
+
+#### Do
+
+```jsx
+export const Card = memo(function Card(props) {
+  return <div>{props.title}</div>;
+});
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+export const Card = memo((props) => <div>{props.title}</div>);
+```
+
+#### Do
+
+```tsx
+export const Card = memo(function Card(props) {
+  return <div>{props.title}</div>;
+});
+```
+
+## Differences from the source
+
+Components defined some other way (`createReactClass`, anonymous default exports) are not checked
+yet.

package/rules/react/exhaustive-deps.md

@@ -0,0 +1,116 @@
+---
+id: react/exhaustive-deps
+title: "Effect and memo dependency lists name every value they read"
+languages: [javascript, jsx, typescript, tsx]
+fix: suggest
+fix_reason: "adding a dependency can make an effect run more often"
+stability: preview
+ported_from: [eslint-plugin-react-hooks/exhaustive-deps]
+since: 0.1.0
+---
+
+The dependency list of `useEffect`, `useLayoutEffect`, `useCallback`, `useMemo` and
+`useImperativeHandle` names every prop, state value and local the callback reads, and nothing from
+outside the component.
+
+**Why:** A missing dependency makes the hook keep a stale value; an outside value in the list does
+nothing.
+
+```codelaw
+native: react/exhaustive-deps
+```
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+function Search({ query }) {
+  useEffect(() => {
+    fetchResults(query);
+  }, []);
+}
+```
+
+#### Do
+
+```js
+function Search({ query }) {
+  useEffect(() => {
+    fetchResults(query);
+  }, [query]);
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+function Search({ query }) {
+  useEffect(() => {
+    fetchResults(query);
+  }, []);
+}
+```
+
+#### Do
+
+```jsx
+function Search({ query }) {
+  useEffect(() => {
+    fetchResults(query);
+  }, [query]);
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+function Search({ query }) {
+  useEffect(() => {
+    fetchResults(query);
+  }, []);
+}
+```
+
+#### Do
+
+```ts
+function Search({ query }) {
+  useEffect(() => {
+    fetchResults(query);
+  }, [query]);
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+function Search({ query }) {
+  useEffect(() => {
+    fetchResults(query);
+  }, []);
+}
+```
+
+#### Do
+
+```tsx
+function Search({ query }) {
+  useEffect(() => {
+    fetchResults(query);
+  }, [query]);
+}
+```
+
+## Differences from the source
+
+State setters, reducer dispatchers and refs are treated as stable, as upstream does. Dependencies
+are compared by their root name (`props` covers `props.id`).

package/rules/react/hook-prefix.md

@@ -0,0 +1,108 @@
+---
+id: react/hook-prefix
+title: "Functions that call hooks are named use…"
+languages: [javascript, jsx, typescript, tsx]
+fix: manual
+fix_reason: "every caller of the function must be renamed too"
+stability: preview
+since: 0.1.0
+---
+
+A function that isn't a component (PascalCase) and calls a hook is a custom hook, and is named
+`use…`.
+
+**Why:** React and its tools recognise hooks by the `use` prefix; without it the Rules of Hooks
+can't be checked for the function's callers.
+
+```codelaw
+match:
+  kind: function_declaration
+  all:
+    - has: { field: name, regex: '^[a-z]', not: { regex: '^use[A-Z]' }, pattern: $NAME }
+    - has:
+        field: body
+        has:
+          stopBy: { any: [{ kind: function_declaration }, { kind: arrow_function }, { kind: function_expression }] }
+          kind: call_expression
+          has: { field: function, regex: '^(React\.)?use[A-Z]' }
+message: "`$NAME` calls hooks, so it is a hook: name it `use…`"
+```
+
+## How to fix
+
+1. Rename the function to start with `use` (e.g. `loadUser` → `useUser`).
+2. Rename its callers.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+function currentUser() {
+  return useContext(UserContext);
+}
+```
+
+#### Do
+
+```js
+function useCurrentUser() {
+  return useContext(UserContext);
+}
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+function currentUser() {
+  return useContext(UserContext);
+}
+```
+
+#### Do
+
+```jsx
+function useCurrentUser() {
+  return useContext(UserContext);
+}
+```
+
+### TypeScript
+
+#### Don't
+
+```ts
+function currentUser() {
+  return useContext(UserContext);
+}
+```
+
+#### Do
+
+```ts
+function useCurrentUser() {
+  return useContext(UserContext);
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+function currentUser() {
+  return useContext(UserContext);
+}
+```
+
+#### Do
+
+```tsx
+function useCurrentUser() {
+  return useContext(UserContext);
+}
+```

package/rules/react/jsx-key.md

@@ -0,0 +1,99 @@
+---
+id: react/jsx-key
+title: "Elements in an array or a map() callback have a key"
+languages: [javascript, jsx, tsx]
+fix: manual
+fix_reason: "the key must be a stable identity of the item, which only the author knows"
+stability: preview
+ported_from: [eslint-plugin-react/jsx-key]
+since: 0.1.0
+---
+
+An element written in an array literal, or returned by a `.map()` callback, has a `key` prop.
+
+**Why:** Without keys, React can't match list items between renders, which loses state and re-
+renders more than it must.
+
+```codelaw
+match:
+  any:
+    - kind: jsx_element
+    - kind: jsx_self_closing_element
+  not:
+    any:
+      - has: { stopBy: neighbor, kind: jsx_attribute, regex: '^key\b' }
+      - has: { field: open_tag, has: { stopBy: neighbor, kind: jsx_attribute, regex: '^key\b' } }
+      - has: { stopBy: neighbor, kind: jsx_expression, regex: '^\{\s*\.\.\.' }
+      - has: { field: open_tag, has: { stopBy: neighbor, kind: jsx_expression, regex: '^\{\s*\.\.\.' } }
+  inside:
+    stopBy: neighbor
+    any:
+      - kind: array
+      - kind: arrow_function
+        inside:
+          stopBy: neighbor
+          kind: arguments
+          inside: { stopBy: neighbor, kind: call_expression, has: { field: function, kind: member_expression, regex: '\.map$' } }
+      - kind: parenthesized_expression
+        inside:
+          stopBy: neighbor
+          kind: arrow_function
+          inside:
+            stopBy: neighbor
+            kind: arguments
+            inside: { stopBy: neighbor, kind: call_expression, has: { field: function, kind: member_expression, regex: '\.map$' } }
+message: "An element in a list needs a `key` so React can tell its items apart"
+```
+
+## How to fix
+
+1. Give the element a `key` that identifies the item, such as its id.
+2. Avoid the array index if items can be reordered or removed.
+
+## Examples
+
+### JavaScript
+
+#### Don't
+
+```js
+const items = todos.map((todo) => <li>{todo.text}</li>);
+```
+
+#### Do
+
+```js
+const items = todos.map((todo) => <li key={todo.id}>{todo.text}</li>);
+```
+
+### JSX
+
+#### Don't
+
+```jsx
+const items = todos.map((todo) => <li>{todo.text}</li>);
+```
+
+#### Do
+
+```jsx
+const items = todos.map((todo) => <li key={todo.id}>{todo.text}</li>);
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+const items = todos.map((todo) => <li>{todo.text}</li>);
+```
+
+#### Do
+
+```tsx
+const items = todos.map((todo) => <li key={todo.id}>{todo.text}</li>);
+```
+
+## Differences from the source
+
+Elements returned from a `.map()` callback's block body (`return <li/>`) are not checked yet.