From bc5614bdc0ee3814238b59905131fe814c93f805 Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Mon, 11 May 2020 15:16:55 +0800
Subject: [PATCH] feat(require-param): add `checkDestructured` option; fixes
 #530

---
 src/rules/requireParam.js             | 64 ++++++++++++++++-----------
 test/rules/assertions/requireParam.js | 50 +++++++++++++++++++++
 2 files changed, 87 insertions(+), 27 deletions(-)

diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
index 2cdf7fc07..c3164bab8 100644
--- a/src/rules/requireParam.js
+++ b/src/rules/requireParam.js
@@ -1,3 +1,4 @@
+import _ from 'lodash';
 import iterateJsdoc from '../iterateJsdoc';
 
 type T = [string, () => T];
@@ -47,11 +48,14 @@ export default iterateJsdoc(({
   }
 
   const {
+    autoIncrementBase = 0,
+    checkRestProperty = false,
+    checkDestructured = true,
+    checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/',
     enableFixer = true,
     enableRootFixer = true,
-    checkRestProperty = false,
     enableRestElementFixer = true,
-    checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/',
+    unnamedRootBase = ['root'],
   } = context.options[0] || {};
 
   const lastSlashPos = checkTypesPattern.lastIndexOf('/');
@@ -93,10 +97,6 @@ export default iterateJsdoc(({
     return paramTags.length;
   };
 
-  const {
-    autoIncrementBase = 0,
-    unnamedRootBase = ['root'],
-  } = context.options[0] || {};
   let [nextRootName, incremented, namer] = rootNamer([...unnamedRootBase], autoIncrementBase);
 
   functionParameterNames.forEach((functionParameterName, functionParameterIdx) => {
@@ -125,32 +125,39 @@ export default iterateJsdoc(({
       }
 
       names.forEach((paramName, idx) => {
-        if (jsdocParameterNames && !jsdocParameterNames.find(({name}) => {
+        // Add root if the root name is not in the docs (and is not already
+        //  in the tags to be fixed)
+        if (!jsdocParameterNames.find(({name}) => {
           return name === rootName;
+        }) && !missingTags.find(({functionParameterName: fpn}) => {
+          return fpn === rootName;
         })) {
-          if (!missingTags.find(({functionParameterName: fpn}) => {
-            return fpn === rootName;
-          })) {
-            const emptyParamIdx = jsdocParameterNames.findIndex(({name}) => {
-              return !name;
-            });
+          const emptyParamIdx = jsdocParameterNames.findIndex(({name}) => {
+            return !name;
+          });
 
-            if (emptyParamIdx > -1) {
-              missingTags.push({
-                functionParameterIdx: emptyParamIdx,
-                functionParameterName: rootName,
-                inc,
-                remove: true,
-              });
-            } else {
-              missingTags.push({
-                functionParameterIdx: paramIndex[rootName],
-                functionParameterName: rootName,
-                inc,
-              });
-            }
+          if (emptyParamIdx > -1) {
+            missingTags.push({
+              functionParameterIdx: emptyParamIdx,
+              functionParameterName: rootName,
+              inc,
+              remove: true,
+            });
+          } else {
+            missingTags.push({
+              functionParameterIdx: _.has(paramIndex, rootName) ?
+                paramIndex[rootName] :
+                paramIndex[paramName],
+              functionParameterName: rootName,
+              inc,
+            });
           }
         }
+
+        if (!checkDestructured) {
+          return;
+        }
+
         if (!checkRestProperty && rests[idx]) {
           return;
         }
@@ -252,6 +259,9 @@ export default iterateJsdoc(({
             default: true,
             type: 'boolean',
           },
+          checkDestructured: {
+            type: 'boolean',
+          },
           checkGetters: {
             default: false,
             type: 'boolean',
diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js
index 9ea5c846d..8725aa68c 100644
--- a/test/rules/assertions/requireParam.js
+++ b/test/rules/assertions/requireParam.js
@@ -84,6 +84,39 @@ export default {
           }
       `,
     },
+    {
+      code: `
+          /**
+           * @param foo
+           */
+          function quux (foo, bar, {baz}) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @param "bar" declaration.',
+        },
+        {
+          message: 'Missing JSDoc @param "root0" declaration.',
+        },
+      ],
+      options: [
+        {
+          checkDestructured: false,
+        },
+      ],
+      output: `
+          /**
+           * @param foo
+           * @param bar
+           * @param root0
+           */
+          function quux (foo, bar, {baz}) {
+
+          }
+      `,
+    },
     {
       code: `
           /**
@@ -2696,5 +2729,22 @@ export default {
       `,
       parser: require.resolve('@typescript-eslint/parser'),
     },
+    {
+      code: `
+          /**
+           * @param foo
+           * @param bar
+           * @param cfg
+           */
+          function quux (foo, bar, {baz}) {
+
+          }
+      `,
+      options: [
+        {
+          checkDestructured: false,
+        },
+      ],
+    },
   ],
 };