From c4d1b801e86da183a2d5ff2adb10ddf0a0eae756 Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Tue, 28 Jul 2020 18:11:10 +0800
Subject: [PATCH] feat(`check-param-names`): add `checkDestructured` option to
 allow disabling of destructured checking; fixes part of #616

Also improves display of errors when destructured properties are present
---
 README.md                                | 19 ++++++++++++++
 src/rules/checkParamNames.js             | 26 +++++++++++++++----
 test/rules/assertions/checkParamNames.js | 32 ++++++++++++++++++++++++
 3 files changed, 72 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 4380fcad2..c83c3086d 100644
--- a/README.md
+++ b/README.md
@@ -2103,6 +2103,16 @@ function quux() {
 }
 // Settings: {"jsdoc":{"structuredTags":{"see":{"name":false,"required":["name"]}}}}
 // Message: Cannot add "name" to `require` with the tag's `name` set to `false`
+
+/**
+ * @param root
+ * @param foo
+ */
+function quux ({foo, bar}, baz) {
+
+}
+// Options: [{"checkDestructured":false}]
+// Message: Expected @param names to be "root, baz". Got "root, foo".
 ````
 
 The following patterns are not considered problems:
@@ -2359,6 +2369,15 @@ export class Thing {
     this.foo = new C();
   }
 }
+
+/**
+ * @param foo
+ * @param root
+ */
+function quux (foo, {bar}) {
+
+}
+// Options: [{"checkDestructured":false}]
 ````
 
 
diff --git a/src/rules/checkParamNames.js b/src/rules/checkParamNames.js
index f0a9cb011..d3a1be43b 100644
--- a/src/rules/checkParamNames.js
+++ b/src/rules/checkParamNames.js
@@ -3,6 +3,7 @@ import iterateJsdoc from '../iterateJsdoc';
 const validateParameterNames = (
   targetTagName : string,
   allowExtraTrailingParamDocs: boolean,
+  checkDestructured : boolean,
   checkRestProperty : boolean,
   checkTypesRegex : RegExp,
   enableFixer: boolean,
@@ -54,6 +55,9 @@ const validateParameterNames = (
     }
 
     if (Array.isArray(functionParameterName)) {
+      if (!checkDestructured) {
+        return false;
+      }
       if (tag.type && tag.type.search(checkTypesRegex) === -1) {
         return false;
       }
@@ -123,14 +127,20 @@ const validateParameterNames = (
     }
 
     if (funcParamName !== tag.name.trim()) {
-      // Todo: This won't work for array or object child items
-      const expectedNames = functionParameterNames.join(', ');
+      // Todo: Improve for array or object child items
       const actualNames = paramTagsNonNested.map(([, {name}]) => {
         return name.trim();
+      });
+      const expectedNames = functionParameterNames.map((item, idx) => {
+        if (item?.[1]?.names) {
+          return actualNames[idx];
+        }
+
+        return item;
       }).join(', ');
 
       report(
-        `Expected @${targetTagName} names to be "${expectedNames}". Got "${actualNames}".`,
+        `Expected @${targetTagName} names to be "${expectedNames}". Got "${actualNames.join(', ')}".`,
         null,
         tag,
       );
@@ -191,6 +201,7 @@ export default iterateJsdoc(({
 }) => {
   const {
     allowExtraTrailingParamDocs,
+    checkDestructured = true,
     checkRestProperty = false,
     checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/',
     enableFixer = false,
@@ -210,6 +221,7 @@ export default iterateJsdoc(({
   const isError = validateParameterNames(
     targetTagName,
     allowExtraTrailingParamDocs,
+    checkDestructured,
     checkRestProperty,
     checkTypesRegex,
     enableFixer,
@@ -217,12 +229,13 @@ export default iterateJsdoc(({
     jsdoc, jsdocNode, utils, report,
   );
 
-  if (isError) {
+  if (isError || !checkDestructured) {
     return;
   }
 
   validateParameterNamesDeep(
-    targetTagName, allowExtraTrailingParamDocs, jsdocParameterNamesDeep,
+    targetTagName, allowExtraTrailingParamDocs,
+    jsdocParameterNamesDeep,
     jsdoc, report,
   );
 }, {
@@ -238,6 +251,9 @@ export default iterateJsdoc(({
           allowExtraTrailingParamDocs: {
             type: 'boolean',
           },
+          checkDestructured: {
+            type: 'boolean',
+          },
           checkRestProperty: {
             type: 'boolean',
           },
diff --git a/test/rules/assertions/checkParamNames.js b/test/rules/assertions/checkParamNames.js
index 159e04d0c..bca936eb1 100644
--- a/test/rules/assertions/checkParamNames.js
+++ b/test/rules/assertions/checkParamNames.js
@@ -876,6 +876,24 @@ export default {
         },
       },
     },
+    {
+      code: `
+          /**
+           * @param root
+           * @param foo
+           */
+          function quux ({foo, bar}, baz) {
+
+          }
+      `,
+      errors: [{
+        line: 4,
+        message: 'Expected @param names to be "root, baz". Got "root, foo".',
+      }],
+      options: [{
+        checkDestructured: false,
+      }],
+    },
   ],
   valid: [
     {
@@ -1247,5 +1265,19 @@ export default {
       `,
       parser: require.resolve('@typescript-eslint/parser'),
     },
+    {
+      code: `
+          /**
+           * @param foo
+           * @param root
+           */
+          function quux (foo, {bar}) {
+
+          }
+      `,
+      options: [{
+        checkDestructured: false,
+      }],
+    },
   ],
 };