eslint-plugin-jsdoc 61.0.1 → 61.1.0

package/src/jsdocUtils.js

@@ -6,6 +6,7 @@ import {
 } from './tagNames.js';
 import WarnSettings from './WarnSettings.js';
 import {
+  stringify,
   tryParse,
 } from '@es-joy/jsdoccomment';
 
@@ -1896,6 +1897,185 @@ const strictNativeTypes = [
   'RegExp',
 ];
 
+/**
+ * @param {import('@es-joy/jsdoccomment').JsdocBlockWithInline} jsdoc
+ * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
+ * @param {import('jsdoc-type-pratt-parser').RootResult} parsedType
+ * @param {string} indent
+ * @param {string} typeBracketSpacing
+ */
+const rewireByParsedType = (jsdoc, tag, parsedType, indent, typeBracketSpacing = '') => {
+  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 = beginNameOrDescIdx === -1 ?
+    null :
+    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: '',
+        } : (nameAndDesc ? {
+          name: nameAndDesc[0].tokens.name,
+          postType: ' ',
+        } : {})),
+        type: '{' + typeBracketSpacing + firstTypeLine + (!typeLines.length && lastTypeLine === undefined ? typeBracketSpacing + '}' : ''),
+      },
+    },
+    // 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
+    nameAndDesc && beginNameOrDescIdx > 0
+  ) {
+    if (typeLines.length || lastTypeLine !== undefined) {
+      src.push({
+        number: src.length + 1,
+        source: '',
+        tokens: {
+          ...nameAndDesc[0].tokens,
+          type: lastTypeLine + typeBracketSpacing + '}',
+        },
+      });
+    }
+
+    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 (nameAndDesc) {
+    if ((typeLines.length || lastTypeLine !== undefined) && 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 + typeBracketSpacing + '}',
+        },
+      });
+    }
+
+    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: {
+        ...tag.source[0].tokens,
+        delimiter: tag.source[0].tokens.delimiter === '/**' ? '*' : tag.source[0].tokens.delimiter,
+        postTag: '',
+        start: indent + ' ',
+        tag: '',
+        type: lastTypeLine + typeBracketSpacing + '}',
+      },
+    });
+  }
+
+  tag.source = src;
+
+  // Properly rewire `jsdoc.source`
+  const firstTagIdx = jsdoc.source.findIndex(({
+    tokens: {
+      tag: tg,
+    },
+  }) => {
+    return tg;
+  });
+
+  const initialEndSource = jsdoc.source.find(({
+    tokens: {
+      end,
+    },
+  }) => {
+    return end;
+  });
+
+  jsdoc.source = [
+    ...jsdoc.source.slice(0, firstTagIdx),
+    ...jsdoc.tags.flatMap(({
+      source,
+    }) => {
+      return source;
+    }),
+  ];
+
+  if (initialEndSource && !jsdoc.source.at(-1)?.tokens?.end) {
+    jsdoc.source.push(initialEndSource);
+  }
+};
+
 export {
   comparePaths,
   dropPathSegmentQuotes,
@@ -1935,6 +2115,7 @@ export {
   overrideTagStructure,
   parseClosureTemplateTag,
   pathDoesNotBeginWith,
+  rewireByParsedType,
   setTagStructure,
   strictNativeTypes,
   tagMightHaveEitherTypeOrNamePosition,

package/src/rules/tsMethodSignatureStyle.js

@@ -0,0 +1,300 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  rewireByParsedType,
+} from '../jsdocUtils.js';
+import {
+  parse as parseType,
+  traverse,
+} from '@es-joy/jsdoccomment';
+
+export default iterateJsdoc(({
+  context,
+  indent,
+  jsdoc,
+  utils,
+}) => {
+  const functionType = context.options[0] ?? 'property';
+  const {
+    enableFixer = true,
+  } = context.options[1] ?? {};
+
+  /**
+   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
+   */
+  const checkType = (tag) => {
+    const potentialType = tag.type;
+    let parsedType;
+    try {
+      parsedType = parseType(
+        /** @type {string} */ (potentialType), 'typescript',
+      );
+    } catch {
+      return;
+    }
+
+    traverse(parsedType, (nde, parentNode) => {
+      // @ts-expect-error Adding our own property for use below
+      nde.parentNode = parentNode;
+    });
+
+    traverse(parsedType, (nde, parentNode, property, idx) => {
+      switch (nde.type) {
+        case 'JsdocTypeFunction': {
+          if (functionType !== 'method') {
+            break;
+          }
+
+          if (parentNode?.type === 'JsdocTypeObjectField' &&
+            typeof parentNode.key === 'string'
+          ) {
+            utils.reportJSDoc(
+              'Found function property; prefer method signature.',
+              tag,
+              enableFixer ? () => {
+                const objectField = parentNode;
+                const obj =
+                  /**
+                   * @type {import('jsdoc-type-pratt-parser').ObjectFieldResult & {
+                   *   parentNode: import('jsdoc-type-pratt-parser').ObjectResult
+                   * }}
+                   */
+                  (objectField).parentNode;
+
+                const index = obj.elements.indexOf(parentNode);
+
+                obj.elements[index] = {
+                  /* c8 ignore next 5 -- Guard */
+                  meta: nde.meta ?
+                    {
+                      quote: objectField.meta.quote,
+                      ...nde.meta,
+                    } :
+                    {
+                      quote: objectField.meta.quote,
+                    },
+                  name: /** @type {string} */ (objectField.key),
+                  parameters: nde.parameters,
+                  returnType: /** @type {import('jsdoc-type-pratt-parser').RootResult} */ (
+                    nde.returnType
+                  ),
+                  type: 'JsdocTypeMethodSignature',
+                  typeParameters: nde.typeParameters,
+                };
+
+                rewireByParsedType(jsdoc, tag, parsedType, indent);
+              } : null,
+            );
+            break;
+          }
+
+          if (parentNode?.type === 'JsdocTypeParenthesis' &&
+            // @ts-expect-error Our own added API
+            parentNode.parentNode?.type === 'JsdocTypeIntersection' &&
+            // @ts-expect-error Our own added API
+            parentNode.parentNode.parentNode.type === 'JsdocTypeObjectField' &&
+            // @ts-expect-error Our own added API
+            typeof parentNode.parentNode.parentNode.key === 'string'
+          ) {
+            // @ts-expect-error Our own added API
+            const intersection = parentNode.parentNode;
+            const objectField = intersection.parentNode;
+            const object = objectField.parentNode;
+            // const objFieldIndex = object.elements.indexOf(objectField);
+
+            /**
+             * @param {import('jsdoc-type-pratt-parser').FunctionResult} func
+             */
+            const convertToMethod = (func) => {
+              return /** @type {import('jsdoc-type-pratt-parser').MethodSignatureResult} */ ({
+                /* c8 ignore next 5 -- Guard */
+                meta: func.meta ?
+                  {
+                    quote: objectField.meta.quote,
+                    ...func.meta,
+                  } :
+                  {
+                    quote: objectField.meta.quote,
+                  },
+                name: /** @type {string} */ (objectField.key),
+                parameters: func.parameters,
+                returnType: /** @type {import('jsdoc-type-pratt-parser').RootResult} */ (
+                  func.returnType
+                ),
+                type: 'JsdocTypeMethodSignature',
+                typeParameters: func.typeParameters,
+              });
+            };
+
+            /** @type {import('jsdoc-type-pratt-parser').MethodSignatureResult[]} */
+            const methods = [];
+            /** @type {number[]} */
+            const methodIndexes = [];
+            for (const [
+              index,
+              element,
+            ] of intersection.elements.entries()) {
+              if (
+                element.type !== 'JsdocTypeParenthesis' ||
+                element.element.type !== 'JsdocTypeFunction'
+              ) {
+                return;
+              }
+
+              methods.push(convertToMethod(element.element));
+              methodIndexes.push(index);
+            }
+
+            utils.reportJSDoc(
+              'Found function property; prefer method signature.',
+              tag,
+              enableFixer ? () => {
+                for (const methodIndex of methodIndexes.toReversed()) {
+                  object.elements.splice(methodIndex, 1);
+                }
+
+                object.elements.splice(methodIndexes[0], 0, ...methods);
+
+                rewireByParsedType(jsdoc, tag, parsedType, indent);
+              } : null,
+            );
+          }
+
+          break;
+        }
+
+        case 'JsdocTypeMethodSignature': {
+          if (functionType !== 'property') {
+            break;
+          }
+
+          /**
+           * @param {import('jsdoc-type-pratt-parser').MethodSignatureResult} node
+           */
+          const convertToFunction = (node) => {
+            return {
+              arrow: true,
+              constructor: false,
+              meta: /** @type {Required<import('jsdoc-type-pratt-parser').MethodSignatureResult['meta']>} */ (
+                node.meta
+              ),
+              parameters: node.parameters,
+              parenthesis: true,
+              returnType: node.returnType,
+              type: 'JsdocTypeFunction',
+              typeParameters: node.typeParameters,
+            };
+          };
+
+          utils.reportJSDoc(
+            'Found method signature; prefer function property.',
+            tag,
+            enableFixer ? () => {
+              /* c8 ignore next 3 -- TS guard */
+              if (!parentNode || !property || typeof idx !== 'number') {
+                throw new Error('Unexpected lack of parent or property');
+              }
+
+              const object = /** @type {import('jsdoc-type-pratt-parser').ObjectResult} */ (
+                parentNode
+              );
+
+              const funcs = [];
+              const removals = [];
+
+              for (const [
+                index,
+                element,
+              ] of object.elements.entries()) {
+                if (element.type === 'JsdocTypeMethodSignature' &&
+                  element.name === nde.name
+                ) {
+                  funcs.push(convertToFunction(element));
+                  if (index !== idx) {
+                    removals.push(index);
+                  }
+                }
+              }
+
+              if (funcs.length === 1) {
+                object.elements[idx] = /** @type {import('jsdoc-type-pratt-parser').ObjectFieldResult} */ ({
+                  key: nde.name,
+                  meta: nde.meta,
+                  optional: false,
+                  readonly: false,
+                  right: funcs[0],
+                  type: 'JsdocTypeObjectField',
+                });
+              } else {
+                for (const removal of removals.toReversed()) {
+                  object.elements.splice(removal, 1);
+                }
+
+                object.elements[idx] = {
+                  key: nde.name,
+                  meta: nde.meta,
+                  optional: false,
+                  readonly: false,
+                  right: {
+                    elements: funcs.map((func) => {
+                      return /** @type {import('jsdoc-type-pratt-parser').ParenthesisResult} */ ({
+                        element: func,
+                        type: 'JsdocTypeParenthesis',
+                      });
+                    }),
+                    type: 'JsdocTypeIntersection',
+                  },
+                  type: 'JsdocTypeObjectField',
+                };
+              }
+
+              rewireByParsedType(jsdoc, tag, parsedType, indent);
+            } : null,
+          );
+        }
+
+          break;
+      }
+    });
+  };
+
+  const tags = utils.filterTags(({
+    tag,
+  }) => {
+    return Boolean(tag !== 'import' && utils.tagMightHaveTypePosition(tag));
+  });
+
+  for (const tag of tags) {
+    if (tag.type) {
+      checkType(tag);
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Prefers either function properties or method signatures',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/ts-method-signature-style.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        enum: [
+          'method',
+          'property',
+        ],
+        type: 'string',
+      },
+      {
+        additionalProperties: false,
+        properties: {
+          enableFixer: {
+            description: 'Whether to enable the fixer. Defaults to `true`.',
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/tsNoEmptyObjectType.js

@@ -0,0 +1,61 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  parse as parseType,
+  traverse,
+} from '@es-joy/jsdoccomment';
+
+export default iterateJsdoc(({
+  settings,
+  utils,
+}) => {
+  if (settings.mode !== 'typescript') {
+    return;
+  }
+
+  /**
+   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
+   */
+  const checkType = (tag) => {
+    const potentialType = tag.type;
+    let parsedType;
+    try {
+      parsedType = parseType(
+        /** @type {string} */ (potentialType), 'typescript',
+      );
+    } catch {
+      return;
+    }
+
+    traverse(parsedType, (nde) => {
+      switch (nde.type) {
+        case 'JsdocTypeObject': {
+          if (!nde.elements.length) {
+            utils.reportJSDoc('No empty object type.', tag);
+          }
+        }
+      }
+    });
+  };
+
+  const tags = utils.filterTags(({
+    tag,
+  }) => {
+    return Boolean(tag !== 'import' && utils.tagMightHaveTypePosition(tag));
+  });
+
+  for (const tag of tags) {
+    if (tag.type) {
+      checkType(tag);
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Warns against use of the empty object type',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/ts-no-empty-object-type.md#repos-sticky-header',
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+});

package/src/rules/tsNoUnnecessaryTemplateExpression.js

@@ -0,0 +1,130 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  rewireByParsedType,
+} from '../jsdocUtils.js';
+import {
+  parse as parseType,
+  traverse,
+} from '@es-joy/jsdoccomment';
+
+export default iterateJsdoc(({
+  context,
+  indent,
+  jsdoc,
+  settings,
+  utils,
+}) => {
+  if (settings.mode !== 'typescript') {
+    return;
+  }
+
+  const {
+    enableFixer = true,
+  } = context.options[0] ?? {};
+
+  /**
+   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
+   */
+  const checkType = (tag) => {
+    const potentialType = tag.type;
+    /** @type {import('jsdoc-type-pratt-parser').RootResult} */
+    let parsedType;
+    try {
+      parsedType = parseType(
+        /** @type {string} */ (potentialType), 'typescript',
+      );
+    } catch {
+      return;
+    }
+
+    traverse(parsedType, (nde, parentNode, property, index) => {
+      switch (nde.type) {
+        case 'JsdocTypeTemplateLiteral': {
+          const stringInterpolationIndex = nde.interpolations.findIndex((interpolation) => {
+            return interpolation.type === 'JsdocTypeStringValue';
+          });
+          if (stringInterpolationIndex > -1) {
+            utils.reportJSDoc(
+              'Found an unnecessary string literal within a template.',
+              tag,
+              enableFixer ? () => {
+                nde.literals.splice(
+                  stringInterpolationIndex,
+                  2,
+                  nde.literals[stringInterpolationIndex] +
+                    /** @type {import('jsdoc-type-pratt-parser').StringValueResult} */
+                    (nde.interpolations[stringInterpolationIndex]).value +
+                    nde.literals[stringInterpolationIndex + 1],
+                );
+
+                nde.interpolations.splice(
+                  stringInterpolationIndex, 1,
+                );
+
+                rewireByParsedType(jsdoc, tag, parsedType, indent);
+              } : null,
+            );
+          } else if (nde.literals.length === 2 && nde.literals[0] === '' &&
+            nde.literals[1] === ''
+          ) {
+            utils.reportJSDoc(
+              'Found a lone template expression within a template.',
+              tag,
+              enableFixer ? () => {
+                const interpolation = nde.interpolations[0];
+
+                if (parentNode && property) {
+                  if (typeof index === 'number') {
+                    // @ts-expect-error Safe
+                    parentNode[property][index] = interpolation;
+                  } else {
+                    // @ts-expect-error Safe
+                    parentNode[property] = interpolation;
+                  }
+                } else {
+                  parsedType = interpolation;
+                }
+
+                rewireByParsedType(jsdoc, tag, parsedType, indent);
+              } : null,
+            );
+          }
+        }
+      }
+    });
+  };
+
+  const tags = utils.filterTags(({
+    tag,
+  }) => {
+    return Boolean(tag !== 'import' && utils.tagMightHaveTypePosition(tag));
+  });
+
+  for (const tag of tags) {
+    if (tag.type) {
+      checkType(tag);
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Catches unnecessary template expressions such as string expressions within a template literal.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/ts-no-unnecessary-template-expression.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          enableFixer: {
+            description: 'Whether to enable the fixer. Defaults to `true`.',
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});