eslint-plugin-jsdoc 64.4.0 → 64.5.0

package/README.md

@@ -552,6 +552,7 @@ non-default-recommended fixer).
 ||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
 |:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) before, after, or between tags. |
 ||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |
+|Off in TS; On in TS flavor|| [ts-ban-ts-comment](./docs/rules/ts-ban-ts-comment.md#readme) | Disallows (or requires descriptions for) `@ts-<directive>` comments, mirroring `@typescript-eslint/ban-ts-comment`. |
 ||:wrench:| [ts-method-signature-style](./docs/rules/ts-method-signature-style.md#readme) | Prefers either function properties or method signatures |
 |:heavy_check_mark:|| [ts-no-empty-object-type](./docs/rules/ts-no-empty-object-type.md#readme) | Warns against use of the empty object type |
 ||:wrench:| [ts-no-unnecessary-template-expression](./docs/rules/ts-no-unnecessary-template-expression.md#readme) | Catches unnecessary template expressions such as string expressions within a template literal. |

package/dist/rules/tsBanTsComment.d.ts

@@ -0,0 +1,13 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;
+export type DirectiveConfig = boolean | "allow-with-description" | {
+    descriptionFormat: string;
+};
+export type OptionsShape = {
+    minimumDescriptionLength?: number;
+    "ts-check"?: DirectiveConfig;
+    "ts-expect-error"?: DirectiveConfig;
+    "ts-ignore"?: DirectiveConfig;
+    "ts-nocheck"?: DirectiveConfig;
+};
+//# sourceMappingURL=tsBanTsComment.d.ts.map

package/dist/rules.d.ts

@@ -3065,6 +3065,66 @@ export interface Rules {
         }
       ];
 
+  /** Disallows (or requires descriptions for) `@ts-<directive>` comments, mirroring `@typescript-eslint/ban-ts-comment`. */
+  "jsdoc/ts-ban-ts-comment": 
+    | []
+    | [
+        {
+          /**
+           * A minimum character length for descriptions when `allow-with-description` is enabled. Defaults to `3`.
+           */
+          minimumDescriptionLength?: number;
+          /**
+           * Whether (and how) to allow `@ts-check` directives.
+           */
+          "ts-check"?:
+            | boolean
+            | "allow-with-description"
+            | {
+                /**
+                 * A regular expression indicating the format the directive should follow
+                 */
+                descriptionFormat?: string;
+              };
+          /**
+           * Whether (and how) to allow `@ts-expect-error` directives.
+           */
+          "ts-expect-error"?:
+            | boolean
+            | "allow-with-description"
+            | {
+                /**
+                 * A regular expression indicating the format the directive should follow
+                 */
+                descriptionFormat?: string;
+              };
+          /**
+           * Whether (and how) to allow `@ts-ignore` directives.
+           */
+          "ts-ignore"?:
+            | boolean
+            | "allow-with-description"
+            | {
+                /**
+                 * A regular expression indicating the format the directive should follow
+                 */
+                descriptionFormat?: string;
+              };
+          /**
+           * Whether (and how) to allow `@ts-nocheck` directives.
+           */
+          "ts-nocheck"?:
+            | boolean
+            | "allow-with-description"
+            | {
+                /**
+                 * A regular expression indicating the format the directive should follow
+                 */
+                descriptionFormat?: string;
+              };
+        }
+      ];
+
   /** Prefers either function properties or method signatures */
   "jsdoc/ts-method-signature-style": 
     | []

package/package.json

@@ -157,5 +157,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.4.0"
+  "version": "64.5.0"
 }

package/src/index.js

@@ -69,6 +69,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 tsBanTsComment from './rules/tsBanTsComment.js';
 import tsMethodSignatureStyle from './rules/tsMethodSignatureStyle.js';
 import tsNoEmptyObjectType from './rules/tsNoEmptyObjectType.js';
 import tsNoUnnecessaryTemplateExpression from './rules/tsNoUnnecessaryTemplateExpression.js';
@@ -270,6 +271,7 @@ index.rules = {
   'sort-tags': sortTags,
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
+  'ts-ban-ts-comment': tsBanTsComment,
   'ts-method-signature-style': tsMethodSignatureStyle,
   'ts-no-empty-object-type': tsNoEmptyObjectType,
   'ts-no-unnecessary-template-expression': tsNoUnnecessaryTemplateExpression,
@@ -367,6 +369,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',
+      'jsdoc/ts-ban-ts-comment': 'off',
       'jsdoc/ts-method-signature-style': 'off',
       'jsdoc/ts-no-empty-object-type': warnOrError,
       'jsdoc/ts-no-unnecessary-template-expression': 'off',
@@ -440,6 +443,7 @@ const createRecommendedTypeScriptFlavorRuleset = (warnOrError, flatName) => {
       ...ruleset.rules,
       /* eslint-disable @stylistic/indent -- Extra indent to avoid use by auto-rule-editing */
         'jsdoc/no-undefined-types': 'off',
+        'jsdoc/ts-ban-ts-comment': warnOrError,
       /* eslint-enable @stylistic/indent */
     },
   };

package/src/rules/tsBanTsComment.js

@@ -0,0 +1,295 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+/**
+ * @typedef {boolean|'allow-with-description'|{descriptionFormat: string}} DirectiveConfig
+ */
+
+/**
+ * @typedef {{
+ *   minimumDescriptionLength?: number,
+ *   'ts-check'?: DirectiveConfig,
+ *   'ts-expect-error'?: DirectiveConfig,
+ *   'ts-ignore'?: DirectiveConfig,
+ *   'ts-nocheck'?: DirectiveConfig,
+ * }} OptionsShape
+ */
+
+const defaultMinimumDescriptionLength = 3;
+
+// https://github.com/microsoft/TypeScript/blob/main/src/compiler/parser.ts
+const singleLinePragmaRegExp =
+  /^\/\/\/?\s*@ts-(?<directive>check|nocheck)(?<description>.*)$/v;
+
+// https://github.com/microsoft/TypeScript/blob/main/src/compiler/scanner.ts
+const commentDirectiveRegExpSingleLine =
+  /^\/*\s*@ts-(?<directive>expect-error|ignore)(?<description>.*)/v;
+const commentDirectiveRegExpMultiLine =
+  /^\s*(?:\/|\*)*\s*@ts-(?<directive>expect-error|ignore)(?<description>.*)/v;
+
+const lineBreakRegExp = /\r\n|\r|\n/v;
+
+/**
+ * @param {RegExp} regExp
+ * @param {string} str
+ * @returns {{description: string, directive: string}|null}
+ */
+const execDirectiveRegExp = (regExp, str) => {
+  const match = regExp.exec(str);
+  if (!match?.groups) {
+    return null;
+  }
+
+  return {
+    description: /** @type {string} */ (match.groups.description),
+    directive: /** @type {string} */ (match.groups.directive),
+  };
+};
+
+/**
+ * @param {import('estree').Comment} comment
+ * @returns {{description: string, directive: string}|null}
+ */
+const findDirectiveInComment = (comment) => {
+  if (comment.type === 'Line') {
+    const matchedPragma = execDirectiveRegExp(singleLinePragmaRegExp, `//${comment.value}`);
+    if (matchedPragma) {
+      return matchedPragma;
+    }
+
+    return execDirectiveRegExp(commentDirectiveRegExpSingleLine, comment.value);
+  }
+
+  const commentLines = comment.value.split(lineBreakRegExp);
+
+  return execDirectiveRegExp(
+    commentDirectiveRegExpMultiLine,
+    /** @type {string} */ (commentLines.at(-1)),
+  );
+};
+
+export default iterateJsdoc(({
+  allComments,
+  context,
+  makeReport,
+  sourceCode,
+}) => {
+  const [
+    {
+      minimumDescriptionLength = defaultMinimumDescriptionLength,
+      'ts-check': tsCheck = false,
+      'ts-expect-error': tsExpectError = 'allow-with-description',
+      'ts-ignore': tsIgnore = true,
+      'ts-nocheck': tsNoCheck = true,
+    } = /** @type {OptionsShape} */ ({}),
+  ] = /** @type {[OptionsShape]} */ (context.options);
+
+  /** @type {{[key: string]: DirectiveConfig}} */
+  const directiveOptions = {
+    'ts-check': tsCheck,
+    'ts-expect-error': tsExpectError,
+    'ts-ignore': tsIgnore,
+    'ts-nocheck': tsNoCheck,
+  };
+
+  const firstStatement = sourceCode.ast.body.at(0);
+
+  for (const comment of /** @type {import('estree').Comment[]} */ (
+    /** @type {unknown} */ (allComments)
+  )) {
+    const match = findDirectiveInComment(comment);
+    if (!match) {
+      continue;
+    }
+
+    const {
+      description,
+      directive,
+    } = match;
+
+    if (directive === 'nocheck' && firstStatement) {
+      const firstStatementLine = /** @type {import('eslint').AST.SourceLocation} */ (
+        firstStatement.loc
+      ).start.line;
+      const commentLine = /** @type {import('eslint').AST.SourceLocation} */ (
+        comment.loc
+      ).start.line;
+      if (firstStatementLine <= commentLine) {
+        continue;
+      }
+    }
+
+    const option = directiveOptions[`ts-${directive}`];
+
+    const report = /** @type {import('../iterateJsdoc.js').MakeReport} */ (
+      makeReport
+    )(context, /** @type {import('estree').Node} */ (/** @type {unknown} */ (comment)));
+
+    if (option === true) {
+      if (directive === 'ignore') {
+        report(
+          'Use "@ts-expect-error" instead of "@ts-ignore", as "@ts-ignore" will do nothing if the following line is error-free.',
+          null,
+          null,
+          undefined,
+          [
+            {
+              desc: 'Replace "@ts-ignore" with "@ts-expect-error".',
+              fix (fixer) {
+                const commentText = comment.value.replace('@ts-ignore', '@ts-expect-error');
+
+                return fixer.replaceText(
+                  /** @type {import('estree').Node & {range: [number, number]}} */ (
+                    /** @type {unknown} */ (comment)
+                  ),
+                  comment.type === 'Line' ? `//${commentText}` : `/*${commentText}*/`,
+                );
+              },
+            },
+          ],
+        );
+      } else {
+        report(`Do not use "@ts-${directive}" because it alters compilation errors.`);
+      }
+    } else if (
+      option === 'allow-with-description' ||
+      (typeof option === 'object' && option.descriptionFormat)
+    ) {
+      const trimmedDescription = description.trim();
+      if (trimmedDescription.length < minimumDescriptionLength) {
+        report(
+          `Include a description after the "@ts-${directive}" directive to explain why the @ts-${directive} is necessary. The description must be ${minimumDescriptionLength} characters or longer.`,
+        );
+      } else if (
+        typeof option === 'object' &&
+        option.descriptionFormat &&
+        !new RegExp(option.descriptionFormat, 'v').test(description)
+      ) {
+        report(
+          `The description for the "@ts-${directive}" directive must match the ${option.descriptionFormat} format.`,
+        );
+      }
+    }
+  }
+}, {
+  checkFile: true,
+  meta: {
+    docs: {
+      description: 'Disallows (or requires descriptions for) `@ts-<directive>` comments, mirroring `@typescript-eslint/ban-ts-comment`.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/ts-ban-ts-comment.md#repos-sticky-header',
+    },
+    hasSuggestions: true,
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          minimumDescriptionLength: {
+            description: 'A minimum character length for descriptions when `allow-with-description` is enabled. Defaults to `3`.',
+            type: 'integer',
+          },
+          'ts-check': {
+            description: 'Whether (and how) to allow `@ts-check` directives.',
+            oneOf: [
+              {
+                type: 'boolean',
+              },
+              {
+                description: 'Whether to allow the directive if a description is present',
+                enum: [
+                  'allow-with-description',
+                ],
+                type: 'string',
+              },
+              {
+                additionalProperties: false,
+                properties: {
+                  descriptionFormat: {
+                    description: 'A regular expression indicating the format the directive should follow',
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+            ],
+          },
+          'ts-expect-error': {
+            description: 'Whether (and how) to allow `@ts-expect-error` directives.',
+            oneOf: [
+              {
+                type: 'boolean',
+              },
+              {
+                description: 'Whether to allow the directive if a description is present',
+                enum: [
+                  'allow-with-description',
+                ],
+                type: 'string',
+              },
+              {
+                additionalProperties: false,
+                properties: {
+                  descriptionFormat: {
+                    description: 'A regular expression indicating the format the directive should follow',
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+            ],
+          },
+          'ts-ignore': {
+            description: 'Whether (and how) to allow `@ts-ignore` directives.',
+            oneOf: [
+              {
+                type: 'boolean',
+              },
+              {
+                description: 'Whether to allow the directive if a description is present',
+                enum: [
+                  'allow-with-description',
+                ],
+                type: 'string',
+              },
+              {
+                additionalProperties: false,
+                properties: {
+                  descriptionFormat: {
+                    description: 'A regular expression indicating the format the directive should follow',
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+            ],
+          },
+          'ts-nocheck': {
+            description: 'Whether (and how) to allow `@ts-nocheck` directives.',
+            oneOf: [
+              {
+                type: 'boolean',
+              },
+              {
+                description: 'Whether to allow the directive if a description is present',
+                enum: [
+                  'allow-with-description',
+                ],
+                type: 'string',
+              },
+              {
+                additionalProperties: false,
+                properties: {
+                  descriptionFormat: {
+                    description: 'A regular expression indicating the format the directive should follow',
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+            ],
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules.d.ts

@@ -3065,6 +3065,66 @@ export interface Rules {
         }
       ];
 
+  /** Disallows (or requires descriptions for) `@ts-<directive>` comments, mirroring `@typescript-eslint/ban-ts-comment`. */
+  "jsdoc/ts-ban-ts-comment": 
+    | []
+    | [
+        {
+          /**
+           * A minimum character length for descriptions when `allow-with-description` is enabled. Defaults to `3`.
+           */
+          minimumDescriptionLength?: number;
+          /**
+           * Whether (and how) to allow `@ts-check` directives.
+           */
+          "ts-check"?:
+            | boolean
+            | "allow-with-description"
+            | {
+                /**
+                 * A regular expression indicating the format the directive should follow
+                 */
+                descriptionFormat?: string;
+              };
+          /**
+           * Whether (and how) to allow `@ts-expect-error` directives.
+           */
+          "ts-expect-error"?:
+            | boolean
+            | "allow-with-description"
+            | {
+                /**
+                 * A regular expression indicating the format the directive should follow
+                 */
+                descriptionFormat?: string;
+              };
+          /**
+           * Whether (and how) to allow `@ts-ignore` directives.
+           */
+          "ts-ignore"?:
+            | boolean
+            | "allow-with-description"
+            | {
+                /**
+                 * A regular expression indicating the format the directive should follow
+                 */
+                descriptionFormat?: string;
+              };
+          /**
+           * Whether (and how) to allow `@ts-nocheck` directives.
+           */
+          "ts-nocheck"?:
+            | boolean
+            | "allow-with-description"
+            | {
+                /**
+                 * A regular expression indicating the format the directive should follow
+                 */
+                descriptionFormat?: string;
+              };
+        }
+      ];
+
   /** Prefers either function properties or method signatures */
   "jsdoc/ts-method-signature-style": 
     | []