[New] forward-ref-uses-ref: add rule for checking ref parameter

Author: NotWoods

CHANGELOG.md

@@ -14,6 +14,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 * version settings: Allow react defaultVersion to be configurable ([#3771][] @onlywei)
 * [`jsx-closing-tag-location`]: add `line-aligned` option ([#3777] @kimtaejin3)
 * [`no-danger`]: add `customComponentNames` option ([#3748][] @akulsr0)
+* [`forward-ref-uses-ref`]: add rule for checking ref parameter is added ([#3667][] @NotWoods)
 
 ### Changed
 * [Refactor] `variableUtil`: Avoid creating a single flat variable scope for each lookup ([#3782][] @DanielRosenwasser)
@@ -27,6 +28,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 [#3748]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3748
 [#3724]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3724
 [#3694]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3694
+[#3694]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3667
 
 ### Fixed
 * [`no-invalid-html-attribute`]: substitute placeholders in suggestion messages ([#3759][] @mdjermanovic)

README.md

@@ -301,6 +301,7 @@ module.exports = [
 | [forbid-elements](docs/rules/forbid-elements.md)                                             | Disallow certain elements                                                                                                                    |    |    |    |    |    |
 | [forbid-foreign-prop-types](docs/rules/forbid-foreign-prop-types.md)                         | Disallow using another component's propTypes                                                                                                 |    |    |    |    |    |
 | [forbid-prop-types](docs/rules/forbid-prop-types.md)                                         | Disallow certain propTypes                                                                                                                   |    |    |    |    |    |
+| [forward-ref-uses-ref](docs/rules/forward-ref-uses-ref.md)                                   | Require all forwardRef components include a ref parameter                                                                                    |    |    |    | 💡 |    |
 | [function-component-definition](docs/rules/function-component-definition.md)                 | Enforce a specific function type for function components                                                                                     |    |    | 🔧 |    |    |
 | [hook-use-state](docs/rules/hook-use-state.md)                                               | Ensure destructuring and symmetric naming of useState hook value and setter variables                                                        |    |    |    | 💡 |    |
 | [iframe-missing-sandbox](docs/rules/iframe-missing-sandbox.md)                               | Enforce sandbox attribute on iframe elements                                                                                                 |    |    |    |    |    |

docs/rules/forward-ref-uses-ref.md

@@ -0,0 +1,45 @@
+# Require all forwardRef components include a ref parameter (`react/forward-ref-uses-ref`)
+
+💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
+<!-- end auto-generated rule header -->
+
+Requires that components wrapped with `forwardRef` must have a `ref` parameter. Omitting the `ref` argument is usually a bug, and components not using `ref` don't need to be wrapped by `forwardRef`.
+
+See <https://react.dev/reference/react/forwardRef>
+
+## Rule Details
+
+This rule checks all React components using `forwardRef` and verifies that there is a second parameter.
+
+The following patterns are considered warnings:
+
+```jsx
+var React = require('react');
+
+var Component = React.forwardRef((props) => (
+    <div />
+));
+```
+
+The following patterns are **not** considered warnings:
+
+```jsx
+var React = require('react');
+
+var Component = React.forwardRef((props, ref) => (
+    <div ref={ref} />
+));
+
+var Component = React.forwardRef((props, ref) => (
+    <div />
+));
+
+var Component = (props) => (
+    <div />
+);
+```
+
+## When not to use
+
+If you don't want to enforce that components using `forwardRef` utilize the forwarded ref.

lib/rules/forward-ref-uses-ref.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Require all forwardRef components include a ref parameter
+ */
+
+'use strict';
+
+const isParenthesized = require('../util/ast').isParenthesized;
+const docsUrl = require('../util/docsUrl');
+const report = require('../util/report');
+const getMessageData = require('../util/message');
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+const messages = {
+  missingRefParameter: 'forwardRef is used with this component but no ref parameter is set',
+  addRefParameter: 'Add a ref parameter',
+  removeForwardRef: 'Remove forwardRef wrapper',
+};
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Require all forwardRef components include a ref parameter',
+      category: 'Possible Errors',
+      recommended: false,
+      url: docsUrl('forward-ref-uses-ref'),
+    },
+    messages,
+    schema: [],
+    type: 'suggestion',
+    hasSuggestions: true,
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode();
+    /**
+     * @param {ASTNode} node
+     * @returns {boolean} If the node represents the identifier `forwardRef`.
+     */
+    function isForwardRefIdentifier(node) {
+      return node.type === 'Identifier' && node.name === 'forwardRef';
+    }
+
+    /**
+     * @param {ASTNode} node
+     * @returns {boolean} If the node represents a function call `forwardRef()` or `React.forwardRef()`.
+     */
+    function isForwardRefCall(node) {
+      return (
+        node.type === 'CallExpression'
+        && (isForwardRefIdentifier(node.callee)
+          || (node.callee.type === 'MemberExpression' && isForwardRefIdentifier(node.callee.property)))
+      );
+    }
+
+    return {
+      'FunctionExpression, ArrowFunctionExpression'(node) {
+        if (!isForwardRefCall(node.parent)) {
+          return;
+        }
+
+        if (node.params.length === 1) {
+          report(context, messages.missingRefParameter, 'missingRefParameter', {
+            node,
+            suggest: [
+              Object.assign(
+                getMessageData('addRefParameter', messages.addRefParameter),
+                {
+                  fix(fixer) {
+                    const param = node.params[0];
+                    // If using shorthand arrow function syntax, add parentheses around the new parameter pair
+                    const shouldAddParentheses = node.type === 'ArrowFunctionExpression' && !isParenthesized(context, param);
+                    return [].concat(
+                      shouldAddParentheses ? fixer.insertTextBefore(param, '(') : [],
+                      fixer.insertTextAfter(param, `, ref${shouldAddParentheses ? ')' : ''}`)
+                    );
+                  },
+                }
+              ),
+              Object.assign(
+                getMessageData('removeForwardRef', messages.removeForwardRef),
+                {
+                  fix: (fixer) => fixer.replaceText(node.parent, sourceCode.getText(node)),
+                }
+              ),
+            ],
+          });
+        }
+      },
+    };
+  },
+};

lib/rules/index.js

@@ -15,6 +15,7 @@ module.exports = {
   'forbid-elements': require('./forbid-elements'),
   'forbid-foreign-prop-types': require('./forbid-foreign-prop-types'),
   'forbid-prop-types': require('./forbid-prop-types'),
+  'forward-ref-uses-ref': require('./forward-ref-uses-ref'),
   'function-component-definition': require('./function-component-definition'),
   'hook-use-state': require('./hook-use-state'),
   'iframe-missing-sandbox': require('./iframe-missing-sandbox'),