eslint-plugin-jsdoc 54.4.1 → 54.6.0

package/src/index.js

@@ -58,80 +58,140 @@ import sortTags from './rules/sortTags.js';
 import tagLines from './rules/tagLines.js';
 import textEscaping from './rules/textEscaping.js';
 import validTypes from './rules/validTypes.js';
+import {
+  merge,
+} from 'object-deep-merge';
 
 /* eslint-disable jsdoc/valid-types -- Bug */
 /**
  * @typedef {"recommended" | "stylistic" | "contents" | "logical" | "requirements"} ConfigGroups
  * @typedef {"" | "-typescript" | "-typescript-flavor"} ConfigVariants
  * @typedef {"" | "-error"} ErrorLevelVariants
- * @type {import('eslint').ESLint.Plugin & {
+ * @type {((
+ *   cfg?: {
+ *     mergeSettings?: boolean,
+ *     config?: `flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}`,
+ *     settings?: Partial<import('./iterateJsdoc.js').Settings>
+ *   }
+ * ) => import('eslint').Linter.Config) & import('eslint').ESLint.Plugin & {
  *   configs: Record<`flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}`,
  *   import('eslint').Linter.Config>
  * }}
  */
-const index = {
-  /* eslint-enable jsdoc/valid-types -- Bug */
-  // @ts-expect-error Ok
-  configs: {},
-  rules: {
-    'check-access': checkAccess,
-    'check-alignment': checkAlignment,
-    'check-examples': checkExamples,
-    'check-indentation': checkIndentation,
-    'check-line-alignment': checkLineAlignment,
-    'check-param-names': checkParamNames,
-    'check-property-names': checkPropertyNames,
-    'check-syntax': checkSyntax,
-    'check-tag-names': checkTagNames,
-    'check-template-names': checkTemplateNames,
-    'check-types': checkTypes,
-    'check-values': checkValues,
-    'convert-to-jsdoc-comments': convertToJsdocComments,
-    'empty-tags': emptyTags,
-    'implements-on-classes': implementsOnClasses,
-    'imports-as-dependencies': importsAsDependencies,
-    'informative-docs': informativeDocs,
-    'lines-before-block': linesBeforeBlock,
-    'match-description': matchDescription,
-    'match-name': matchName,
-    'multiline-blocks': multilineBlocks,
-    'no-bad-blocks': noBadBlocks,
-    'no-blank-block-descriptions': noBlankBlockDescriptions,
-    'no-blank-blocks': noBlankBlocks,
-    'no-defaults': noDefaults,
-    'no-missing-syntax': noMissingSyntax,
-    'no-multi-asterisks': noMultiAsterisks,
-    'no-restricted-syntax': noRestrictedSyntax,
-    'no-types': noTypes,
-    'no-undefined-types': noUndefinedTypes,
-    'require-asterisk-prefix': requireAsteriskPrefix,
-    'require-description': requireDescription,
-    'require-description-complete-sentence': requireDescriptionCompleteSentence,
-    'require-example': requireExample,
-    'require-file-overview': requireFileOverview,
-    'require-hyphen-before-param-description': requireHyphenBeforeParamDescription,
-    'require-jsdoc': requireJsdoc,
-    'require-param': requireParam,
-    'require-param-description': requireParamDescription,
-    'require-param-name': requireParamName,
-    'require-param-type': requireParamType,
-    'require-property': requireProperty,
-    'require-property-description': requirePropertyDescription,
-    'require-property-name': requirePropertyName,
-    'require-property-type': requirePropertyType,
-    'require-returns': requireReturns,
-    'require-returns-check': requireReturnsCheck,
-    'require-returns-description': requireReturnsDescription,
-    'require-returns-type': requireReturnsType,
-    'require-template': requireTemplate,
-    'require-throws': requireThrows,
-    'require-yields': requireYields,
-    'require-yields-check': requireYieldsCheck,
-    'sort-tags': sortTags,
-    'tag-lines': tagLines,
-    'text-escaping': textEscaping,
-    'valid-types': validTypes,
-  },
+// @ts-expect-error Ok
+const index = function (cfg) {
+  /** @type {import('eslint').Linter.Config} */
+  let outputConfig = {
+    plugins: {
+      jsdoc: index,
+    },
+  };
+  if (
+    cfg?.config
+  ) {
+    // @ts-expect-error Security check
+    if (cfg.config === '__proto__') {
+      throw new TypeError('Disallowed config value');
+    }
+
+    outputConfig = index.configs[cfg.config];
+  }
+
+  outputConfig.settings = {
+    jsdoc: cfg?.mergeSettings === false ?
+      cfg.settings :
+      merge(
+        {},
+        cfg?.settings ?? {},
+        cfg?.config?.includes('recommended') ?
+          {
+            // We may need to drop these for "typescript" (non-"flavor") configs,
+            //   if support is later added: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
+            structuredTags: {
+              next: {
+                required: [
+                  'type',
+                ],
+              },
+              throws: {
+                required: [
+                  'type',
+                ],
+              },
+              yields: {
+                required: [
+                  'type',
+                ],
+              },
+            },
+          } :
+          {},
+      ),
+  };
+
+  return outputConfig;
+};
+/* eslint-enable jsdoc/valid-types -- Bug */
+
+index.configs = {};
+index.rules = {
+  'check-access': checkAccess,
+  'check-alignment': checkAlignment,
+  'check-examples': checkExamples,
+  'check-indentation': checkIndentation,
+  'check-line-alignment': checkLineAlignment,
+  'check-param-names': checkParamNames,
+  'check-property-names': checkPropertyNames,
+  'check-syntax': checkSyntax,
+  'check-tag-names': checkTagNames,
+  'check-template-names': checkTemplateNames,
+  'check-types': checkTypes,
+  'check-values': checkValues,
+  'convert-to-jsdoc-comments': convertToJsdocComments,
+  'empty-tags': emptyTags,
+  'implements-on-classes': implementsOnClasses,
+  'imports-as-dependencies': importsAsDependencies,
+  'informative-docs': informativeDocs,
+  'lines-before-block': linesBeforeBlock,
+  'match-description': matchDescription,
+  'match-name': matchName,
+  'multiline-blocks': multilineBlocks,
+  'no-bad-blocks': noBadBlocks,
+  'no-blank-block-descriptions': noBlankBlockDescriptions,
+  'no-blank-blocks': noBlankBlocks,
+  'no-defaults': noDefaults,
+  'no-missing-syntax': noMissingSyntax,
+  'no-multi-asterisks': noMultiAsterisks,
+  'no-restricted-syntax': noRestrictedSyntax,
+  'no-types': noTypes,
+  'no-undefined-types': noUndefinedTypes,
+  'require-asterisk-prefix': requireAsteriskPrefix,
+  'require-description': requireDescription,
+  'require-description-complete-sentence': requireDescriptionCompleteSentence,
+  'require-example': requireExample,
+  'require-file-overview': requireFileOverview,
+  'require-hyphen-before-param-description': requireHyphenBeforeParamDescription,
+  'require-jsdoc': requireJsdoc,
+  'require-param': requireParam,
+  'require-param-description': requireParamDescription,
+  'require-param-name': requireParamName,
+  'require-param-type': requireParamType,
+  'require-property': requireProperty,
+  'require-property-description': requirePropertyDescription,
+  'require-property-name': requirePropertyName,
+  'require-property-type': requirePropertyType,
+  'require-returns': requireReturns,
+  'require-returns-check': requireReturnsCheck,
+  'require-returns-description': requireReturnsDescription,
+  'require-returns-type': requireReturnsType,
+  'require-template': requireTemplate,
+  'require-throws': requireThrows,
+  'require-yields': requireYields,
+  'require-yields-check': requireYieldsCheck,
+  'sort-tags': sortTags,
+  'tag-lines': tagLines,
+  'text-escaping': textEscaping,
+  'valid-types': validTypes,
 };
 
 /**

package/src/rules/requireJsdoc.js

@@ -104,6 +104,10 @@ const OPTIONS_SCHEMA = {
       default: false,
       type: 'boolean',
     },
+    exemptOverloadedImplementations: {
+      default: false,
+      type: 'boolean',
+    },
     fixerMessage: {
       default: '',
       type: 'string',
@@ -169,6 +173,10 @@ const OPTIONS_SCHEMA = {
       },
       type: 'object',
     },
+    skipInterveningOverloadedDeclarations: {
+      default: true,
+      type: 'boolean',
+    },
   },
   type: 'object',
 };
@@ -302,6 +310,8 @@ const getOption = (context, baseObject, option, key) => {
  *   enableFixer: boolean,
  *   exemptEmptyConstructors: boolean,
  *   exemptEmptyFunctions: boolean,
+ *   skipInterveningOverloadedDeclarations: boolean,
+ *   exemptOverloadedImplementations: boolean,
  *   fixerMessage: string,
  *   minLineCount: undefined|import('../iterateJsdoc.js').Integer,
  *   publicOnly: boolean|{[key: string]: boolean|undefined}
@@ -314,9 +324,11 @@ const getOptions = (context, settings) => {
     enableFixer = true,
     exemptEmptyConstructors = true,
     exemptEmptyFunctions = false,
+    exemptOverloadedImplementations = false,
     fixerMessage = '',
     minLineCount = undefined,
     publicOnly,
+    skipInterveningOverloadedDeclarations = true,
   } = context.options[0] || {};
 
   return {
@@ -324,6 +336,7 @@ const getOptions = (context, settings) => {
     enableFixer,
     exemptEmptyConstructors,
     exemptEmptyFunctions,
+    exemptOverloadedImplementations,
     fixerMessage,
     minLineCount,
     publicOnly: ((baseObj) => {
@@ -386,9 +399,52 @@ const getOptions = (context, settings) => {
       /** @type {import('json-schema').JSONSchema4Object} */
       (OPTIONS_SCHEMA.properties).require,
     ),
+    skipInterveningOverloadedDeclarations,
   };
 };
 
+/**
+ * @param {ESLintOrTSNode} node
+ */
+const isFunctionWithOverload = (node) => {
+  if (node.type !== 'FunctionDeclaration') {
+    return false;
+  }
+
+  let parent;
+  let child;
+
+  if (node.parent?.type === 'Program') {
+    parent = node.parent;
+    child = node;
+  } else if (node.parent?.type === 'ExportNamedDeclaration' &&
+      node.parent?.parent.type === 'Program') {
+    parent = node.parent?.parent;
+    child = node.parent;
+  }
+
+  if (!child || !parent) {
+    return false;
+  }
+
+  const functionName = node.id.name;
+
+  const idx = parent.body.indexOf(child);
+  const prevSibling = parent.body[idx - 1];
+
+  return (
+    // @ts-expect-error Should be ok
+    (prevSibling?.type === 'TSDeclareFunction' &&
+      // @ts-expect-error Should be ok
+      functionName === prevSibling.id.name) ||
+    (prevSibling?.type === 'ExportNamedDeclaration' &&
+      // @ts-expect-error Should be ok
+      prevSibling.declaration?.type === 'TSDeclareFunction' &&
+      // @ts-expect-error Should be ok
+      prevSibling.declaration?.id?.name === functionName)
+  );
+};
+
 /** @type {import('eslint').Rule.RuleModule} */
 export default {
   create (context) {
@@ -408,9 +464,11 @@ export default {
       enableFixer,
       exemptEmptyConstructors,
       exemptEmptyFunctions,
+      exemptOverloadedImplementations,
       fixerMessage,
       minLineCount,
       require: requireOption,
+      skipInterveningOverloadedDeclarations,
     } = opts;
 
     const publicOnly =
@@ -476,7 +534,15 @@ export default {
         }
       }
 
-      const jsDocNode = getJSDocComment(sourceCode, node, settings);
+      if (exemptOverloadedImplementations && isFunctionWithOverload(node)) {
+        return;
+      }
+
+      const jsDocNode = getJSDocComment(
+        sourceCode, node, settings, {
+          checkOverloads: skipInterveningOverloadedDeclarations,
+        },
+      );
 
       if (jsDocNode) {
         return;

package/src/rules/requireTemplate.js

@@ -42,6 +42,7 @@ export default iterateJsdoc(({
   /**
    * @param {import('@typescript-eslint/types').TSESTree.FunctionDeclaration|
    *   import('@typescript-eslint/types').TSESTree.ClassDeclaration|
+   *   import('@typescript-eslint/types').TSESTree.TSDeclareFunction|
    *   import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration|
    *   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration
    */
@@ -79,6 +80,7 @@ export default iterateJsdoc(({
     switch (nde.type) {
       case 'ClassDeclaration':
       case 'FunctionDeclaration':
+      case 'TSDeclareFunction':
       case 'TSInterfaceDeclaration':
       case 'TSTypeAliasDeclaration':
         checkTypeParams(nde);
@@ -97,6 +99,7 @@ export default iterateJsdoc(({
         switch (nde.declaration?.type) {
           case 'ClassDeclaration':
           case 'FunctionDeclaration':
+          case 'TSDeclareFunction':
           case 'TSInterfaceDeclaration':
           case 'TSTypeAliasDeclaration':
             checkTypeParams(nde.declaration);