feat(check-tag-names): add inlineTags option with default inline tag checking

Author: brettz9

.README/rules/check-tag-names.md

@@ -192,6 +192,16 @@ tag to `false`:
 }
 ```
 
+Also checks for unknown inline tags, with the following being permitted by default
+(see the `inlineTags` option):
+
+```
+link
+linkcode
+linkplain
+tutorial
+```
+
 ## Fixer
 
 Auto-removes types that are redundant with the [`typed` option](#typed).
@@ -207,7 +217,7 @@ Auto-removes types that are redundant with the [`typed` option](#typed).
 |Context|everywhere|
 |Tags|N/A|
 |Recommended|true|
-|Options|`definedTags`, `enableFixer`, `jsxTags`, `typed`|
+|Options|`definedTags`, `enableFixer`, `inlineTags`, `jsxTags`, `typed`|
 |Settings|`tagNamePreference`, `mode`|
 
 ## Failing examples

docs/rules/check-tag-names.md

@@ -6,6 +6,7 @@
 * [Options](#user-content-check-tag-names-options)
     * [`definedTags`](#user-content-check-tag-names-options-definedtags)
     * [`enableFixer`](#user-content-check-tag-names-options-enablefixer)
+    * [`inlineTags`](#user-content-check-tag-names-options-inlinetags)
     * [`jsxTags`](#user-content-check-tag-names-options-jsxtags)
     * [`typed`](#user-content-check-tag-names-options-typed)
 * [Context and settings](#user-content-check-tag-names-context-and-settings)
@@ -203,6 +204,16 @@ tag to `false`:
 }
 ```
 
+Also checks for unknown inline tags, with the following being permitted by default
+(see the `inlineTags` option):
+
+```
+link
+linkcode
+linkplain
+tutorial
+```
+
 <a name="user-content-check-tag-names-fixer"></a>
 <a name="check-tag-names-fixer"></a>
 ## Fixer
@@ -232,6 +243,13 @@ The format is as follows:
 ### <code>enableFixer</code>
 
 Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#user-content-typed).
+<a name="user-content-check-tag-names-options-inlinetags"></a>
+<a name="check-tag-names-options-inlinetags"></a>
+### <code>inlineTags</code>
+
+List of tags to allow inline.
+
+Defaults to array of `'link', 'linkcode', 'linkplain', 'tutorial'`
 <a name="user-content-check-tag-names-options-jsxtags"></a>
 <a name="check-tag-names-options-jsxtags"></a>
 ### <code>jsxTags</code>
@@ -313,7 +331,7 @@ this
 |Context|everywhere|
 |Tags|N/A|
 |Recommended|true|
-|Options|`definedTags`, `enableFixer`, `jsxTags`, `typed`|
+|Options|`definedTags`, `enableFixer`, `inlineTags`, `jsxTags`, `typed`|
 |Settings|`tagNamePreference`, `mode`|
 
 <a name="user-content-check-tag-names-failing-examples"></a>
@@ -765,6 +783,13 @@ function quux () {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"todo":{"message":"Please don't use todo"}}}}
 // Message: Please don't use todo
+
+/**
+ * An {@inline sth} tag in the description and {@another} with a {@link}.
+ * @param {SomeType} name And an {@inlineTag} inside a tag description.
+ * @param {AnotherType} anotherName And yet {@another}
+ */
+// Message: Invalid JSDoc inline tag name "inline"
 ````
 
 
@@ -1121,5 +1146,12 @@ interface WebTwain {
  * A comment related to the module
  */
 // "jsdoc/check-tag-names": ["error"|"warn", {"typed":true}]
+
+/**
+ * An {@inline sth} tag in the description and {@another} with a {@link}.
+ * @param {SomeType} name And an {@inlineTag} inside a tag description.
+ * @param {AnotherType} anotherName And yet {@another}
+ */
+// "jsdoc/check-tag-names": ["error"|"warn", {"inlineTags":["inline","another","inlineTag","link"]}]
 ````
 

src/iterateJsdoc.js

@@ -436,6 +436,14 @@ import esquery from 'esquery';
  *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
  */
 
+/**
+ * @callback getInlineTags
+ * @returns {(import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
+ *     line?: number | undefined; column?: number | undefined;
+ *   })[]}
+ */
+
 /**
  * @callback GetTagsByType
  * @param {import('comment-parser').Spec[]} tags
@@ -533,6 +541,7 @@ import esquery from 'esquery';
  *   getPresentTags: GetPresentTags,
  *   filterTags: FilterTags,
  *   filterAllTags: FilterAllTags,
+ *   getInlineTags: getInlineTags,
  *   getTagsByType: GetTagsByType,
  *   hasOptionTag: HasOptionTag,
  *   getClassNode: GetClassNode,
@@ -1641,6 +1650,10 @@ const getUtils = (
     });
   };
 
+  utils.getInlineTags = () => {
+    return jsdocUtils.getInlineTags(jsdoc);
+  };
+
   /** @type {GetTagsByType} */
   utils.getTagsByType = (tags) => {
     return jsdocUtils.getTagsByType(context, mode, tags);

src/jsdocUtils.js

@@ -836,14 +836,15 @@ const forEachPreferredTag = (
 };
 
 /**
- * Get all tags, inline tags and inline tags in tags
+ * Get all inline tags and inline tags in tags
  * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @returns {(import('comment-parser').Spec|
- *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
+ *     line?: number | undefined; column?: number | undefined;
+ *   })[]}
  */
-const getAllTags = (jsdoc) => {
+const getInlineTags = (jsdoc) => {
   return [
-    ...jsdoc.tags,
     ...jsdoc.inlineTags.map((inlineTag) => {
       // Tags don't have source or line numbers, so add before returning
       let line = -1;
@@ -863,18 +864,6 @@ const getAllTags = (jsdoc) => {
       return inlineTag;
     }),
     ...jsdoc.tags.flatMap((tag) => {
-      let tagBegins = -1;
-      for (const {
-        tokens: {
-          tag: tg,
-        },
-      } of jsdoc.source) {
-        tagBegins++;
-        if (tg) {
-          break;
-        }
-      }
-
       for (const inlineTag of tag.inlineTags) {
         /** @type {import('./iterateJsdoc.js').Integer} */
         let line = 0;
@@ -890,7 +879,7 @@ const getAllTags = (jsdoc) => {
           }
         }
 
-        inlineTag.line = tagBegins + line - 1;
+        inlineTag.line = line;
       }
 
       return (
@@ -906,6 +895,21 @@ const getAllTags = (jsdoc) => {
   ];
 };
 
+/**
+ * Get all tags, inline tags and inline tags in tags
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+ * @returns {(import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
+ *     line?: number | undefined; column?: number | undefined;
+ *   })[]}
+ */
+const getAllTags = (jsdoc) => {
+  return [
+    ...jsdoc.tags,
+    ...getInlineTags(jsdoc),
+  ];
+};
+
 /**
  * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {string[]} targetTagNames
@@ -1853,6 +1857,7 @@ export {
   getContextObject,
   getFunctionParameterNames,
   getIndent,
+  getInlineTags,
   getJsdocTagsDeep,
   getPreferredTagName,
   getPreferredTagNameSimple,

src/rules.d.ts

@@ -261,6 +261,12 @@ export interface Rules {
            * Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#typed).
            */
           enableFixer?: boolean;
+          /**
+           * List of tags to allow inline.
+           *
+           * Defaults to array of `'link', 'linkcode', 'linkplain', 'tutorial'`
+           */
+          inlineTags?: string[];
           /**
            * If this is set to `true`, all of the following tags used to control JSX output are allowed:
            *

src/rules/checkTagNames.js

@@ -75,11 +75,15 @@ export default iterateJsdoc(({
      * @type {{
      *   definedTags: string[],
      *   enableFixer: boolean,
+     *   inlineTags: string[],
      *   jsxTags: boolean,
      *   typed: boolean
      }} */ {
       definedTags = [],
       enableFixer = true,
+      inlineTags = [
+        'link', 'linkcode', 'linkplain', 'tutorial',
+      ],
       jsxTags,
       typed,
     } = context.options[0] || {};
@@ -278,6 +282,12 @@ export default iterateJsdoc(({
       report(`Invalid JSDoc tag name "${tagName}".`, null, jsdocTag);
     }
   }
+
+  for (const inlineTag of utils.getInlineTags()) {
+    if (!inlineTags.includes(inlineTag.tag)) {
+      report(`Invalid JSDoc inline tag name "${inlineTag.tag}"`, null, inlineTag);
+    }
+  }
 }, {
   iterateAllJsdocs: true,
   meta: {
@@ -308,6 +318,15 @@ The format is as follows:
             description: 'Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#typed).',
             type: 'boolean',
           },
+          inlineTags: {
+            description: `List of tags to allow inline.
+
+Defaults to array of \`'link', 'linkcode', 'linkplain', 'tutorial'\``,
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
           jsxTags: {
             description: `If this is set to \`true\`, all of the following tags used to control JSX output are allowed:
 

test/rules/assertions/checkTagNames.js

@@ -1029,6 +1029,33 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       },
     },
+    {
+      code: `
+        /**
+         * An {@inline sth} tag in the description and {@another} with a {@link}.
+         * @param {SomeType} name And an {@inlineTag} inside a tag description.
+         * @param {AnotherType} anotherName And yet {@another}
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Invalid JSDoc inline tag name "inline"',
+        },
+        {
+          line: 3,
+          message: 'Invalid JSDoc inline tag name "another"',
+        },
+        {
+          line: 4,
+          message: 'Invalid JSDoc inline tag name "inlineTag"',
+        },
+        {
+          line: 5,
+          message: 'Invalid JSDoc inline tag name "another"',
+        },
+      ],
+    },
   ],
   valid: [
     {
@@ -1453,5 +1480,24 @@ export default /** @type {import('../index.js').TestCases} */ ({
         },
       ],
     },
+    {
+      code: `
+        /**
+         * An {@inline sth} tag in the description and {@another} with a {@link}.
+         * @param {SomeType} name And an {@inlineTag} inside a tag description.
+         * @param {AnotherType} anotherName And yet {@another}
+         */
+      `,
+      options: [
+        {
+          inlineTags: [
+            'inline',
+            'another',
+            'inlineTag',
+            'link',
+          ],
+        },
+      ],
+    },
   ],
 });