eslint-plugin-jsdoc 52.0.4 → 53.0.1

package/src/rules/emptyTags.js

@@ -1,98 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-const defaultEmptyTags = new Set([
-  'abstract', 'async', 'generator', 'global', 'hideconstructor',
-
-  // jsdoc doesn't use this form in its docs, but allow for compatibility with
-  //  TypeScript which allows and Closure which requires
-  'ignore',
-
-  // jsdoc doesn't use but allow for TypeScript
-  'inheritDoc', 'inner', 'instance',
-  'internal',
-
-  'overload',
-
-  'override',
-  'readonly',
-]);
-
-const emptyIfNotClosure = new Set([
-  // Closure doesn't allow with this casing
-  'inheritdoc', 'package', 'private', 'protected', 'public',
-
-  'static',
-]);
-
-const emptyIfClosure = new Set([
-  'interface',
-]);
-
-export default iterateJsdoc(({
-  jsdoc,
-  settings,
-  utils,
-}) => {
-  const emptyTags = utils.filterTags(({
-    tag: tagName,
-  }) => {
-    return defaultEmptyTags.has(tagName) ||
-      utils.hasOptionTag(tagName) && jsdoc.tags.some(({
-        tag,
-      }) => {
-        return tag === tagName;
-      }) ||
-      settings.mode === 'closure' && emptyIfClosure.has(tagName) ||
-      settings.mode !== 'closure' && emptyIfNotClosure.has(tagName);
-  });
-
-  for (const [
-    key,
-    tag,
-  ] of emptyTags.entries()) {
-    const content = tag.name || tag.description || tag.type;
-    if (content.trim() && (
-      // Allow for JSDoc-block final asterisks
-      key !== emptyTags.length - 1 || !(/^\s*\*+$/v).test(content)
-    )) {
-      const fix = () => {
-        // By time of call in fixer, `tag` will have `line` added
-        utils.setTag(
-          /**
-           * @type {import('comment-parser').Spec & {
-           *   line: import('../iterateJsdoc.js').Integer
-           * }}
-           */ (tag),
-        );
-      };
-
-      utils.reportJSDoc(`@${tag.tag} should be empty.`, tag, fix, true);
-    }
-  }
-}, {
-  checkInternal: true,
-  checkPrivate: true,
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Expects specific tags to be empty of any content.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/empty-tags.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          tags: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/implementsOnClasses.js

@@ -1,64 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  report,
-  utils,
-}) => {
-  const iteratingFunction = utils.isIteratingFunction();
-
-  if (iteratingFunction) {
-    if (utils.hasATag([
-      'class',
-      'constructor',
-    ]) ||
-      utils.isConstructor()
-    ) {
-      return;
-    }
-  } else if (!utils.isVirtualFunction()) {
-    return;
-  }
-
-  utils.forEachPreferredTag('implements', (tag) => {
-    report('@implements used on a non-constructor function', null, tag);
-  });
-}, {
-  contextDefaults: true,
-  meta: {
-    docs: {
-      description: 'Reports an issue with any non-constructor function using `@implements`.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/implements-on-classes.md#repos-sticky-header',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          contexts: {
-            items: {
-              anyOf: [
-                {
-                  type: 'string',
-                },
-                {
-                  additionalProperties: false,
-                  properties: {
-                    comment: {
-                      type: 'string',
-                    },
-                    context: {
-                      type: 'string',
-                    },
-                  },
-                  type: 'object',
-                },
-              ],
-            },
-            type: 'array',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/importsAsDependencies.js

@@ -1,133 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-import {
-  parse,
-  traverse,
-  tryParse,
-} from '@es-joy/jsdoccomment';
-import {
-  readFileSync,
-} from 'fs';
-import {
-  isBuiltin as isBuiltinModule,
-} from 'node:module';
-import {
-  join,
-} from 'path';
-
-/**
- * @type {Set<string>|null}
- */
-let deps;
-
-const setDeps = function () {
-  try {
-    const pkg = JSON.parse(
-      // @ts-expect-error It's ok
-      readFileSync(join(process.cwd(), './package.json')),
-    );
-    deps = new Set([
-      ...(pkg.dependencies ?
-        /* c8 ignore next 2 */
-        Object.keys(pkg.dependencies) :
-        []),
-      ...(pkg.devDependencies ?
-        /* c8 ignore next 2 */
-        Object.keys(pkg.devDependencies) :
-        []),
-    ]);
-  /* c8 ignore next -- our package.json exists */
-  } catch (error) {
-    /* c8 ignore next -- our package.json exists */
-    deps = null;
-    /* c8 ignore next 4 -- our package.json exists */
-    /* eslint-disable no-console -- Inform user */
-    console.log(error);
-    /* eslint-enable no-console -- Inform user */
-  }
-};
-
-const moduleCheck = new Map();
-
-export default iterateJsdoc(({
-  jsdoc,
-  settings,
-  utils,
-}) => {
-  if (deps === undefined) {
-    setDeps();
-  }
-
-  /* c8 ignore next 3 -- our package.json exists */
-  if (deps === null) {
-    return;
-  }
-
-  const {
-    mode,
-  } = settings;
-
-  for (const tag of jsdoc.tags) {
-    let typeAst;
-    try {
-      typeAst = mode === 'permissive' ? tryParse(tag.type) : parse(tag.type, mode);
-    } catch {
-      continue;
-    }
-
-    // eslint-disable-next-line no-loop-func -- Safe
-    traverse(typeAst, (nde) => {
-      /* c8 ignore next 3 -- TS guard */
-      if (deps === null) {
-        return;
-      }
-
-      if (nde.type === 'JsdocTypeImport') {
-        let mod = nde.element.value.replace(
-          /^(@[^\/]+\/[^\/]+|[^\/]+).*$/v, '$1',
-        );
-
-        if ((/^[.\/]/v).test(mod)) {
-          return;
-        }
-
-        if (isBuiltinModule(mod)) {
-          // mod = '@types/node';
-          // moduleCheck.set(mod, !deps.has(mod));
-          return;
-        } else if (!moduleCheck.has(mod)) {
-          let pkg;
-          try {
-            pkg = JSON.parse(
-              // @ts-expect-error It's ok
-              readFileSync(join(process.cwd(), 'node_modules', mod, './package.json')),
-            );
-          } catch {
-            // Ignore
-          }
-
-          if (!pkg || (!pkg.types && !pkg.typings)) {
-            mod = `@types/${mod}`;
-          }
-
-          moduleCheck.set(mod, !deps.has(mod));
-        }
-
-        if (moduleCheck.get(mod)) {
-          utils.reportJSDoc(
-            'import points to package which is not found in dependencies',
-            tag,
-          );
-        }
-      }
-    });
-  }
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Reports if JSDoc `import()` statements point to a package which is not listed in `dependencies` or `devDependencies`',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/imports-as-dependencies.md#repos-sticky-header',
-    },
-    type: 'suggestion',
-  },
-});

package/src/rules/informativeDocs.js

@@ -1,189 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-import {
-  areDocsInformative,
-} from 'are-docs-informative';
-
-const defaultAliases = {
-  a: [
-    'an', 'our',
-  ],
-};
-
-const defaultUselessWords = [
-  'a', 'an', 'i', 'in', 'of', 's', 'the',
-];
-
-/* eslint-disable complexity -- Temporary */
-
-/**
- * @param {import('eslint').Rule.Node|import('@typescript-eslint/types').TSESTree.Node|null|undefined} node
- * @returns {string[]}
- */
-const getNamesFromNode = (node) => {
-  switch (node?.type) {
-    case 'AccessorProperty':
-    case 'MethodDefinition':
-    case 'PropertyDefinition':
-    case 'TSAbstractAccessorProperty':
-    case 'TSAbstractMethodDefinition':
-    case 'TSAbstractPropertyDefinition':
-      return [
-        ...getNamesFromNode(
-        /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (
-            node.parent
-          ).parent,
-        ),
-        ...getNamesFromNode(
-        /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-          (node.key),
-        ),
-      ];
-
-    case 'ClassDeclaration':
-    case 'ClassExpression':
-    case 'FunctionDeclaration':
-    case 'FunctionExpression':
-    case 'TSDeclareFunction':
-    case 'TSEnumDeclaration':
-    case 'TSEnumMember':
-    case 'TSInterfaceDeclaration':
-    case 'TSMethodSignature':
-    case 'TSModuleDeclaration':
-    case 'TSTypeAliasDeclaration':
-      return getNamesFromNode(
-      /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */
-        (node).id,
-      );
-    case 'ExportDefaultDeclaration':
-    case 'ExportNamedDeclaration':
-      return getNamesFromNode(
-      /** @type {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration} */
-        (node).declaration,
-      );
-    case 'Identifier':
-      return [
-        node.name,
-      ];
-    case 'Property':
-      return getNamesFromNode(
-      /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-        (node.key),
-      );
-    case 'VariableDeclaration':
-      return getNamesFromNode(
-      /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-        (node.declarations[0]),
-      );
-    case 'VariableDeclarator':
-      return [
-        ...getNamesFromNode(
-        /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-          (node.id),
-        ),
-        ...getNamesFromNode(
-        /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-          (node.init),
-        ),
-      ].filter(Boolean);
-    default:
-      return [];
-  }
-};
-/* eslint-enable complexity -- Temporary */
-
-export default iterateJsdoc(({
-  context,
-  jsdoc,
-  node,
-  report,
-  utils,
-}) => {
-  const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */ {
-    aliases = defaultAliases,
-    excludedTags = [],
-    uselessWords = defaultUselessWords,
-  } = context.options[0] || {};
-  const nodeNames = getNamesFromNode(node);
-
-  /**
-   * @param {string} text
-   * @param {string} extraName
-   * @returns {boolean}
-   */
-  const descriptionIsRedundant = (text, extraName = '') => {
-    const textTrimmed = text.trim();
-    return Boolean(textTrimmed) && !areDocsInformative(textTrimmed, [
-      extraName, nodeNames,
-    ].filter(Boolean).join(' '), {
-      aliases,
-      uselessWords,
-    });
-  };
-
-  const {
-    description,
-    lastDescriptionLine,
-  } = utils.getDescription();
-  let descriptionReported = false;
-
-  for (const tag of jsdoc.tags) {
-    if (excludedTags.includes(tag.tag)) {
-      continue;
-    }
-
-    if (descriptionIsRedundant(tag.description, tag.name)) {
-      utils.reportJSDoc(
-        'This tag description only repeats the name it describes.',
-        tag,
-      );
-    }
-
-    descriptionReported ||= tag.description === description &&
-      /** @type {import('comment-parser').Spec & {line: import('../iterateJsdoc.js').Integer}} */
-      (tag).line === lastDescriptionLine;
-  }
-
-  if (!descriptionReported && descriptionIsRedundant(description)) {
-    report('This description only repeats the name it describes.');
-  }
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description:
-        'This rule reports doc comments that only restate their attached name.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md#repos-sticky-header',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          aliases: {
-            patternProperties: {
-              '.*': {
-                items: {
-                  type: 'string',
-                },
-                type: 'array',
-              },
-            },
-          },
-          excludedTags: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-          uselessWords: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/linesBeforeBlock.js

@@ -1,134 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-/**
- * Punctuators that begin a logical group should not require a line before it skipped. Specifically
- * `[` starts an array, `{` starts an object or block, `(` starts a grouping, and `=` starts a
- * declaration (like a variable or a type alias).
- */
-const startPunctuators = new Set([
-  '(', '=', '[', '{',
-]);
-
-export default iterateJsdoc(({
-  context,
-  jsdocNode,
-  report,
-  sourceCode,
-  utils,
-}) => {
-  const {
-    checkBlockStarts,
-    excludedTags = [
-      'type',
-    ],
-    ignoreSameLine = true,
-    ignoreSingleLines = true,
-    lines = 1,
-  } = context.options[0] || {};
-
-  if (utils.hasATag(excludedTags)) {
-    return;
-  }
-
-  const tokensBefore = sourceCode.getTokensBefore(jsdocNode, {
-    includeComments: true,
-  });
-  const tokenBefore = tokensBefore.at(-1);
-  if (
-    !tokenBefore || (
-      tokenBefore.type === 'Punctuator' &&
-      !checkBlockStarts &&
-      startPunctuators.has(tokenBefore.value)
-    )
-  ) {
-    return;
-  }
-
-  if (tokenBefore.loc?.end?.line + lines >=
-  /** @type {number} */
-      (jsdocNode.loc?.start?.line)
-  ) {
-    const startLine = jsdocNode.loc?.start?.line;
-    const sameLine = tokenBefore.loc?.end?.line === startLine;
-
-    if (sameLine && ignoreSameLine) {
-      return;
-    }
-
-    if (ignoreSingleLines && jsdocNode.loc?.start.line === jsdocNode.loc?.end.line) {
-      return;
-    }
-
-    /** @type {import('eslint').Rule.ReportFixer} */
-    const fix = (fixer) => {
-      let indent = '';
-      if (sameLine) {
-        const spaceDiff = /** @type {number} */ (jsdocNode.loc?.start?.column) -
-        /** @type {number} */ (tokenBefore.loc?.end?.column);
-        // @ts-expect-error Should be a comment
-        indent = /** @type {import('estree').Comment} */ (
-          jsdocNode
-        ).value.match(/^\*\n([\t ]*) \*/v)?.[1]?.slice(spaceDiff);
-        if (!indent) {
-          /** @type {import('eslint').AST.Token|import('estree').Comment|undefined} */
-          let tokenPrior = tokenBefore;
-          let startColumn;
-          while (tokenPrior && tokenPrior?.loc?.start?.line === startLine) {
-            startColumn = tokenPrior.loc?.start?.column;
-            tokenPrior = tokensBefore.pop();
-          }
-
-          indent = ' '.repeat(
-            /* c8 ignore next */
-            /** @type {number} */ (startColumn ? startColumn - 1 : 0),
-          );
-        }
-      }
-
-      return fixer.insertTextAfter(
-        /** @type {import('eslint').AST.Token} */
-        (tokenBefore),
-        '\n'.repeat(lines) +
-        (sameLine ? '\n' + indent : ''),
-      );
-    };
-
-    report(`Required ${lines} line(s) before JSDoc block`, fix);
-  }
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Enforces minimum number of newlines before JSDoc comment blocks',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/lines-before-block.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          checkBlockStarts: {
-            type: 'boolean',
-          },
-          excludedTags: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-          ignoreSameLine: {
-            type: 'boolean',
-          },
-          ignoreSingleLines: {
-            type: 'boolean',
-          },
-          lines: {
-            type: 'integer',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});