@hypersolid-dev/eslint-config 4.0.0 → 6.0.0

package/dist/shared.d.ts

@@ -12,6 +12,25 @@ export declare const NUMBER_GLOBAL_RESTRICTIONS: {
     name: string;
     message: string;
 }[];
-export declare function raiseWarnings(configs: Linter.Config[]): Linter.Config[];
-export declare function scopeToCode(configs: readonly Linter.Config[]): Linter.Config[];
-export declare function reactConfigs(): Linter.Config[];
+/** `no-restricted-syntax` entries per preset; a later config replaces the options, so each preset spreads the ones before it. */
+export declare const BASE_RESTRICTED_SYNTAX: {
+    selector: string;
+    message: string;
+}[];
+export declare const REACT_RESTRICTED_SYNTAX: {
+    selector: string;
+    message: string;
+}[];
+/** `@typescript-eslint/naming-convention` entries per preset, for the same reason. Destructured names come from elsewhere (`const { user_id } = payload`). */
+export declare const NAMING_CONVENTION: ({
+    selector: string;
+    modifiers: string[];
+    format: null;
+} | {
+    selector: string;
+    format: string[];
+    modifiers?: undefined;
+})[];
+export declare const raiseWarnings: (configs: Linter.Config[]) => Linter.Config[];
+export declare const scopeToCode: (configs: readonly Linter.Config[]) => Linter.Config[];
+export declare const reactConfigs: () => Linter.Config[];

package/dist/shared.js

@@ -1,7 +1,8 @@
 import eslintReact from '@eslint-react/eslint-plugin';
+import reactDoctor from 'eslint-plugin-react-doctor';
 import reactHooks from 'eslint-plugin-react-hooks';
 import unicorn from 'eslint-plugin-unicorn';
-import hypersolid from './plugins/props-destructuring.js';
+import hypersolid from './plugins/hypersolid.js';
 export const CODE_FILES = ['**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'];
 // Tests, stories, mocks and test setup: each preset relaxes a few rules here that test doubles break by design.
 export const TEST_FILES = [
@@ -18,82 +19,208 @@ export const NUMBER_GLOBAL_RESTRICTIONS = ['isFinite', 'isNaN'].map((name) => ({
     name,
     message: `Use Number.${name}; the global coerces its argument.`,
 }));
+/** `no-restricted-syntax` entries per preset; a later config replaces the options, so each preset spreads the ones before it. */
+export const BASE_RESTRICTED_SYNTAX = [
+    {
+        selector: "CallExpression[callee.property.name='catch'] > :matches(ArrowFunctionExpression, FunctionExpression).arguments:matches([body.type='Identifier'][body.name='undefined'], [body.type='Literal'][body.value=null], [body.type='BlockStatement'][body.body.length=0], [body.type='UnaryExpression'][body.operator='void'])",
+        message: 'An empty catch hides the failure. Log it, recover from it, or drop the catch when the promise cannot reject.',
+    },
+    {
+        selector: ":matches(ExportSpecifier[local.name='default'], ImportSpecifier[imported.name='default'])",
+        message: 'Import a default as a default (`import name from "…"`), then `export { name };` if it has to be re-exported.',
+    },
+];
+export const REACT_RESTRICTED_SYNTAX = [
+    ...BASE_RESTRICTED_SYNTAX,
+    {
+        selector: 'ExpressionStatement > Literal[value=/^use no (memo|forget)$/]',
+        message: 'Leave this component in the React Compiler; opting a subtree out is a performance decision that needs a reviewed reason.',
+    },
+    {
+        selector: ":matches(JSXExpressionContainer, JSXSpreadAttribute) CallExpression[callee.type='Identifier'][callee.name=/^use([A-Z0-9]|$)/]:not(Property[key.name=/^[A-Z]/] > ArrowFunctionExpression CallExpression)",
+        message: 'Call this hook at the top of the component and pass its result: `const fade = useAnimatedStyle(…)`, then `style={fade}`.',
+    },
+    {
+        selector: "MemberExpression[object.name='React'][property.name=/^use/]",
+        message: "Import React hooks from 'react' (`import { useEffect } from 'react'`) instead of `React.use*`.",
+    },
+];
+/** `@typescript-eslint/naming-convention` entries per preset, for the same reason. Destructured names come from elsewhere (`const { user_id } = payload`). */
+export const NAMING_CONVENTION = [
+    { selector: 'variable', modifiers: ['destructured'], format: null },
+    { selector: 'variable', format: ['camelCase', 'PascalCase', 'UPPER_CASE'] },
+    { selector: 'function', format: ['camelCase', 'PascalCase'] },
+    { selector: 'typeLike', format: ['PascalCase'] },
+];
 // Every enabled rule is an error: a warning is either worth fixing or not worth reporting.
-export function raiseWarnings(configs) {
-    return configs.map((config) => {
-        if (!config.rules) {
-            return config;
+export const raiseWarnings = (configs) => configs.map((config) => {
+    if (!config.rules) {
+        return config;
+    }
+    const rules = {};
+    for (const [name, entry] of Object.entries(config.rules)) {
+        if (entry === undefined) {
+            continue;
         }
-        const rules = {};
-        for (const [name, entry] of Object.entries(config.rules)) {
-            if (entry === undefined) {
-                continue;
-            }
-            const [severity, ...ruleOptions] = Array.isArray(entry) ? entry : [entry];
-            rules[name] = severity === 'warn' || severity === 1 ? ['error', ...ruleOptions] : entry;
-        }
-        return { ...config, rules };
-    });
-}
-export function scopeToCode(configs) {
-    return configs.map((config) => ({ files: CODE_FILES, ...config }));
-}
+        const [severity, ...ruleOptions] = Array.isArray(entry) ? entry : [entry];
+        rules[name] = severity === 'warn' || severity === 1 ? ['error', ...ruleOptions] : entry;
+    }
+    return { ...config, rules };
+});
+export const scopeToCode = (configs) => configs.map((config) => ({ files: CODE_FILES, ...config }));
 // The React block shared by `react` and `react-native`.
-export function reactConfigs() {
-    return [
-        ...scopeToCode([
-            // React correctness for TypeScript projects. Bad: `this.state.count = 1`, `<li>` in a `.map()` without `key`.
-            eslintReact.configs['recommended-typescript'],
-            // The official hooks rules plus the React Compiler checks. Bad: `if (isOpen) useEffect(…)`, a missing effect dependency.
-            reactHooks.configs.flat['recommended-latest'],
-        ]),
-        {
-            name: '@hypersolid-dev/react',
-            files: CODE_FILES,
-            plugins: { '@hypersolid-dev': hypersolid, unicorn },
-            languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },
-            rules: {
-                // Off: react-hooks/exhaustive-deps reports it. Bad: `useEffect(() => log(id), [])` reported twice.
-                '@eslint-react/exhaustive-deps': 'off',
-                // Off: react-hooks/rules-of-hooks reports it. Bad: `if (isOpen) useEffect(…)` reported twice.
-                '@eslint-react/rules-of-hooks': 'off',
-                // Off: react-hooks/error-boundaries reports it. Bad: `try { return <Child /> } catch {…}` reported twice.
-                '@eslint-react/error-boundaries': 'off',
-                // Off: react-hooks/purity reports it. Bad: `const id = Math.random()` in render reported twice.
-                '@eslint-react/purity': 'off',
-                // Off: react-hooks/set-state-in-effect reports it. Bad: `useEffect(() => setCount(1))` reported twice.
-                '@eslint-react/set-state-in-effect': 'off',
-                // Off: react-hooks/set-state-in-render reports it. Bad: `setCount(1)` in the component body reported twice.
-                '@eslint-react/set-state-in-render': 'off',
-                // Off: react-hooks/static-components reports it. Bad: a component created during render reported twice.
-                '@eslint-react/static-components': 'off',
-                // Off: react-hooks/unsupported-syntax reports it. Bad: `eval(code)` in a component reported twice.
-                '@eslint-react/unsupported-syntax': 'off',
-                // Off: react-hooks/use-memo reports it. Bad: `useMemo(async () => …)` reported twice.
-                '@eslint-react/use-memo': 'off',
-                // A component defined inside another remounts on every render. Bad: `function List() { function Row() {…} return <Row />; }`.
-                '@eslint-react/no-nested-component-definitions': 'error',
-                // List items need a `key`. Bad: `items.map((item) => <Row item={item} />)`.
-                '@eslint-react/no-missing-key': 'error',
-                // Sibling keys are unique. Bad: `<Row key="a" /><Row key="a" />`.
-                '@eslint-react/no-duplicate-key': 'error',
-                // An index key breaks state when the list reorders. Bad: `items.map((item, index) => <Row key={index} />)`.
-                '@eslint-react/no-array-index-key': 'error',
-                // A new context value each render re-renders every consumer. Bad: `<Context value={{ user }}>`.
-                '@eslint-react/no-unstable-context-value': 'error',
-                // Props are readable from the component's signature; a union props type may keep `props`. Bad: `const Card = (props: Props) => <h1>{props.title}</h1>`.
-                '@hypersolid-dev/props-destructuring': 'error',
-                // A boolean reads as a claim; hook and mock names are exempt. Bad: `const visible = true` (use `isVisible`).
-                'unicorn/consistent-boolean-name': ['error', REACT_BOOLEAN_NAME_OPTIONS],
-            },
+export const reactConfigs = () => [
+    ...scopeToCode([
+        // React correctness for TypeScript projects. Bad: `this.state.count = 1`, `<li>` in a `.map()` without `key`.
+        eslintReact.configs['recommended-typescript'],
+        // The official hooks rules plus the React Compiler checks. Bad: `if (isOpen) useEffect(…)`, a missing effect dependency.
+        reactHooks.configs.flat['recommended-latest'],
+    ]),
+    {
+        name: '@hypersolid-dev/react',
+        files: CODE_FILES,
+        plugins: { '@hypersolid-dev': hypersolid, unicorn },
+        languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },
+        rules: {
+            // Off: react-hooks/exhaustive-deps reports it. Bad: `useEffect(() => log(id), [])` reported twice.
+            '@eslint-react/exhaustive-deps': 'off',
+            // Off: react-hooks/rules-of-hooks reports it. Bad: `if (isOpen) useEffect(…)` reported twice.
+            '@eslint-react/rules-of-hooks': 'off',
+            // Off: react-hooks/error-boundaries reports it. Bad: `try { return <Child /> } catch {…}` reported twice.
+            '@eslint-react/error-boundaries': 'off',
+            // Off: react-hooks/purity reports it. Bad: `const id = Math.random()` in render reported twice.
+            '@eslint-react/purity': 'off',
+            // Off: react-hooks/set-state-in-effect reports it. Bad: `useEffect(() => setCount(1))` reported twice.
+            '@eslint-react/set-state-in-effect': 'off',
+            // Off: react-hooks/set-state-in-render reports it. Bad: `setCount(1)` in the component body reported twice.
+            '@eslint-react/set-state-in-render': 'off',
+            // Off: react-hooks/static-components reports it. Bad: a component created during render reported twice.
+            '@eslint-react/static-components': 'off',
+            // Off: react-hooks/unsupported-syntax reports it. Bad: `eval(code)` in a component reported twice.
+            '@eslint-react/unsupported-syntax': 'off',
+            // Off: react-hooks/use-memo reports it. Bad: `useMemo(async () => …)` reported twice.
+            '@eslint-react/use-memo': 'off',
+            // A component defined inside another remounts on every render. Bad: `function List() { function Row() {…} return <Row />; }`.
+            '@eslint-react/no-nested-component-definitions': 'error',
+            // List items need a `key`. Bad: `items.map((item) => <Row item={item} />)`.
+            '@eslint-react/no-missing-key': 'error',
+            // Sibling keys are unique. Bad: `<Row key="a" /><Row key="a" />`.
+            '@eslint-react/no-duplicate-key': 'error',
+            // An index key breaks state when the list reorders. Bad: `items.map((item, index) => <Row key={index} />)`.
+            '@eslint-react/no-array-index-key': 'error',
+            // A new context value each render re-renders every consumer. Bad: `<Context value={{ user }}>`.
+            '@eslint-react/no-unstable-context-value': 'error',
+            // Props are readable from the component's signature; a union props type may keep `props`. Bad: `const Card = (props: Props) => <h1>{props.title}</h1>`.
+            '@hypersolid-dev/props-destructuring': 'error',
+            // A boolean reads as a claim; hook and mock names are exempt. Bad: `const visible = true` (use `isVisible`).
+            'unicorn/consistent-boolean-name': ['error', REACT_BOOLEAN_NAME_OPTIONS],
+            // Base's empty catch and default specifiers, plus compiler opt-outs, hooks inside JSX and `React.useX`. Bad: `style={useAnimatedStyle(…)}`, `React.useState(0)`.
+            'no-restricted-syntax': ['error', ...REACT_RESTRICTED_SYNTAX],
+            // Base's naming, plus: a boolean prop is a state, not a command. Bad: `type Props = { showBadge: boolean }` (use `hasBadge`).
+            '@typescript-eslint/naming-convention': [
+                'error',
+                ...NAMING_CONVENTION,
+                { selector: 'typeProperty', types: ['boolean'], format: null, custom: { regex: '^(show|display|hide)[A-Z]', match: false } },
+            ],
+            // A fragment around one child renders nothing extra. Bad: `<><Row /></>`.
+            '@eslint-react/jsx-no-useless-fragment': 'error',
+            // A literal default prop is a new object each render and breaks memoization. Bad: `({ items = [] }: Props)`.
+            '@eslint-react/no-unstable-default-props': 'error',
+            // State synced from props in an effect renders one frame stale. Bad: `useEffect(() => setFullName(first + last), [first, last])`.
+            'react-hooks/no-deriving-state-in-effects': 'error',
+            // Off: memo-dependencies and exhaustive-effect-dependencies check the same arrays with the compiler's analysis, so one missing dependency would be reported twice.
+            'react-hooks/exhaustive-deps': 'off',
+            // The compiler's dependency check for memos: missing and unused deps. Bad: `useMemo(() => a + b, [a])`.
+            'react-hooks/memo-dependencies': 'error',
+            // The same check for effects; plugin 7.1.1 ships it inert, so `environment` turns it on. Bad: `useEffect(() => log(id), [])`.
+            'react-hooks/exhaustive-effect-dependencies': ['error', { environment: { validateExhaustiveEffectDependencies: 'all' } }],
+            // `{count && <Badge />}` renders `0`, which crashes React Native outside `<Text>`. Bad: `{items.length && <List />}`.
+            '@hypersolid-dev/boolean-guard': 'error',
+            // Styled JSX built in a component body is a component without a name. Bad: `const header = <View style={s.header}>…</View>`.
+            '@hypersolid-dev/no-markup-variable': 'error',
+            // A `use*Effect` hook takes its callback first, like `useEffect`. Bad: `useFocusEffect(deps, () => …)`.
+            '@hypersolid-dev/effect-takes-callback': 'error',
+            // A `useCallback` with empty deps that captures nothing is a module-level function. Bad: `useCallback(() => track('open'), [])`.
+            '@hypersolid-dev/no-unnecessary-use-callback': 'error',
+            // A component forwards the event; the caller builds the payload. Bad: `onPress={() => onSelect(item.id)}` inside `Row`.
+            '@hypersolid-dev/no-callback-payload': 'error',
+            // A comment on a type member is JSDoc, the form editors show. Bad: `// The title\ntitle: string` in a props type.
+            '@hypersolid-dev/jsdoc-for-props': 'error',
+        },
+    },
+    {
+        /**
+         * React Doctor's bug catchers, as used in the ESPN Goal pilot; test doubles break them by design.
+         * Left out as duplicates: `no-create-ref-in-function-component` (@eslint-react/no-create-ref), and
+         * `effect-listener-cleanup-mismatch` and `effect-remove-listener-inline-handler` (@eslint-react/web-api-no-leaked-event-listener).
+         */
+        name: '@hypersolid-dev/react/react-doctor',
+        files: CODE_FILES,
+        ignores: TEST_FILES,
+        plugins: { 'react-doctor': reactDoctor },
+        rules: {
+            // A value computed from props or state is read where used, not copied into state. Bad: `const [full, setFull] = useState(first + last)` kept in sync by an effect.
+            'react-doctor/no-derived-state': 'error',
+            // A refetch from an effect double-fetches and races the cache; key the query instead. Bad: `useEffect(() => { refetch(); }, [id])`.
+            'react-doctor/query-no-query-in-effect': 'error',
+            // A write behind `useQuery` posts again on focus and mount; writes are mutations. Bad: `useQuery({ queryFn: () => api.post(…) })`.
+            'react-doctor/query-no-usequery-for-mutation': 'error',
+            // A `requestAnimationFrame` loop without a cancel keeps running after unmount. Bad: an effect that schedules `tick` with no `cancelAnimationFrame` cleanup.
+            'react-doctor/effect-raf-loop-needs-cancel': 'error',
+            // A timer ref holding a cleared id still reads as pending. Bad: `clearTimeout(timer.current)` without `timer.current = undefined`.
+            'react-doctor/no-stale-timer-ref': 'error',
+            // An effect wrapper must return the callback's cleanup. Bad: `useEffect(() => { callback(); }, deps)` in a `useMountEffect(callback)`.
+            'react-doctor/no-effect-wrapper-discards-callback-cleanup-return': 'error',
+            // A fetch in an effect races on re-run and is neither cached nor deduplicated. Bad: `useEffect(() => { fetch(url).then(setData); }, [url])`.
+            'react-doctor/no-fetch-in-effect': 'error',
+            // A toggle from a deferred callback reads a stale value; use the updater. Bad: `setTimeout(() => setOpen(!open))`.
+            'react-doctor/no-boolean-toggle-without-functional-update': 'error',
+            // Mutating state and setting it hands React the same reference, so nothing re-renders. Bad: `items.push(item); setItems(items)`.
+            'react-doctor/no-direct-state-mutation': 'error',
+            // The same mutation through an alias. Bad: `const next = state; next.done = true; setState(next)`.
+            'react-doctor/no-mutate-then-set-or-return-same-reference': 'error',
+            // `sort`, `reverse` and `splice` reorder a prop in place; use `toSorted` and friends. Bad: `props.items.sort(byName)`.
+            'react-doctor/no-mutating-array-method-on-prop-or-hook-result': 'error',
+            // React may call an updater twice, so a side effect in one runs twice. Bad: `setCount((count) => { track(count); return count + 1; })`.
+            'react-doctor/no-side-effect-in-state-updater-function': 'error',
+            // After `.fill(x)` every element is x, so every key is the same. Bad: `Array(3).fill(0).map((value) => <Dot key={value} />)`.
+            'react-doctor/no-fill-map-element-as-key': 'error',
+            // Calling a component runs its hooks as the caller's. Bad: `{Row(props)}` instead of `<Row {...props} />`.
+            'react-doctor/no-call-component-as-function': 'error',
+            // A context created in render is new each time, so consumers lose their provider. Bad: `const Theme = createContext(light)` inside a component.
+            'react-doctor/no-create-context-in-render': 'error',
+            // Render can be discarded, so calling a prop callback from it reports UI that never committed. Bad: `onReady()` in the component body.
+            'react-doctor/no-prop-callback-in-render': 'error',
+            // State plus a subscribing effect tears under concurrent rendering. Bad: `useEffect(() => store.subscribe(() => setValue(store.get())))`.
+            'react-doctor/prefer-use-sync-external-store': 'error',
+            // A hook renamed on import hides from the hooks rules, which match on the name. Bad: `import { useQuery as query } from '…'`.
+            'react-doctor/hook-import-rename-loses-use-prefix': 'error',
+            // An index read is typed `T` but is `undefined` on a short array. Bad: `items[0].title` without a length check.
+            'react-doctor/no-array-index-deref-without-bounds-or-empty-guard': 'error',
+            // Arithmetic binds tighter than `??`. Bad: `count ?? 0 + 1` (means `count ?? (0 + 1)`).
+            'react-doctor/no-nullish-coalescing-arithmetic-precedence': 'error',
+            // A whole-object parameter default is dropped as soon as any object is passed. Bad: `({ size, color } = { size: 1, color: 'red' })`.
+            'react-doctor/no-whole-object-default-losing-per-key-defaults': 'error',
+            // An explicit `undefined` prop erases the default it is spread over. Bad: `{ ...DEFAULTS, ...props }`.
+            'react-doctor/no-spread-props-over-defaults-clobbers-with-undefined': 'error',
+            // fetch resolves on a 4xx or 5xx, so parsing without checking `ok` reads the error body as data. Bad: `(await fetch(url)).json()`.
+            'react-doctor/no-fetch-response-used-without-status-check': 'error',
+            // An unescaped search term turns `.` and `(` into pattern syntax. Bad: `new RegExp(query)`.
+            'react-doctor/no-unescaped-dynamic-string-in-regexp': 'error',
         },
-        {
-            name: '@hypersolid-dev/react/tests',
-            files: TEST_FILES,
-            rules: {
-                // Off: a mocked hook keeps the `use` name of the hook it replaces. Bad: `const useUser = () => fakeUser` in a mock.
-                '@eslint-react/no-unnecessary-use-prefix': 'off',
-            },
+    },
+    {
+        name: '@hypersolid-dev/react/tests',
+        files: TEST_FILES,
+        rules: {
+            // Off: tests build markup and callbacks inline by design. Bad: `const tree = <Row />` in a test reported.
+            '@hypersolid-dev/boolean-guard': 'off',
+            '@hypersolid-dev/no-markup-variable': 'off',
+            '@hypersolid-dev/effect-takes-callback': 'off',
+            '@hypersolid-dev/no-unnecessary-use-callback': 'off',
+            '@hypersolid-dev/no-callback-payload': 'off',
+            // Off: a mocked hook keeps the `use` name of the hook it replaces. Bad: `const useUser = () => fakeUser` in a mock.
+            '@eslint-react/no-unnecessary-use-prefix': 'off',
         },
-    ];
-}
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersolid-dev/eslint-config",
-  "version": "4.0.0",
+  "version": "6.0.0",
   "description": "Shared ESLint flat config for Hypersolid TypeScript projects",
   "license": "MIT",
   "keywords": [
@@ -12,7 +12,8 @@
     "react",
     "react-native",
     "next",
-    "node"
+    "node",
+    "jest"
   ],
   "type": "module",
   "exports": {
@@ -35,6 +36,10 @@
     "./next": {
       "types": "./dist/next.d.ts",
       "default": "./dist/next.js"
+    },
+    "./jest": {
+      "types": "./dist/jest.d.ts",
+      "default": "./dist/jest.js"
     }
   },
   "files": [
@@ -75,9 +80,14 @@
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-expo": "^1.2.1",
     "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-jest": "^29.17.0",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-no-secrets": "^2.3.3",
-    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-prefer-arrow-functions": "^3.10.2",
+    "eslint-plugin-react-doctor": "0.9.22",
+    "eslint-plugin-react-hooks": "7.1.1",
+    "eslint-plugin-sonarjs": "^4.2.2",
+    "eslint-plugin-testing-library": "^7.16.2",
     "eslint-plugin-unicorn": "^79.0.0",
     "globals": "^17.13.0",
     "typescript-eslint": "^8.72.1"