eslint-plugin-jsdoc 50.6.16 → 50.7.0

package/src/getDefaultTagStructureForMode.js

@@ -152,14 +152,14 @@ const getDefaultTagStructureForMode = (mode) => {
 
     [
       'class', new Map(/** @type {[string, string|boolean][]} */ ([
-        // Allows for "name"'s in signature, but indicated as optional
+        // Not in use, but should be this value if using to power `empty-tags`
         [
-          'namepathRole', 'namepath-defining',
+          'nameAllowed', true,
         ],
 
-        // Not in use, but should be this value if using to power `empty-tags`
+        // Allows for "name"'s in signature, but indicated as optional
         [
-          'nameAllowed', true,
+          'namepathRole', 'namepath-defining',
         ],
 
         [
@@ -258,17 +258,17 @@ const getDefaultTagStructureForMode = (mode) => {
 
     [
       'event', new Map(/** @type {[string, string|boolean][]} */ ([
-        // The doc signature of `event` seems to require a "name"
-        [
-          'nameRequired', true,
-        ],
-
         // Appears to require a "name" in its signature, albeit somewhat
         //  different from other "name"'s (including as described
         //  at https://jsdoc.app/about-namepaths.html )
         [
           'namepathRole', 'namepath-defining',
         ],
+
+        // The doc signature of `event` seems to require a "name"
+        [
+          'nameRequired', true,
+        ],
       ])),
     ],
 
@@ -313,13 +313,13 @@ const getDefaultTagStructureForMode = (mode) => {
           'namepathRole', 'namepath-referencing',
         ],
 
-        // Does not show curly brackets in either the signature or examples
         [
-          'typeAllowed', isTypescriptOrClosure || isPermissive,
+          'nameRequired', isJsdoc,
         ],
 
+        // Does not show curly brackets in either the signature or examples
         [
-          'nameRequired', isJsdoc,
+          'typeAllowed', isTypescriptOrClosure || isPermissive,
         ],
 
         // "namepath"
@@ -367,6 +367,14 @@ const getDefaultTagStructureForMode = (mode) => {
       ])),
     ],
 
+    [
+      'func', new Map(/** @type {[string, string|boolean][]} */ ([
+        // Allows for "name"'s in signature, but indicated as optional
+        [
+          'namepathRole', 'namepath-defining',
+        ],
+      ])),
+    ],
     [
       'function', new Map(/** @type {[string, string|boolean][]} */ ([
         // Allows for "name"'s in signature, but indicated as optional
@@ -383,14 +391,6 @@ const getDefaultTagStructureForMode = (mode) => {
         ],
       ])),
     ],
-    [
-      'func', new Map(/** @type {[string, string|boolean][]} */ ([
-        // Allows for "name"'s in signature, but indicated as optional
-        [
-          'namepathRole', 'namepath-defining',
-        ],
-      ])),
-    ],
 
     [
       'host', new Map(/** @type {[string, string|boolean][]} */ ([
@@ -413,18 +413,28 @@ const getDefaultTagStructureForMode = (mode) => {
     ],
 
     [
-      'interface', new Map(/** @type {[string, string|boolean][]} */ ([
-        // Allows for "name" in signature, but indicates as optional
+      'implements', new Map(/** @type {[string, string|boolean][]} */ ([
+        // Shows curly brackets in the doc signature and examples
+        // "typeExpression"
         [
-          'namepathRole',
-          isJsdocTypescriptOrPermissive ? 'namepath-defining' : false,
+          'typeRequired', true,
         ],
+      ])),
+    ],
 
+    [
+      'interface', new Map(/** @type {[string, string|boolean][]} */ ([
         // Not in use, but should be this value if using to power `empty-tags`
         [
           'nameAllowed', isClosure,
         ],
 
+        // Allows for "name" in signature, but indicates as optional
+        [
+          'namepathRole',
+          isJsdocTypescriptOrPermissive ? 'namepath-defining' : false,
+        ],
+
         [
           'typeAllowed', false,
         ],
@@ -433,23 +443,13 @@ const getDefaultTagStructureForMode = (mode) => {
 
     [
       'internal', new Map(/** @type {[string, string|boolean][]} */ ([
-        // https://www.typescriptlang.org/tsconfig/#stripInternal
-        [
-          'namepathRole', false,
-        ],
         // Not in use, but should be this value if using to power `empty-tags`
         [
           'nameAllowed', false,
         ],
-      ])),
-    ],
-
-    [
-      'implements', new Map(/** @type {[string, string|boolean][]} */ ([
-        // Shows curly brackets in the doc signature and examples
-        // "typeExpression"
+        // https://www.typescriptlang.org/tsconfig/#stripInternal
         [
-          'typeRequired', true,
+          'namepathRole', false,
         ],
       ])),
     ],
@@ -531,7 +531,7 @@ const getDefaultTagStructureForMode = (mode) => {
     ],
 
     [
-      'memberof', new Map(/** @type {[string, string|boolean][]} */ ([
+      'memberof!', new Map(/** @type {[string, string|boolean][]} */ ([
         // Signature seems to require a "namepath" (and no counter-examples),
         //  though it allows an incomplete namepath ending with connecting symbol
         [
@@ -545,7 +545,7 @@ const getDefaultTagStructureForMode = (mode) => {
       ])),
     ],
     [
-      'memberof!', new Map(/** @type {[string, string|boolean][]} */ ([
+      'memberof', new Map(/** @type {[string, string|boolean][]} */ ([
         // Signature seems to require a "namepath" (and no counter-examples),
         //  though it allows an incomplete namepath ending with connecting symbol
         [
@@ -777,7 +777,7 @@ const getDefaultTagStructureForMode = (mode) => {
     ],
 
     [
-      'returns', new Map(/** @type {[string, string|boolean][]} */ ([
+      'return', new Map(/** @type {[string, string|boolean][]} */ ([
         // Shows curly brackets in the signature and in the examples
         [
           'typeAllowed', true,
@@ -785,7 +785,7 @@ const getDefaultTagStructureForMode = (mode) => {
       ])),
     ],
     [
-      'return', new Map(/** @type {[string, string|boolean][]} */ ([
+      'returns', new Map(/** @type {[string, string|boolean][]} */ ([
         // Shows curly brackets in the signature and in the examples
         [
           'typeAllowed', true,
@@ -859,13 +859,13 @@ const getDefaultTagStructureForMode = (mode) => {
           'namepathRole', isJsdoc ? 'namepath-referencing' : false,
         ],
 
+        // namepath
         [
-          'typeRequired', isTypescriptOrClosure,
+          'typeOrNameRequired', isJsdoc,
         ],
 
-        // namepath
         [
-          'typeOrNameRequired', isJsdoc,
+          'typeRequired', isTypescriptOrClosure,
         ],
       ])),
     ],
@@ -948,7 +948,7 @@ const getDefaultTagStructureForMode = (mode) => {
     ],
 
     [
-      'yields', new Map(/** @type {[string, string|boolean][]} */ ([
+      'yield', new Map(/** @type {[string, string|boolean][]} */ ([
         // Shows curly brackets in the signature and in the examples
         [
           'typeAllowed', true,
@@ -956,7 +956,7 @@ const getDefaultTagStructureForMode = (mode) => {
       ])),
     ],
     [
-      'yield', new Map(/** @type {[string, string|boolean][]} */ ([
+      'yields', new Map(/** @type {[string, string|boolean][]} */ ([
         // Shows curly brackets in the signature and in the examples
         [
           'typeAllowed', true,

package/src/getJsdocProcessorPlugin.js

@@ -1,25 +1,32 @@
-// Todo: Support TS by fenced block type
-
-import {readFileSync} from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import * as espree from 'espree';
 import {
-  getRegexFromString,
   forEachPreferredTag,
-  getTagDescription,
   getPreferredTagName,
+  getRegexFromString,
+  getTagDescription,
   hasTag,
 } from './jsdocUtils.js';
 import {
   parseComment,
 } from '@es-joy/jsdoccomment';
+import * as espree from 'espree';
+import {
+  readFileSync,
+} from 'node:fs';
+import {
+  dirname as getDirname,
+  join,
+} from 'node:path';
+import {
+  fileURLToPath,
+} from 'node:url';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+const dirname = getDirname(fileURLToPath(import.meta.url));
 
-const {version} = JSON.parse(
+const {
+  version,
+} = JSON.parse(
   // @ts-expect-error `Buffer` is ok for `JSON.parse`
-  readFileSync(join(__dirname, '../package.json'))
+  readFileSync(join(dirname, '../package.json')),
 );
 
 // const zeroBasedLineIndexAdjust = -1;
@@ -51,20 +58,20 @@ const countChars = (str, ch) => {
 /**
  * @param {string} text
  * @returns {[
-*   import('./iterateJsdoc.js').Integer,
-*   import('./iterateJsdoc.js').Integer
-* ]}
-*/
+ *   import('./iterateJsdoc.js').Integer,
+ *   import('./iterateJsdoc.js').Integer
+ * ]}
+ */
 const getLinesCols = (text) => {
- const matchLines = countChars(text, '\n');
+  const matchLines = countChars(text, '\n');
 
- const colDelta = matchLines ?
-   text.slice(text.lastIndexOf('\n') + 1).length :
-   text.length;
+  const colDelta = matchLines ?
+    text.slice(text.lastIndexOf('\n') + 1).length :
+    text.length;
 
- return [
-   matchLines, colDelta,
- ];
+  return [
+    matchLines, colDelta,
+  ];
 };
 
 /**
@@ -73,20 +80,21 @@ const getLinesCols = (text) => {
 
 /**
  * @typedef {object} JsdocProcessorOptions
- * @property {boolean} [captionRequired]
- * @property {Integer} [paddedIndent]
- * @property {boolean} [checkDefaults]
- * @property {boolean} [checkParams]
- * @property {boolean} [checkExamples]
- * @property {boolean} [checkProperties]
- * @property {string} [matchingFileName]
- * @property {string} [matchingFileNameDefaults]
- * @property {string} [matchingFileNameParams]
- * @property {string} [matchingFileNameProperties]
- * @property {string} [exampleCodeRegex]
- * @property {string} [rejectExampleCodeRegex]
- * @property {"script"|"module"} [sourceType]
- * @property {import('eslint').Linter.ESTreeParser|import('eslint').Linter.NonESTreeParser} [parser]
+ * @property {boolean} [captionRequired] Require captions for example tags
+ * @property {Integer} [paddedIndent] See docs
+ * @property {boolean} [checkDefaults] See docs
+ * @property {boolean} [checkParams] See docs
+ * @property {boolean} [checkExamples] See docs
+ * @property {boolean} [checkProperties] See docs
+ * @property {string} [matchingFileName] See docs
+ * @property {string} [matchingFileNameDefaults] See docs
+ * @property {string} [matchingFileNameParams] See docs
+ * @property {string} [matchingFileNameProperties] See docs
+ * @property {string} [exampleCodeRegex] See docs
+ * @property {string} [rejectExampleCodeRegex] See docs
+ * @property {string[]} [allowedLanguagesToProcess] See docs
+ * @property {"script"|"module"} [sourceType] See docs
+ * @property {import('eslint').Linter.ESTreeParser|import('eslint').Linter.NonESTreeParser} [parser] See docs
  */
 
 /**
@@ -96,20 +104,23 @@ const getLinesCols = (text) => {
  */
 export const getJsdocProcessorPlugin = (options = {}) => {
   const {
-    exampleCodeRegex = null,
-    rejectExampleCodeRegex = null,
-    checkExamples = true,
+    allowedLanguagesToProcess = [
+      'js', 'ts', 'javascript', 'typescript',
+    ],
+    captionRequired = false,
     checkDefaults = false,
+    checkExamples = true,
     checkParams = false,
     checkProperties = false,
+    exampleCodeRegex = null,
     matchingFileName = null,
     matchingFileNameDefaults = null,
     matchingFileNameParams = null,
     matchingFileNameProperties = null,
     paddedIndent = 0,
-    captionRequired = false,
+    parser = undefined,
+    rejectExampleCodeRegex = null,
     sourceType = 'module',
-    parser = undefined
   } = options;
 
   /** @type {RegExp} */
@@ -178,18 +189,18 @@ export const getJsdocProcessorPlugin = (options = {}) => {
      * }} cfg
      */
     const checkSource = ({
-      filename,
-      ext,
+      cols = 0,
       defaultFileName,
+      ext,
+      filename,
       lines = 0,
-      cols = 0,
       skipInit,
       source,
-      targetTagName,
       sources = [],
       tag = {
         line: 0,
       },
+      targetTagName,
     }) => {
       if (!skipInit) {
         sources.push({
@@ -231,16 +242,16 @@ export const getJsdocProcessorPlugin = (options = {}) => {
         const codeStartCol = likelyNestedJSDocIndentSpace;
 
         textsAndFileNames.push({
-          text: src,
           filename: file,
+          text: src,
         });
         otherInfo.push({
-          targetTagName,
-          ext,
-          codeStartLine,
           codeStartCol,
+          codeStartLine,
+          commentLineCols,
+          ext,
           nonJSPrefacingCols,
-          commentLineCols
+          targetTagName,
         });
       };
 
@@ -272,8 +283,8 @@ export const getJsdocProcessorPlugin = (options = {}) => {
       }
 
       return {
-        ext,
         defaultFileName,
+        ext,
         filename,
       };
     };
@@ -342,11 +353,11 @@ export const getJsdocProcessorPlugin = (options = {}) => {
 
       if (captionRequired && (!match || !match[1].trim())) {
         extraMessages.push({
-          line: 1 + commentLineCols[0] + (tag.line ?? tag.source[0].number),
           column: commentLineCols[1] + 1,
-          severity: 2,
+          line: 1 + commentLineCols[0] + (tag.line ?? tag.source[0].number),
           message: `@${targetTagName} error - Caption is expected for examples.`,
-          ruleId: 'jsdoc/example-missing-caption'
+          ruleId: 'jsdoc/example-missing-caption',
+          severity: 2,
         });
         return;
       }
@@ -365,6 +376,16 @@ export const getJsdocProcessorPlugin = (options = {}) => {
         return;
       }
 
+      // If `allowedLanguagesToProcess` is falsy, all languages should be processed.
+      if (allowedLanguagesToProcess) {
+        const matches = (/^\s*```(?<language>\S+)([\s\S]*)```\s*$/u).exec(source);
+        if (matches?.groups && !allowedLanguagesToProcess.includes(
+          matches.groups.language.toLowerCase(),
+        )) {
+          return;
+        }
+      }
+
       const sources = [];
       let skipInit = false;
       if (exampleCodeRegex) {
@@ -378,9 +399,9 @@ export const getJsdocProcessorPlugin = (options = {}) => {
         exampleCodeRegExp.lastIndex = 0;
         while ((exampleCode = exampleCodeRegExp.exec(source)) !== null) {
           const {
-            index,
             '0': n0,
             '1': n1,
+            index,
           } = exampleCode;
 
           // Count anything preceding user regex match (can affect line numbering)
@@ -475,6 +496,76 @@ export const getJsdocProcessorPlugin = (options = {}) => {
           name: 'eslint-plugin-jsdoc/preprocessor',
           version,
         },
+        /**
+         * @param {import('eslint').Linter.LintMessage[][]} messages
+         * @param {string} filename
+         */
+        postprocess ([
+          jsMessages,
+          ...messages
+        // eslint-disable-next-line no-unused-vars -- Placeholder
+        ], filename) {
+          for (const [
+            idx,
+            message,
+          ] of messages.entries()) {
+            const {
+              codeStartCol,
+              codeStartLine,
+              commentLineCols,
+              nonJSPrefacingCols,
+              targetTagName,
+            } = otherInfo[idx];
+
+            for (const msg of message) {
+              const {
+                column,
+                endColumn,
+                endLine,
+                fatal,
+                line,
+                message: messageText,
+                ruleId,
+                severity,
+
+                // Todo: Make fixable
+                // fix
+                // fix: {range: [number, number], text: string}
+                // suggestions: {desc: , messageId:, fix: }[],
+              } = msg;
+
+              const [
+                codeCtxLine,
+                codeCtxColumn,
+              ] = commentLineCols;
+              const startLine = codeCtxLine + codeStartLine + line;
+
+              // Seems to need one more now
+              const startCol = 1 +
+                codeCtxColumn + codeStartCol + (
+              // This might not work for line 0, but line 0 is unlikely for examples
+                line <= 1 ? nonJSPrefacingCols + firstLinePrefixLength : preTagSpaceLength
+              ) + column;
+
+              msg.message = '@' + targetTagName + ' ' + (severity === 2 ? 'error' : 'warning') +
+                (ruleId ? ' (' + ruleId + ')' : '') + ': ' +
+                (fatal ? 'Fatal: ' : '') +
+                messageText;
+              msg.line = startLine;
+              msg.column = startCol;
+              msg.endLine = endLine ? startLine + endLine : startLine;
+              // added `- column` to offset what `endColumn` already seemed to include
+              msg.endColumn = endColumn ? startCol - column + endColumn : startCol;
+            }
+          }
+
+          const ret = [
+            ...jsMessages,
+          ].concat(...messages, ...extraMessages);
+          extraMessages = [];
+          return ret;
+        },
+
         /**
          * @param {string} text
          * @param {string} filename
@@ -485,20 +576,22 @@ export const getJsdocProcessorPlugin = (options = {}) => {
 
             // May be running a second time so catch and ignore
             try {
-              ast = parser
+              ast = parser ?
                 // @ts-expect-error Should be present
-                ? parser.parseForESLint(text, {
+                parser.parseForESLint(text, {
+                  comment: true,
                   ecmaVersion: 'latest',
                   sourceType,
-                  comment: true
-                }).ast
-                : espree.parse(text, {
+                }).ast :
+                espree.parse(text, {
+                  comment: true,
                   ecmaVersion: 'latest',
                   sourceType,
-                  comment: true
                 });
-            } catch (err) {
-              return [text];
+            } catch {
+              return [
+                text,
+              ];
             }
 
             /** @type {[number, number][]} */
@@ -513,18 +606,25 @@ export const getJsdocProcessorPlugin = (options = {}) => {
             ).filter((comment) => {
               return (/^\*\s/u).test(comment.value);
             }).map((comment) => {
-              /* c8 ignore next -- Unsupporting processors only? */
-              const [start] = comment.range ?? [];
+              const [
+                start,
+                /* c8 ignore next -- Unsupporting processors only? */
+              ] = comment.range ?? [];
               const textToStart = text.slice(0, start);
 
-              const [lines, cols] = getLinesCols(textToStart);
+              const [
+                lines,
+                cols,
+              ] = getLinesCols(textToStart);
 
               // const lines = [...textToStart.matchAll(/\n/gu)].length
               // const lastLinePos = textToStart.lastIndexOf('\n');
               // const cols = lastLinePos === -1
               //   ? 0
               //   : textToStart.slice(lastLinePos).length;
-              commentLineCols.push([lines, cols]);
+              commentLineCols.push([
+                lines, cols,
+              ]);
               return parseComment(comment);
             });
 
@@ -534,72 +634,19 @@ export const getJsdocProcessorPlugin = (options = {}) => {
                 return getTextsAndFileNames(
                   jsdoc,
                   filename,
-                  commentLineCols[idx]
+                  commentLineCols[idx],
                 );
-              }).filter(Boolean)
+              }).filter(Boolean),
             ];
-          /* c8 ignore next 3 */
-          } catch (err) {
-            console.log('err', filename, err);
+          /* c8 ignore next 6 */
+          } catch (error) {
+            // eslint-disable-next-line no-console -- Debugging
+            console.log('err', filename, error);
           }
-        },
 
-        /**
-         * @param {import('eslint').Linter.LintMessage[][]} messages
-         * @param {string} filename
-         */
-        postprocess ([jsMessages, ...messages], filename) {
-          messages.forEach((message, idx) => {
-            const {
-              targetTagName,
-              codeStartLine,
-              codeStartCol,
-              nonJSPrefacingCols,
-              commentLineCols
-            } = otherInfo[idx];
-
-            message.forEach((msg) => {
-              const {
-                message,
-                ruleId,
-                severity,
-                fatal,
-                line,
-                column,
-                endColumn,
-                endLine,
-
-                // Todo: Make fixable
-                // fix
-                // fix: {range: [number, number], text: string}
-                // suggestions: {desc: , messageId:, fix: }[],
-              } = msg;
-
-              const [codeCtxLine, codeCtxColumn] = commentLineCols;
-              const startLine = codeCtxLine + codeStartLine + line;
-              const startCol = 1 + // Seems to need one more now
-                codeCtxColumn + codeStartCol + (
-                  // This might not work for line 0, but line 0 is unlikely for examples
-                  line <= 1 ? nonJSPrefacingCols + firstLinePrefixLength : preTagSpaceLength
-                ) + column;
-
-              msg.message = '@' + targetTagName + ' ' + (severity === 2 ? 'error' : 'warning') +
-                (ruleId ? ' (' + ruleId + ')' : '') + ': ' +
-                (fatal ? 'Fatal: ' : '') +
-                message;
-              msg.line = startLine;
-              msg.column = startCol;
-              msg.endLine = endLine ? startLine + endLine : startLine;
-              // added `- column` to offset what `endColumn` already seemed to include
-              msg.endColumn = endColumn ? startCol - column + endColumn : startCol;
-            });
-          });
-
-          const ret = [...jsMessages].concat(...messages, ...extraMessages);
-          extraMessages = [];
-          return ret;
+          return [];
         },
-        supportsAutofix: true
+        supportsAutofix: true,
       },
     },
   };