eslint-plugin-jsdoc 64.5.3 → 65.0.0

package/README.md

@@ -265,7 +265,7 @@ and specify `eslint-plugin-jsdoc` as a plugin.
 
 Finally, enable all of the rules that you would like to use.
 
-```javascript
+```json5
 {
     "rules": {
         "jsdoc/check-access": 1, // Recommended
@@ -298,6 +298,9 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/no-restricted-syntax": 1,
         "jsdoc/no-types": 1, // Recommended for TS configs
         "jsdoc/no-undefined-types": 1, // Recommended for non-TS configs
+        "jsdoc/no-unnecessary-type-assertion": 1,
+        "jsdoc/normalize-see-links": 1,
+        "jsdoc/prefer-import-tag": 1,
         "jsdoc/reject-any-type": 1, // Recommended
         "jsdoc/reject-function-type": 1, // Recommended
         "jsdoc/require-asterisk-prefix": 1,
@@ -322,6 +325,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/require-returns-description": 1, // Recommended
         "jsdoc/require-returns-type": 1, // Recommended in non-TS configs
         "jsdoc/require-returns": 1, // Recommended
+        "jsdoc/require-tags": 1,
         "jsdoc/require-template": 1,
         "jsdoc/require-template-description": 1,
         "jsdoc/require-throws": 1,
@@ -334,9 +338,11 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/sort-tags": 1,
         "jsdoc/tag-lines": 1, // Recommended
         "jsdoc/text-escaping": 1,
+        "jsdoc/ts-ban-ts-comment": 1,
         "jsdoc/ts-method-signature-style": 1,
-        "jsdoc/ts-prefer-function-type": 1,
+        "jsdoc/ts-no-empty-object-type": 1, // Recommended
         "jsdoc/ts-no-unnecessary-template-expression": 1,
+        "jsdoc/ts-prefer-function-type": 1,
         "jsdoc/type-formatting": 1,
         "jsdoc/valid-types": 1 // Recommended
     }

package/dist/rules.d.ts

@@ -51,6 +51,10 @@ export interface Rules {
            * Allows indentation of nested sections on subsequent lines (like bullet lists)
            */
           allowIndentedSections?: boolean;
+          /**
+           * Allows there to be no space after asterisks and before content.
+           */
+          allowNoSpaceAfterAsterisk?: boolean;
           /**
            * Array of tags (e.g., `['example', 'description']`) whose content will be
            * "hidden" from the `check-indentation` rule. Defaults to `['example']`.
@@ -121,6 +125,7 @@ export interface Rules {
           /**
            * Use this to change the tags which are sought for alignment changes. Defaults to an array of
            * `['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return', 'template']`.
+           * Add the value "-any" to the array if you want alignment to apply to all tags.
            */
           tags?: string[];
           /**

package/package.json

@@ -7,7 +7,7 @@
   "dependencies": {
     "@es-joy/jsdoccomment": "~0.98.0",
     "@es-joy/resolve.exports": "1.2.0",
-    "@typescript-eslint/utils": "^8.70.0",
+    "@typescript-eslint/utils": "^8.70.1",
     "are-docs-informative": "^0.1.1",
     "comment-parser": "1.4.9",
     "debug": "^4.4.3",
@@ -24,34 +24,34 @@
   "description": "JSDoc linting rules for ESLint.",
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@babel/core": "8.0.5",
+    "@babel/core": "8.0.6",
     "@babel/eslint-parser": "8.0.5",
     "@babel/plugin-transform-flow-strip-types": "8.0.1",
-    "@babel/preset-env": "8.0.5",
+    "@babel/preset-env": "8.0.6",
     "@es-joy/escodegen": "^4.2.0",
     "@es-joy/jsdoc-eslint-parser": "^0.29.0",
     "@eslint/core": "^1.2.1",
     "@hkdobrev/run-if-changed": "^0.9.0",
     "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/github": "^12.0.9",
-    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/github": "^12.0.10",
+    "@semantic-release/npm": "^13.2.0",
     "@types/chai": "^5.2.3",
     "@types/debug": "^4.1.13",
     "@types/esquery": "^1.5.4",
     "@types/estree": "^1.0.9",
     "@types/json-schema": "^7.0.15",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.2",
     "@types/semver": "^7.8.0",
     "@types/spdx-expression-parse": "^4.0.0",
-    "@typescript-eslint/types": "8.70.0",
+    "@typescript-eslint/types": "8.70.1",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-transform-import-meta": "^3.0.0",
     "c8": "^12.0.0",
     "camelcase": "^9.0.0",
     "chai": "^6.2.2",
     "decamelize": "^6.0.1",
-    "eslint": "10.10.0",
+    "eslint": "10.11.0",
     "eslint-config-canonical": "^47.4.2",
     "gitdown": "^4.1.1",
     "glob": "^13.0.6",
@@ -70,7 +70,7 @@
     "sinon": "^22.1.0",
     "ts-api-utils": "^2.5.0",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.70.0"
+    "typescript-eslint": "8.70.1"
   },
   "engines": {
     "node": "^22.22.2 || >=24.15.0"
@@ -163,5 +163,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "64.5.3"
+  "version": "65.0.0"
 }

package/src/alignTransform.js

@@ -66,6 +66,10 @@ const zeroWidth = {
  * @returns {boolean}
  */
 const shouldAlign = (tags, index, source) => {
+  if (tags.includes('-any')) {
+    return true;
+  }
+
   const tag = source[index].tokens.tag.replace('@', '');
   const includesTag = tags.includes(tag);
 

package/src/rules/checkIndentation.js

@@ -32,8 +32,7 @@ const maskCodeBlocks = (str) => {
  */
 const getLineNumber = (lines, lineIndex) => {
   const precedingText = lines.slice(0, lineIndex).join('\n');
-  const lineBreaks = precedingText.match(/\n/gv) || [];
-  return lineBreaks.length + 1;
+  return precedingText.split('\n').length;
 };
 
 export default iterateJsdoc(({
@@ -43,8 +42,17 @@ export default iterateJsdoc(({
   sourceCode,
 }) => {
   const options = context.options[0] || {};
-  const /** @type {{excludeTags: string[], allowIndentedSections: boolean}} */ {
+
+  /**
+   * @type {{
+   *   excludeTags: string[],
+   *   allowIndentedSections: boolean,
+   *   allowNoSpaceAfterAsterisk: boolean,
+   * }}
+   */
+  const {
     allowIndentedSections = false,
+    allowNoSpaceAfterAsterisk = false,
     excludeTags = [
       'example',
     ],
@@ -64,6 +72,14 @@ export default iterateJsdoc(({
       lineIndex,
       line,
     ] of lines.entries()) {
+      // Check for no space between the asterisk prefix and content
+      if (!allowNoSpaceAfterAsterisk && /^(?:\/?\**|[\t ]*)\*[^\s*\/]/v.test(line)) {
+        report('There must be a space after the asterisk.', null, {
+          line: getLineNumber(lines, lineIndex),
+        });
+        return;
+      }
+
       // Check for indentation (two or more spaces after *)
       const indentMatch = line.match(/^(?:\/?\**|[\t ]*)\*([\t ]{2,})/v);
 
@@ -118,11 +134,37 @@ export default iterateJsdoc(({
       }
     }
   } else {
+    // Check for no space between the asterisk prefix and content
+    let noSpaceLastIndex = 0;
+    if (!allowNoSpaceAfterAsterisk) {
+      const noSpaceReg = /^(?:\/?\**|[ \t]*)\*[^\s*\/]/gmv;
+      if (noSpaceReg.test(text)) {
+        noSpaceLastIndex = noSpaceReg.lastIndex;
+      }
+    }
+
+    // Check for indentation (two or more spaces after *)
     const reg = /^(?:\/?\**|[ \t]*)\*[ \t]{2}/gmv;
+    let hasIndent = false;
+    let indentLastIndex = 0;
     if (reg.test(text)) {
-      const lineBreaks = text.slice(0, reg.lastIndex).match(/\n/gv) || [];
+      hasIndent = true;
+      indentLastIndex = reg.lastIndex;
+    }
+
+    // Report whichever issue appears first in the text
+    if (noSpaceLastIndex && (!hasIndent || noSpaceLastIndex <= indentLastIndex)) {
+      const line = text.slice(0, noSpaceLastIndex).split('\n').length - 1;
+      report('There must be a space after the asterisk.', null, {
+        line,
+      });
+      return;
+    }
+
+    if (hasIndent) {
+      const line = text.slice(0, indentLastIndex).split('\n').length - 1;
       report('There must be no indentation.', null, {
-        line: lineBreaks.length,
+        line,
       });
     }
   }
@@ -141,6 +183,10 @@ export default iterateJsdoc(({
             description: 'Allows indentation of nested sections on subsequent lines (like bullet lists)',
             type: 'boolean',
           },
+          allowNoSpaceAfterAsterisk: {
+            description: 'Allows there to be no space after asterisks and before content.',
+            type: 'boolean',
+          },
           excludeTags: {
             description: `Array of tags (e.g., \`['example', 'description']\`) whose content will be
 "hidden" from the \`check-indentation\` rule. Defaults to \`['example']\`.

package/src/rules/checkLineAlignment.js

@@ -311,7 +311,10 @@ export default iterateJsdoc(({
     return;
   }
 
-  const foundTags = utils.getPresentTags(applicableTags);
+  const foundTags = applicableTags.includes('-any') ?
+    utils.filterTags(Boolean) :
+    utils.getPresentTags(applicableTags);
+
   if (context.options[0] !== 'any') {
     for (const tag of foundTags) {
       checkNotAlignedPerTag(
@@ -433,7 +436,8 @@ main description. If \`false\` or unset, will be set to a single space.`,
           },
           tags: {
             description: `Use this to change the tags which are sought for alignment changes. Defaults to an array of
-\`['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return', 'template']\`.`,
+\`['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return', 'template']\`.
+Add the value "-any" to the array if you want alignment to apply to all tags.`,
             items: {
               type: 'string',
             },

package/src/rules/noUnnecessaryTypeAssertion.js

@@ -10,24 +10,11 @@ let warned = false;
 /** @type {any} */
 let ts;
 
+let tsAttempted = false;
+
 // 1. Create a require function bound to the current file's URL
 const require = createRequire(import.meta.url);
 
-try {
-  // 2. Attempt to import the package synchronously
-  ts = require('typescript');
-/* c8 ignore next 10 -- Guard */
-} catch (error) {
-  // 3. Fall back gracefully if it is not installed
-  if (/** @type {{code?: string}} */ (error).code !== 'MODULE_NOT_FOUND') {
-    // Re-throw if it's a different error (e.g., syntax error inside the package)
-    throw error;
-  }
-
-  // eslint-disable-next-line no-console -- Warning user
-  console.warn('⚠️ typescript is not installed. `jsdoc/no-unnecessary-type-assertion` will not work. To disable this warning, you must disable the rule.');
-}
-
 // Helper to check for standard literals and boolean/enum/template literals
 /**
  * @param {any} type The type is `ts.Type`
@@ -70,9 +57,30 @@ export default iterateJsdoc(({
   utils,
 // eslint-disable-next-line complexity -- Numerous type/option permutations
 }) => {
-  /* c8 ignore next 4 -- Guard */
   // Already handled
   if (!ts) {
+    /* c8 ignore next 3 -- Guard (only reachable if `typescript` failed to load on a prior call) */
+    if (tsAttempted) {
+      return;
+    }
+
+    try {
+      // 2. Attempt to import the package synchronously
+      ts = require('typescript');
+    /* c8 ignore next 10 -- Guard */
+    } catch (error) {
+      // 3. Fall back gracefully if it is not installed
+      if (/** @type {{code?: string}} */ (error).code !== 'MODULE_NOT_FOUND') {
+        // Re-throw if it's a different error (e.g., syntax error inside the package)
+        throw error;
+      }
+
+      // eslint-disable-next-line no-console -- Warning user
+      console.warn('⚠️ typescript is not installed. `jsdoc/no-unnecessary-type-assertion` will not work. To disable this warning, you must disable the rule.');
+    } finally {
+      tsAttempted = true;
+    }
+
     return;
   }
 

package/src/rules.d.ts

@@ -51,6 +51,10 @@ export interface Rules {
            * Allows indentation of nested sections on subsequent lines (like bullet lists)
            */
           allowIndentedSections?: boolean;
+          /**
+           * Allows there to be no space after asterisks and before content.
+           */
+          allowNoSpaceAfterAsterisk?: boolean;
           /**
            * Array of tags (e.g., `['example', 'description']`) whose content will be
            * "hidden" from the `check-indentation` rule. Defaults to `['example']`.
@@ -121,6 +125,7 @@ export interface Rules {
           /**
            * Use this to change the tags which are sought for alignment changes. Defaults to an array of
            * `['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return', 'template']`.
+           * Add the value "-any" to the array if you want alignment to apply to all tags.
            */
           tags?: string[];
           /**