feat(check-tag-names): allow reporting of normally valid tag names (fixes gajus#108)

feat(check-tag-names): allow custom error messages when suggesting tags to replace (as with types in `check-types`)

Reporting normally valid tags may be of interest for tags like `@todo`. This is implemented by allowing the user to set targeted `tagNamePreference` tags to `false` or to an object with only a `message` and no `replacement`

Custom messages for `check-tag-names` are implemented by allowing the user to set  targeted `tagNamePreference` tags to an object with `message` and `replacement` (mirroring `preferredTypes` behavior). Note that for other rules leveraging `tagNamePreference` (via `utils.getPreferredTagName`) to find the user's preferred tag name, the `replacement` will be used in the likes of error messages but not the `message`.

Also, for various (param, return, and description-related) rules which have used `tagNamePreference` (via the `utils.getPreferredTagName` utility), report to user if they have blocked (probably inadvertently) and not indicated a replacement for the relevant tag needed by the rule in the `tagNamePreference` setting.

Author: brettz9

.README/README.md

@@ -147,6 +147,60 @@ Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a
 }
 ```
 
+One may also use an object with a `message` and `replacement`, with `{{tagName}}` and `{{preferredType}}` (or its alias `{{replacement}}`) as template variables to be
+substituted within `message`.
+
+The following will report the message `@extends is to be used over @augments as it is more evocative of classes than @augments` upon encountering `@augments`.
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "augments": {
+                  "message": "@{{replacement}} is to be used over @{{tagName}} as it is more evocative of classes than @augments",
+                  "replacement": "extends"
+                }
+            }
+        }
+    }
+}
+```
+
+If one wishes to reject a normally valid tag, e.g., `@todo`, one may set the tag to `false`:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "todo": false
+            }
+        }
+    }
+}
+```
+
+Or one may set the targeted tag to an object with a custom `message`, but without a `replacement` property:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "todo": {
+                  "message": "We expect immediate perfection, so don't leave to-dos in your code."
+                }
+            }
+        }
+    }
+}
+```
+
+
 The defaults in `eslint-plugin-jsdoc` (for tags which offer
 aliases) are as follows:
 

src/iterateJsdoc.js

@@ -25,6 +25,7 @@ const parseComment = (commentNode, indent) => {
 const getUtils = (
   node,
   jsdoc,
+  jsdocNode,
   {
     tagNamePreference,
     additionalTagNames,
@@ -37,6 +38,7 @@ const getUtils = (
     allowAugmentsExtendsWithoutParam,
     checkSeesForNamepaths
   },
+  report,
   context
 ) => {
   const ancestors = context.getAncestors();
@@ -57,15 +59,36 @@ const getUtils = (
   };
 
   utils.getJsdocParameterNamesDeep = () => {
-    return jsdocUtils.getJsdocParameterNamesDeep(jsdoc, utils.getPreferredTagName('param'));
+    const param = utils.getPreferredTagName('param');
+    if (!param) {
+      return false;
+    }
+
+    return jsdocUtils.getJsdocParameterNamesDeep(jsdoc, param);
   };
 
   utils.getJsdocParameterNames = () => {
-    return jsdocUtils.getJsdocParameterNames(jsdoc, utils.getPreferredTagName('param'));
+    const param = utils.getPreferredTagName('param');
+    if (!param) {
+      return false;
+    }
+
+    return jsdocUtils.getJsdocParameterNames(jsdoc, param);
   };
 
-  utils.getPreferredTagName = (name) => {
-    return jsdocUtils.getPreferredTagName(name, tagNamePreference);
+  utils.getPreferredTagName = (name, allowObjectReturn = false, defaultMessage = 'Unexpected tag `@{{tagName}}`') => {
+    const ret = jsdocUtils.getPreferredTagName(name, tagNamePreference);
+    const isObject = ret && typeof ret === 'object';
+    if (ret === false || isObject && !ret.replacement) {
+      const message = isObject && ret.message || defaultMessage;
+      report(message, null, utils.getTags(name)[0], {
+        tagName: name
+      });
+
+      return false;
+    }
+
+    return isObject && !allowObjectReturn ? ret.replacement : ret;
   };
 
   utils.isValidTag = (name) => {
@@ -346,17 +369,19 @@ const iterateAllJsdocs = (iterator, ruleConfig) => {
             const indent = _.repeat(' ', comment.loc.start.column);
             const jsdoc = parseComment(comment, indent);
             const settings = getSettings(context);
+            const report = makeReport(context, comment);
+            const jsdocNode = comment;
 
             iterator({
               context,
               indent,
               jsdoc,
-              jsdocNode: comment,
+              jsdocNode,
               node: null,
-              report: makeReport(context, comment),
+              report,
               settings: getSettings(context),
               sourceCode: context.getSourceCode(),
-              utils: getUtils(null, jsdoc, settings, context)
+              utils: getUtils(null, jsdoc, jsdocNode, settings, report, context)
             });
           });
         }
@@ -433,7 +458,9 @@ export default function iterateJsdoc (iterator, ruleConfig) {
         const utils = getUtils(
           node,
           jsdoc,
+          jsdocNode,
           settings,
+          report,
           context
         );
 

src/rules/checkParamNames.js

@@ -92,6 +92,9 @@ export default iterateJsdoc(({
 }) => {
   const functionParameterNames = utils.getFunctionParameterNames();
   const jsdocParameterNamesDeep = utils.getJsdocParameterNamesDeep();
+  if (!jsdocParameterNamesDeep) {
+    return;
+  }
   const targetTagName = utils.getPreferredTagName('param');
   const isError = validateParameterNames(targetTagName, functionParameterNames, jsdoc, report);
 

src/rules/checkTagNames.js

@@ -11,18 +11,34 @@ export default iterateJsdoc(({
     return;
   }
   jsdoc.tags.forEach((jsdocTag) => {
-    if (utils.isValidTag(jsdocTag.tag)) {
-      const preferredTagName = utils.getPreferredTagName(jsdocTag.tag);
+    const tagName = jsdocTag.tag;
+    if (utils.isValidTag(tagName)) {
+      let message = 'Invalid JSDoc tag (preference). Replace "{{tagName}}" JSDoc tag with "{{preferredTagName}}".';
+      let preferredTagName = utils.getPreferredTagName(
+        tagName,
+        true,
+        'Blacklisted tag found (`@{{tagName}}`)'
+      );
+      if (!preferredTagName) {
+        return;
+      }
+      if (preferredTagName && typeof preferredTagName === 'object') {
+        ({message, replacement: preferredTagName} = preferredTagName);
+      }
 
-      if (preferredTagName !== jsdocTag.tag) {
-        report('Invalid JSDoc tag (preference). Replace "' + jsdocTag.tag + '" JSDoc tag with "' + preferredTagName + '".', (fixer) => {
-          const replacement = sourceCode.getText(jsdocNode).replace('@' + jsdocTag.tag, '@' + preferredTagName);
+      if (preferredTagName !== tagName) {
+        report(message, (fixer) => {
+          const replacement = sourceCode.getText(jsdocNode).replace('@' + tagName, '@' + preferredTagName);
 
           return fixer.replaceText(jsdocNode, replacement);
-        }, jsdocTag);
+        }, jsdocTag, {
+          preferredTagName,
+          replacement: preferredTagName,
+          tagName
+        });
       }
     } else {
-      report('Invalid JSDoc tag name "' + jsdocTag.tag + '".', null, jsdocTag);
+      report('Invalid JSDoc tag name "' + tagName + '".', null, jsdocTag);
     }
   });
 }, {

src/rules/requireDescription.js

@@ -11,6 +11,9 @@ export default iterateJsdoc(({
   }
 
   const targetTagName = utils.getPreferredTagName('description');
+  if (!targetTagName) {
+    return;
+  }
 
   const functionExamples = _.filter(jsdoc.tags, {
     tag: targetTagName

src/rules/requireHyphenBeforeParamDescription.js

@@ -11,6 +11,9 @@ export default iterateJsdoc(({
   let always;
 
   const targetTagName = utils.getPreferredTagName('param');
+  if (!targetTagName) {
+    return;
+  }
 
   if (_.has(context.options, 0)) {
     always = context.options[0] === 'always';

src/rules/requireParam.js

@@ -7,6 +7,9 @@ export default iterateJsdoc(({
 }) => {
   const functionParameterNames = utils.getFunctionParameterNames();
   const jsdocParameterNames = utils.getJsdocParameterNames();
+  if (!jsdocParameterNames) {
+    return;
+  }
 
   if (utils.avoidDocs('param')) {
     return;

src/rules/requireParamDescription.js

@@ -5,6 +5,9 @@ export default iterateJsdoc(({
   utils
 }) => {
   const targetTagName = utils.getPreferredTagName('param');
+  if (!targetTagName) {
+    return;
+  }
 
   utils.forEachTag(targetTagName, (jsdocParameter) => {
     if (!jsdocParameter.description) {

src/rules/requireParamName.js

@@ -5,6 +5,9 @@ export default iterateJsdoc(({
   utils
 }) => {
   const targetTagName = utils.getPreferredTagName('param');
+  if (!targetTagName) {
+    return;
+  }
 
   utils.forEachTag(targetTagName, (jsdocParameter) => {
     if (jsdocParameter.tag && jsdocParameter.name === '') {

src/rules/requireParamType.js

@@ -5,6 +5,9 @@ export default iterateJsdoc(({
   utils
 }) => {
   const targetTagName = utils.getPreferredTagName('param');
+  if (!targetTagName) {
+    return;
+  }
 
   utils.forEachTag(targetTagName, (jsdocParameter) => {
     if (!jsdocParameter.type) {

src/rules/requireReturns.js

@@ -55,6 +55,9 @@ export default iterateJsdoc(({
   const options = context.options[0] || {};
 
   const tagName = utils.getPreferredTagName('returns');
+  if (!tagName) {
+    return;
+  }
   const tags = utils.getTags(tagName);
 
   if (tags.length > 1) {

src/rules/requireReturnsCheck.js

@@ -27,6 +27,9 @@ export default iterateJsdoc(({
   }
 
   const tagName = utils.getPreferredTagName('returns');
+  if (!tagName) {
+    return;
+  }
   const tags = utils.getTags(tagName);
 
   if (tags.length === 0) {

src/rules/requireReturnsDescription.js

@@ -5,6 +5,9 @@ export default iterateJsdoc(({
   utils
 }) => {
   const targetTagName = utils.getPreferredTagName('returns');
+  if (!targetTagName) {
+    return;
+  }
 
   utils.forEachTag(targetTagName, (jsdocTag) => {
     const type = jsdocTag.type && jsdocTag.type.trim();

src/rules/requireReturnsType.js

@@ -5,6 +5,9 @@ export default iterateJsdoc(({
   utils
 }) => {
   const targetTagName = utils.getPreferredTagName('returns');
+  if (!targetTagName) {
+    return;
+  }
 
   utils.forEachTag(targetTagName, (jsdocTag) => {
     if (!jsdocTag.type) {

test/rules/assertions/checkParamNames.js

@@ -190,6 +190,28 @@ export default {
       parserOptions: {
         sourceType: 'module'
       }
+    },
+    {
+      code: `
+          /**
+           * @param foo
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Unexpected tag `@param`'
+        }
+      ],
+      settings: {
+        jsdoc: {
+          tagNamePreference: {
+            param: false
+          }
+        }
+      }
     }
   ],
   valid: [