eslint-plugin-jsdoc 55.1.2 → 55.3.0

package/package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.56.0",
+    "@es-joy/jsdoccomment": "~0.57.0",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.4.1",
@@ -42,7 +42,7 @@
     "@types/node": "^24.3.1",
     "@types/semver": "^7.7.1",
     "@types/spdx-expression-parse": "^3.0.5",
-    "@typescript-eslint/types": "^8.42.0",
+    "@typescript-eslint/types": "^8.43.0",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^7.0.1",
     "babel-plugin-transform-import-meta": "^2.3.3",
@@ -54,9 +54,9 @@
     "eslint-config-canonical": "~45.0.0",
     "gitdown": "^4.1.1",
     "glob": "^11.0.3",
-    "globals": "^16.3.0",
+    "globals": "^16.4.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^5.1.1",
+    "jsdoc-type-pratt-parser": "^5.2.0",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
     "lint-staged": "^16.1.6",
@@ -66,7 +66,7 @@
     "rimraf": "^6.0.1",
     "semantic-release": "^24.2.7",
     "typescript": "5.9.2",
-    "typescript-eslint": "^8.42.0"
+    "typescript-eslint": "^8.43.0"
   },
   "engines": {
     "node": ">=20.11.0"
@@ -160,5 +160,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": "55.1.2"
+  "version": "55.3.0"
 }

package/src/index-cjs.js

@@ -57,6 +57,7 @@ import requireYieldsCheck from './rules/requireYieldsCheck.js';
 import sortTags from './rules/sortTags.js';
 import tagLines from './rules/tagLines.js';
 import textEscaping from './rules/textEscaping.js';
+import typeFormatting from './rules/typeFormatting.js';
 import validTypes from './rules/validTypes.js';
 
 /* eslint-disable jsdoc/valid-types -- Bug */
@@ -129,6 +130,7 @@ index.rules = {
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
+  'type-formatting': typeFormatting,
   'valid-types': validTypes,
 };
 
@@ -206,6 +208,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',
+      'jsdoc/type-formatting': 'off',
       'jsdoc/valid-types': warnOrError,
     },
   };

package/src/index-esm.js

@@ -13,7 +13,7 @@ export default index;
 /* eslint-disable jsdoc/valid-types -- Bug */
 /**
  * @type {((
- *   cfg?: {
+ *   cfg?: import('eslint').Linter.Config & {
  *     mergeSettings?: boolean,
  *     config?: `flat/${import('./index-cjs.js').ConfigGroups}${import('./index-cjs.js').ConfigVariants}${import('./index-cjs.js').ErrorLevelVariants}`,
  *     settings?: Partial<import('./iterateJsdoc.js').Settings>,
@@ -29,19 +29,62 @@ export const jsdoc = function (cfg) {
       jsdoc: index,
     },
   };
-  if (
-    cfg?.config
-  ) {
-    // @ts-expect-error Security check
-    if (cfg.config === '__proto__') {
-      throw new TypeError('Disallowed config value');
+
+  if (cfg) {
+    if (cfg.config) {
+      // @ts-expect-error Security check
+      if (cfg.config === '__proto__') {
+        throw new TypeError('Disallowed config value');
+      }
+
+      outputConfig = index.configs[cfg.config];
     }
 
-    outputConfig = index.configs[cfg.config];
-  }
+    if (cfg.rules) {
+      outputConfig.rules = {
+        ...outputConfig.rules,
+        ...cfg.rules,
+      };
+    }
+
+    if (cfg.plugins) {
+      outputConfig.plugins = {
+        ...outputConfig.plugins,
+        ...cfg.plugins,
+      };
+    }
+
+    if (cfg.name) {
+      outputConfig.name = cfg.name;
+    }
+
+    if (cfg.basePath) {
+      outputConfig.basePath = cfg.basePath;
+    }
+
+    if (cfg.files) {
+      outputConfig.files = cfg.files;
+    }
+
+    if (cfg.ignores) {
+      outputConfig.ignores = cfg.ignores;
+    }
 
-  if (cfg?.rules) {
-    outputConfig.rules = cfg.rules;
+    if (cfg.language) {
+      outputConfig.language = cfg.language;
+    }
+
+    if (cfg.languageOptions) {
+      outputConfig.languageOptions = cfg.languageOptions;
+    }
+
+    if (cfg.linterOptions) {
+      outputConfig.linterOptions = cfg.linterOptions;
+    }
+
+    if (cfg.processor) {
+      outputConfig.processor = cfg.processor;
+    }
   }
 
   outputConfig.settings = {
@@ -78,3 +121,7 @@ export const jsdoc = function (cfg) {
 
   return outputConfig;
 };
+
+export {
+  getJsdocProcessorPlugin,
+} from './getJsdocProcessorPlugin.js';

package/src/index.js

@@ -63,6 +63,7 @@ import requireYieldsCheck from './rules/requireYieldsCheck.js';
 import sortTags from './rules/sortTags.js';
 import tagLines from './rules/tagLines.js';
 import textEscaping from './rules/textEscaping.js';
+import typeFormatting from './rules/typeFormatting.js';
 import validTypes from './rules/validTypes.js';
 
 /* eslint-disable jsdoc/valid-types -- Bug */
@@ -135,6 +136,7 @@ index.rules = {
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
+  'type-formatting': typeFormatting,
   'valid-types': validTypes,
 };
 
@@ -212,6 +214,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',
+      'jsdoc/type-formatting': 'off',
       'jsdoc/valid-types': warnOrError,
     },
   };
@@ -536,7 +539,7 @@ export default index;
 /* eslint-disable jsdoc/valid-types -- Bug */
 /**
  * @type {((
- *   cfg?: {
+ *   cfg?: import('eslint').Linter.Config & {
  *     mergeSettings?: boolean,
  *     config?: `flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}`,
  *     settings?: Partial<import('./iterateJsdoc.js').Settings>,
@@ -552,19 +555,62 @@ export const jsdoc = function (cfg) {
       jsdoc: index,
     },
   };
-  if (
-    cfg?.config
-  ) {
-    // @ts-expect-error Security check
-    if (cfg.config === '__proto__') {
-      throw new TypeError('Disallowed config value');
+
+  if (cfg) {
+    if (cfg.config) {
+      // @ts-expect-error Security check
+      if (cfg.config === '__proto__') {
+        throw new TypeError('Disallowed config value');
+      }
+
+      outputConfig = index.configs[cfg.config];
     }
 
-    outputConfig = index.configs[cfg.config];
-  }
+    if (cfg.rules) {
+      outputConfig.rules = {
+        ...outputConfig.rules,
+        ...cfg.rules,
+      };
+    }
+
+    if (cfg.plugins) {
+      outputConfig.plugins = {
+        ...outputConfig.plugins,
+        ...cfg.plugins,
+      };
+    }
+
+    if (cfg.name) {
+      outputConfig.name = cfg.name;
+    }
+
+    if (cfg.basePath) {
+      outputConfig.basePath = cfg.basePath;
+    }
+
+    if (cfg.files) {
+      outputConfig.files = cfg.files;
+    }
 
-  if (cfg?.rules) {
-    outputConfig.rules = cfg.rules;
+    if (cfg.ignores) {
+      outputConfig.ignores = cfg.ignores;
+    }
+
+    if (cfg.language) {
+      outputConfig.language = cfg.language;
+    }
+
+    if (cfg.languageOptions) {
+      outputConfig.languageOptions = cfg.languageOptions;
+    }
+
+    if (cfg.linterOptions) {
+      outputConfig.linterOptions = cfg.linterOptions;
+    }
+
+    if (cfg.processor) {
+      outputConfig.processor = cfg.processor;
+    }
   }
 
   outputConfig.settings = {
@@ -601,3 +647,7 @@ export const jsdoc = function (cfg) {
 
   return outputConfig;
 };
+
+export {
+  getJsdocProcessorPlugin,
+} from './getJsdocProcessorPlugin.js';

package/src/rules/typeFormatting.js

@@ -0,0 +1,348 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  parse as parseType,
+  stringify,
+  traverse,
+  tryParse as tryParseType,
+} from '@es-joy/jsdoccomment';
+
+export default iterateJsdoc(({
+  context,
+  indent,
+  jsdoc,
+  settings,
+  utils,
+}) => {
+  const {
+    arrayBrackets = 'square',
+    enableFixer = true,
+    genericDot = false,
+    objectFieldIndent = '',
+    objectFieldQuote = null,
+    objectFieldSeparator = null,
+    propertyQuotes = null,
+    separatorForSingleObjectField = false,
+    stringQuotes = 'single',
+  } = context.options[0] || {};
+
+  const {
+    mode,
+  } = settings;
+
+  /**
+   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
+   */
+  const checkTypeFormats = (tag) => {
+    const potentialType = tag.type;
+    let parsedType;
+    try {
+      parsedType = mode === 'permissive' ?
+        tryParseType(/** @type {string} */ (potentialType)) :
+        parseType(/** @type {string} */ (potentialType), mode);
+    } catch {
+      return;
+    }
+
+    const fix = () => {
+      const typeLines = stringify(parsedType).split('\n');
+      const firstTypeLine = typeLines.shift();
+      const lastTypeLine = typeLines.pop();
+
+      const beginNameOrDescIdx = tag.source.findIndex(({
+        tokens,
+      }) => {
+        return tokens.name || tokens.description;
+      });
+
+      const nameAndDesc = tag.source.slice(beginNameOrDescIdx);
+      const initialNumber = tag.source[0].number;
+      const src = [
+        // Get inevitably present tag from first `tag.source`
+        {
+          number: initialNumber,
+          source: '',
+          tokens: {
+            ...tag.source[0].tokens,
+            ...(typeLines.length || lastTypeLine ? {
+              end: '',
+              name: '',
+              postName: '',
+              postType: '',
+            } : {}),
+            type: '{' + firstTypeLine + (!typeLines.length && lastTypeLine === undefined ? '}' : ''),
+          },
+        },
+        // Get any intervening type lines
+        ...(typeLines.length ? typeLines.map((typeLine, idx) => {
+          return {
+            number: initialNumber + idx + 1,
+            source: '',
+            tokens: {
+              // Grab any delimiter info from first item
+              ...tag.source[0].tokens,
+              delimiter: tag.source[0].tokens.delimiter === '/**' ? '*' : tag.source[0].tokens.delimiter,
+              end: '',
+              name: '',
+              postName: '',
+              postTag: '',
+              postType: '',
+              start: indent + ' ',
+              tag: '',
+              type: typeLine,
+            },
+          };
+        }) : []),
+      ];
+
+      // Merge any final type line and name and description
+      if (
+        // Name and description may be already included if present with the tag
+        beginNameOrDescIdx > 0
+      ) {
+        src.push({
+          number: src.length + 1,
+          source: '',
+          tokens: {
+            ...nameAndDesc[0].tokens,
+            type: lastTypeLine + '}',
+          },
+        });
+
+        if (
+          // Get any remaining description lines
+          nameAndDesc.length > 1
+        ) {
+          src.push(
+            ...nameAndDesc.slice(1).map(({
+              source,
+              tokens,
+            }, idx) => {
+              return {
+                number: src.length + idx + 2,
+                source,
+                tokens,
+              };
+            }),
+          );
+        }
+      } else {
+        if (lastTypeLine) {
+          src.push({
+            number: src.length + 1,
+            source: '',
+            tokens: {
+              ...nameAndDesc[0].tokens,
+              delimiter: nameAndDesc[0].tokens.delimiter === '/**' ? '*' : nameAndDesc[0].tokens.delimiter,
+              postTag: '',
+              start: indent + ' ',
+              tag: '',
+              type: lastTypeLine + '}',
+            },
+          });
+        }
+
+        if (
+          // Get any remaining description lines
+          nameAndDesc.length > 1
+        ) {
+          src.push(
+            ...nameAndDesc.slice(1).map(({
+              source,
+              tokens,
+            }, idx) => {
+              return {
+                number: src.length + idx + 2,
+                source,
+                tokens,
+              };
+            }),
+          );
+        }
+      }
+
+      tag.source = src;
+
+      // Properly rewire `jsdoc.source`
+      const firstTagIdx = jsdoc.source.findIndex(({
+        tokens: {
+          tag: tg,
+        },
+      }) => {
+        return tg;
+      });
+
+      jsdoc.source = [
+        ...jsdoc.source.slice(0, firstTagIdx),
+        ...jsdoc.tags.flatMap(({
+          source,
+        }) => {
+          return source;
+        }),
+      ];
+    };
+
+    /** @type {string[]} */
+    const errorMessages = [];
+    let needToReport = false;
+    traverse(parsedType, (nde) => {
+      let typeFound = true;
+      let errorMessage = '';
+      const initialType = stringify(
+        /** @type {import('jsdoc-type-pratt-parser').RootResult} */ (nde),
+      );
+      switch (nde.type) {
+        case 'JsdocTypeGeneric': {
+          const typeNode = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (nde);
+          if ('value' in typeNode.left && typeNode.left.value === 'Array') {
+            typeNode.meta.brackets = arrayBrackets;
+            errorMessage = `Array bracket style should be ${arrayBrackets}`;
+          } else {
+            typeNode.meta.dot = genericDot;
+            errorMessage = `Dot usage should be ${genericDot}`;
+          }
+
+          break;
+        }
+
+        case 'JsdocTypeObject': {
+          const typeNode = /** @type {import('jsdoc-type-pratt-parser').ObjectResult} */ (nde);
+          typeNode.meta.separator = objectFieldSeparator ?? undefined;
+          typeNode.meta.separatorForSingleObjectField = separatorForSingleObjectField;
+          typeNode.meta.propertyIndent = objectFieldIndent;
+          errorMessage = `Inconsistent ${objectFieldSeparator} usage`;
+          break;
+        }
+
+        case 'JsdocTypeObjectField': {
+          const typeNode = /** @type {import('jsdoc-type-pratt-parser').ObjectFieldResult} */ (nde);
+          if (objectFieldQuote ||
+            (typeof typeNode.key === 'string' && !(/\s/v).test(typeNode.key))
+          ) {
+            typeNode.meta.quote = objectFieldQuote ?? undefined;
+            errorMessage = `Inconsistent object field quotes ${objectFieldQuote}`;
+          } else {
+            typeFound = false;
+          }
+
+          break;
+        }
+
+        case 'JsdocTypeProperty': {
+          const typeNode = /** @type {import('jsdoc-type-pratt-parser').PropertyResult} */ (nde);
+
+          if (propertyQuotes ||
+            (typeof typeNode.value === 'string' && !(/\s/v).test(typeNode.value))
+          ) {
+            typeNode.meta.quote = propertyQuotes ?? undefined;
+            errorMessage = `Inconsistent ${propertyQuotes} property quotes usage`;
+          } else {
+            typeFound = false;
+          }
+
+          break;
+        }
+
+        case 'JsdocTypeStringValue': {
+          const typeNode = /** @type {import('jsdoc-type-pratt-parser').StringValueResult} */ (nde);
+          typeNode.meta.quote = stringQuotes;
+          errorMessage = `Inconsistent ${stringQuotes} string quotes usage`;
+          break;
+        }
+
+        default:
+          typeFound = false;
+          break;
+      }
+
+      if (typeFound) {
+        const convertedType = stringify(/** @type {import('jsdoc-type-pratt-parser').RootResult} */ (nde));
+        if (initialType !== convertedType) {
+          needToReport = true;
+          errorMessages.push(errorMessage);
+        }
+      }
+    });
+
+    if (needToReport) {
+      for (const errorMessage of errorMessages) {
+        utils.reportJSDoc(
+          errorMessage, tag, enableFixer ? fix : null, true,
+        );
+      }
+    }
+  };
+
+  const tags = utils.getPresentTags([
+    'param',
+    'returns',
+  ]);
+  for (const tag of tags) {
+    checkTypeFormats(tag);
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Formats JSDoc type values.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/type-formatting.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          arrayBrackets: {
+            enum: [
+              'angle',
+              'square',
+            ],
+          },
+          enableFixer: {
+            type: 'boolean',
+          },
+          genericDot: {
+            type: 'boolean',
+          },
+          objectFieldIndent: {
+            type: 'string',
+          },
+          objectFieldQuote: {
+            enum: [
+              'double',
+              'single',
+              null,
+            ],
+          },
+          objectFieldSeparator: {
+            enum: [
+              'comma',
+              'comma-and-linebreak',
+              'linebreak',
+              'semicolon',
+              'semicolon-and-linebreak',
+              null,
+            ],
+          },
+          propertyQuotes: {
+            enum: [
+              'double',
+              'single',
+              null,
+            ],
+          },
+          separatorForSingleObjectField: {
+            type: 'boolean',
+          },
+          stringQuotes: {
+            enum: [
+              'double',
+              'single',
+            ],
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules.d.ts

@@ -756,6 +756,28 @@ export interface Rules {
         }
       ];
 
+  "jsdoc/type-formatting": 
+    | []
+    | [
+        {
+          arrayBrackets?: "angle" | "square";
+          enableFixer?: boolean;
+          genericDot?: boolean;
+          objectFieldIndent?: string;
+          objectFieldQuote?: "double" | "single" | null;
+          objectFieldSeparator?:
+            | "comma"
+            | "comma-and-linebreak"
+            | "linebreak"
+            | "semicolon"
+            | "semicolon-and-linebreak"
+            | null;
+          propertyQuotes?: "double" | "single" | null;
+          separatorForSingleObjectField?: boolean;
+          stringQuotes?: "double" | "single";
+        }
+      ];
+
   "jsdoc/valid-types": 
     | []
     | [