eslint-plugin-jsdoc 65.0.2 → 65.2.0

package/README.md

@@ -494,7 +494,7 @@ non-default-recommended fixer).
 ||:wrench:| [check-line-alignment](./docs/rules/check-line-alignment.md#readme) | Reports invalid alignment of JSDoc block lines. |
 |:heavy_check_mark:|:wrench:| [check-param-names](./docs/rules/check-param-names.md#readme) | Checks for dupe `@param` names, that nested param names have roots, and that parameter names in function declarations match JSDoc param names. |
 |:heavy_check_mark:|:wrench:| [check-property-names](./docs/rules/check-property-names.md#readme) | Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots. |
-||| [check-syntax](./docs/rules/check-syntax.md#readme) | Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode). |
+||:wrench:| [check-syntax](./docs/rules/check-syntax.md#readme) | Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode). |
 |:heavy_check_mark:|:wrench:| [check-tag-names](./docs/rules/check-tag-names.md#readme) | Reports invalid block tag names. |
 ||| [check-template-names](./docs/rules/check-template-names.md#readme) | Checks that any `@template` names are actually used in the connected `@typedef` or type alias. |
 |:heavy_check_mark:|:wrench:| [check-types](./docs/rules/check-types.md#readme) | Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements). |

package/dist/rules.d.ts

@@ -7,6 +7,10 @@ export interface Rules {
     | []
     | [
         {
+          /**
+           * Whether to ignore empty and whitespace-only lines (e.g., to allow a formatter to handle)
+           */
+          ignoreEmptyLines?: boolean;
           /**
            * Set to 0 if you wish to avoid the normal requirement for an inner indentation of
            * one space. Defaults to 1 (one space of normal inner indentation).
@@ -266,7 +270,19 @@ export interface Rules {
       ];
 
   /** Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode). */
-  "jsdoc/check-syntax": [];
+  "jsdoc/check-syntax": 
+    | []
+    | [
+        {
+          /**
+           * Whether to enable the fixer to replace the Closure Compiler style `{type=}`
+           * with `{type} [name]` on `@param` and `@property` tags, and with
+           * `{type|undefined}` on other tags.
+           * Defaults to `false`.
+           */
+          enableFixer?: boolean;
+        }
+      ];
 
   /** Reports invalid block tag names. */
   "jsdoc/check-tag-names": 
@@ -3301,7 +3317,7 @@ export interface Rules {
            */
           stringQuotes?: "double" | "single";
           /**
-           * If `objectFieldSeparatorTrailingPunctuation` is set, this will determine whether the trailing puncutation is only added when the type is multiline
+           * If `objectFieldSeparatorTrailingPunctuation` is set, this will determine whether the trailing punctuation is only added when the type is multiline
            */
           trailingPunctuationMultilineOnly?: boolean;
           /**

package/package.json

@@ -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": "65.0.2"
+  "version": "65.2.0"
 }

package/src/rules/checkAlignment.js

@@ -8,6 +8,7 @@ export default iterateJsdoc(({
   sourceCode,
 }) => {
   const {
+    ignoreEmptyLines = false,
     innerIndent = 1,
   } = context.options[0] || {};
 
@@ -15,6 +16,9 @@ export default iterateJsdoc(({
   const indentLevel = indent.length + innerIndent;
   const sourceLines = sourceCode.getText(jsdocNode).split('\n')
     .slice(1)
+    .filter((line) => {
+      return !ignoreEmptyLines || line.trim();
+    })
     .map((line, number) => {
       return {
         line: line.split('*')[0],
@@ -67,6 +71,10 @@ export default iterateJsdoc(({
       {
         additionalProperties: false,
         properties: {
+          ignoreEmptyLines: {
+            description: 'Whether to ignore empty and whitespace-only lines (e.g., to allow a formatter to handle)',
+            type: 'boolean',
+          },
           innerIndent: {
             default: 1,
             description: `Set to 0 if you wish to avoid the normal requirement for an inner indentation of

package/src/rules/checkIndentation.js

@@ -118,8 +118,8 @@ export default iterateJsdoc(({
         hasSeenContent = true;
       }
 
-      // Reset section indent when we encounter a tag
-      if (/@\w+/v.test(line)) {
+      // Reset section indent when we encounter a block tag
+      if (/^(?:\/?\**|[\t ]*)\*[ \t]*@\w+/v.test(line)) {
         currentSectionIndent = null;
       }
     }

package/src/rules/checkSyntax.js

@@ -1,20 +1,116 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 
+// Closure's `{type=} name` is written `{type} [name]` in JSDoc/TypeScript
+const namedTags = new Set([
+  'arg', 'argument', 'param', 'prop', 'property',
+]);
+
+// Types that do not need parentheses before `|undefined`
+const simpleType = /^[\w$.]+$/v;
+
+/**
+ * Builds the fix for a tag with a Closure style optional type (`{type=}`), if
+ * there is one.
+ *
+ * Named tags (`@param {type=} name`) become `{type} [name]`; for other tags
+ * (or a missing or defaulted name), the type is joined with `undefined`.
+ * @param {import('comment-parser').Spec} tag
+ * @returns {() => void}
+ */
+const getFix = (tag) => {
+  const {
+    source,
+  } = tag;
+
+  // For a type over several lines, the end of the type is on the line that has the name
+  const lastTypeLine = /** @type {import('comment-parser').Line} */ (source.findLast(({
+    tokens,
+  }) => {
+    return tokens.type.endsWith('=}');
+  }));
+
+  const firstTypeLine = /** @type {import('comment-parser').Line} */ (source.find(({
+    tokens,
+  }) => {
+    return tokens.type;
+  }));
+
+  const nameTokens = source.find(({
+    tokens,
+  }) => {
+    return tokens.name;
+  })?.tokens;
+
+  // A name with a default (`[foo=bar]`) is already bracketed; a bare `foo=bar` is not a valid name
+  if (namedTags.has(tag.tag) && nameTokens && (!nameTokens.name.includes('=') || nameTokens.name.startsWith('['))) {
+    return () => {
+      lastTypeLine.tokens.type = `${lastTypeLine.tokens.type.slice(0, -2)}}`;
+      if (!nameTokens.name.startsWith('[')) {
+        nameTokens.name = `[${nameTokens.name}]`;
+      }
+
+      tag.optional = true;
+    };
+  }
+
+  const isSingleLine = firstTypeLine === lastTypeLine;
+  const inner = lastTypeLine.tokens.type.slice(isSingleLine ? 1 : 0, -2);
+  if (isSingleLine && simpleType.test(inner)) {
+    return () => {
+      lastTypeLine.tokens.type = `{${inner}|undefined}`;
+    };
+  }
+
+  return () => {
+    firstTypeLine.tokens.type = `{(${firstTypeLine.tokens.type.slice(1)}`;
+    lastTypeLine.tokens.type = `${lastTypeLine.tokens.type.slice(0, -2)})|undefined}`;
+  };
+};
+
 export default iterateJsdoc(({
+  context,
   jsdoc,
   report,
   settings,
+  utils,
 }) => {
+  const {
+    enableFixer = false,
+  } = context.options[0] || {};
+
   const {
     mode,
   } = settings;
 
   // Don't check for "permissive" and "closure"
   if (mode === 'jsdoc' || mode === 'typescript') {
+    /** @type {import('comment-parser').Spec|undefined} */
+    let firstTag;
+    /** @type {(() => void)[]} */
+    const fixes = [];
+
     for (const tag of jsdoc.tags) {
-      if (tag.type.slice(-1) === '=') {
-        report('Syntax should not be Google Closure Compiler style.', null, tag);
-        break;
+      if (tag.type.slice(-1) !== '=') {
+        continue;
+      }
+
+      firstTag ??= tag;
+
+      if (enableFixer) {
+        fixes.push(getFix(tag));
+      }
+    }
+
+    if (firstTag) {
+      const message = 'Syntax should not be Google Closure Compiler style.';
+      if (fixes.length) {
+        utils.reportJSDoc(message, firstTag, () => {
+          for (const fix of fixes) {
+            fix();
+          }
+        });
+      } else {
+        report(message, null, firstTag);
       }
     }
   }
@@ -25,6 +121,22 @@ export default iterateJsdoc(({
       description: 'Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-syntax.md#repos-sticky-header',
     },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          enableFixer: {
+            description: `Whether to enable the fixer to replace the Closure Compiler style \`{type=}\`
+with \`{type} [name]\` on \`@param\` and \`@property\` tags, and with
+\`{type|undefined}\` on other tags.
+Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
     type: 'suggestion',
   },
 });

package/src/rules/typeFormatting.js

@@ -668,7 +668,7 @@ or \`double\`. Defaults to 'double'.`,
             type: 'string',
           },
           trailingPunctuationMultilineOnly: {
-            description: 'If `objectFieldSeparatorTrailingPunctuation` is set, this will determine whether the trailing puncutation is only added when the type is multiline',
+            description: 'If `objectFieldSeparatorTrailingPunctuation` is set, this will determine whether the trailing punctuation is only added when the type is multiline',
             type: 'boolean',
           },
           typeBracketSpacing: {

package/src/rules.d.ts

@@ -7,6 +7,10 @@ export interface Rules {
     | []
     | [
         {
+          /**
+           * Whether to ignore empty and whitespace-only lines (e.g., to allow a formatter to handle)
+           */
+          ignoreEmptyLines?: boolean;
           /**
            * Set to 0 if you wish to avoid the normal requirement for an inner indentation of
            * one space. Defaults to 1 (one space of normal inner indentation).
@@ -266,7 +270,19 @@ export interface Rules {
       ];
 
   /** Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode). */
-  "jsdoc/check-syntax": [];
+  "jsdoc/check-syntax": 
+    | []
+    | [
+        {
+          /**
+           * Whether to enable the fixer to replace the Closure Compiler style `{type=}`
+           * with `{type} [name]` on `@param` and `@property` tags, and with
+           * `{type|undefined}` on other tags.
+           * Defaults to `false`.
+           */
+          enableFixer?: boolean;
+        }
+      ];
 
   /** Reports invalid block tag names. */
   "jsdoc/check-tag-names": 
@@ -3301,7 +3317,7 @@ export interface Rules {
            */
           stringQuotes?: "double" | "single";
           /**
-           * If `objectFieldSeparatorTrailingPunctuation` is set, this will determine whether the trailing puncutation is only added when the type is multiline
+           * If `objectFieldSeparatorTrailingPunctuation` is set, this will determine whether the trailing punctuation is only added when the type is multiline
            */
           trailingPunctuationMultilineOnly?: boolean;
           /**