fix(require-param, check-param-names): check deeply destructured …

…parameters (fixes #569) (#630) * test: add test case * fix: destructuring false errors of require-param rule. * test: fix test case * docs: update README * refactor: resolve conflict with another rule * test: add invalid test case * docs: update README * refactor: fix to improve performence * test: add detailed case for added code * test: add nested test case * fix(`check-param-name`): fix up destructuring false errors The error mentioned in issue #569 also occurred in `check-param-name` rule. So I fixed.
gajus · Sep 7, 2020 · 428174d · 428174d
1 parent dd4a985
commit 428174d
Show file tree

Hide file tree

Showing 5 changed files with 376 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -2132,6 +2132,31 @@ function quux ({foo, bar}, baz) {
 }
 // Options: [{"checkDestructured":false}]
 // Message: Expected @param names to be "root, baz". Got "root, foo".
+
+/**
+ * Description.
+ * @param {Object} options
+ * @param {FooBar} foo
+ */
+function quux ({ foo: { bar } }) {}
+// Message: Missing @param "options.foo"
+
+/**
+ * Description.
+ * @param {Object} options
+ * @param options.foo
+ */
+function quux ({ foo: { bar } }) {}
+// Message: Missing @param "options.foo.bar"
+
+/**
+ * Description.
+ * @param {object} options Options.
+ * @param {object} options.foo A description.
+ * @param {object} options.foo.bar
+ */
+function foo({ foo: { bar: { baz } }}) {}
+// Message: Missing @param "options.foo.bar.baz"
 ````
 
 The following patterns are not considered problems:
@@ -2408,6 +2433,29 @@ class A {
   {
   }
 }
+
+/**
+ * Description.
+ * @param {Object} options Options.
+ * @param {FooBar} options.foo foo description.
+ */
+function quux ({ foo: { bar }}) {}
+
+/**
+ * Description.
+ * @param {FooBar} options
+ * @param {Object} options.foo
+ */
+function quux ({ foo: { bar } }) {}
+// Options: [{"checkTypesPattern":"FooBar"}]
+
+/**
+ * Description.
+ * @param {Object} options
+ * @param {FooBar} options.foo
+ * @param {FooBar} options.baz
+ */
+function quux ({ foo: { bar }, baz: { cfg } }) {}
 ````
 
 
@@ -11595,6 +11643,48 @@ module.exports = class GraphQL {
 	}
 })();
 // Message: Missing JSDoc @param "param" declaration.
+
+/**
+ * Description.
+ * @param {Object} options
+ * @param {Object} options.foo
+ */
+function quux ({ foo: { bar } }) {}
+// Message: Missing JSDoc @param "options.foo.bar" declaration.
+
+/**
+ * Description.
+ * @param {FooBar} options
+ * @param {FooBar} options.foo
+ */
+function quux ({ foo: { bar } }) {}
+// Options: [{"checkTypesPattern":"FooBar"}]
+// Message: Missing JSDoc @param "options.foo.bar" declaration.
+
+/**
+ * Description.
+ * @param {Object} options
+ * @param {FooBar} foo
+ */
+function quux ({ foo: { bar } }) {}
+// Message: Missing JSDoc @param "options.foo" declaration.
+
+/**
+ * Description.
+ * @param {Object} options
+ * @param options.foo
+ */
+function quux ({ foo: { bar } }) {}
+// Message: Missing JSDoc @param "options.foo.bar" declaration.
+
+/**
+ * Description.
+ * @param {object} options Options.
+ * @param {object} options.foo A description.
+ * @param {object} options.foo.bar 
+ */
+function foo({ foo: { bar: { baz } }}) {}
+// Message: Missing JSDoc @param "options.foo.bar.baz" declaration.
 ````
 
 The following patterns are not considered problems:
@@ -12169,6 +12259,21 @@ function quux ({foo: bar}) {
 module.exports = function a(b) {
   console.info(b);
 };
+
+/**
+ * Description.
+ * @param {Object} options Options.
+ * @param {FooBar} options.foo foo description.
+ */
+function quux ({ foo: { bar } }) {}
+
+/**
+ * Description.
+ * @param {FooBar} options
+ * @param {Object} options.foo
+ */
+function quux ({ foo: { bar } }) {}
+// Options: [{"checkTypesPattern":"FooBar"}]
 ````
 
 

diff --git a/src/rules/checkParamNames.js b/src/rules/checkParamNames.js
@@ -78,15 +78,29 @@ const validateParameterNames = (
       const actualNames = paramTags.map(([, paramTag]) => {
         return paramTag.name.trim();
       });
+      const actualTypes = paramTags.map(([, paramTag]) => {
+        return paramTag.type;
+      });
 
       const missingProperties = [];
+      const notCheckingNames = [];
 
       expectedNames.forEach((name, idx) => {
-        if (!actualNames.some(utils.comparePaths(name))) {
+        if (notCheckingNames.some((notCheckingName) => {
+          return name.startsWith(notCheckingName);
+        })) {
+          return;
+        }
+        const actualNameIdx = actualNames.findIndex((actualName) => {
+          return utils.comparePaths(name)(actualName);
+        });
+        if (actualNameIdx === -1) {
           if (!checkRestProperty && rests[idx]) {
             return;
           }
           missingProperties.push(name);
+        } else if (actualTypes[actualNameIdx].search(checkTypesRegex) === -1 && actualTypes[actualNameIdx] !== '') {
+          notCheckingNames.push(name);
         }
       });
 

diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
@@ -130,6 +130,7 @@ export default iterateJsdoc(({
       }
 
       const {hasRestElement, hasPropertyRest, rests, names} = functionParameterName[1];
+      const notCheckingNames = [];
       if (!enableRestElementFixer && hasRestElement) {
         return;
       }
@@ -178,6 +179,20 @@ export default iterateJsdoc(({
 
         const fullParamName = `${rootName}.${paramName}`;
 
+        const notCheckingName = jsdocParameterNames.find(({name, type: paramType}) => {
+          return utils.comparePaths(name)(fullParamName) && paramType.search(checkTypesRegex) === -1 && paramType !== '';
+        });
+
+        if (notCheckingName !== undefined) {
+          notCheckingNames.push(notCheckingName.name);
+        }
+
+        if (notCheckingNames.find((name) => {
+          return fullParamName.startsWith(name);
+        })) {
+          return;
+        }
+
         if (jsdocParameterNames && !jsdocParameterNames.find(({name}) => {
           return utils.comparePaths(name)(fullParamName);
         })) {

diff --git a/test/rules/assertions/checkParamNames.js b/test/rules/assertions/checkParamNames.js
@@ -894,6 +894,55 @@ export default {
         checkDestructured: false,
       }],
     },
+    {
+      code: `
+      /**
+       * Description.
+       * @param {Object} options
+       * @param {FooBar} foo
+       */
+      function quux ({ foo: { bar } }) {}
+      `,
+      errors: [
+        {
+          message: 'Missing @param "options.foo"',
+        },
+        {
+          message: 'Missing @param "options.foo.bar"',
+        },
+      ],
+    },
+    {
+      code: `
+      /**
+       * Description.
+       * @param {Object} options
+       * @param options.foo
+       */
+      function quux ({ foo: { bar } }) {}
+      `,
+      errors: [
+        {
+          message: 'Missing @param "options.foo.bar"',
+        },
+      ],
+    },
+    {
+      code: `
+      /**
+       * Description.
+       * @param {object} options Options.
+       * @param {object} options.foo A description.
+       * @param {object} options.foo.bar
+       */
+      function foo({ foo: { bar: { baz } }}) {}
+      `,
+      errors: [
+        {
+          message: 'Missing @param "options.foo.bar.baz"',
+        },
+      ],
+    },
   ],
   valid: [
     {
@@ -1297,5 +1346,41 @@ export default {
         sourceType: 'module',
       },
     },
+    {
+      code: `
+      /**
+       * Description.
+       * @param {Object} options Options.
+       * @param {FooBar} options.foo foo description.
+       */
+      function quux ({ foo: { bar }}) {}
+      `,
+    },
+    {
+      code: `
+      /**
+       * Description.
+       * @param {FooBar} options
+       * @param {Object} options.foo
+       */
+      function quux ({ foo: { bar } }) {}
+      `,
+      options: [
+        {
+          checkTypesPattern: 'FooBar',
+        },
+      ],
+    },
+    {
+      code: `
+      /**
+       * Description.
+       * @param {Object} options
+       * @param {FooBar} options.foo
+       * @param {FooBar} options.baz
+       */
+      function quux ({ foo: { bar }, baz: { cfg } }) {}
+      `,
+    },
   ],
 };