eslint-plugin-jsdoc 61.0.1 → 61.1.1

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',
+  },
+});

package/src/rules/tsPreferFunctionType.js

@@ -0,0 +1,127 @@
+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 {
+    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) => {
+      // @ts-expect-error Adding our own property for use below
+      nde.parentNode = parentNode;
+    });
+
+    traverse(parsedType, (nde, parentNode, property, index) => {
+      switch (nde.type) {
+        case 'JsdocTypeCallSignature': {
+          const object = /** @type {import('jsdoc-type-pratt-parser').ObjectResult} */ (
+            parentNode
+          );
+          if (typeof index === 'number' && object.elements.length === 1) {
+            utils.reportJSDoc(
+              'Call signature found; function type preferred.',
+              tag,
+              enableFixer ? () => {
+                const func = /** @type {import('jsdoc-type-pratt-parser').FunctionResult} */ ({
+                  arrow: true,
+                  constructor: false,
+                  meta: /** @type {Required<import('jsdoc-type-pratt-parser').MethodSignatureResult['meta']>} */ (
+                    nde.meta
+                  ),
+                  parameters: nde.parameters,
+                  parenthesis: true,
+                  returnType: nde.returnType,
+                  type: 'JsdocTypeFunction',
+                  typeParameters: nde.typeParameters,
+                });
+
+                if (property && 'parentNode' in object && object.parentNode) {
+                  if (typeof object.parentNode === 'object' &&
+                      'elements' in object.parentNode &&
+                      Array.isArray(object.parentNode.elements)
+                  ) {
+                    const idx = object.parentNode.elements.indexOf(object);
+                    object.parentNode.elements[idx] = func;
+                  /* c8 ignore next 6 -- Guard */
+                  } else {
+                    throw new Error(
+                      // @ts-expect-error Ok
+                      `Rule currently unable to handle type ${object.parentNode.type}`,
+                    );
+                  }
+                } else {
+                  parsedType = func;
+                }
+
+                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 function types over call signatures when there are no other properties.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/ts-prefer-function-type.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          enableFixer: {
+            description: 'Whether to enable the fixer or not',
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/typeFormatting.js

@@ -1,4 +1,7 @@
 import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  rewireByParsedType,
+} from '../jsdocUtils.js';
 import {
   parse as parseType,
   stringify,
@@ -67,156 +70,7 @@ export default iterateJsdoc(({
     }
 
     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 = 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: '',
-            } : {}),
-            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
-      ) {
-        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 (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,
-              };
-            }),
-          );
-        }
-      }
-
-      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);
-      }
+      rewireByParsedType(jsdoc, tag, parsedType, indent, typeBracketSpacing);
     };
 
     /** @type {string[]} */

package/src/rules/validTypes.js

@@ -366,7 +366,7 @@ export default iterateJsdoc(({
 
     // VALID TYPE
     const hasTypePosition = mightHaveTypePosition === true && Boolean(tag.type);
-    if (hasTypePosition) {
+    if (hasTypePosition && (tag.type !== 'const' || tag.tag !== 'type')) {
       validTypeParsing(tag.type);
     }
 

package/src/rules.d.ts

@@ -2938,6 +2938,47 @@ export interface Rules {
         }
       ];
 
+  /** Prefers either function properties or method signatures */
+  "jsdoc/ts-method-signature-style": 
+    | []
+    | ["method" | "property"]
+    | [
+        "method" | "property",
+        {
+          /**
+           * Whether to enable the fixer. Defaults to `true`.
+           */
+          enableFixer?: boolean;
+        }
+      ];
+
+  /** Warns against use of the empty object type */
+  "jsdoc/ts-no-empty-object-type": [];
+
+  /** Catches unnecessary template expressions such as string expressions within a template literal. */
+  "jsdoc/ts-no-unnecessary-template-expression": 
+    | []
+    | [
+        {
+          /**
+           * Whether to enable the fixer. Defaults to `true`.
+           */
+          enableFixer?: boolean;
+        }
+      ];
+
+  /** Prefers function types over call signatures when there are no other properties. */
+  "jsdoc/ts-prefer-function-type": 
+    | []
+    | [
+        {
+          /**
+           * Whether to enable the fixer or not
+           */
+          enableFixer?: boolean;
+        }
+      ];
+
   /** Formats JSDoc type values. */
   "jsdoc/type-formatting": 
     | []