fix(check-tag-names): should have previously auto-allowed `settings…

….jsdoc.structuredTags` tags
gajus · Jan 23, 2021 · 5f586fd · 5f586fd
1 parent 3896162
commit 5f586fd
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 2 deletions.
diff --git a/.README/rules/check-tag-names.md b/.README/rules/check-tag-names.md
@@ -118,6 +118,10 @@ Because the tags indicated as replacements in
 `settings.jsdoc.tagNamePreference` will automatically be considered as valid,
 the above works.
 
+Likewise are the tag keys of `settings.jsdoc.structuredTags` automatically
+considered as valid (as their defining an expected structure for tags implies
+the tags may be used).
+
 For [TypeScript](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc)
 (or Closure), when `settings.jsdoc.mode` is set to `typescript` or `closure`,
 one may also use the following:

diff --git a/README.md b/README.md
@@ -3394,6 +3394,10 @@ Because the tags indicated as replacements in
 `settings.jsdoc.tagNamePreference` will automatically be considered as valid,
 the above works.
 
+Likewise are the tag keys of `settings.jsdoc.structuredTags` automatically
+considered as valid (as their defining an expected structure for tags implies
+the tags may be used).
+
 For [TypeScript](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc)
 (or Closure), when `settings.jsdoc.mode` is set to `typescript` or `closure`,
 one may also use the following:
@@ -3476,6 +3480,11 @@ The following patterns are considered problems:
 let a;
 // Message: Invalid JSDoc tag name "typoo".
 
+/** @typoo {string} */
+let a;
+// Settings: {"jsdoc":{"structuredTags":{"parameter":{"name":"namepath-referencing","required":["type","name"],"type":true}}}}
+// Message: Invalid JSDoc tag name "typoo".
+
 /**
  * @Param
  */
@@ -3829,6 +3838,14 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
 
+/**
+ * @parameter foo
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"structuredTags":{"parameter":{"name":"namepath-referencing","required":["type","name"],"type":true}}}}
+
 /**
  * @bar foo
  */

diff --git a/src/rules/checkTagNames.js b/src/rules/checkTagNames.js
@@ -13,7 +13,8 @@ export default iterateJsdoc(({
   const {definedTags = []} = context.options[0] || {};
 
   let definedPreferredTags = [];
-  const {tagNamePreference} = settings;
+  const {tagNamePreference, structuredTags} = settings;
+  const definedStructuredTags = Object.keys(structuredTags);
   const definedNonPreferredTags = Object.keys(tagNamePreference);
   if (definedNonPreferredTags.length) {
     definedPreferredTags = Object.values(tagNamePreference).map((preferredTag) => {
@@ -38,7 +39,10 @@ export default iterateJsdoc(({
 
   jsdoc.tags.forEach((jsdocTag) => {
     const tagName = jsdocTag.tag;
-    if (utils.isValidTag(tagName, [...definedTags, ...definedPreferredTags, ...definedNonPreferredTags])) {
+    if (utils.isValidTag(tagName, [
+      ...definedTags, ...definedPreferredTags, ...definedNonPreferredTags,
+      ...definedStructuredTags,
+    ])) {
       let preferredTagName = utils.getPreferredTagName({
         allowObjectReturn: true,
         defaultMessage: `Blacklisted tag found (\`@${tagName}\`)`,

diff --git a/test/rules/assertions/checkTagNames.js b/test/rules/assertions/checkTagNames.js
@@ -27,6 +27,29 @@ export default {
         },
       ],
     },
+    {
+      code: `
+        /** @typoo {string} */
+        let a;
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Invalid JSDoc tag name "typoo".',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          structuredTags: {
+            parameter: {
+              name: 'namepath-referencing',
+              required: ['type', 'name'],
+              type: true,
+            },
+          },
+        },
+      },
+    },
     {
       code: `
           /**
@@ -597,6 +620,27 @@ export default {
         },
       },
     },
+    {
+      code: `
+          /**
+           * @parameter foo
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          structuredTags: {
+            parameter: {
+              name: 'namepath-referencing',
+              required: ['type', 'name'],
+              type: true,
+            },
+          },
+        },
+      },
+    },
     {
       code: `
           /**