@depup/eslint-plugin-jsdoc 62.8.0-depup.0

package/src/rules/escapeInlineTags.js

@@ -0,0 +1,189 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  settings,
+  utils,
+}) => {
+  const {
+    mode,
+  } = settings;
+
+  if (mode !== 'typescript') {
+    return;
+  }
+
+  const {
+    allowedInlineTags = [],
+    enableFixer = false,
+    fixType = 'backslash',
+  } = context.options[0] || {};
+
+  const {
+    description,
+  } = utils.getDescription();
+
+  /** @type {string[]} */
+  const tagNames = [];
+
+  /** @type {number[]} */
+  const indexes = [];
+
+  const unescapedInlineTagRegex = /(?:^|\s)@(\w+)/gv;
+  for (const [
+    idx,
+    descLine,
+  ] of (
+      description.startsWith('\n') ? description.slice(1) : description
+    ).split('\n').entries()
+  ) {
+    descLine.replaceAll(unescapedInlineTagRegex, (_, tagName) => {
+      if (allowedInlineTags.includes(tagName)) {
+        return _;
+      }
+
+      tagNames.push(tagName);
+      indexes.push(idx);
+
+      return _;
+    });
+  }
+
+  for (const [
+    idx,
+    tagName,
+  ] of tagNames.entries()) {
+    utils.reportJSDoc(
+      `Unexpected inline JSDoc tag. Did you mean to use {@${tagName}}, \\@${tagName}, or \`@${tagName}\`?`,
+      {
+        line: indexes[idx] + 1,
+      },
+      enableFixer ?
+        () => {
+          utils.setBlockDescription((info, seedTokens, descLines) => {
+            return descLines.map((desc) => {
+              const newDesc = desc.replaceAll(
+                new RegExp(`(^|\\s)@${
+                  // No need to escape, as contains only safe characters
+                  tagName
+                }`, 'gv'),
+                fixType === 'backticks' ? '$1`@' + tagName + '`' : '$1\\@' + tagName,
+              );
+
+              return {
+                number: 0,
+                source: '',
+                tokens: seedTokens({
+                  ...info,
+                  description: newDesc,
+                  postDelimiter: newDesc.trim() ? ' ' : '',
+                }),
+              };
+            });
+          });
+        } :
+        null,
+    );
+  }
+
+  /**
+   * @param {string} tagName
+   * @returns {[
+   *   RegExp,
+   *   (description: string) => string
+   * ]}
+   */
+  const escapeInlineTags = (tagName) => {
+    const regex = new RegExp(`(^|\\s)@${
+      // No need to escape, as contains only safe characters
+      tagName
+    }`, 'gv');
+
+    return [
+      regex,
+      /**
+       * @param {string} desc
+       */
+      (desc) => {
+        return desc.replaceAll(
+          regex,
+          fixType === 'backticks' ? '$1`@' + tagName + '`' : '$1\\@' + tagName,
+        );
+      },
+    ];
+  };
+
+  for (const tag of jsdoc.tags) {
+    if (tag.tag === 'example') {
+      continue;
+    }
+
+    /** @type {string} */
+    let tagName = '';
+    while (/** @type {string[]} */ (
+      utils.getTagDescription(tag, true)
+    // eslint-disable-next-line no-loop-func -- Safe
+    ).some((desc) => {
+      tagName = unescapedInlineTagRegex.exec(desc)?.[1] ?? '';
+      if (allowedInlineTags.includes(tagName)) {
+        return false;
+      }
+
+      return tagName;
+    })) {
+      const line = utils.setTagDescription(tag, ...escapeInlineTags(tagName)) +
+          tag.source[0].number;
+      utils.reportJSDoc(
+        `Unexpected inline JSDoc tag. Did you mean to use {@${tagName}}, \\@${tagName}, or \`@${tagName}\`?`,
+        {
+          line,
+        },
+        enableFixer ? () => {} : null,
+        true,
+      );
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Reports use of JSDoc tags in non-tag positions (in the default "typescript" mode).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/escape-inline-tags.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowedInlineTags: {
+            description: 'A listing of tags you wish to allow unescaped. Defaults to an empty array.',
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          enableFixer: {
+            description: 'Whether to enable the fixer. Defaults to `false`.',
+            type: 'boolean',
+          },
+          fixType: {
+            description: `How to escape the inline tag.
+
+May be "backticks" to enclose tags in backticks (treating as code segments), or
+"backslash" to escape tags with a backslash, i.e., \`\\@\`
+
+Defaults to "backslash".`,
+            enum: [
+              'backticks',
+              'backslash',
+            ],
+            type: 'string',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/implementsOnClasses.js

@@ -0,0 +1,78 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  const iteratingFunction = utils.isIteratingFunctionOrVariable();
+
+  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: 'Prohibits use of `@implements` on non-constructor functions (to enforce the tag only being used on classes/constructors).',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/implements-on-classes.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            description: `Set this to an array of strings representing the AST context (or an object with
+\`context\` and \`comment\` properties) where you wish the rule to be applied.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want
+the rule to apply to any JSDoc block throughout your files (as is necessary
+for finding function blocks not attached to a function declaration or
+expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
+\`@method\`) (including those associated with an \`@interface\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
+            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

@@ -0,0 +1,132 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  parse,
+  traverse,
+  tryParse,
+} from '@es-joy/jsdoccomment';
+import * as resolve from '@es-joy/resolve.exports';
+import {
+  readFileSync,
+} from 'node:fs';
+import {
+  isBuiltin as isBuiltinModule,
+} from 'node:module';
+import {
+  join,
+} from 'node:path';
+
+/**
+ * @type {Set<string>|null}
+ */
+let deps;
+
+const setDeps = function () {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(process.cwd(), './package.json'), 'utf8'),
+    );
+    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(
+              readFileSync(join(process.cwd(), 'node_modules', mod, './package.json'), 'utf8'),
+            );
+          } catch {
+            // Ignore
+          }
+
+          if (!pkg || (!pkg.types && !pkg.typings && !resolve.types(pkg))) {
+            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

@@ -0,0 +1,228 @@
+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',
+];
+
+/**
+ * @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 [];
+  }
+};
+
+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: {
+            description: `The \`aliases\` option allows indicating words as synonyms (aliases) of each other.
+
+For example, with \`{ aliases: { emoji: ["smiley", "winkey"] } }\`, the following comment would be considered uninformative:
+
+\`\`\`js
+/** A smiley/winkey. */
+let emoji;
+\`\`\`
+
+The default \`aliases\` option is:
+
+\`\`\`json
+{
+  "a": ["an", "our"]
+}
+\`\`\``,
+            patternProperties: {
+              '.*': {
+                items: {
+                  type: 'string',
+                },
+                type: 'array',
+              },
+            },
+          },
+          excludedTags: {
+            description: `Tags that should not be checked for valid contents.
+
+For example, with \`{ excludedTags: ["category"] }\`, the following comment would not be considered uninformative:
+
+\`\`\`js
+/** @category Types */
+function computeTypes(node) {
+  // ...
+}
+\`\`\`
+
+No tags are excluded by default.`,
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          uselessWords: {
+            description: `Words that are ignored when searching for one that adds meaning.
+
+For example, with \`{ uselessWords: ["our"] }\`, the following comment would be considered uninformative:
+
+\`\`\`js
+/** Our text. */
+let text;
+\`\`\`
+
+The default \`uselessWords\` option is:
+
+\`\`\`json
+["a", "an", "i", "in", "of", "s", "the"]
+\`\`\``,
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});